Handbook - Architecture

Ingest Flow

The ingest flow accepts OTLP data, publishes one persist command, and lets storage-write persist asynchronously.

On this page
On this page

The ingest flow accepts OTLP data, publishes one persist command, and lets storage-write persist asynchronously.

Sequence

diagram
POST /v1/traces, /v1/logs, /v1/metrics or gRPC Export Validate route, content type, size, and auth Decode and normalize OTLP Publish PersistTelemetryCommand or PersistMetricsCommand Publish ack OTLP export response Durable delivery Idempotent persistence Ack after commit TracePersistedNotification for live fanout OTLP sender OTLP collector NATS JetStream storage-write SurrealDB storage-read
Mermaid diagram rendered with beautiful-mermaid.

Important Semantics

  • Authentication and authorization happen before body decode except method, content-type, and request-size checks.
  • HTTP 200 means the command was accepted by JetStream, not that data is already queryable.
  • storage-write acknowledges only after persistence succeeds.
  • post-persist notifications contain trace IDs and non-sensitive routing hints only.
  • project ownership comes from auth context or local token mapping, not OTLP attributes.

Subjects

SignalSubject
Tracestelemetry.ingest.traces
Logstelemetry.ingest.logs
Metricstelemetry.ingest.metrics

Failure Examples

FailureError
Unsupported HTTP content typeERR-002
Missing deployed or local-token authERR-015
Forbidden project or missing ingest scopeERR-016
NATS publish unavailableERR-013
Publish acknowledgement timeoutERR-014

Next Step

See the sender setup guide: Ingest OTLP.

Last updated .