IBM Cloud Docs
Learning about IBM Cloud Logs Routing

Learning about IBM Cloud Logs Routing

You can use the IBM Cloud Logs Routing service to route platform logs that are generated by selected IBM Cloud service instances to your chosen destination (target).

Flow of platform logs
Figure 1. Flow of platform logs

For more information, see About platform logs.

To configure platform logs, you must configure tenants and targets (destinations) in your IBM Cloud account.

A tenant is the account-specific configuration of IBM Cloud Logs Routing running within a region. You can define up to 2 target destinations per tenant per region. Destinations must be of different type. The target defines where the logs are routed.

The following figure shows a high level view of the components and how they relate to each other:

High level view of the components
Figure 2. High level view of the components

Tenants

When you manage tenants, consider the following information:

  • You must create a tenant in your account in each region where you want to use IBM Cloud Logs Routing to collect and route platform logs.

    Each region is independent.

    Regions do not share data.

  • When you create a tenant, you must define 1 target destination. For more information, see Creating a tenant.

  • You can define up to 2 target destinations per target. The targets must be of different type.

  • When you update a tenant, you can modify the name of the tenant only.

  • When you delete a tenant, you also delete the target definitions. If you want to delete a target destination instance, you must delete the instance separately.

  • You can list all the tenants in an account by using the v1/tenants route.

  • To get the details of a tenant, the route accepts a query parameter name to return details of the named tenant.

Targets

IBM Cloud Logs Routing supports the following types of targets:

The IBM Cloud Logs Routing target instance can be located in the same account, a different account, and the same or different region as the IBM Cloud Logs Routing tenant.

When you manage targets, consider the following information:

  • When you create a target, you can only add 1 target.

    When tenant is created, at least one target has to be specified. You can only define 2 targets per tenant. Therefore, you can only add 1 target to an existing tenant.

    The target name must be unique within the region and not exceed 35 characters in length. If you attempt to create a target with a name that already exists within the region or is too long, an error is returned and your target is not created.

  • You can update the target configuration details such as target host, target port, target name, target instance CRN, and more.

  • You can delete only 1 target from a tenant.

  • You can list all the targets in a tenant by using the v1/tenants/tenantID/targets route.

  • To get the details of a target, the route accepts a query parameter name to return details of the named target.

Authorization between the IBM Cloud Logs Routing service and the target destination instances is done as follows:

  • For IBM Cloud Logs targets, authorization is done through IAM.
  • For IBM Log Analysis targets, you must provide ingestion details that include the credentials.

Connecting to IBM Cloud Logs Routing

IBM® Cloud Logs Routing provides API endpoints for both management functions, such as creating (onboarding) as a tenant, and ingestion of logs. These API endpoints are separate endpoints that are accessed by using specific URLs in each supported region. You can find the endpoints for each supported region here.

You can manage IBM Cloud Logs Routing by using the management API. The management API supports either a public endpoint or a private endpoint. A public endpoint can be reached over the internet, whereas a private endpoint can be accessed only from within the IBM Cloud private network.

You can send logs to a target destination by using the ingestion API. The ingestion API supports only private endpoints and is therefore not accessible from the public internet.

Through the IBM Cloud Logs Routing UI, you can create a tenant in a region by using the public network.

You must ensure that you can connect to both the management and ingestion endpoints.

Flow of routed logs
Figure 1. Resources

The IBM® Cloud Logs Routing supports the following types of endpoints to privately connect to IBM Cloud Logs Routing:

  • IBM Cloud Cloud Service Endpoint (CSE)
  • Virtual Private Endpoint (VPE) for VPC for VPC.

If you are connecting from an IBM Cloud VPC, you can connect by using either a CSE or VPE for VPC. For more information, see Using virtual private endpoints for VPC to privately connect to IBM Cloud Logs Routing.

If you are connecting from a system that is not contained in an IBM Cloud VPC, your only private endpoint option is to connect by using a CSE. Connecting to IBM Cloud Logs Routing by using a CSE might not require any additional work on your part. Access to CSEs is only available from within the IBM Cloud private network. For more information, see Using service endpoints to privately connect to IBM Cloud Logs Routing.

You can only access the IBM Cloud Logs Routing UI through the public network.

You can manage IBM Cloud Logs Routing by using the management API. The management API supports either a public endpoint or a private endpoint. A public endpoint can be reached over the internet, whereas a private endpoint can be accessed only from within the IBM Cloud private network.

  • To create, update, or delete a configuration, you must use the IBM Cloud Logs Routing management API.
  • To see the list of management endpoints, see Endpoints.

Using the public endpoint does not require additional work.

Common use cases configuring IBM Cloud Logs Routing

  • Consolidate log data: You might want to configure IBM Cloud Logs Routing to send logs to a single target destination.
  • Data residency posture: You might want to keep log data within a designated location or country. Logs that are generated in IBM Cloud can be routed to a destination in the location of your choice.

Determining the origin of IBM Cloud log data

You can determine the details of the IBM Cloud service that generates the log data by looking into the logSourceCRN value that is included in the log line.

The logSourceCRN value is the Cloud Resource Name (CRN) of the originating IBM Cloud service. This value includes location, service name, and service instance ID.