Sending logs by using the REST API

You can send logs to an IBM Log Analysis instance by using the Ingestion REST API.

As of 28 March 2024 the IBM Log Analysis and IBM Cloud Activity Tracker services are deprecated and will no longer be supported as of 30 March 2025. Customers will need to migrate to IBM Cloud Logs, which replaces these two services, prior to 30 March 2025. IBM Cloud Logs will become generally available during the summer of 2024 in Frankfurt and Madrid with day-one support for EU-managed controls. The service will continue its worldwide multizone region (MZR) roll-out through 3Q2024.

Complete the following steps to send logs programmatically by using the REST API:

Step 1. Get the ingestion API key

Note: You must have manager role for the IBM Log Analysis instance or service to complete this step. For more information, see Granting permissions to manage logs and configure alerts.

Complete the following steps to get the ingestion key:

Launch the IBM Log Analysis web UI.
Click the Settings icon > Organization.
Select API keys.

You can see the ingestion keys that have been created.
Copy a key. You can use an existing ingestion key or click Generate Ingestion Key to create a new one. When you generate a key, the key is added to the list.

Step 2. Send logs

To send logs, run the following cURL command:

curl "ENDPOINT/logs/ingest?QUERY_PARAMETERS" -u INGESTION_KEY: --header "Content-Type: application/json; charset=UTF-8" -d "LOG_LINES"

Where

ENDPOINT represents the entry point to the service. Each region has a different URL. To get the endpoint for a location, see Ingestion endpoints.
QUERY_PARAMETERS are parameters that define the filtering criteria that are applied to the ingestion request.
LOG_LINES describe the set of log lines that you want to send. It is defined as an array of objects.
INGESTION_KEY is the key that you created in the previous step.

The following table lists the query parameters:

Query parameters
Query parameter	Type	Status	Description
`hostname`	`string`	required	Host name of the source.
`mac`	`string`	optional	The network mac address of the host computer.
`ip`	`string`	optional	The local IP address of the host computer.
`now`	`date-time`	optional	The source UNIX timestamp in milliseconds at the time of the request. Used to calculate time drift.
`tags`	`string`	optional	Tags that are used to dynamically group hosts.

The following table lists the data that is required per log line:

Line object fields
Parameters	Type	Description
`timestamp`		UNIX timestamp, including milliseconds, when the log entry was recorded.
`line`	`string`	Text of the log line.
`app`	`string`	Name of the application that generates the log line.
`level`	`string`	Set a value for the level. For example, sample values for this parameter are `INFO`, `WARNING`, `ERROR`.
`meta`		This field is reserved for custom information that is associated with a log line. To add metadata to an API call, specify the meta field under the lines object. Metadata can be viewed inside that line's context.

For example, the following sample shows the JSON for a log line that you want to ingest:

{
  "lines": [
    {
      "timestamp": 2018-11-02T10:53:06+00:00,
      "line":"This is my first log line.",
      "app":"myapp",
      "level": "INFO",
      "meta": {
        "customfield": {"nestedfield": "nestedvalue"}
      }
    }
  ]
}

Example

The following sample shows the cURL command to send 1 log line to an instance of the IBM Log Analysis service:

curl "https://logs.us-south.logging.cloud.ibm.com/logs/ingest?hostname=MYHOST&now=$(date +%s)000" -u xxxxxxxxxxxxxxxxxxxxxxx: --header "Content-Type: application/json; charset=UTF-8" -d "{\"lines\":[{\"line\":\"This is a sample test log statement\",\"timestamp\":\"2018-11-02T10:53:06+00:00\",\"level\":\"INFO\",\"app\":\"myapp\"}]}"

Limits when you send logs

There are limits when sending logs. For more information see Limits when sending logs.