Metrics Routing API Version 3 | IBM Cloud API Docs

Introduction

Last updated: 2023-06-05

You can configure IBM Cloud® Metrics Routing to manage metrics routing in your IBM Cloud account.

IBM Cloud Metrics Routing provides a REST API that you can use to define, retrieve, and modify targets and routes. For details about using IBM Cloud Metrics Routing, see the IBM Cloud documentation.

Endpoint URL

You can use private and public API endpoints to manage IBM Cloud Metrics Routing.

The IBM Cloud Metrics Routing API uses the following regional private endpoint URL.

https://private.<region>.metrics-router.cloud.ibm.com/api/v3

The IBM Cloud Metrics Routing API uses the following regional public endpoint URL.

https://<region>.metrics-router.cloud.ibm.com/api/v3

When you call the API, you must add the path for each method to form the complete API endpoint for your request.

Replace <region> with the prefix that represents the geographic area where you would like to enable the IBM Cloud Metrics Routing service. For more information, see Locations.

For more information about supported endpoints, see Endpoints.

Example API request

curl -X <request_method> "https://<region>.metrics-router.cloud.ibm.com/api/v3/<method_endpoint>"

Replace <request_method>, <region, and <method_endpoint> in this example with the values for your particular API call. Some API calls require an additional request payload. See the API Schema and examples for details.

The code examples on this tab use the IBM Cloud Metrics Routing SDK for Go.

Installation

go get -u github.com/IBM/platform-services-go-sdk/metricsrouterv3

GitHub

https://github.com/IBM/platform-services-go-sdk/metricsrouterv3

Authentication

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access with IAM.

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token.

You can build your API request by pairing a service endpoint with your authentication credentials. For example, if you plan to configure a routing target for the us-south region for your auditing events, use the following endpoint and API headers to list the targets in your service:

curl -X GET \
    "https://us-south.metrics-router.cloud.ibm.com/api/v3/targets" \
    -H "accept: application/json" \
    -H "Authorization: Bearer <access_token>" \

Replace <access_token> with your IBM Cloud IAM token.

You can retrieve an access token by first creating an API key, and then exchanging your API key for an IBM Cloud IAM token. For more information, see Retrieving an access token programmatically.

To find out more about setting up the IBM Cloud Metrics Routing API, see Getting started.

In this scenario, configuration is defined with an external credentials file and authenticator that is constructed by SDK's authenticator factory during client initialization. It avoids hardcoding credentials within application code.

The default name of the credentials file is metrics_router_v3.env . It is expected to be located in either the current directory or in the user's home directory. The path and name of the file can be controlled by using the IBM_CREDENTIALS_FILE environment variable.

The name of each configuration property contains the service name along with the actual attribute name in the form <service-name>_<attribute-name>.

It is not necessary to use a .env file, these properties can be set by using environment variables with the same name in the environment where the applications ran.

To retrieve your access token:

curl -X POST "https://iam.cloud.ibm.com/identity/token"   -H "Content-Type: application/x-www-form-urlencoded"   -H "Accept: application/json"   -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>" > token.json

Replace <API_KEY> with your service credentials. Then use the full access_token value, prefixed by the Bearer token type, to authenticate your API requests.

Variable guide for the authentication code samples

`{apikey}`	IAM API key
`{url}`	URL of Metrics Router API endpoint

SDK managing the IAM token. Replace {apikey} and {url}.

METRICS_ROUTER_URL={url}
METRICS_ROUTER_APIKEY={apikey}

import (
    "github.com/IBM/platform-services-go-sdk/metricsrouterv3"
)

metricsRouterServiceOptions := &metricsrouterv3.MetricsRouterV3Options{}

metricsRouterService, err = metricsrouterv3.NewMetricsRouterV3UsingExternalConfig(metricsRouterServiceOptions)

Programmatic authentication

In this scenario authentication that is configured by constructing an authenticator instance provides the configuration attributes programmatically and then passing this instance to a client instantiation.

SDK managing the IAM token.

import (
    "github.com/IBM/go-sdk-core/v5/core"
    "github.com/IBM/platform-services-go-sdk/metricsrouterv3"
)
authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
}
metricsrouterv3.NewMetricsRouterV3(
    &smetricsrouterv3.MetricsRouterV3Options{
        URL:           "{url}",
        Authenticator: authenticator,
    }
)

Auditing

You can monitor API activity within your account by using IBM Cloud Metrics Routing. For more information, see Getting started.

Whenever an API method is called, an auditing event is generated that you can then track and audit in your account. The specific event type is listed for each individual method.

Error handling

The IBM Cloud Metrics Routing service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Table 1. Status codes
Status code	Status	Description
200	OK	The request was successful.
201	OK	The request was successful. A resource is created.
400	Bad Request	The request was unsuccessful. This is often due to a missing required parameter.
401	Unauthorized	The IAM token taht is used in the API request is invalid or expired.
403	Forbidden	The operation is forbidden due to insufficient permissions.
404	Not Found	The requested resource doesn't exist or is already deleted.
409	Conflict	The request conflicts with the current state of customer resources in the system.
429	Too Many Requests	Too many requests hit the API too quickly.
500	Internal Server Error	Something went wrong when processing your request.

If an error response from the server endpoint the Go SDK creates an error object that contains either the HTTP response error message or a generic error message.

An extra detailedResponse is returned by the service that contains the following fields:

Go exception fields
Field	Description
StatusCode	HTTP response status code
Result	JSON error response object that is unmarshalled as `map[string]interface{}`
RawResult	raw non-JSON error response object as `[]byte`

Example error handling

_, detailedResponse, err := // Invoke a metrics-router-v3 method request
if err != nil {
    if (detailedResponse != nil) {
      fmt.Println("Error status code: ", detailedResponse.StatusCode)
      fmt.Println("Error message:     ", err.Error())
      errorMap, ok := detailedResponse.GetResultAsMap(); if ok {
        fmt.Println("Reason:          ", errorMap["reason"])
      }
    } else {
      // Handle other error conditions
      fmt.Println("Error message: ", err.Error())
    }
  }

Creates a target that includes information about the destination required to write platform metrics to that target. You can send your platform metrics from all regions to a single target, different targets or multiple targets. One target per region is not required. You can define up to 16 targets per account.

POST /targets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.target.create

Auditing

Calling this method generates the following auditing event.

metrics-router.target.create

Request

Request Body

Required*

TargetPrototype

The request payload to create a target.

Example request to create a metrics routing target

curl -X POST   https://<region>.metrics-router.cloud.ibm.com/api/v3/targets   -H "Authorization: Bearer <IAM_TOKEN>"   -H 'content-type: application/json'   -d '{
    "name": "a-sysdig-target-us-south",
    "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:22222222-2222-2222-2222-222222222222::"
  }'

Example request to create a metrics routing target

name := "a-sysdig-target-us-south"
destinationCRN := "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:22222222-2222-2222-2222-222222222222::"
createTargetOptions := metricsRouterService.NewCreateTargetOptions(name, destinationCRN)
target, response, err := metricsRouterService.CreateTarget(createTargetOptions)

if err != nil {
  fmt.Println("metrics-router: Create Target encountered an error - %s.\n", err.Error())
}

Response

Response Body

Target

Property values for a target in responses.

Status Code

201
The metrics routing target was successfully created.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 201

{
  "name": "a-sysdig-target-us-south",
  "id": "c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/4329073d16d2f3663f74bfa955259139::target:c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:22222222-2222-2222-2222-222222222222::",
  "target_type": "sysdig_monitor",
  "created_at": "2022-02-01T19:39:38.174Z",
  "updated_at": "2022-02-01T19:39:38.174Z"
}

List all targets that are defined for your account.

GET /targets

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.target.list

Auditing

Calling this method generates the following auditing event.

metrics-router.target.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request to list metrics routing targets

curl -X GET https://<region>.metrics-router.cloud.ibm.com/api/v3/targets -H "Authorization: Bearer <IAM_TOKEN>"

Example request to list metrics routing targets

listTargetsOptions := metricsRouterService.NewListTargetsOptions()
targets, response, err := metricsRouterService.ListTargets(listTargetsOptions)

if err != nil {
  fmt.Printf("metrics-router: List Targets encountered an error - %s.\n", err.Error())
}

Response

Response Body

TargetCollection

A list of target resources.

Status Code

200
A list of targets were successfully retrieved.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "targets": [
    {
      "name": "a-sysdig-target-us-south",
      "id": "c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
      "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/4329073d16d2f3663f74bfa955259139::target:c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
      "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:22222222-2222-2222-2222-222222222222::",
      "target_type": "sysdig_monitor",
      "created_at": "2022-02-01T19:39:38.174Z",
      "updated_at": "2022-02-01T19:39:38.174Z"
    }
  ]
}

Retrieve the configuration details of a target.

GET /targets/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.target.get

Auditing

Calling this method generates the following auditing event.

metrics-router.target.get

Request

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the target.

Possible values: 24 ≤ length ≤ 1028, Value must match regular expression ^[a-zA-Z0-9 \-]+$

Example request to get a metrics routing target

curl -X GET   https://<region>.metrics-router.cloud.ibm.com/api/v3/targets/<target_ID>   -H "Authorization: Bearer <IAM_TOKEN>"

Example request to get a metrics routing target

getTargetOptions := metricsRouterService.NewGetTargetOptions(targetID)
target, response, err := metricsRouterService.GetTarget(getTargetOptions)

if err != nil {
  fmt.Printf("metrics-router: Get Target encountered an error - %s.\n", err.Error())
}

Response

Response Body

Target

Property values for a target in responses.

Status Code

200
A target definition was successfully retrieved.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "name": "a-sysdig-target-us-south",
  "id": "c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/4329073d16d2f3663f74bfa955259139::target:c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:22222222-2222-2222-2222-222222222222::",
  "target_type": "sysdig_monitor",
  "created_at": "2022-02-01T19:39:38.174Z",
  "updated_at": "2022-02-01T19:39:38.174Z"
}

Update the configuration details of a target.

PATCH /targets/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.target.update

Auditing

Calling this method generates the following auditing event.

metrics-router.target.update

Request

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the target.

Possible values: 24 ≤ length ≤ 1028, Value must match regular expression ^[a-zA-Z0-9 \-]+$

Request Body

Required*

TargetPatch

The request payload to update a target.

Example request to modify a metrics routing target

curl -X PATCH   https://<region>.metrics-router.cloud.ibm.com/api/v3/targets/<target_ID>   -H "Authorization: Bearer <IAM_TOKEN>"   -H 'accept: application/json'   -d '{
    "name": "a-sysdig-target-modified",
    "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:33333333-3333-3333-3333-333333333333::"
  }'

Example request to modify a metrics routing target

targetID := "c3af557f-fb0e-4476-85c3-0889e7fe7bc4"
targetName := "a-sysdig-target-modified"
destinationCRN := "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:33333333-3333-3333-3333-333333333333::"
updateTargetOptions := &metricsrouterv3.UpdateTargetOptions{
  ID:             core.StringPtr(targetID),
  Name:           core.StringPtr(targetName),
  DestinationCRN: core.StringPtr(destinationCRN),
}
target, response, err := metricsRouterService.UpdateTarget(updateTargetOptions)

if err != nil {
  fmt.Printf("metrics-router: Update Target encountered an error - %s.\n", err.Error())
}

Response

Response Body

Target

Property values for a target in responses.

Status Code

200
The target was successfully updated.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "name": "a-sysdig-target-modified",
  "id": "c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/4329073d16d2f3663f74bfa955259139::target:c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:us-south:a/0be5ad401ae913d8ff665d92680664ed:33333333-3333-3333-3333-333333333333::",
  "target_type": "sysdig_monitor",
  "created_at": "2022-02-01T19:39:38.174Z",
  "updated_at": "2022-02-01T19:39:38.174Z"
}

Delete a target.

DELETE /targets/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.target.delete

Auditing

Calling this method generates the following auditing event.

metrics-router.target.delete

Request

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the target.

Possible values: 24 ≤ length ≤ 1028, Value must match regular expression ^[a-zA-Z0-9 \-]+$

Example request to delete a metrics routing target

curl -X DELETE   https://<region>.metrics-router.cloud.ibm.com/api/v3/targets/<target_ID>   -H "Authorization: Bearer <IAM_TOKEN>"

Example request to delete a metrics routing target

deleteTargetOptions := metricsRouterService.NewDeleteTargetOptions(targetID)
response, err := metricsRouterService.DeleteTarget(deleteTargetOptions)

if err != nil {
  fmt.Printf("metrics-router: Remove Target encountered an error - %s.\n", err.Error())
}

Response

Status Code

204
The target was successfully deleted.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Create a route with rules that specify how to manage platform metrics routing.

POST /routes

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.route.create

Auditing

Calling this method generates the following auditing event.

metrics-router.route.create

Request

Request Body

Required*

RoutePrototype

The request payload to create a route.

Example request to create a send metrics routing route

curl -X POST   https://<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": "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","messagehub"]
          }
        ]
      }
    ]
  }'

Example request to create a drop metrics routing route

curl -X POST   https://<region>.metrics-router.cloud.ibm.com/api/v3/routes   -H "Authorization: Bearer <IAM_TOKEN>"   -H 'content-type: application/json'   -d '{
    "name": "my-drop-route",
    "rules": [
      {
        "action": "drop",
        "targets": [],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["eu-de"]
          }
        ]
      }
    ]
  }'

Example request to create a send metrics routing route

targetIdentityModel := &metricsrouterv3.TargetIdentity{
    ID: core.StringPtr("50375218-7cff-4234-bbb4-171bebab8408"),
}

targetIdentityModel1 := &metricsrouterv3.TargetIdentity{
    ID: core.StringPtr("c7519d8a-5f97-498b-a229-8542f60955cd"),
}

inclusionFilterPrototypeModel := &metricsrouterv3.InclusionFilterPrototype{
  Operand:  core.StringPtr("location"),
  Operator: core.StringPtr("is"),
  Values:   []string{"us-south"},
}

inclusionFilterPrototypeModel1 := &metricsrouterv3.InclusionFilterPrototype{
  Operand:  core.StringPtr("service_name"),
  Operator: core.StringPtr("in"),
  Values:   []string{"codeengine","messagehub"},
}

rulePrototypeModel := &metricsrouterv3.RulePrototype{
  Action:           core.StringPtr("send"),
  Targets:          []metricsrouterv3.TargetIdentity{*targetIdentityModel, *targetIdentityModel1},
  InclusionFilters: []metricsrouterv3.InclusionFilterPrototype{*inclusionFilterPrototypeModel, *inclusionFilterPrototypeModel1},
}

createRouteOptions := metricsRouterService.NewCreateRouteOptions(
  "my-route",
  []metricsrouterv3.RulePrototype{*rulePrototypeModel},
)

route, response, err := metricsRouterService.CreateRoute(createRouteOptions)

if err != nil {
  fmt.Printf("metrics-router: Create Route encountered an error - %s.\n", err.Error())
}

Example request to create a drop metrics routing route

inclusionFilterPrototypeModel := &metricsrouterv3.InclusionFilterPrototype{
  Operand:  core.StringPtr("location"),
  Operator: core.StringPtr("is"),
  Values:   []string{"eu-de"},
}

rulePrototypeModel := &metricsrouterv3.RulePrototype{
  Action:           core.StringPtr("drop"),
  Targets:          []metricsrouterv3.TargetIdentity{},
  InclusionFilters: []metricsrouterv3.InclusionFilterPrototype{*inclusionFilterPrototypeModel},
}

createRouteOptions := metricsRouterService.NewCreateRouteOptions(
  "my-drop-route",
  []metricsrouterv3.RulePrototype{*rulePrototypeModel},
)

route, response, err := metricsRouterService.CreateRoute(createRouteOptions)

if err != nil {
  fmt.Printf("metrics-router: Create Route encountered an error - %s.\n", err.Error())
}

Response

Response Body

Route

The route resource. The scope of the route is account wide. That means all the routes are evaluated in all regions, except the ones limited by region.

Status Code

201
A route was successfully created.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 201

{
  "id": "ebd9d812-13da-461a-b772-33485e6046fe",
  "name": "my-route",
  "crn": "crn:v1:bluemix:public:metrics-router:global:a/08daa472aa7c4fd087506cca2a3e514e::route:ebd9d812-13da-461a-b772-33485e6046fe",
  "rules": [
    {
      "action": "send",
      "targets": [
        {
          "id": "50375218-7cff-4234-bbb4-171bebab8408",
          "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/08daa472aa7c4fd087506cca2a3e514e::target:50375218-7cff-4234-bbb4-171bebab8408",
          "name": "default-us-south-target",
          "target_type": "sysdig_monitor"
        },
        {
          "id": "c7519d8a-5f97-498b-a229-8542f60955cd",
          "crn": "crn:v1:bluemix:public:metrics-router:au-syd:a/08daa472aa7c4fd087506cca2a3e514e::target:c7519d8a-5f97-498b-a229-8542f60955cd",
          "name": "default-au-syd-south-target",
          "target_type": "sysdig_monitor"
        }
      ],
      "inclusion_filters": [
        {
          "operand": "location",
          "operator": "is",
          "values": [
            "us-east"
          ]
        },
        {
          "operand": "service_name",
          "operator": "in",
          "values": [
            "codeengine",
            "messagehub"
          ]
        }
      ]
    }
  ],
  "created_at": "2022-01-26T16:05:42.728Z",
  "updated_at": "2022-01-26T16:05:42.728Z"
}

List the routes that are configured for an account.

GET /routes

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.route.list

Auditing

Calling this method generates the following auditing event.

metrics-router.route.list

Request

No Request Parameters

This method does not accept any request parameters.

Example request to list metrics routing routes

curl -X GET https://<region>.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: Bearer <IAM_TOKEN>"

Example request to list metrics routing routes

listRoutesOptions := metricsRouterService.NewListRoutesOptions()
routes, response, err := metricsRouterService.ListRoutes(listRoutesOptions)

if err != nil {
  fmt.Printf("metrics-router: List Routes encountered an error - %s.\n", err.Error())
}

Response

Response Body

RouteCollection

A list of route resources.

Status Code

200
A list of routes were successfully retrieved.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "routes": [
    {
      "id": "ebd9d812-13da-461a-b772-33485e6046fe",
      "name": "my-route",
      "crn": "crn:v1:bluemix:public:metrics-router:global:a/08daa472aa7c4fd087506cca2a3e514e::route:ebd9d812-13da-461a-b772-33485e6046fe",
      "rules": [
        {
          "action": "send",
          "targets": [
            {
              "id": "50375218-7cff-4234-bbb4-171bebab8408",
              "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/08daa472aa7c4fd087506cca2a3e514e::target:50375218-7cff-4234-bbb4-171bebab8408",
              "name": "default-us-south-target",
              "target_type": "sysdig_monitor"
            },
            {
              "id": "c7519d8a-5f97-498b-a229-8542f60955cd",
              "crn": "crn:v1:bluemix:public:metrics-router:au-syd:a/08daa472aa7c4fd087506cca2a3e514e::target:c7519d8a-5f97-498b-a229-8542f60955cd",
              "name": "default-au-syd-target",
              "target_type": "sysdig_monitor"
            }
          ],
          "inclusion_filters": [
            {
              "operand": "location",
              "operator": "is",
              "values": [
                "us-east"
              ]
            },
            {
              "operand": "service_name",
              "operator": "in",
              "values": [
                "codeengine",
                "messagehub"
              ]
            }
          ]
        }
      ],
      "created_at": "2022-01-26T16:05:42.728Z",
      "updated_at": "2022-01-26T16:05:42.728Z"
    }
  ]
}

Get the configuration details of a route.

GET /routes/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.route.get

Auditing

Calling this method generates the following auditing event.

metrics-router.route.get

Request

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the route.

Possible values: 24 ≤ length ≤ 1028, Value must match regular expression ^[a-zA-Z0-9 \-]+$

Example request to get a metrics routing route

curl -X GET   https://<region>.metrics-router.cloud.ibm.com/api/v3/routes/<route_ID>   -H "Authorization: Bearer <IAM_TOKEN>"

Example request to get a metrics routing route

getRouteOptions := metricsRouterService.NewGetRouteOptions(routeID)
route, response, err := metricsRouterService.GetRoute(getRouteOptions)

if err != nil {
  fmt.Printf("metrics-router: Get Route encountered an error - %s.\n", err.Error())
}

Response

Response Body

Route

The route resource. The scope of the route is account wide. That means all the routes are evaluated in all regions, except the ones limited by region.

Status Code

200
A route definition was successfully retrieved.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "id": "ebd9d812-13da-461a-b772-33485e6046fe",
  "name": "my-route",
  "crn": "crn:v1:bluemix:public:metrics-router:global:a/08daa472aa7c4fd087506cca2a3e514e::route:ebd9d812-13da-461a-b772-33485e6046fe",
  "rules": [
    {
      "action": "send",
      "targets": [
        {
          "id": "50375218-7cff-4234-bbb4-171bebab8408",
          "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/08daa472aa7c4fd087506cca2a3e514e::target:50375218-7cff-4234-bbb4-171bebab8408",
          "name": "default-us-south-target",
          "target_type": "sysdig_monitor"
        },
        {
          "id": "c7519d8a-5f97-498b-a229-8542f60955cd",
          "crn": "crn:v1:bluemix:public:metrics-router:au-syd:a/08daa472aa7c4fd087506cca2a3e514e::target:c7519d8a-5f97-498b-a229-8542f60955cd",
          "name": "default-au-syd-target",
          "target_type": "sysdig_monitor"
        }
      ],
      "inclusion_filters": [
        {
          "operand": "location",
          "operator": "is",
          "values": [
            "us-east"
          ]
        },
        {
          "operand": "service_name",
          "operator": "in",
          "values": [
            "codeengine",
            "messagehub"
          ]
        }
      ]
    }
  ],
  "created_at": "2022-01-26T16:05:42.728Z",
  "updated_at": "2022-01-26T16:05:42.728Z"
}

Update the configuration details of a route.

PATCH /routes/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.route.update

Auditing

Calling this method generates the following auditing event.

metrics-router.route.update

Request

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the route.

Possible values: 24 ≤ length ≤ 1028, Value must match regular expression ^[a-zA-Z0-9 \-]+$

Request Body

Required*

RoutePatch

The request payload to update a route.

Example request to modify a metrics routing route to send metrics

curl -X PATCH   https://<region>.metrics-router.cloud.ibm.com/api/v3/routes/<route_ID>   -H "Authorization: Bearer <IAM_TOKEN>"   -H 'accept: application/json'   -d '{
    "name": "my-route-01-modified",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "d3ebcda8-953d-45ea-a4a7-b47f8c4a9742"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["eu-de"]
          }
        ]
      }
    ]
  }'

Example request to modify a metrics routing route to drop metrics

curl -X PATCH   https://<region>.metrics-router.cloud.ibm.com/api/v3/routes/<route_ID>   -H "Authorization: Bearer <IAM_TOKEN>"   -H 'accept: application/json'   -d '{
    "name": "my-drop-route",
    "rules": [
      {
        "action": "drop",
        "targets": [],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["eu-de"]
          }
        ]
      }
    ]
  }'

Example request to modify a metrics routing route to send metrics

targetIdentityModel := &metricsrouterv3.TargetIdentity{
    ID: core.StringPtr("c3af557f-fb0e-4476-85c3-0889e7fe7bc4"),
}

inclusionFilterPrototypeModel := &metricsrouterv3.InclusionFilterPrototype{
  Operand:  core.StringPtr("location"),
  Operator: core.StringPtr("is"),
  Values:   []string{"eu-de"},
}

rulePrototypeModel := &metricsrouterv3.RulePrototype{
  Action:           core.StringPtr("send"),
  Targets:          []metricsrouterv3.TargetIdentity{*targetIdentityModel},
  InclusionFilters: []metricsrouterv3.InclusionFilterPrototype{*inclusionFilterPrototypeModel},
}

updateRouteOptions := &metricsrouterv3.UpdateRouteOptions{
  ID:    core.StringPtr("ebd9d812-13da-461a-b772-33485e6046fe"),
  Name:  core.StringPtr("my-route"),
  Rules: []metricsrouterv3.RulePrototype{*rulePrototypeModel},
}

route, response, err := metricsRouterService.UpdateRoute(updateRouteOptions)

if err != nil {
  fmt.Printf("metrics-router: Update Route encountered an error - %s.\n", err.Error())
}

Example request to modify a metrics routing route to drop metrics

inclusionFilterPrototypeModel := &metricsrouterv3.InclusionFilterPrototype{
  Operand:  core.StringPtr("location"),
  Operator: core.StringPtr("is"),
  Values:   []string{"eu-de"},
}

rulePrototypeModel := &metricsrouterv3.RulePrototype{
  Action:           core.StringPtr("drop"),
  Targets:          []metricsrouterv3.TargetIdentity{},
  InclusionFilters: []metricsrouterv3.InclusionFilterPrototype{*inclusionFilterPrototypeModel},
}

updateRouteOptions := &metricsrouterv3.UpdateRouteOptions{
  ID:    core.StringPtr("ebd9d812-13da-461a-b772-33485e6046fe"),
  Name:  core.StringPtr("my-route"),
  Rules: []metricsrouterv3.RulePrototype{*rulePrototypeModel},
}

route, response, err := metricsRouterService.UpdateRoute(updateRouteOptions)

if err != nil {
  fmt.Printf("metrics-router: Update Route encountered an error - %s.\n", err.Error())
}

Response

Response Body

Route

The route resource. The scope of the route is account wide. That means all the routes are evaluated in all regions, except the ones limited by region.

Status Code

200
The route was successfully updated.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "id": "c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "name": "my-route-01-modified",
  "crn": "crn:v1:bluemix:public:metrics-router:global:a/4329073d16d2f3663f74bfa955259139::route:c3af557f-fb0e-4476-85c3-0889e7fe7bc4",
  "rules": [
    {
      "action": "send",
      "targets": [
        {
          "id": "d3ebcda8-953d-45ea-a4a7-b47f8c4a9742",
          "crn": "crn:v1:bluemix:public:metrics-router:eu-de:a/08daa472aa7c4fd087506cca2a3e514e::target:d3ebcda8-953d-45ea-a4a7-b47f8c4a9742",
          "name": "default-eu-de-target",
          "target_type": "sysdig_monitor"
        }
      ],
      "inclusion_filters": [
        {
          "operand": "location",
          "operator": "is",
          "values": [
            "eu-de"
          ]
        }
      ]
    }
  ],
  "created_at": "2022-01-26T17:18:02.487Z",
  "updated_at": "2022-01-26T17:59:29.763Z"
}

Deletes a route.

DELETE /routes/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.route.delete

Auditing

Calling this method generates the following auditing event.

metrics-router.route.delete

Request

Path Parameters

id
Required*
string
The v4 UUID that uniquely identifies the route.

Possible values: 24 ≤ length ≤ 1028, Value must match regular expression ^[a-zA-Z0-9 \-]+$

Example request

curl -X DELETE   https://<region>.metrics-router.cloud.ibm.com/api/v3/routes/<route_ID>   -H "Authorization: Bearer <IAM_TOKEN>"

Example request

deleteRouteOptions := metricsRouterService.NewDeleteRouteOptions(routeID)
response, err := metricsRouterService.DeleteRoute(deleteRouteOptions)

if err != nil {
  fmt.Printf("metrics-router: Delete Route encountered an error - %s.\n", err.Error())
}

Response

Status Code

204
The route was successfully deleted.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get information about the current account level settings for Metrics Routing service.

GET /settings

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.setting.get

Auditing

Calling this method generates the following auditing event.

metrics-router.setting.get

Request

No Request Parameters

This method does not accept any request parameters.

Example request to get metrics routing setting

curl -X GET https://<region>.metrics-router.cloud.ibm.com/api/v3/settings -H "Authorization: Bearer <IAM_TOKEN>"

Example request to get metrics routing setting

getSettingsOptions := metricsRouterService.NewGetSettingsOptions()
settings, response, err := metricsRouterService.GetSettings(getSettingsOptions)

if err != nil {
  fmt.Printf("metrics-router: Get Settings encountered an error - %s.\n", err.Error())
}

Response

Response Body

Setting

Metrics routing settings response.

Status Code

200
Metrics Routing service settings was successfully retrieved.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "default_targets": [
    {
      "id": "50375218-7cff-4234-bbb4-171bebab8408",
      "crn": "crn:v1:bluemix:public:metrics-router:us-south:a/08daa472aa7c4fd087506cca2a3e514e::target:50375218-7cff-4234-bbb4-171bebab8408",
      "name": "default-us-south-target",
      "target_type": "sysdig_monitor"
    },
    {
      "id": "c7519d8a-5f97-498b-a229-8542f60955cd",
      "crn": "crn:v1:bluemix:public:metrics-router:au-syd:a/08daa472aa7c4fd087506cca2a3e514e::target:c7519d8a-5f97-498b-a229-8542f60955cd",
      "name": "default-au-syd-south-target",
      "target_type": "sysdig_monitor"
    }
  ],
  "permitted_target_regions": [
    "us-south",
    "us-east"
  ],
  "primary_metadata_region": "us-south",
  "backup_metadata_region": "us-east",
  "private_api_endpoint_only": false
}

Modify the current account level settings such as default targets, permitted target regions, metadata region primary and secondary.

PATCH /settings

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

metrics-router.setting.set

Auditing

Calling this method generates the following auditing event.

metrics-router.setting.set

Request

Request Body

Required*

SettingPatch

Metrics routing settings request

Example request to update metrics routing setting

curl -X PATCH   https://<region>.metrics-router.cloud.ibm.com/api/v3/settings   -H "Authorization: Bearer <IAM_TOKEN>"   -H 'accept: application/json'   -d '{
    "default_targets": [
      {
        "id": "d3ebcda8-953d-45ea-a4a7-b47f8c4a9742"
      }
    ],
    "permitted_target_regions": ["us-south", "us-east"],
    "primary_metadata_region": "us-south",
    "backup_metadata_region": "us-east",
    "private_api_endpoint_only": false
  }'

Example request to update metrics routing setting

targetIdentityModel := &metricsrouterv3.TargetIdentity{
  ID: core.StringPtr("d3ebcda8-953d-45ea-a4a7-b47f8c4a9742"),
}

updateSettingsOptions := &metricsrouterv3.UpdateSettingsOptions{
  DefaultTargets:         []metricsrouterv3.TargetIdentity{*targetIdentityModel},
  PermittedTargetRegions: []string{"us-south", "us-east"},
  PrimaryMetadataRegion:  core.StringPtr("us-south"),
  BackupMetadataRegion:   core.StringPtr("us-east"),
  PrivateAPIEndpointOnly: core.BoolPtr(false),
}

setting, response, err := metricsRouterService.UpdateSettings(updateSettingsOptions)

if err != nil {
  fmt.Printf("metrics-router: Update Settings encountered an error - %s.\n", err.Error())
}

Response

Response Body

Setting

Metrics routing settings response.

Status Code

200
The settings was successfully modified.
400
The request could not be understood due to malformed syntax.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
409
There is a conflict with the request data and the state of resources in system. Please check error message for details.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "default_targets": [
    {
      "id": "d3ebcda8-953d-45ea-a4a7-b47f8c4a9742",
      "crn": "crn:v1:bluemix:public:metrics-router:eu-de:a/08daa472aa7c4fd087506cca2a3e514e::target:d3ebcda8-953d-45ea-a4a7-b47f8c4a9742",
      "name": "default-eu-de-target",
      "target_type": "sysdig_monitor"
    }
  ],
  "permitted_target_regions": [
    "us-south",
    "us-east"
  ],
  "primary_metadata_region": "us-south",
  "backup_metadata_region": "us-east",
  "private_api_endpoint_only": false
}

Introduction

Endpoint URL

Authentication

Programmatic authentication

Auditing

Error handling

Methods

Create a target

Authorization

Auditing

Request

Request Body

name

destination_crn

region

Response

Response Body

id

name

crn

destination_crn

target_type

created_at

updated_at

region

Status Code

201

400

401

403

409

429

500

List targets

Authorization

Auditing

Request

No Request Parameters

Response

Response Body

targets

Status Code

200

400

401

403

409

429

500

Get details of a target

Authorization

Auditing

Request

Path Parameters

id

Response

Response Body

id

name

crn

destination_crn

target_type

created_at

updated_at

region

Status Code

200

400

401

403

404

409

429

500

Update a target

Authorization

Auditing

Request

Path Parameters

id