Skip to main content

​
Ingestion API

Logs are ingested into LogClaw exclusively via OTLP (OpenTelemetry Protocol). The OTel Collector accepts both gRPC and HTTP transports.

​
Send Logs (HTTP/JSON)

​
method
string
default:"POST"
HTTP method
POST /v1/logs
Send log records in OTLP HTTP/JSON format. Via Dashboard proxy: POST /api/otel/v1/logs Direct: POST http://logclaw-otel-collector:4318/v1/logs

​
Request Headers

HeaderValue
Content-Typeapplication/json

​
Request Body

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "payment-api" }
          },
          {
            "key": "host.name",
            "value": { "stringValue": "pod-abc123" }
          }
        ]
      },
      "scopeLogs": [
        {
          "logRecords": [
            {
              "timeUnixNano": "1709312400000000000",
              "severityText": "ERROR",
              "severityNumber": 17,
              "body": {
                "stringValue": "Connection refused to database"
              },
              "traceId": "abcdef1234567890abcdef1234567890",
              "spanId": "abcdef1234567890",
              "attributes": [
                {
                  "key": "environment",
                  "value": { "stringValue": "production" }
                },
                {
                  "key": "region",
                  "value": { "stringValue": "us-east-1" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

​
Response

200 OK 
{
  "partialSuccess": {}
}
An empty partialSuccess object means all records were accepted.

​
OTLP Field Reference

FieldTypeRequiredDescription
resourceLogsarrayYesArray of resource log groups
resource.attributesarrayNoResource-level attributes (service.name, host.name, etc.)
scopeLogsarrayYesArray of scope log groups
logRecordsarrayYesArray of individual log records
timeUnixNanostringNoTimestamp in nanoseconds since epoch
severityTextstringNoSeverity level: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
severityNumberintegerNoNumeric severity (1-24)
body.stringValuestringYesThe log message
traceIdstringNo32-character hex trace ID
spanIdstringNo16-character hex span ID
attributesarrayNoAdditional key-value attributes

​
Attribute Value Types

OTLP attributes support multiple value types: 
{"key": "name", "value": {"stringValue": "hello"}}
{"key": "count", "value": {"intValue": "42"}}
{"key": "ratio", "value": {"doubleValue": 3.14}}
{"key": "enabled", "value": {"boolValue": true}}

​
Send Logs (gRPC)

grpc://logclaw-otel-collector:4317
Use the OTLP gRPC exporter from any OpenTelemetry SDK. This is the recommended transport for production workloads — binary Protobuf is more compact and efficient than JSON. See the OTLP Integration Guide for SDK examples in Python, Java, Node.js, and Go.

​
Health Check

GET http://logclaw-otel-collector:13133/
Response: 
{
  "status": "Server available",
  "upSince": "2024-01-15T10:30:00Z",
  "uptime": "48h30m"
}

​
Examples

​
curl — Single Log

curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "my-app"}}
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s)000000000'",
          "severityText": "ERROR",
          "body": {"stringValue": "Connection timeout"}
        }]
      }]
    }]
  }'

​
curl — Batch (Multiple Records)

curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "batch-test"}}
        ]
      },
      "scopeLogs": [{
        "logRecords": [
          {
            "timeUnixNano": "'$(date +%s)000000000'",
            "severityText": "INFO",
            "body": {"stringValue": "Request started"}
          },
          {
            "timeUnixNano": "'$(date +%s)000000000'",
            "severityText": "ERROR",
            "body": {"stringValue": "Database connection failed"}
          },
          {
            "timeUnixNano": "'$(date +%s)000000000'",
            "severityText": "WARN",
            "body": {"stringValue": "Retrying in 5 seconds"}
          }
        ]
      }]
    }]
  }'