Managing IBM Cloud Logs 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

Configuring S2S authorization using the UI witihin the same account

Do the following to configure a service-to-service authorization using the IBM Cloud UI.

1. Log in to your IBM Cloud account as the account owner that will be configuring IBM Cloud Activity Tracker Event Routing targets.

   After you log in with your user ID and password, the IBM Cloud dashboard opens.

2. Click Manage > Access (IAM). Manage access and users is displayed.

3. Click Authorizations.

4. Click Create.

5. For Source service select Activity Tracker and for How do you want to scope the access? select All resources.

6. For Target service select IBM Cloud Logs for How do you want to scope the access? select Resources based on selected attributes.

7. Select Service instance and string equals the name of your IBM Cloud Logs instance.

8. For Service access select Sender.

9. Click Authorize. Your new service-to-service authorization will be listed in the Manage authorizations view.

Configuring S2S authorization using the CLI

Do the following to configure a service-to-service authorization using the IBM Cloud CLI.

1. [Log in to your IBM Cloud account] (/docs/cli?topic=cli-ibmcloud_cli#ibmcloud_login) as the account owner that will be configuring IBM Cloud Activity Tracker Event Routing authorization.

2. Create an authorization policy defining your service-to-service authorization.

   ibmcloud iam authorization-policy-create atracker cloud-logs "Sender" [--target-service-instance-id <CLOUD_LOGS_SERVICE_INSTANCE>
   

Configuring S2S authorization using the API

Do the following to configure a service-to-service authorization using the IBM Cloud API.

1. Log in to your IBM Cloud account as the account owner that will be configuring IBM Cloud Activity Tracker Event Routing IAM authorization.

2. Create an authorization_policy_resource.json file defining your service-to-service authorization.

   {
       "type": "authorization",
       "subjects": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "atracker"
                   }
               ]
           }
       ],
       "roles": [
           {
               "role_id": "crn:v1:bluemix:public:iam::::serviceRole:Sender"
           }
       ],
       "resources": [
           {
               "attributes": [
                 {
                      "name": "accountId",
                      "value": "CUSTOMER_ACCOUNT_ID"
                  },
                  {
                       "name": "serviceName",
                       "value": "cloud-logs"
                   },
                   {
                       "name": "serviceInstance",
                       "value": "CLOUD_LOGS_SERVICE_INSTANCE"
                   }
               ]
           }
       ]
   }
   

   Where:

   CUSTOMER_ACCOUNT_ID is the account GUID for the account that will be configuring targets. This can be found by using the ibmcloud account list command.

   CLOUD_LOGS_SERVICE_INSTANCE is the instance ID of the IBM Cloud Logs instance.

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

4. Run the following command to configure your service-to-service authorization:

   curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header "Authorization: $ACCESS_TOKEN" -d @authorization_policy_resource.json "https://iam.cloud.ibm.com/v1/policies"
   

Creating a IBM Cloud Logs target using the CLI

Use this command to create a IBM Cloud Logs target to be used to configure a destination for activity events.

 ibmcloud atracker target create --name TARGET_NAME --type TARGET_TYPE ( [--file CLOUD_LOGS_ENDPOINT_DEFINITION_JSON_FILE] |  ( [--target-crn CLOUD_LOGS_TARGET_CRN] [--region REGION] [--output FORMAT]

OK
Target
Name:                    my-target
ID:                      000000000-00000000-0000-0000-00000000
CRN:                     crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                  us-south
Type:                    cloud_logs
Cloud Logs Target CRN:   crn:v1:staging:public:logs:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
Write Status:            success
CreatedAt:               2024-05-31T19:03:35.427Z
UpdatedAt:               2024-05-31T19:03:35.427Z

Updating a IBM Cloud Logs target using the CLI

Use this command to update a IBM Cloud Logs target for an IBM Cloud Activity Tracker Event Routing region. Any specified value that is different from when the target was originally created will be updated to the value specified in the command.

ibmcloud atracker target update --target TARGET [--name TARGET_NAME] [ [--file CLOUD_LOGS_ENDPOINT_DEFINITION_JSON_FILE] |  [--target-crn CLOUD_LOGS_TARGET_CRN]]] [--output FORMAT]

OK
Target
Name:                    new-target-name
ID:                      000000000-00000000-0000-0000-00000000
CRN:                     crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Region:                  us-south
Type:                    cloud_logs
Cloud Logs Target CRN:   crn:v1:staging:public:logs:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
Write Status:            success
Created:                 2024-05-31T19:03:35.427Z
Updated:                 2024-05-31T19:03:35.427Z

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]

Target
Name:                       new-target-name
ID:                         xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:                        crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:                       cloud_logs
Cloud Logs Target CRN:      crn:v1:staging:public:logs:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
Service to Service Enabled:	true
Write Status:               success
Created:                    2021-07-21T16:04:15.174Z
Updated:                    2021-07-21T17:49:56.452Z

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]

Target
Name:                       new-target-name
ID:                         xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CRN:                        crn:v1:staging:public:atracker:us-south:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
Type:                       cloud_logs
Cloud Logs Target CRN:      crn:v1:staging:public:logs:global:a/xxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:
Service to Service Enabled: true
Write Status:               success
Created:                    2024-06-02T16:04:15.174Z
Updated:                    2024-06-05T17:49:56.452Z

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
target-01                  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   us-south   cloud_logs          2020-11-18T03:52:08.603Z

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 a IBM Cloud Logs target using the API

You can use the following cURL command to create a IBM Cloud Logs target:

curl -X POST  <ENDPOINT>/api/v2/targets   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "cloud_logs",
    "cloudlogs_endpoint": {
      "target_crn": "CLOUD_LOGS_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.

• TARGET_TYPE is the type of the target.

• cloudlogs_endpoint includes information about the target.

  CLOUD_LOGS_CRN indicates the CRN of the IBM Cloud Logs 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": "My CLOUD LOGS target",
    "target_type": "cloud_logs",
    "cloudlogs_endpoint": {
      "target_crn": "crn:v1:bluemix:public:logs:us-south:a/<account-id>:<instance-id>::"
    }
  }'

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 IBM Cloud Logs target using the API

When you update an IBM Cloud Logs 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 cannot change the target_type of a target once created.

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

curl -X PUT  <ENDPOINT>/api/v2/targets/TARGET_ID  -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "TARGET_NAME",
    "target_type": "cloud_logs",
    "cloudlogs_endpoint": {
      "target_crn": "CLOUD_LOGS_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.

• TARGET_TYPE is the type of the target. Set the value to cloud_logs for a IBM Cloud Logs target.

• cloudlogs_endpoint includes information about the target.

  CLOUD_LOGS_CRN indicates the CRN of the IBM Cloud Logs 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/TARGET_ID   -H "Authorization:  $ACCESS_TOKEN"   -H "content-type: application/json"   -d '{
    "name": "My new CLOUD LOGS target name",
    "target_type": "cloud_logs",
    "cloudlogs_endpoint": {
      "target_crn": "crn:v1:bluemix:public:logs:us-south: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/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 use the following cURL request to delete a target in US-South with the ID 00000000-0000-0000-0000-000000000000:

curl -X DELETE 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"

In the response, you get an empty result if the deletion was successful:

{}

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 with the ID 00000000-0000-0000-0000-000000000000:

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

In the response, you get information in the section 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 COS ("target_type": "cloud_object_storage"), IBM Cloud Activity Tracker Event Routing hosted event search offering ("target_type": "logdna"), or IBM Cloud Logs offering ("target_type": "cloud_logs")

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"), IBM Cloud Activity Tracker Event Routing hosted event search offering ("target_type": "logdna"), or IBM Cloud Logs offering ("target_type": "cloud_logs")

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 a IBM Cloud Logs 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 Cloud Logs.
8. Service authorization required: Service authorization is required to allow IBM Cloud Activity Tracker Event Routing to communicate with IBM Cloud Logs. Click Authorize now to create the policy automatically or click Grant access in IAM.
9. Choose destination: Pick Search by instance or Specify CRN
   • Search by instance: Select an IBM Cloud Logs instance from the table or click Create to create a new IBM Cloud Logs instance.

• Target name: Enter a meaningful name for the target.
• Target region: Select the region that will process the event data.
• 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.
• Click Create target.

Updating a IBM Cloud Logs 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 Logs instance 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

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 miscosfigured 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