Sending logs by using the API

You can send logs to an IBM Cloud Logs instance by using the ingestion API.

Authenticate by using a bearer token

You must get an IBM Cloud® Identity and Access Management (IAM) access token to authenticate your requests.

To obtain your token by using the IBM Cloud CLI, complete the following steps:

Log in to IBM Cloud.

Make sure the entity with which you log in has the Sender role for the IBM Cloud Logs service.
Run the following command:
```
ibmcloud iam oauth-tokens
```
Place this token in the Authorization header of the HTTP request in the form Bearer .

For example, you can retrieve your IAM bearer token and export it as an environment variable by running the following CLI command:

export IAM_TOKEN=`ibmcloud iam oauth-tokens --output json | jq -r '.iam_token'`

Send logs by using cURL

The following table outlines the endpoint details:

Singles ingestion endpoint details
Detail	Value
`URL`	`<INSTANCE_ID>.ingress.<REGION>.logs.cloud.ibm.com/logs/v1/singles`
`HTTP Method`	`POST`
Header `Content-Type`	`application/json`
Header `Authorization`	`Bearer $IAM_TOKEN`

Where

INSTANCE_ID: GUID of the IBM Cloud Logs instance where you want to send logs.
REGION: Region where the IBM Cloud Logs instance is located.
IAM_TOKEN: IAM bearer token used to request authorization to seng to logs. The pemission logs.data.send is required.

Use the following cURL command to send a log line:

curl -v --location "<INSTANCE_ID>.ingress.<REGION>.logs.cloud.ibm.com/logs/v1/singles" \
--header "Content-Type: application/json" \
--header "Authorization: $IAM_TOKEN" \
--data '[{
      "applicationName": "ENTER_APPLICATION_NAME",
      "subsystemName": "ENTER_SUBSYSTEM_NAME",
      "severity": "ENTER_SEVERITY",
      "computerName": "ENTER_VALUE",
      "text": ENTER_LOG_LINE,
      "category": "ENTER_VALUE",
      "className": "ENTER_VALUE",
      "methodName": "ENTER_VALUE",
      "threadId": "ENTER_VALUE"
    }]'

The following table outlines the JSON objects that you can include per log line in a request:

Array of JSON objects
Property name	Property type	Required	More information
`applicationName`	`string`	Yes
`subsystemName`	`string`	Yes
`text`	`string/json`	Yes	If you are using Ajax or a similar technology, you might need to send the data with JSON.stringify().
`severity`	`number`	No	`1 – Debug` `2 – Verbose` `3 – Info` `4 – Warn` `5 – Error` `6 – Critical` If not specified, `1 – Debug` will be used.
`timestamp`	`number`	No	UTC milliseconds. If not specified the time when the log reaches the gate way will be used.
`computerName`	`string`	No
`category`	`string`	No
`className`	`string`	No
`methodName`	`string`	No
`threadId`	`string`	No
`hiResTimestamp`	`string`	No	UTC nanoseconds

If you do not specify severity, logs are assigned the severity of 1 – Debug.

You can send up to 2MB per request, which is approximately 3,000 medium-sized logs.

For example, you can run the following command to send logs to an instance in the eu-es region:

curl -v --location "https://90d208cc-e1dd-4fb2-a938-358e5996f056.ingress.eu-es.logs.cloud.ibm.com/logs/v1/singles" \
--header "Content-Type: application/json" \
--header "Authorization: $IAM_TOKEN" \
--data '[{
      "applicationName": "cs-rest-test3",
      "subsystemName": "cs-rest-test3",
      "computerName": "computer test3",
      "text": {"key":"value","message":"148.145.31.214 - user [24/Oct/2023:15:54:46 +0000] \"PATCH /maximized/Triple-buffered_Managed/core.hmtl HTTP/1.1\" 400 7074 1.666 \"-\" \"Mozilla/5.0 (Macintosh; PPC Mac OS X 10_6_4 rv:6.0) Gecko/1929-02-10 Firefox/37.0\" \"-\"","countryme":"Italy"},
      "category": "cat-1",
      "className": "class-1",
      "methodName": "method-1",
      "threadId": "thread-1"
    }]'

The -v option provides verbose output which can help you determine if the command completed successfully or if there were authorization or connectivity issues.