Metrics Routing CLI

The IBM Cloud® command-line interface (CLI) provides extra capabilities for service offerings. This information describes how you can use the CLI to define and manage settings for your IBM Cloud® Metrics Routing instance by using the CLI.

Installing the CLI

Install the IBM Cloud CLI.
Install the CLI by running the following command:
```
ibmcloud plugin install metrics-router
```

You're notified on the command line when updates to the IBM Cloud CLI and plug-ins are available. Be sure to keep your CLI up to date so that you can use the most current commands. You can view the current version of all installed plug-ins by running ibmcloud plugin list.

Before you begin

Before you configure IBM Cloud Metrics Routing routes or targets, you must configure a primary metadata region. The primary metadata region is configured using the ibmcloud metrics-router setting update command --primary-metadata-region option.

If you you do not have a primary metadata region configured, your route and target command will fail.

ibmcloud metrics-router route create

Use this command to create a new route to IBM Cloud Metrics Routing targets.

Targets must be IBM Cloud Monitoring instances.

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

Command options

--name ROUTE_NAME

The name to be given to the route.

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

--file RULES_DEFINITION_JSON_FILE

A JSON file that contains the definition of the rules for route. The file needs to be formatted as follows:

[
  {
    "targets": [{"id":"ID1"},{"id":"ID2"}]
  }
]

Where targets is a comma-separated list of target IDs.

The rule definition can optionally also include inclusion filters. For example,

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

Where:

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.

operand

Operand is the name of the property on which the operator test is run. The following operands are supported: location,service_name,service_instance,resource_type, and resource.

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.

values

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, values must include a single string. When the in operator is used, values 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

--rules RULES

A JSON formatted rule definition enclosed in single quotation marks. For example,

--rules '[{"action": "send", "targets":[{"id": "11111111-1111-1111-1111-111111111111"}], "inclusion_filters":[{"operand": "location","operator": "is","values": ["us-south"]}]}]

Where targets is a comma-separated list of target IDs.

The rule definition can optionally also include inclusion filters. For example,

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

Where:

action

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.

operand

Operand is the name of the property on which the operator test is run. The following operands are supported: location,service_name,service_instance,resource_type, and resource.

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.

values

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

--output FORMAT

If JSON is specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.

--force

Run the command without prompting for confirmation. This flag only applies when the resulting route discards platform metrics.

help | --help | -h

List options available for the command.

ibmcloud metrics-router route update

Use this command to update a route to IBM Cloud Metrics Routing targets. Any specified value that is different from when the route was originally created is updated to the value specified in the command.

Targets must be IBM Cloud Monitoring instances.

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

Command options

--route ROUTE

The existing name or ID of the route.

--name ROUTE_NAME

The updated name to be given to the route (optional).

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

--file RULES_DEFINITION_JSON_FILE

A JSON file that contains the definition of the rules for route. The file needs to be formatted as follows:

[
  {
    "targets": [{"id":"ID1"},{"id":"ID2"}]
  }
]

Where targets is a comma-separated list of target IDs.

The rule definition can optionally also include inclusion filters. For example,

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

Where:

action

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.

operand

Operand is the name of the property on which the operator test is run. The following operands are supported: location,service_name,service_instance,resource_type, and resource.

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.

values

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

--rules RULES

A JSON formatted rule definition enclosed in single quotation marks. For example,

--rules '[{"action": "send", "targets":[{"id": "11111111-1111-1111-1111-111111111111"}], "inclusion_filters":[{"operand": "location","operator": "is","values":["us-south"]}]}]

Where target_ids is a comma-separated list of target IDs.

The rule definition can optionally also include inclusion filters. For example,

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

Where:

action

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.

operand

Operand is the name of the property on which the operator test is run. The following operands are supported: location,service_name,service_instance,resource_type, and resource.

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.

values

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

--output FORMAT

If JSON is specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.

--force

Run the command without prompting for confirmation. This flag only applies when the resulting route discards platform metrics.

help | --help | -h

List options available for the command.

ibmcloud metrics-router route rm

Use this command to delete an IBM Cloud Metrics Routing route.

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

Command options

--route ROUTE: The name or ID of the route to be deleted.
--force: Deletes the route without providing the user with any additional prompt.
help | --help | -h: List options available for the command.

ibmcloud metrics-router route get

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

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

Command options

--route <ROUTE_ID>: The name or ID of the route.
--output FORMAT: If JSON is specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.
help | --help | -h: List options available for the command.

ibmcloud metrics-router route ls

Use this command to list all the configured routes for IBM Cloud Metrics Routing in the account.

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

Command options

--output FORMAT: If JSON is specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.
help | --help | -h: List options available for the command.

ibmcloud metrics-router target create

Use this command to create a target to be used to configure a destination for platform metrics.

Targets must be IBM Cloud Monitoring instances.

ibmcloud metrics-router target create --name TARGET_NAME --destination-crn DESTINATION_TARGET_CRN [--region REGION] [--output FORMAT]

Command options

--region REGION | -r REGION

Name of the region, for example, us-south or eu-gb. If not specified, the region that is logged into, or targeted, is used.

--name TARGET_NAME

The name to be given to the target.

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

--destination-crn DESTINATION_TARGET_CRN

The CRN of the service instance or resource to receive the metrics sent by IBM Cloud Metrics Routing. Ensure you have a service authorization between IBM Cloud Metrics Routing and your IBM Cloud resource. For more information, see Managing authorizations to grant access between services..

--output FORMAT

Support format is JSON. If specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.

help | --help | -h

List options available for the command.

ibmcloud metrics-router target update

Use this command to update a target to be used to configure a destination for platform metrics.

Targets must be IBM Cloud Monitoring instances.

ibmcloud metrics-router target update --target TARGET [--name TARGET_NAME] [--destination-crn DESTINATION_TARGET_CRN] [--output FORMAT]

Command options

--region REGION | -r REGION

Name of the region, for example, us-south or eu-gb. If not specified, the region that is logged into, or targeted, is used.

--target TARGET

The name or id of the target to be updated.

--name TARGET_NAME

The new name to be given to the target.

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

--destination-crn DESTINATION_TARGET_CRN

--output FORMAT

Support format is JSON. If specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.

help | --help | -h

List options available for the command.

ibmcloud metrics-router target rm

Use this command to delete a target.

ibmcloud metrics-router target rm --target TARGET [--force]

Command options

--target TARGET: The ID or name of the target.
--force | -f: Deletes the target without providing the user with any additional prompt.
help | --help | -h: List options available for the command.

ibmcloud metrics-router target get

Use this command to get information about an IBM Cloud Metrics Routing target.

ibmcloud metrics-router target get --target TARGET [--output FORMAT]

Command options

--target TARGET: The ID or name of the target.
--output FORMAT: Supported format is JSON. If specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.
help | --help | -h: List options available for the command.

ibmcloud metrics-router target ls

Use this command to list the configured targets for IBM Cloud Metrics Routing.

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

Command options

--output FORMAT: Supported format is JSON. If specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.
help | --help | -h: List options available for the command.

ibmcloud metrics-router setting get

Use this command to get the settings for the IBM Cloud Metrics Routing account configurations.

ibmcloud metrics-router setting get [--output FORMAT]

Command options

--output FORMAT: If JSON is specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.
help | --help | -h: List options available for the command.

ibmcloud metrics-router setting update

Use this command to modify current settings such as the default targets, permitted target regions, primary and secondary metadata regions in IBM Cloud Metrics Routing. Any value that is different from when the target was originally created is updated to the value specified in the command. If no options are specified, the current settings are returned.

Before you disable public endpoints by setting --private-api-endpoint-only TRUE, make sure your account has access to the private endpoint. You can do this by running the command ibmcloud account show. If VRF Enabled is true and Service Endpoint Enabled is true then you have access to the private endpoint. If you do not have access to the private endpoint, you cannot enable the public endpoint. Private endpoint access is required to enable the public endpoint.

ibmcloud metrics-router setting update [--primary-metadata-region REGION] [--backup-metadata-region REGION] [--private-api-endpoint-only ( TRUE | FALSE )] [--default-targets TARGET] [--permitted-target-regions REGIONS] [--output FORMAT] [--force]

Command options

backup-metadata-region

backup-metadata-region is the location where a backup of the metadata for your IBM Cloud Metrics Routing configuration is stored.

default-targets

default-targets is a list of target IDs. If no routing rules cause metrics to be sent to other targets, these targets receive the metrics. TARGET is a comma-separated list of target IDs.

permitted-target-regions

permitted-target-regions is the list of regions that can be used to define a target. REGION is a comma-separated list of regions. If not specified, any number of regions can be used to define a target.

For example, to limit the regions that can be used to define targets to us-south and eu-de, specify: --permitted-target-regions us-south,eu-de.

To delete all configured regions, specify --permitted-target-regions "".

primary-metadata-region

primary-metadata-region is the location where the metadata for your IBM Cloud Metrics Routing configuration is stored.

private-api-endpoint-only

Specifies whether a private endpoint can be used. If TRUE, only a private endpoint can be used.

--output FORMAT

If JSON specified, output is returned in JSON format. If JSON is not specified, output is returned in a tabular format.

help | --help | -h

List options available for the command.