Entry point for the optional observability stack. LQ.AI emits OTLP traces from the api and gateway and exposes Prometheus /metrics, but ships no-telemetry-by-default — services start without a collector and spans are silently dropped until a backend is wired (PRD §5.7). It routes operators to one of two Compose overlays: grafana-tempo-loki/ for a fully self-hosted stack, or otel-collector-standalone/ to forward spans to an existing OTLP backend. Both leave the base docker-compose.yml unchanged and share the otel-collector service name, so you must compose down before switching. You're deciding which observability recipe to use, or need the no-telemetry-by-default ground truth.
LQ.AI — Observability Deployment Recipes
LQ.AI emits OTLP traces from the API and Gateway services and exposes Prometheus metrics on /metrics. By default, no telemetry leaves the deployment — the services start cleanly without a collector, and span data is silently dropped until you wire a backend (per PRD §5.7). These recipes wire that backend. If you prefer to configure a collector yourself, setting OTEL_EXPORTER_OTLP_ENDPOINT in your .env is sufficient; the recipes here are for operators who want a ready-made setup.
For the full operator guide — signal inventory, span names, attribute schema, sampling guidance, and dashboard reference — see docs/observability.md (note: this file is added in the M3-F3 release alongside these recipes).
Choose a recipe
| Situation | Recipe |
|---|---|
| You are starting fresh and want a self-hosted observability stack with no third-party SaaS. You want traces in Tempo, logs in Loki, metrics in Prometheus, and a Grafana dashboard — all running alongside the main stack in Docker. | grafana-tempo-loki/ |
| You already run Honeycomb, Datadog, Lightstep, Splunk, or any other OTLP-compatible backend, and you just need a collector that forwards LQ.AI's spans to it. You don't want Grafana or Tempo locally. | otel-collector-standalone/ |
Both recipes are Docker Compose overlays. They add services and set OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 on the api and gateway containers. The base stack (docker-compose.yml in the repo root) is unchanged; the overlay is merged at startup with the -f flag.
Switching between recipes
Run docker compose down before switching overlays; the collector service name is the same (otel-collector) in both recipes, and having both active simultaneously is not a supported configuration.