Getting started with IBM Cloud Metrics Routing

Use IBM Cloud® Metrics Routing to configure the routing of platform metrics generated in your IBM Cloud account.

You can use IBM Cloud Metrics Routing, a platform service, to manage platform metrics at the account-level by configuring targets and routes that define where data points are routed. IBM Cloud Metrics Routing can only route metrics that are generated in supported regions by enabled services. Other regions, where IBM Cloud Metrics Routing is not available, continue to manage metrics by using IBM Cloud Monitoring. For more information about IBM Cloud Metrics Routing, see About IBM Cloud Metrics Routing.

A diagram that shows a sample IBM Cloud Metrics Routing architecture. — Figure 1. IBM Cloud Metrics Routing sample architecture

Prerequisites

Install the IBM Cloud CLI.
Install the IBM Cloud Metrics Routing CLI.
You must have a userid with permissions to manage IBM Cloud Metrics Routing. For more information about IAM roles and how to assign them, see Managing access with IAM and Assigning access to IBM Cloud Metrics Routing.
To configure IBM Cloud Metrics Routing to route metrics to a Monitoring instance, you must configure a service to service authorization. You do not have to provide credentials to IBM Cloud Metrics Routing.

For information on configuring service to service authentiation, see Managing authorizations to grant access between services.

Step 1. Configure the account settings

Set these account settings to define where and how metrics are collected, routed, and managed in your account by using IBM Cloud Metrics Routing.

When you configure IBM Cloud Metrics Routing in your account, you can configure account settings such as metadata locations, type of endpoints that are allowed to manage the configuration, locations where targets can be defined, and default targets for collecting metrics in regions that you have not explicitly configured how to route metrics. For more information, see Configuring IBM Cloud Metrics Routing account settings.

Before you can configure targets and routes in the account, you must configure the primary metadata location that defines the region where all your IBM Cloud Metrics Routing resource definitions are stored.

Run the following command to configure the primary metadata location:

ibmcloud metrics-router setting update --primary-metadata-region <REGION>

Where <REGION> is set to a supported region where IBM Cloud Metrics Routing is available. For more information, see Locations.

Before setting the metadata location, check any compliance or industry regulations that apply to the data location.

Step 2. Configure 1 target

A target defines where metrics are collected. For more information about targets, see Understanding how targets work in your account.

When you configure a target, you are defining the destination where you plan to send platform metrics that are collected in a region in your account.

Complete the following steps to configure a target:

Define a target where to route metrics.
```
ibmcloud metrics-router target create --name TARGET_NAME --destination-crn DESTINATION_TARGET_CRN [--region REGION]
```
Where

--name

Defines the name to be given to the target.

--destination-crn

Defines the CRN of the IBM Cloud Monitoring instance where you plan to route the metrics. IBM Cloud Monitoring targets are the only ones supported.

--region

[Optional] Defines the region where the target definition is created. You can only specify a supported region. Set this option if you want to create a target in a region and you are connected to a different one.
Define a service to service authorization between the IBM Cloud Metrics Routing service and the IBM Cloud Monitoring instance that you configured as your destination in the target. For more information, see Managing authorizations to grant access between services.

Step 3. Configure 1 route

A route defines the rules that indicate what metrics are routed in a region and where to store them. Routes are global under an account and are evaluated in all regions where IBM Cloud Metrics Routing is deployed. For more information, see Understanding how routes work in your account.

In this step, you will configure a route to redirect metrics to the target destination that you configured in the previous step.

Run the following command to create the route:

ibmcloud metrics-router route create --name ROUTE_NAME  --rules RULES

Where

--name ROUTE_NAME: Defines the name to be given to the route.
--rules RULES: Defines a JSON formatted rule definition enclosed in single quotes. Learn more.

After you configure a route, it might take up to 1 hour for the configuration to be enabled.

For example, to create a route to send metrics generated in us-east to the target that you created in the previous step, run the following command.

ibmcloud metrics-router route create --name "my-route" --rules '[{"action": "send", "targets":[{"id":"TARGETID"}], "inclusion_filters":[{"operand": "location","operator": "is","values": "us-east"}]}]''

Where TARGETID is the ID of the target that you created in the previous step.

Step 4. Verify collection of metrics

After the target and the route is configured, you must verify that metrics are available.

Launch the IBM Cloud Monitoring UI for the Monitoring instance that you configured as your target, and explore the metrics.