Sending Logs to the LM Logs Ingestion API

If a log integration isn’t available or you have custom logs that you want to analyze, you can send the logs directly to your LogicMonitor account via the logs ingestion API. The received events are mapped to resources in LogicMonitor before they are further processed or stored.

Log Ingestion Endpoint

Note: The logs ingestion API supports receiving compressed payloads that are gzip content encoded.

Resource path

For the logs ingestion endpoint, https://<account>.logicmonitor.com/rest/log/ingest:

• The base URL is https://<account>.logicmonitor.com/rest
• The resource path is /log/ingest

Where <account> is the company name or account name for your LogicMonitor portal.

Note: The base URL for the logs ingestion endpoint is /rest and not /santaba/rest, which is the URL for the LogicMonitor REST API.

Authentication

All requests to the log ingestion API use LogicMonitor’s LMv1 API tokens for authentication. You can create the API tokens in your LogicMonitor account Settings under Users & Roles.

Every request must include an HTTP authorization header in the format:

Authorization: LMv1 AccessId:Signature:Timestamp

The Signature is a base64 and HMAC encoded hash based on your Access Key, a timestamp in epoch milliseconds, and the resource path of the endpoint:

signature = base64(
  HMAC-SHA256(
    Access Key, 
    HTTP VERB 
    + TIMESTAMP
    + POST DATA
    + RESOURCE PATH
  ) 
)

Example Request

Sending a log message for an Amazon EC2 instance to the ingestion endpoint using curl:

curl --location \
--request POST 'https://<account>.logicmonitor.com/rest/log/ingest' \
--header 'Authorization: <LMv1 token>' \
--header 'Content-Type: application/json' \
--data-raw '[{
    "msg": "Generating example log message 31687",
    "_lm.resourceId":{"<property>": "<value>"}
}]'

Parameters

The log ingestion endpoint expects JSON objects as events. These events can have any JSON attribute, but the following tables highlight reserved attributes:

Response Codes

The log ingestion API uses conventional HTTP response codes to indicate the success or failure of an API request.

Example 1: 202 – Accepted

Header:
     X-Request-ID: 38b78dd6-3bc0-4cd9-8a15-6af552d49c3e
Body:
{
    "success": true,
    "message": "Accepted"
}

Example 2: 207 – Multi-status

Header:
     X-Request-ID: 38b78dd6-3bc0-4cd9-8a15-6af552d49c3e
Body:
{
    "success": false,
    "message": "Some events were not accepted. See the 'errors' property for additional information.",
    "errors": [
        {
            "code": 4001,
            "error": "Resource not found",
            "event": {
                "_lm.resourceId": {
                    "system.deviceId": "kish"
                },
                "message": "test"
            }
        },
    ]
}

Custom Error Codes

Custom error codes can be used to provide insights into what went wrong when log ingestion fails. If events do not meet the log ingestion constraints, such as failed mapping to LogicMonitor resource or field requirements, one of the following error message is returned:

Example: Failures

Header:
    X-Request-ID: 38b78dd6-3bc0-4cd9-8a15-6af552d49c3e
Body:
{
    "success": false,
    "message": "Some events were not accepted. See the 'errors' property for additional information.",
    "errors": [
        {
            "code": 4003,
            "error": "Insufficient information for device lookup",
            "event": {
                "message": "test"
            }
        },
        {
            "code": 4004,
            "error": "Missing message field",
            "event": {
                "_lm.resourceId": {
                    "system.deviceId": "kish"
                },
            }
        }
 
    ]
}