Defining match tokens rules

A match tokens rule copies the value of another field to the matchTokens field so that it can be used to match events (alerts) to resources.

About this task

A match tokens rule populates the matchTokens of resources matched by the rule (a simple example is included below the procedure).

Procedure

  1. On the Rules administration page, select the Match tokens rules tab.

  2. Complete the Details section by defining the name, status, and tokens for the rule.

    a. Enter a name, which must be unique within the context of the tenant.

    You cannot change the name of an existing rule. If you want a rule to have a different name, create a new rule, then delete the old one.

    b. Toggle the rule status to be either Enabled or Disabled.

    When observer jobs are run, they apply only the rules that are in an enabled state.

    c. Define merge tokens for the rule, then click Add+.

    The tokens defined as part of a rule contain the list of shared resource parameter names that will become match tokens for those resources to which the rule is applied. Match tokens can be constructed using variable substitutions, which allow you to combine more than one property value in a token and also combine them with literal strings.

  3. Complete the Conditions section by selecting the observers, provider, and resource type for the rule, and by setting the token include / exclude switch.

    a. Select observers to which this rule applies from the Observer name drop-down. Leave empty to apply the rule to all observers.

    b. Select providers to which this rule applies from the Provider name drop-down. Leave empty to apply the rule to all providers.

    c. Select resource types to which this rule applies from the Resource type drop-down. Leave empty to apply the rule to all resource types.

    d. Set the Token filter mode to either Exclude or Include, then define a filter in the format of a regular expression. You can set more than one filter.

    • Exclude: Tokens which match any one of the expressions will not be applied to resources.
    • Include: Only tokens which match one of the expressions will be applied to the applicable resources.

  4. Validate your filters using the Validate token filters button.

  5. Click Save.

Examples

Default merge rule for the Docker Observer**

The following example is the default merge rule defined for the Docker Observer:

rules:
    - name: dockerId
      ruleType: mergeRule
      ruleStatus: enabled
      tokens: [ dockerId ]
      entityTypes: null
      observers: [ docker-observer ]
      providers: null
    - name: almExternalId
      ruleType: mergeRule
      ruleStatus: enabled
      tokens: [ externalId ]
      entityTypes: null
      observers: [ alm-observer ]
      providers: null

Note that the rules name in this example is dockerId``, and that it applies only to instances of observers named docker-observer``. The ruleType property here specifies the mergeRule rule type. This merge rule applies to all entity types and all providers and will copy the dockerId property into the merge tokens for all resources that have this property set.

Example

Match token rules

A match token rule allows the value of another field to be copied to the matchTokens field so that it can be used to match events to resources. It populates the matchTokens of resources matched by the rule.

Simple example of a matchTokensRule:

- name: matchRule
  ruleType: matchTokensRule
  ruleStatus: enabled
  tokens: [ name ]
  entityTypes: null
  observers: null
  providers: null

Resource with variable substitutions and exclude list

{
  "name": "sysNameMatching",
  "tokens": [ "sysName", "${name}/${customField}"],
  "ruleStatus": "enabled",
  "entityTypes": [ "host", "server" ],
  "observers": [ "ITNM", "TADDM" ],
  "providers": [ "*" ],
  "customField": "string",
  "excludeTokens": [ "^asm-default.*"]
}

The ^asm-default.* value set for excludeTokens ensures that any values that match the regular expressions are excluded. The merge token with the value of ${name}/${customField} combine the ${name} and ${customField} properties using the ${} syntax, and demonstrate how variable substitutions work.

Literal values are entered as they are in the merge token, which in this case is the / character.

To be backwards compatible, tokens consisting of a single value, as in the sysName example, are treated as variable substitutions, that is, as if they are ${sysName}.