Defining routing rules

To define a routing rule, you must specify 1 or more targets as the destinations for metrics. You can also define 1 or more inclusion filters that define the conditions of how those metrics are routed to those destinations.

For each route that you define in the account, you can configure up to 10 rules. The rules specify what metrics are routed in a region and where to route them. For more information, see Understanding how routes work in your account.

A rule consists of 1 action, 1 or more targets, and 0 or more inclusion filters.

Targets

Targets define the list of target IDs where the metrics are routed.

You can specify up to three target IDs per rule.
You can define target IDs for resources that are available in the same region where you are configuring the route, in a different region, and in a different account.

For example, you can define a list of targets as follows:

"targets": [{"id":"11111111-1111-1111-1111-111111111111"},{"id":"22222222-2222-2222-2222-222222222222"}]

Targets must be IBM Cloud Monitoring instances.

Action

Action defines whether IBM Cloud® Metrics Routing includes or excludes metrics on the route. Two actions are supported: send and drop. If not specified, the default action is to send the metrics.

send: Metrics are sent, based on the routing rule, on the defined route.
drop: Metrics are excluded, based on the routing rule, when metrics are sent on the defined route.

Inclusion filters

Inclusion filters define the conditions that are used to determine which metrics are routed to the targets specified in the rule.

To route all metrics, exclude the inclusion_filters definition when you configure a route.

Inclusion filters are composed of an operand, operator, and value:

operand

Operand is the name of the property in the target that is used to filter data. The following operands are supported: location, service_name, service_instance, resource_type, and resource. The value is extracted from the target CRN.

operator

Two operators are supported: in and is.

in

The value of the operand property is compared to a list of values.

You can define up to 20 values.

is

The value of the operand property is compared to a single value.

When using is, only 1 value can be specified.

value

A string, or an array of strings, to be compared with the operand property to determine whether the metric is routed or not. When the is operator is used, value must include a single string. When the in operator is used, value can include multiple strings in an array.

Valid values depend on the operand.

location: Any location where IBM Cloud Metrics Routing is available.
service_name: The CRN service name of an [IBM Cloud service that generates metrics managed through IBM Cloud Metrics Routing
service_instance, resource_type, and resource: Values appropriate to an [IBM Cloud service that generates metrics managed through IBM Cloud Metrics Routing

Note these limitations when configuring inclusion filters.

You can configure up to 7 inclusion filters for each rule.
You can configure up to 20 values for inclusion_filter.values.
Each value configured for inclusion_filter.values can be a maximum of 100 characters.

IAM Access

Users must have the appropriate IAM roles to work with routing rules. For information on IAM roles, see Managing IAM access.

Defining routing rules by using the UI

You can configure action and inclusion filter routing rules in the UI. for more information, see Managing routes.

Defining routing rules by using the CLI

Rules for routes and inclusion filters are defined in JSON format. Rules are defined in the following ways:

By using the --rules option information is passed as JSON directly on the command.
By using the --files option information is passed as a JSON file.

Example that uses the --rules option

The following example specifies rules directly on the --rules option. In this example, all metrics from us-east are routed to 11111111-1111-1111-1111-1111111111111. All metrics from appconnect, cloudant, and containers-kupernetes are routed to 22222222-2222-2222-2222-222222222222 and 33333333-3333-3333-3333-3333333333333.

[{"action": "send", "targets":[{"id":"11111111-1111-1111-1111-1111111111111"}], "inclusion_filters":[{"operand": "location","operator": "is","values": ["us-east"]}]},{"targets":[{"id":"22222222-2222-2222-2222-222222222222"},{"id":"33333333-3333-3333-3333-3333333333333"}], "inclusion_filters":[{"operand": "service_name","operator": "in","values": ["appconnect","cloudant","containers-kubernetes"]}]}]'

Example that uses the --file option

The following example specifies rules by passing a JSON file that is named rules_def.json on the --file option:

--file rules_def.json

The rules_def.json file contains:

[
  {
    "action":"send",
    "targets": [
      {
        "id":"11111111-1111-1111-1111-111111111111"
      },
      {
        "id":"22222222-2222-2222-2222-222222222222"
      }
    ],
    "inclusion_filters": [
      {
          "operand": "service_name",
          "operator": "in",
          "values": [
            "appconnect",
            "cloudant",
            "containers-kubernetes"
          ]
        },
        {
          "operand": "location",
          "operator": "in",
          "values": [
            "us-south",
            "eu-de"
          ]
        }
    ]
  }
]

In this example, only metrics from appconnect, cloudant, and containers-kubernetes from the us-south and eu-de regions are routed to targets 11111111-1111-1111-1111-111111111111 and 22222222-2222-2222-2222-222222222222.

Define routing rules by using the API

Targets and inclusion filters are defined in API calls by using rules. The rules are defined in a JSON structure.

For example, the following example creates a route that is named my-route and sends metrics from codeengine, and container-registry in the us-east region to targets 11111111-1111-1111-1111-111111111111 and 22222222-2222-2222-2222-222222222222.

curl -X POST https://private.<REGION>.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: Bearer <IAM_TOKEN>" -H 'content-type: application/json' -d '{
    "name": "my-route",
    "rules": [
      {
        "action":"send",
        "targets": [{"id":"11111111-1111-1111-1111-111111111111"}, {"id":"22222222-2222-2222-2222-222222222222"}],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
  }'

For more information, see the API reference.