IBM Cloud Docs
About targets

About 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. The resource can be located in the same IBM Cloud account where metrics are generated or in a different account.

Understanding how targets work in your account

Note the following information about targets:

  • Targets are regional under an account and can be accessed from any regional IBM Cloud Metrics Routing API endpoint.

  • You can define a target in any of the supported locations where IBM Cloud Metrics Routing is available. For more information, see Locations.

  • You can configure up to 16 targets in each account.

  • You can configure up to two default targets for each IBM Cloud account.

    Default targets collect metrics from locations where you do not specify in the account where to route the metrics that are generated in that location.

  • Information about targets is stored as metadata in the primary and backup locations that you set for the IBM Cloud account. The information that is stored include details about the destinatiion resource and credentials to send metrics.

    The primary metadata location must be set prior to configuring a target.

    If you do not configure a primary metadata location, the location is set to the location where you define your first target in the account. For more information, see Configuring account settings.

  • 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 by using an API endpoint with the following format: https://private.REGION.metrics-router.cloud.ibm.com

    • You can manage targets from the public network by 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 Enforcing private endpoints.

  • The target name must be 1000 characters or less and cannot include any special characters other than space, dash -, dot ., underscore _, and colon :.

    The name must not include any personal identifying information (PII).

Target types

You can configure any of the following target types:

List of targets
Target Type Scope Description
IBM Cloud Monitoring sysdig-monitor Account Use this target to consolidate time series data to the region of your primary operations.

IAM Access

To manage targets, ensure you have the correct IAM permissions to configure IBM Cloud Metrics Routing.

To allow the IBM Cloud Metrics Routing service to send metrics to your Monitoring destinations, you must have a service to service authorization configured in the account where the target is located. For more information, see Managing authorizations to grant access between services.

IAM permissions

The following table lists the IAM actions, their scope and the roles required to manage routes.

IAM action scopes and roles for managing targets
Task IAM Action IAM Policy scope IAM Roles
Create a target metrics-router.target.create Region Administrator
Editor
List all targets metrics-router.target.list Account Administrator
Editor
Operator
Viewer
Get details of a target metrics-router.target.read Region Administrator
Editor
Operator
Viewer
Modify a target metrics-router.target.update Region Administrator
Editor
Delete a target metrics-router.target.delete Region Administrator
Editor

When you use the CLI, notice that you need the metrics-router.target.list role to create, read, update, or delete a target.

Auditing events

The following table lists the IAM actions, their scope and the roles required to manage routes.

Activity Tracker auditing event action
Task Activity Tracker auditing event action
Create a target metrics-router.target.create
List all targets metrics-router.target.list
Get details of a target metrics-router.target.read
Modify a target metrics-router.target.update
Delete a target metrics-router.target.delete

Managing targets using the UI

You can manage your target definition using the IBM Cloud Metrics Routing UI. For more information, see Managing targets.

CLI prerequisites

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

  1. Ensure you have the correct IAM permissions to configure IBM Cloud Metrics Routing.

  2. Install the IBM Cloud CLI.

  3. Install the IBM Cloud Metrics Routing CLI.

CLI commands

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

Target actions
Action Command
Create a target ibmcloud metrics-router target create
Update a target ibmcloud metrics-router target update
Delete a target ibmcloud metrics-router target rm
Read a target ibmcloud metrics-router target get
List all targets ibmcloud metrics-router target ls

For more information, see IBM Cloud Metrics Routing v3 CLI.

API prerequisites

Before you use the API to manage targets, complete the following steps:

  1. Ensure you have the correct IAM permissions to configure IBM Cloud Metrics Routing.

  2. Get an IAM access token. For more information, see Retrieving IAM access tokens.

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

API methods

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

For more information, see IBM Cloud Metrics Routing v3 API.

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 usually 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.
204 OK The target was successfully deleted.
400 Bad Request The request was unsuccessful. You might be missing a parameter that is required.
401 Unauthorized The authorization request fails.
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.