---
name: metrics-router-getting-started
title: Getting started with IBM Cloud Metrics Routing
description: Use IBM Cloud® Metrics Routing to configure the routing of platform metrics generated in your IBM Cloud account.
last-updated: 2026-05-27
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/metrics-router?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Getting started with IBM Cloud Metrics Routing
{: #getting-started}



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

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 route metrics that are generated in [supported regions](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-regions&format=markdown) by enabled services. For more information about IBM Cloud Metrics Routing, see [About IBM Cloud Metrics Routing](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-about&format=markdown).

![A diagram that shows a sample IBM Cloud Metrics Routing architecture.](/images/metrics-routing-ov.png "IBM Cloud Metrics Routing architecture sample."){: caption="IBM Cloud Metrics Routing sample architecture" caption-side="bottom"}

## Prerequisites
{: #getting-started-prereqs}

- [Install the IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-install-ibmcloud-cli&format=markdown).

- [Install the IBM Cloud Metrics Routing CLI](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-metrics-router-cli-config&format=markdown).

- 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](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-iam&format=markdown) and [Assigning access to IBM Cloud Metrics Routing](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-iam-assign-access&format=markdown).

- 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.](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-iam-service-auth&format=markdown)



## Step 1. Configure the account settings
{: #getting-started-step1}

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](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-settings&format=markdown).

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.
{: important}

Run the following command to configure the primary metadata location:

```pre
ibmcloud metrics-router setting update --primary-metadata-region <REGION>
```
{: codeblock}

Where `<REGION>` is set to a supported region where IBM Cloud Metrics Routing is available. For more information, see [Locations](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-regions&format=markdown).

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



## Step 2. Configure 1 target
{: #getting-started-step2}

A target defines where metrics are collected. For more information about targets, see [Understanding how targets work in your account](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-target&interface=cli&format=markdown#target_behavior).

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:

1. Define a target where to route metrics.

    ```text
    ibmcloud metrics-router target create --name TARGET_NAME --destination-crn DESTINATION_TARGET_CRN [--region REGION]
    ```
    {: pre}

    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](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-regions&interface=cli&format=markdown). Set this option if you want to create a target in a region and you are connected to a different one.

2. 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](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-iam-service-auth&format=markdown).

## Step 3. Configure 1 route
{: #getting-started-step3}

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](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-routes&interface=cli&format=markdown#route_behaviour).

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:

```text
ibmcloud metrics-router route create --name ROUTE_NAME  --rules RULES
```
{: pre}

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](https://cloud.ibm.com/docs/metrics-router?topic=metrics-router-route_rules_definitions&interface=cli&format=markdown).

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

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.

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

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


## Step 4. Verify collection of metrics
{: #getting-started-step4}


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

[Launch the IBM Cloud Monitoring UI](https://cloud.ibm.com/docs/monitoring?topic=monitoring-launch&format=markdown) for the Monitoring instance that you configured as your target, and explore the metrics.

Alternatively, you can use pre-built, open-source and enterprise-ready [Terraform IBM Modules (TIM)](https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-about-tim&format=markdown){: external} for [IBM Cloud Monitoring](https://registry.terraform.io/modules/terraform-ibm-modules/cloud-monitoring/ibm/latest/submodules/metrics_routing){: external} to configure targets, routes and account settings. This module simplifies the creation and management of targets and routes following the best practices.
{: tip}