The Trigger Agent compares the contents of a field from an incoming Event with predefined rules, when the rules match, an Event emit is triggered.

Use the Trigger Agent to ignore Events that don’t require processing; to send Events downstream for additional analysis; to further process events that are sent from a particular application.

Features

  • Trigger an Event emit based on the following:
    • regex: The contents of a field at a defined path match a defined regular expression.
    • !regex: The contents of a field at a defined path do not match a defined regular expression.
    • field<value: The number in a field at a defined path is less than a specified value.
    • field<=value: The number in a field at a defined path is less than or equal to a specified value.
    • field==value: The number in a field at a defined path is equal to a specified value.
    • field!=value: The number in a field at a defined path is not equal to a specified value.
    • field>=value: The number in a field at a defined path is greater than or equal to a specified value.
    • field>value: The number in a field at a defined path is greater than a specified value.
    • not in: The value specified is not contained in a field at a defined path.
  • Regex patterns are matched case-insensitive.
  • The value can be a single value or an array of values. In the case of an array, all items must be strings, and if one or more values match, then the rule matches.

Configuration Options

  • rules: The rules array contains sets of type, path and value fields.
    • type: Chose one of ‘regex’, ‘!regex’, ‘field<value’, ‘field<=value’, ‘field==value’, ‘field!=value’, ‘field>=value’, ‘field>value’, and ‘not in’ and compares with the value
    • path: Specify the wrapped JSONPath for the field containing the value to compare. When an incoming event contains an array, a wildcard (e.g.: numbers[*]) can be supplied to apply the rule to all elements of the array.
    • value: Specify regex, number, or array depending on the match type.
  • must_match: (Optional) By default, all rules must match for the Agent to trigger an Event emit. You can switch this so that only one rule must match by setting must_match to ‘1’.
  • emit_no_match: (Optional) By default, an event will only be emitted if the rules match. By setting emit_no_match to true an event will also be emitted if the rules do not match.
  • expected_update_period_in_days: Set this key to the maximum amount of time expected to pass between Events being created by this Agent. If this period passes without any Events being emitted, the Agent will be flagged as “Not Working”.

Emitted Events

When a rules is matched, Events emitted by the Trigger Agent will look the below:

{ 
  "rule_matched": true 
}

Example Configuration Options

Emit an Event when the contents of the ‘size’ field in an incoming Events are greater than 5.

{
  "rules": [
    {
      "type": "field>value",
      "path": "{{.size}}",
      "value": "5"
    }
  ],
  "expected_update_period_in_days": "2"
}

Emit an Event when the content of the ‘body’ field contain an email address.

{
  "rules": [
    {
      "type": "regex",
      "path": "{{.body}}",
      "value": "\\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}\\b"
    }
  ],
  "expected_update_period_in_days": "2"
}

Emit an Event when ‘dog’ or ‘cat’ are not contained in the ‘animal’ field of an incoming event.

{
  "rules": [
    {
      "type": "not in",
      "path": "{{.animal}}",
      "value": ["dog","cat"]
    }
  ],
  "expected_update_period_in_days": "2"
}

Emit an Event when the contents of the ‘size’ field of an incoming Event is greater than 0 AND the contents of the ‘username’ field is “alice”.

{
  "rules": [
    {
      "type": "field>value",
      "path": "{{.size}}",
      "value": 0
    },
    {
      "type": "field==value",
      "path": "{{.username}}",
      "value": "alice"
    }
  ],
  "expected_update_period_in_days": "2"
}

Emit an Event when the contents of the ‘size’ field of an incoming Event is greater than 0 OR the contents of the ‘username’ field is “alice”.

{
  "rules": [
    {
      "type": "field>value",
      "path": "{{.size}}",
      "value": 0
    },
    {
      "type": "field==value",
      "path": "{{.username}}",
      "value": "alice"
    }
  ],
  "must_match":1,
  "expected_update_period_in_days": "2"
}

When receiving the following event:

{
  "students": [
    {
      "name": "Alice",
      "age": "20"
    },
    {
      "name": "Bob",
      "age": "33"
    },
    {
      "name": "Carol",
      "age": "29"
    }
  ]
}

Emit an event if any of the students are over 25 years of age:

{
  "rules": [
    {
      "type": "field>value",
      "value": "25",
      "path": "{{.students[*].age}}"
    }
  ],
  "must_match": "1",
  "expected_update_period_in_days": "2"
}