Introduction

You can configure IBM® Cloud Logs Routing to manage logs routing in your IBM Cloud account.

IBM Cloud Logs Routing provides a REST API that you can use to define, retrieve, and modify targets and routes. For details about using IBM Cloud Logs Routing, see the IBM Cloud documentation.

Endpoint URL

You can use private and public API endpoints to manage IBM Cloud Logs Routing.

The IBM Cloud Logs Routing API uses the following regional private endpoint URL.

https://api.private.<region>.logs-router.cloud.ibm.com/v3

The IBM Cloud Logs Routing API uses the following regional public endpoint URL.

https://api.<region>.logs-router.cloud.ibm.com/v3

When you call the API, you must add the path for each method to form the complete API endpoint for your request.

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

For more information about supported endpoints, see Endpoints.

Example API request

curl -X <request_method> "https://api.<region>.logs-router.cloud.ibm.com/v3/<method_endpoint>"

Replace <request_method>, <region, and <method_endpoint> in this example with the values for your particular API call. Some API calls require an additional request payload. See the API Schema and examples for details.

The code examples on this tab use the IBM Cloud Logs Routing SDK for Go.

Installation

go get -u github.com/IBM/platform-services-go-sdk/logsrouterv3

GitHub

Authentication

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access with IAM.

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token.

You can build your API request by pairing a service endpoint with your authentication credentials. For example, if you plan to configure a routing target for the us-south region for your platform logs, use the following endpoint and API headers to list the targets in your service:

curl -X GET \
    "https://api.us-south.logs-router.cloud.ibm.com/v3/targets" \
    -H "accept: application/json" \
    -H "Authorization: Bearer <access_token>" \

Replace <access_token> with your IBM Cloud IAM token.

You can retrieve an access token by first creating an API key, and then exchanging your API key for an IBM Cloud IAM token.

To find out more about setting up the IBM Cloud Logs Routing API, see Getting started.

To retrieve your access token:

curl -X POST \
"https://iam.cloud.ibm.com/identity/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>" > token.json

Replace <API_KEY> with your service credentials. Then use the full access_token value, prefixed by the Bearer token type, to authenticate your API requests.

In this scenario, configuration is defined with an external credentials file and authenticator that is constructed by SDK's authenticator factory during client initialization. It avoids hardcoding credentials within application code.

The default name of the credentials file is logs_router_v3.env . It is expected to be located in either the current directory or in the user's home directory. The path and name of the file can be controlled by using the IBM_CREDENTIALS_FILE environment variable.

The name of each configuration property contains the service name along with the actual attribute name in the form <service-name>_<attribute-name>.

It is not necessary to use a .env file, these properties can be set by using environment variables with the same name in the environment where the applications ran.

Variable guide for the authentication code samples

`{apikey}`	IAM API key
`{url}`	URL of Logs Router V3 API endpoint

SDK managing the IAM token. Replace {apikey} and {url}.

LOGS_ROUTER_URL={url}
LOGS_ROUTER_APIKEY={apikey}

import (
    "github.com/IBM/platform-services-go-sdk/logsrouterv3"
)

logsRouterServiceOptions := &logsrouterv3.LogsRouterV3Options{}

logsRouterService, err = logsrouterv3.NewLogsRouterV3UsingExternalConfig(logsRouterServiceOptions)

Programmatic authentication

In this scenario authentication that is configured by constructing an authenticator instance provides the configuration attributes programmatically and then passing this instance to a client instantiation.

SDK managing the IAM token.

import (
    "github.com/IBM/go-sdk-core/v5/core"
    "github.com/IBM/platform-services-go-sdk/logsrouterv3"
)
authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
}
logsrouterv3.NewLogsRouterV3(
    &slogsrouterv3.LogsRouterV3Options{
        URL:           "{url}",
        Authenticator: authenticator,
    }
)

Auditing

You can monitor API activity within your account by using IBM Cloud Logs Routing. For more information, see Getting started.

Whenever an API method is called, an auditing event is generated that you can then track and audit in your account. The specific event type is listed for each individual method.

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 is some sort of failure, and a 500 type response usually indicates an internal system error.

| 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. This is often due to a missing required parameter. | | 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. | | 409 | Conflict | The request conflicts with the current state of customer resources in the system. | | 429 | Too Many Requests | Too many requests hit the API too quickly. | | 500 | Internal Server Error | Something went wrong when processing your request. |

If an error response from the server endpoint the Go SDK creates an error object that contains either the HTTP response error message or a generic error message.

An extra detailedResponse is returned by the service that contains the following fields:

| Field | Description | |------------|-------------| | StatusCode | HTTP response status code | | Result | JSON error response object that is unmarshalled as map[string]interface{} | | RawResult | raw non-JSON error response object as []byte |

Example error handling

_, detailedResponse, err := // Invoke a logs-router-v3 method request
if err != nil {
    if (detailedResponse != nil) {
      fmt.Println("Error status code: ", detailedResponse.StatusCode)
      fmt.Println("Error message:     ", err.Error())
      errorMap, ok := detailedResponse.GetResultAsMap(); if ok {
        fmt.Println("Reason:          ", errorMap["reason"])
      }
    } else {
      // Handle other error conditions
      fmt.Println("Error message: ", err.Error())
    }
  }

Logs Routing V3 | IBM Cloud API Docs