Managing IBM Cloud Activity Tracker hosted event search targets

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 Activity Tracker Event Routing CLI.

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

Creating an IBM Cloud Activity Tracker hosted event search offering target using the CLI

Use this command to create an IBM Cloud Activity Tracker hosted event search offering target to be used to configure a destination for activity events.

ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file LOGDNA_ENDPOINT_DEFINITION_JSON_FILE] | ( [--target-crn LOGDNA_TARGET_CRN] [--ingestion-key LOGDNA_INGESTION_KEY] ) ) [--region REGION] [--output FORMAT]

OK
Target
Name:                eu-de-logdna-target
ID:                  cccccccc-cccc-cccc-cccc-cccccccccccc
CRN:                 crn:v1:bluemix:public:atracker:eu-de:a/11111111111111111111111111111111::target:cccccccc-cccc-cccc-cccc-cccccccccccc
Type:                logdna
LogDNA Target CRN:   crn:v1:bluemix:public:logdna:eu-de:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::
CreatedAt:           2022-05-06T18:59:26.760Z
UpdatedAt:           2022-05-06T18:59:26.760Z

Updating an IBM Cloud Activity Tracker hosted event search offering target using the CLI

Use this command to update an IBM Cloud Activity Tracker hosted event search offering target to be used to configure a destination for activity events.

ibmcloud atracker target update --target TARGET [--name TARGET_NAME] ( --file @LOGDNA_ENDPOINT_DEFINITION_JSON_FILE ) | (--target-crn LOGDNA_TARGET_CRN --ingestion-key LOGDNA_INGESTION_KEY )  [--region REGION] [--output FORMAT]

OK
Target
Name:                eu-de-logdna-target
ID:                  cccccccc-cccc-cccc-cccc-cccccccccccc
CRN:                 crn:v1:bluemix:public:atracker:eu-de:a/11111111111111111111111111111111::target:cccccccc-cccc-cccc-cccc-cccccccccccc
Type:                logdna
LogDNA Target CRN:   crn:v1:bluemix:public:logdna:eu-de:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::
CreatedAt:           2022-05-06T18:59:26.760Z
UpdatedAt:           2022-05-06T19:16:50.090Z

Deleting a target using the CLI

Use this command to delete a target.

ibmcloud atracker target rm --target TARGET [--force]

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.

Are you sure you want to remove the Target bearing Target ID 33333333-3333-3333-3333-333333333333? [y/N]> y
FAILED
Something went wrong. Error:
 Status Code:  404
 Incident ID:  67a33257-d5a4-46ec-94d9-14eb70e94f3d
 Code:         not_found
 Message:      The target id specified in `target_id` field is not found.

Validating a target using the CLI

Use this command to validate that a target is correctly configured for an IBM Cloud Activity Tracker Event Routing region.

ibmcloud atracker target validate --target TARGET [--region REGION] [--output FORMAT]

TBD

Getting information about a target using the CLI

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

ibmcloud atracker target get --target TARGET [--output FORMAT]

OK
Target
Name:                new-target-name
ID:                  cccccccc-cccc-cccc-cccc-cccccccccccc
CRN:                 crn:v1:bluemix:public:atracker:eu-de:a/11111111111111111111111111111111::target:cccccccc-cccc-cccc-cccc-cccccccccccc
Type:                logdna
LogDNA Target CRN:   crn:v1:bluemix:public:logdna:eu-de:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::
CreatedAt:           2022-05-06T18:59:26.760Z
UpdatedAt:           2022-05-06T19:16:50.090Z

Listing all targets in a region

Use this command to list the configured targets for an IBM Cloud Activity Tracker Event Routing region.

ibmcloud atracker target ls [--output FORMAT]

Name                       ID                                     Region     Type                     Created
test-eu-de-target           xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   eu-de   logdna     2022-02-26T06:53:13.466Z

API targets and actions

The following table lists the actions that you can run to manage 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.atracker.cloud.ibm.com

• You can manage targets from the public network using an API endpoint with the following format: https://REGION.atracker.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.

Creating an IBM Cloud Activity Tracker hosted event search offering target using the API

You can use the following cURL command to create an IBM Cloud Activity Tracker hosted event search offering target:

curl -X POST <ENDPOINT>/api/v2/targets
  -H "Authorization: Bearer IAM_TOKEN"
  -H 'content-type: application/json'
  -d '{
       "name": "TARGET_NAME",
       "target_type": "TARGET_TYPE",
       "logdna_endpoint": {
         "target_crn": "TARGET_CRN",
         "ingestion_key": "TARGET_KEY"
        }
      }

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.

• TARGET_TYPE is the type of the target. The valid type is logdna.

• logdna_endpoint includes information about the target. This includes the CRN of the IBM Cloud Activity Tracker hosted event search offering instance and the ingestion key of the instance.

  TARGET_CRN indicates the CRN of the IBM Cloud Activity Tracker Event Routing instance.

  TARGET_KEY is the ingestion key for the IBM Cloud Activity Tracker Event Routing instance.

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

curl -X POST https://private.us-south.atracker.cloud.ibm.com/api/v2/targets -H "Authorization:  $ACCESS_TOKEN" -H "content-type: application/json" -d '{
     "name": "a-target-us-south",
       "target_type": "logdna",
         "logdna_endpoint": {
           "target_crn": "crn:v1:staging:public:logdna:us-south:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::",
           "ingestion_key": "xxxxxxxxxxxxxxxxxx"
    }
  }'

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 an IBM Cloud Activity Tracker hosted event search offering target

When you update an IBM Cloud Activity Tracker hosted event search offering 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.

You can use the following cURL command to update an IBM Cloud Activity Tracker hosted event search offering target:

curl -X PUT <ENDPOINT>/api/v2/targets
  -H "Authorization: Bearer IAM_TOKEN"
  -H 'content-type: application/json'
  -d '{
       "name": "TARGET_NAME",
       "target_type": "TARGET_TYPE",
       "logdna_endpoint": {
         "target_crn": "TARGET_CRN",
         "ingestion_key": "TARGET_KEY"
        }
      }'

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.

• TARGET_TYPE is the type of the target. The valid type is logdna.

• logdna_endpoint includes information about the target. This includes the CRN of the IBM Cloud Activity Tracker hosted event search offering instance and the ingestion key of the instance.

  TARGET_CRN indicates the CRN of the IBM Cloud Activity Tracker Event Routing instance.

  TARGET_KEY is the ingestion key for the IBM Cloud Activity Tracker Event Routing instance.

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

curl -X PUT https://private.us-south.atracker.cloud.ibm.com/api/v2/targets -H "Authorization:  $ACCESS_TOKEN" -H "content-type: application/json" -d '{
     "name": "a-target-us-south",
       "target_type": "logdna",
         "logdna_endpoint": {
           "target_crn": "crn:v1:staging:public:logdna:us-south:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::",
           "ingestion_key": "xxxxxxxxxxxxxxxxxx"
    }
  }'

Deleting a target using the API

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

curl -X DELETE <ENDPOINT>/api/v2/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.

Validating a target using the API

You can use the following cURL command to validate a target by checking the credentials to write to the target.

curl -X POST <ENDPOINT>/api/v2/targets/TARGET_ID/validate -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 validate a target in US-South:

curl -X POST https://private.us-south.atracker.cloud.ibm.com/api/v2/targets/<TARGET_ID>/validate   -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

In the response, you get information in the section cos_write_status, for example:

"write_status": {
    "status": "success"
  },

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/v2/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.atracker.cloud.ibm.com/api/v2/targets/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Results will show if the target is a COS ("target_type": "cloud_object_storage") target or an IBM Cloud Activity Tracker hosted event search offering ("target_type": "logdna") target.

Listing all targets using the API

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

curl -X GET <ENDPOINT>/api/v2/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.atracker.cloud.ibm.com/api/v2/targets -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Results will show if the target is COS ("target_type": "cloud_object_storage") or an IBM Cloud Activity Tracker hosted event search offering ("target_type": "logdna").

HTTP response codes

When you use the IBM Cloud Activity Tracker Event 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:

Creating an IBM Cloud Activity Tracker hosted event search offering 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 > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.
6. Click Create to open the create panel.
7. Choose type: Click Activity Tracker.
8. Choose destination: Pick Search by instance or Specify CRN
   • Search by instance: Select an IBM Cloud Activity Tracker hosted event search instance from the table or click Create to create a new IBM Cloud Activity Tracker hosted event search instance.
   • Specify CRN: Enter the Cloud Resource Name (CRN) of the IBM Cloud Activity Tracker hosted event search instance. If you want to target an instance in a different account, you must specify the CRN.
9. Ingestion key: Select or enter the ingestion key for the targeted IBM Cloud Activity Tracker hosted event search instance.
10. Target name: Enter a meaningful name for the target.
11. Target region: Select the region that will process the event data.
12. Toggle Set as default target to automatically set your new target as a default target in your IBM Cloud Activity Tracker Event Routing settings. See the default targets documentation for more details.
13. Click Create target.

Updating an IBM Cloud Activity Tracker hosted event search offering 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 > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.
6. Determine which target to update and click the .
7. Click Unset as default to remove your target as a default target in your IBM Cloud Activity Tracker Event 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 or region. You can also toggle Default target to add or remove your target as a default target in your IBM Cloud Activity Tracker Event Routing settings.
10. Click Save to update your target.
11. Destination: Click Edit to change the IBM Cloud Activity Tracker hosted event search instance and ingestion key associated with your target.
12. Click Save to update your target.

Deleting a target using the UI

You cannot delete an IBM Cloud Activity Tracker Event 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 > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.
6. Determine which target to delete and click the .
7. Click Delete and then click Delete in the confirmation panel.

Listing all targets in a region using the UI

1. Log in to your IBM Cloud account.
2. Click the Menu icon > Observability.
3. Select Activity Tracker.
4. Select Routing.
5. Select Targets.

The table details:

• Target type
• Destination name
• Destination region
• Routes: If it is used in any routes
• Target status:
  • Active: The target is working as expected
  • Error: The target is misconfigured and events will not be routed to the destination. Update your target details or destination to fix the target configuration or delete the target if it is no longer needed