IBM Cloud Docs
Managing Monitoring targets

Managing Monitoring targets

You can manage Monitoring targets in your account by using the IBM Cloud Metrics Routing UI, the IBM Cloud Metrics Routing CLI, the IBM Cloud Metrics Routing REST API, and the IBM Cloud Metrics Routing Terraform provider. A target is a resource where you can collect metrics.

For more information on IBM Cloud Metrics Routing targets, see Targets.

About Monitoring targets

You can configure IBM Cloud Metrics Routing to route metrics that are generated in different regions where the service is supported to a Monitoring target.

  • You can only route metrics that are generated in regions where IBM Cloud Metrics Routing is available. For more information, see Regions.

  • If you have regulatory and compliance requirements, check the Monitoring target is available in a valid location.

  • 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. You can define a service to service authorization between the IBM Cloud Metrics Routing service and an instance of the Monitoring service in the same account, or between the IBM Cloud Metrics Routing service and an instance of the Monitoring service in a different account.

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

IAM Access

You must have the correct IAM permissions to manage targets. For information, see Managing IAM access.

Creating a target using the UI

Do the following to create a target using the UI.

Only resources in your account are listed and selectable. To specify a resource in a different account, select Specify CRN under Choose destination.

  1. Log in to your IBM Cloud account.

  2. Click the Menu icon Menu icon > Observability.

  3. Click Monitoring.

  4. Click Routing.

  5. Click the Targets tab.

  6. Click Create to open the create panel.

  7. Service authorization required: Service authorization is required to allow IBM Cloud Metrics Routing to communicate with IBM Cloud Monitoring. Click Authorize now to create the policy automatically or click Grant access in IAM.

  8. Choose destination: Pick Search by instance or Specify CRN

    • Search by instance: Select an IBM Cloud Monitoring instance from the table or click Create to create a new IBM Cloud Monitoring instance.
    • Specify CRN: Enter the Cloud Resource Name (CRN) of the IBM Cloud Monitoring instance. This enables you to enter a CRN from a different account.
  9. Specify the target details.

    • Target name: Enter a meaningful name for the target.

    • Target region: Select the target region.

  • Toggle Set as default target to automatically set your new target as a default target in your IBM Cloud Metrics Routing settings. See the default targets documentation for more details.
  1. Click Create target.

Updating a target using the UI

Do the following to update a target using the UI.

Only resources in your account are listed and selectable. To specify a resource in a different account, select Specify CRN under Choose destination.

  1. Log in to your IBM Cloud account.

  2. Click the Menu icon Menu icon > Observability.

  3. Click Monitoring.

  4. Click Routing.

  5. Click the Targets tab.

  6. Determine which target to update and click the Actions icon.

  7. Click Unset as default to remove your target as a default target in your IBM Cloud Metrics Routing settings. See the default targets documentation for more details.

  8. Click Edit to open the update panel.

  9. Details: Click Edit to update your target's name. You can also toggle Default target to add or remove your target as a default target in your IBM Cloud Metrics Routing settings.

    You can also view the routes associated with the target.

  10. Click Save to update your target.

  11. Destination: Click Edit to change the IBM Cloud Monitoring instance associated with your target.

  12. Click Save to update your target.

Deleting a target using the UI

Do the following to delete a target using the UI.

You cannot delete an IBM Cloud Metrics Routing target if it is used in a route or as a default target setting.

  1. Log in to your IBM Cloud account.

  2. Click the Menu icon Menu icon > Observability.

  3. Click Monitoring.

  4. Click Routing.

  5. Click the Targets tab.

  6. Determine which target to update and click the Actions icon.

  7. Click Delete and then click Delete in the confirmation panel.

Listing all targets using the UI

Do the following to list all the targets using the UI.

  1. Log in to your IBM Cloud account.

  2. Click the Menu icon Menu icon > Observability.

  3. Click Monitoring.

  4. Click Routing.

  5. Click the Targets tab.

The table shows:

  • Target type

  • Destination name

  • Destination region

  • Routes: The number of routes if the target is used in any defined route.

CLI prerequisites

Before you use the CLI to manage targets, 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

  4. 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.

Creating a Monitoring target by using the CLI

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

Target names are unique in the account.

ibmcloud metrics-router target create --name TARGET_NAME --destination-crn CRN_VALUE [--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 logged into, or targeted, will be 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 CRN_VALUE

The CRN of the Monitoring instance.

--output FORMAT

Currently supported format is JSON. If specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

help | --help | -h

List options available for the command.

Example

The following is an example using the ibmcloud metrics-router target create --name my-target --destination-crn crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:: command.

This example shows an example successful target creation.

Target
Name:               		my-target
ID:                 		000000000-00000000-0000-0000-00000000
REGION:                         us-east
Type:               		sysdig_monitor
Destination CRN:     		crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
CreatedAt:            		2021-07-21T16:04:15.174Z
UpdatedAt:            		2021-07-21T16:04:15.174Z

Updating a Monitoring target using the CLI

Use this command to update a Monitoring target. You can modify the name of a target and the destination CRN. Any specified value that is different from when the target was originally created will be updated to the value specified in the command.

Target names are unique in the account.

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

Command options

--target TARGET

The ID or current target name.

--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 Monitoring instance.

--output FORMAT

Currently supported format is JSON. If specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

help | --help | -h

List options available for the command.

Example

The following is an example using the ibmcloud metrics-router target update --target my-target --name my-new-target-name command.

Target
Name:               		my-new-target-name
ID:                 		000000000-00000000-0000-0000-00000000
REGION:                         us-east
CRN:                		crn:v1:bluemix:public:metrics-router:us-south:a/xxxxxxxxxx:000000000-00000000-0000-0000-00000000
Type:               		sysdig_monitor
Destination CRN:     		crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
CreatedAt:            		2021-07-21T16:04:15.174Z
UpdatedAt:            		2021-07-21T16:04:15.174Z

Deleting a target using the CLI

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
Will delete the target without providing the user with any additional prompt.
help | --help | -h
List options available for the command.

Example

The following is an example using the ibmcloud metrics-router target rm --target xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx command.

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

Getting information about a target using the CLI

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

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

Command options

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

Example

The following is an example using the ibmcloud metrics-router target get --target new-target-name command showing a Monitoring target.

Name:               		my-target
ID:                 		000000000-00000000-0000-0000-00000000
REGION:                         us-east
CRN:                		crn:v1:bluemix:public:metrics-router:us-south:a/xxxxxxxxxx:000000000-00000000-0000-0000-00000000
Type:               		sysdig_monitor
Destination CRN:     		crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::
CreatedAt:            		2021-07-21T16:04:15.174Z
UpdatedAt:            		2021-07-21T16:04:15.174Z

Listing all targets in a region

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

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

Command options

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

Example

The following is an example using the ibmcloud metrics-router target ls command.

Name                       ID                                     Region     Type              	CreatedAt                   UpdatedAt
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south    sysdig_monitor    2020-11-18T03:52:08.603Z    2020-11-19T03:52:08.603Z
target-02                  yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy   us-south    sysdig_monitor    2020-11-18T03:52:01.592Z    2020-11-19T03:52:08.603Z
target-02-backup           zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz   us-east     sysdig_monitor    2021-02-26T06:53:13.466Z    2020-11-19T03:52:08.603Z

API targets and actions

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

Target actions by using the IBM Cloud Metrics Routing REST API
Action REST API Method API_URL
Create a target POST <ENDPOINT>/api/v3/targets
Update a target PATCH <ENDPOINT>/api/v3/targets/<TARGET_ID>
Delete a target DELETE <ENDPOINT>/api/v3/targets/<TARGET_ID>
Read a target GET <ENDPOINT>/api/v3/targets/<TARGET_ID>
List all targets GET <ENDPOINT>/api/v3/targets

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

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

  • You can manage targets 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 target and region settings.

For more information about the REST API, see Targets.

API prerequisites

To make API calls to manage targets, 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 target. For more information, see Endpoints.
  3. 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 modify settings API method.

Creating a Monitoring target using the API

You can use the following cURL command to create a Monitoring target:

Target names are unique in the account.

curl -X POST <ENDPOINT>/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "TARGET_NAME",
    "destination_crn": "CRN"
  }'

Where

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

  • TARGET_NAME is the name of the target. The maximum length of the name is 256 characters.

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

  • CRN indicates the CRN of the Monitoring instance.

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

curl -X POST https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My-target",
    "target_type": "crn:v1:bluemix:public:sysdig-monitor:au-syd:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx::"
  }'

In the response, you get information about the target such as the id, that indicates the GUID of the target, and the crn, that indicates the CRN of the target.

Updating a Monitoring target using the API

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

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

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

Target names are unique in the account.

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

curl -X PATCH <ENDPOINT>/api/v3/targets/TARGET_ID -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "TARGET_NAME",
    "destination_crn": "CRN"
  }'

Where

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

  • TARGET_ID is the ID of the target.

  • TARGET_NAME is the name of the target. The maximum length of the name is 256 characters.

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

  • CRN indicates the CRN of the Monitoring instance.

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

curl -X PATCH https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My target",
    "destination_crn": "crn:v1:bluemix:public:sysdig-monitor:au-syd:a/<account-id>:<instance-id>::"
    }
  }'

Deleting a target using the API

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

curl -X DELETE <ENDPOINT>/api/v3/targets/<TARGET_ID> -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 target. For more information, see Endpoints.
  • <TARGET_ID> is the ID of the target.

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

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

Viewing a target using the API

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

curl -X GET <ENDPOINT>/api/v3/targets/<TARGET_ID> -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 target. For more information, see Endpoints.
  • <TARGET_ID> is the ID of the target.

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

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

Listing all targets using the API

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

curl -X GET <ENDPOINT>/api/v3/targets -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 target. For more information, see Endpoints.

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

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/targets -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:

List of HTTP response 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. You might be missing a parameter that is required.
401 Unauthorized The IAM token that 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.
429 Too Many Requests Too many requests hit the API too quickly.
500 Internal Server Error Something went wrong in IBM Cloud Metrics Routing processing.