Introduction

The IBM® Cloud Logs Routing platform service collects application logs and delivers them to a customer-provided logging endpoint.

The IBM Cloud Logs Routing service is available as a regular offering. The only supported log sinks available are IBM Cloud Logs and IBM Log Analysis.

There is a go SDK available to access this service and a terraform provider to support automated setup.

The customer can create (onboard) a tenant for IBM Cloud Logs Routing using either a curl command and the management API described in this documentation, via the IBM Cloud Web Console or by automation using the terraform provider. To collect the logs from the customer's IBM Cloud Kubernetes Service, Red Hat OpenShift on IBM Cloud, IBM® Virtual Servers with Linux or VPC clusters, the log collecting agent must be installed in those environments.

This is a versioned API. To pin your application to a dedicated version add the http header IBM-API-Version with the date in the format YYYY-MM-DD. To use the latest version of the API specify the current day.

Endpoint URLs

The IBM Cloud Logs Routing Services API for tenant creation (onboarding) and tenant deletion (off-boarding) uses site-specific endpoint URLs to register or unregister with the service.

IBM Cloud Logs Routing supports classic infrastructure as well as the Virtual Private Cloud (VPC) endpoint gateway (VPE gateway).

Private management endpoint URL for the VPC infrastructure:

https://management.private.<region>.logs-router.cloud.ibm.com/v1

Management endpoint URL for the classic infrastructure:

https://management.private.<region>.logs-router.cloud.ibm.com:3443/v1

The ingestion endpoint used by the log collecting agent is for IBM-internal use only. It is listed here for reference only.

Private ingestion endpoint URL for VPC infrastructure:

ingester.private.<region>.logs-router.cloud.ibm.com:443/v1/logs/ws

Ingestion endpoint URL for classic infrastructure:

ingester.private.<region>.logs-router.cloud.ibm.com:3443/v1/logs/ws

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

Example API request

curl -X {request_method} \
    --header "Authorization: Bearer {bearer_token}" \
    --header "Accept: application/json"
    --header "X-Trace-ID: A58646E9-F4D5-4327-81B1-AE8D501F35E2"
    [--data "{request_body}"] \
    "https://management.private.us-south.logs-router.cloud.ibm.com/{method_endpoint}"

Replace {bearer_token}, {request_method}, {method_endpoint} and [optional] {request_body} in this example with the values for your particular API call.

Tracing

An optional header X-Trace-ID is used to trace the transactions performed by the User. Trace ID should be a valid UUID v4 format. The UUID should be unique and added to logs and appropriate database artifacts. The UUID can be used to follow the flow for debugging purposes.

Authentication

Authorization to the IBM Cloud Logs Routing service REST API is enforced by an IBM Cloud® Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Retrieving an access token is supported using an IAM Trusted Profile or IAM API key.

To request an access token with a Trusted Profile from within your IBM Cloud Kubernetes Service or Red Hat OpenShift cluster, run the following command:

curl -X POST \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data "grant_type=urn:ibm:params:oauth:grant-type:cr-token" \
    --data "profile_id={trusted_profile_id}" \
    --data-urlencode "cr_token@{path_to_token}" \
    https://iam.cloud.ibm.com/identity/token

Replace {trusted_profile_id} and {path_to_token} with the correct values for your environment.

To request an access token with an IAM api_key, run the following command:

curl -X POST \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
    --data "apikey=${IAM_API_KEY}" \
    "https://iam.cloud.ibm.com/identity/token"

Replace {IAM_API_KEY} with your IAM API key.

The access token is provided in the returned JSON data in the field .access_token.

Auditing

You can use the IBM Cloud Logs service to track and monitor how users, applications and services interact with the IBM Cloud Logs Routing service in IBM Cloud.

For more information about how to monitor activities, see Auditing events for IBM® Cloud Logs Routing.

Error handling

The IBM Cloud Logs Routing Service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates that a parameter validation failed and can occur if required parameters are missing or if any parameter values are invalid. A 401 or 403 response indicates that the incoming request did not contain valid authentication information. A 500 type response indicates an internal server error that is seen in an unexpected error situation.

The IBM Cloud Logs Routing REST APIs return standard HTTP status codes to indicate the success or failure of a request. The format of the response is represented in JSON as follows:

{
    "errors": [
    {
        "code": "not_authorized",
        "message": "The specified token does not have authority to create a tenant."
    }
    ],
    "status_code": 403
}

If an operation cannot be fulfilled, an appropriate 400 or 500 series HTTP response is returned from the server. The operations that are defined in the Reference section describe example errors that might be returned from a failed request. All responses from the Identity Services REST API are in JSON format.

The following table shows the potential error codes the API might return.

| HTTP Error Code | Description | Recovery | |-----------------|-------------|----------| | 200 | Success | The request was successful. | | 201 | Created | The resource was successfully created. | | 204 | No Content | The request was successful. No response body is provided. | | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. The token is either missing or expired. Get a new valid token and try again. | | 403 | Forbidden | The supplied authentication is not authorized to perform the operation. If this error persists, contact the account owner to check your permissions. | | 404 | Not Found | The requested resource can't be found. | | 412 | Precondition failed | The content of the If-Match header does not match the expectation in an update request. | | 415 | Bad Request | Missing or wrong header | | 500 | Internal error | Error that is seen in an unexpected error situation. |

logs-router v1 | IBM Cloud API Docs