Managing routes

Creating a route using the UI

Do the following to create a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Monitoring.

4. Click Routing.

5. Click the Routes tab.

6. Click Create to open the create a route page.

7. Enter a meaningful name for the route.

8. Click Next.

9. In Routing rules, modify the Action for Rule 1:

   • Select Send for the rule to route metrics to the associated targets.

   • Select Drop for the rule to drop metrics matching this rule.

10. Add the inclusion filters to determine the metrics routed to the targets specified in the rule.

Select the desired filter and condition and specify the value to be matched by the inclusion filter.

To add multiple inclusion filters, click Add filter to add additional filters.

11. Add the target to associate with the rule by selecting a target from the list. If you do not have a target defined, click Add target to create a new target.

12. Click Add rule to add additional rules to the route.

    The order of route rules affects the routing behavior. Rules are processed in order and once a rule is matched, the subsequent rules are not processed.

    The order of the routing rules can be changed by clicking the up and down arrows to the right of each rule definition.

    If you need to remove a rule or filter, click the Remove icon associated with the rule or filter.

    You can configure up to 10 rules per route.

13. After defining your route, click Next.

14. Review the route definition ensuring the order of the rules is as intended.

15. Click Create.

Updating a route using the UI

Do the following to update a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Monitoring.

4. Click Routing.

5. Click the Routes tab.

6. Determine which route to update and click the .

7. Click Rename to rename the route.

8. Click Edit to update the route rules.

9. In Routing rules, modify the Action for the rule:

   • Select Send for the rule to route metrics to the associated targets.

   • Select Drop for the rule to drop metrics matching this rule.

10. Add or modify the inclusion filters to determine the metrics routed to the targets specified in the rule.

Select the desired filter and condition and specify the value to be matched by the inclusion filter.

To add multiple inclusion filters, click Add filter to add additional filters.

11. Modify the target to associate with the rule by selecting a target from the list. If you do not have a target defined, click Add target to create a new target.

12. Click Add rule to add additional rules to the route.

    The order of route rules affects the routing behavior. Rules are processed in order and once a rule is matched, the subsequent rules are not processed.

    The order of the routing rules can be changed by clicking the up and down arrows to the right of each rule definition.

    If you need to remove a rule or filter, click the Remove icon associated with the rule or filter.

    You can configure up to 10 rules per route.

13. Click Update to make changes to your route.

Viewing a route using the UI

Do the following to view a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Monitoring.

4. Click Routing.

5. Click the Routes tab.

   The configured routes are listed. The order of the routes does not affect the routing behavior since they are processed independently.

   Each route displays the route name and rules.

   The routes page also displays Routing guidance with additional information about configuring routing.

Deleting a route using the UI

Do the following to delete a route using the UI.

1. Log in to your IBM Cloud account.

2. Click the Menu icon > Observability.

3. Click Monitoring.

4. Click Routing.

5. Click the Routes tab.

6. Determine which route to delete and click the .

7. Click Delete to delete the entire route. You must enter the route name before the route is deleted.

CLI prerequisites

Before you use the CLI to manage routes, complete the following steps:

1. Install the IBM Cloud CLI.

2. Install the IBM Cloud Metrics Routing CLI.

3. Log in to IBM Cloud. Run the following command: ibmcloud login

Creating a route by using the CLI

Use this command to create a route.

Route names are unique in the account.

ibmcloud metrics-router route create --name ROUTE_NAME ( --rules RULES |  --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]

ibmcloud mr route create --name target1 --rules '[{"action": "send", "targets":[{"id":"551957a7-c1e3-4160-84d8-4268709f6743"}]}]'
OK
Route
Name:         target1
ID:           06a29ca2-40f5-4371-ae3c-76a896577bd3
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:06a29ca2-40f5-4371-ae3c-76a896577bd3
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T21:14:21.460Z
Updated At:   2023-05-30T21:14:21.460Z

Updating a route using the CLI

Use this command to update a route. Any specified value that is different from when the route was originally created will be updated to the value specified in the command.

ibmcloud metrics-router route update --route ROUTE [--name ROUTE_NAME] ( --rules RULES |  --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]

ibmcloud mr route update --route target1 --name target2
OK
Route
Name:         target2
ID:           06a29ca2-40f5-4371-ae3c-76a896577bd3
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:06a29ca2-40f5-4371-ae3c-76a896577bd3
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T21:14:21.460Z
Updated At:   2023-05-30T21:19:40.953Z

Deleting a route using the CLI

Use this command to delete a route.

ibmcloud metrics-router ROUTE rm --route route [--force]

Are you sure you want to remove the route with route ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx? [y/N]>y
OK
Route with name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx was successfully removed.

Getting information about a route using the CLI

Use this command to get information about a route for an IBM Cloud Metrics Routing region.

ibmcloud metrics-router ROUTE get --route route [--output FORMAT]

ibmcloud mr route get --route route-all
OK
Route
Name:         route-all
ID:           f22e9cb6-2fcd-456d-9cf2-27813b1cc375
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:f22e9cb6-2fcd-456d-9cf2-27813b1cc375
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T08:04:53.183Z
Updated At:   2023-05-30T08:53:22.824Z

Listing all routes in a region

Use this command to list the configured routes for an IBM Cloud Metrics Routing region.

ibmcloud metrics-router route ls [--output FORMAT]

ibmcloud mr route ls
OK
Routes
Name:         route-all
ID:           f22e9cb6-2fcd-456d-9cf2-27813b1cc375
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:f22e9cb6-2fcd-456d-9cf2-27813b1cc375
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T08:04:53.183Z
Updated At:   2023-05-30T08:53:22.824Z

API routes and actions

The following table lists the actions that you can run to manage routes:

You can use private and public endpoints to manage routes. For more information about the list of ENDPOINTS that are available, see Endpoints.

• You can manage routes from the private network using an API endpoint with the following format: https://private.REGION.metrics-router.cloud.ibm.com

• You can manage routes from the public network using an API endpoint with the following format: https://REGION.metrics-router.cloud.ibm.com

• You can disable the public endpoints by updating the account settings. For more information, see Configuring route and region settings.

For more information about the REST API, see routes.

API prerequisites

To make API calls to manage routes, complete the following steps:

1. Get an IAM access token. For more information, see Retrieving IAM access tokens.
2. Identify the API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

Creating a route using the API

You can use the following cURL command to create a route:

Route names are unique in the account. You cannot reuse a route name to configure multiple destinations.

curl -X POST <ENDPOINT>/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    -d '{
    "name": "ROUTE_NAME",
    "rules": [
      RULES
    ]
  }'

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

ROUTE_NAME

The name to be given to the route.

Do not include any personal identifying information (PII) in any resource names.

RULES

JSON formatted rules array definition in single quotes that define how metrics are routed. For more information, see Defining routing rules.

For example, you can use the following cURL request to create a route:

curl -X POST https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My-route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
  }'

Updating a route using the API

You can modify the name of a route and rules. Any specified value that is different from when the route was originally created will be updated to the value specified in the request.

When you update a route, you must include the route information in the data section of the request.

• You must pass all fields.
• Update the fields that need to be changed.

Route names are unique in the account. You cannot reuse a route name to configure multiple destinations.

You can use the following cURL command to update a route:

curl -X PATCH <ENDPOINT>/api/v3/routes/ROUTE_ID -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "ROUTE_NAME",
    "rules": [
      RULES
    ]
  }'

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

ROUTE_ID

ID of the route.

ROUTE_NAME

Name of the route. The maximum length of the name is 256 characters.

Do not include any personal identifying information (PII) in any resource names.

RULES

JSON formatted rules array definition in single quotes that define how metrics are routed. For more information, see Defining routing rules.

For example, you can use the following cURL request to create a route in Dallas:

curl -X PATCH https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
    }
  }'

Deleting a route using the API

You can use the following cURL command to delete a route:

curl -X DELETE <ENDPOINT>/api/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

<route_ID>

ID of the route.

For example, you can use the following cURL request to delete a route with the ID 00000000-0000-0000-0000-000000000000:

curl -X DELETE https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Viewing a route using the API

You can use the following cURL command to view the configuration details of 1 route:

curl -X GET <ENDPOINT>/api/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

<ENDPOINT>

API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

<route_ID>

ID of the route.

For example, you can run the following cURL request to get information about a route with the ID 00000000-0000-0000-0000-000000000000:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Listing all routes using the API

You can use the following cURL command to view all routes:

curl -X GET <ENDPOINT>/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

• <ENDPOINT> is the API endpoint in the region where you plan to configure or manage a route. For more information, see Endpoints.

For example, you can run the following cURL request to get information about the routes that are defined in Dallas:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

HTTP response codes

When you use the IBM Cloud Metrics Routing REST API, you can get standard HTTP response codes to indicate whether a method completed successfully.

• A 200 response always indicates success.
• A 4xx response indicates a failure.
• A 5xx response indicates an internal system error.

See the following table for some HTTP response codes: