Skip to main content
OpenLIT’s image includes a first-party OTLP receiver. Applications, SDKs, and the openlit CLI send traces, metrics, and logs to it. The receiver writes ClickHouse otel_* tables. The OpenLIT image does not ship otelcol.

​
Endpoints

The OpenLIT UI also proxies /v1/* from the app origin to this process, so the same HTTP paths work through the dashboard host when you cannot reach :4318 directly. Docker Compose and Kubernetes examples publish 4317 and 4318 on the OpenLIT service (openlit), not a separate otel-collector container. Point exporters at the receiver:
Supported metric types: gauge, sum, histogram, summary, and exponential histogram (otel_metrics_* tables).

​
Authentication

Send an OpenLIT API key so ingest is scoped to organisation → project → environment and writes to that project’s ClickHouse:
x-openlit-api-key is also accepted. Client x-database-config-id headers are ignored. A valid key stamps organisation.environment.name, openlit.organisation.id, and openlit.project.id. It does not overwrite client deployment.environment. Without a key, data is written to INIT_DB_* unless OTLP_REQUIRE_API_KEY=true. In OpenLIT Enterprise, a key restricted to specific features must include Telemetry ingestion to send data; otherwise ingest is rejected as unauthorized. Key lookups are cached for up to 30 seconds, so access changes can take that long to apply to ingestion.

​
Schema

On first ingest, and again if an insert fails because otel_* tables were dropped, the receiver runs CREATE TABLE IF NOT EXISTS for the OTLP schema and retries the write once. Compose and Kubernetes ClickHouse init scripts still create the same tables on an empty volume. The ClickHouse user needs CREATE TABLE (or the tables must already exist). If create is denied and the tables are missing, ingest fails with an explicit error.

​
Realtime signals

When NATS_URL is set (Docker Compose sets it by default), the receiver also publishes a compact signal for each GenAI span to NATS JetStream. The bundled openlit-engine evaluates threshold alerts on these signals within seconds, without querying ClickHouse.
  • Signals are published after the ClickHouse insert succeeds. Publishing never blocks ingest: if the publish buffer is full, signals are dropped and counted.
  • Only GenAI spans (with a gen_ai.* attribute) sent with a project-scoped API key are published. Spans without a key are stored but not evaluated.
  • The environment is lowercased, and spans whose environment is not a valid OpenLIT environment name are not published.
  • The subject is openlit.signal.<organisation>.<project>.<environment>, and each message is deduplicated by trace and span ID for 2 minutes.
  • A signal carries the service, model, provider, operation, status, error type, latency, token counts, cost, and up to 64 span or resource attributes. Every value is truncated to 256 bytes and credential-like values are redacted.
  • Prompt, completion, message, and secret attributes are never published. Personal attributes (user, session, and conversation IDs, email, phone, IP, URL paths, server addresses) are only published when listed in OPENLIT_SIGNAL_ATTRIBUTES.
  • The stream is file-backed and bounded by age (default 10 minutes) and size (default 256 MiB).
See Realtime variables for NATS credentials, TLS, and limits.

​
Optional sidecar Collector

Keep using your own OpenTelemetry Collector for fan-out, sampling, or processors. Forward OTLP to OpenLIT instead of writing ClickHouse from otelcol. A starter config is in assets/otel-collector-config.yaml. To send SDK data to a Collector you operate (not into OpenLIT), see OpenTelemetry Collector destination.

Self-host OpenLIT

Docker Compose and Helm deploy OpenLIT plus ClickHouse. OTLP ingest is built in.

Telemetry

Explore traces, metrics, and logs after they land in ClickHouse.