Forwarder JSON intake

When to use it #

The forwarder endpoint accepts a simpler document than OTLP: an array of log records with flat attributes. Use it when the sender is a script, a legacy forwarder, or any component that cannot produce OTLP.

POST /otlp/v1/logs/json

Document shape #

The body is a JSON object. records carries the logs; anything omitted takes a sensible default so a minimal sender works.

{
  "service": "checkout",
  "env": "production",
  "host": "ip-10-0-1-42",
  "source": "checkout-worker",
  "records": [
    {
      "message": "Order 8821 failed to settle",
      "status": "error",
      "service": "checkout",
      "timestamp": "2026-03-04T11:22:33.481Z",
      "attributes": {
        "order.id": "8821",
        "payment.provider": "stripe",
        "retry.count": 3
      }
    }
  ]
}

Record fields #

• message — the log text. This is what search matches against.
• status — severity: debug, info, warn, error, or critical.
• service — overrides the document-level service for this record.
• timestamp — ISO 8601. Defaults to the time of receipt.
• attributes — arbitrary key/value pairs, promoted to searchable fields.

Top-level service, env and host apply to every record and can be overridden per record. Setting them once at the top is the tidier choice for a single-service forwarder.

Sending from a script #

curl -X POST "$SENTINEL_HOST/otlp/v1/logs/json" \
  -H "content-type: application/json" \
  -H "x-sentinel-api-key: $SENTINEL_API_KEY" \
  -d '{
    "service": "batch-worker",
    "env": "production",
    "records": [{"message": "nightly export complete", "status": "info"}]
  }'

Status codes #

200  Accepted.
400  The body was not JSON, or carried no records.
401  The API key was missing or not recognised.
403  The key lacks the logs ingest scope.
413  The body exceeded 4 MiB.
429  Over the sender's ingest rate.

Forwarding from an existing shipper #

Most shippers can emit NDJSON to an HTTP endpoint. To reuse one, map its output onto the record shape above and point it at the JSON path — the ingestion behaviour is otherwise identical to OTLP.