feat: add one-command demo that populates Grafana

compose.demo.yml runs a tiny auto-instrumented FastAPI service plus a curl
load loop, emitting real OTLP traces, metrics, and trace-correlated logs.
'just demo' brings up the core stack with the overlay.

Author: simonvanlierde

compose.demo.yml

@@ -0,0 +1,47 @@
+# Demo overlay: a tiny auto-instrumented FastAPI service plus a load
+# generator, so the stack has real traces, metrics, and correlated logs
+# to show. Not for production.
+#
+#   just demo        # core stack + this overlay
+#   just demo-down
+
+services:
+  demo-api:
+    build: ./demo
+    restart: unless-stopped
+    depends_on: [ otel-collector ]
+    environment:
+      OTEL_SERVICE_NAME: demo-api
+      OTEL_RESOURCE_ATTRIBUTES: env=demo
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
+      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
+      OTEL_TRACES_EXPORTER: otlp
+      OTEL_METRICS_EXPORTER: otlp
+      OTEL_LOGS_EXPORTER: otlp
+      # Ship Python log records via OTLP with trace context attached.
+      OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED: "true"
+      OTEL_METRIC_EXPORT_INTERVAL: "10000"
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  demo-load:
+    image: curlimages/curl:8.21.0
+    restart: unless-stopped
+    depends_on: [ demo-api ]
+    command:
+      - sh
+      - -c
+      - |
+        while true; do
+          curl -s -o /dev/null demo-api:8000/
+          curl -s -o /dev/null demo-api:8000/work
+          sleep 1
+        done
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"

demo/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.13-slim
+
+RUN pip install --no-cache-dir \
+    fastapi==0.139.0 \
+    uvicorn==0.49.0 \
+    opentelemetry-distro==0.64b0 \
+    opentelemetry-exporter-otlp==1.43.0 \
+    opentelemetry-instrumentation-fastapi==0.64b0
+
+WORKDIR /app
+COPY app.py .
+
+CMD ["opentelemetry-instrument", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

demo/app.py

@@ -0,0 +1,26 @@
+# Minimal FastAPI service for the demo overlay. All telemetry (traces,
+# metrics, logs with trace context) comes from OTel auto-instrumentation —
+# see compose.demo.yml. No OTel code needed here.
+import logging
+import random
+import time
+
+from fastapi import FastAPI, HTTPException
+
+log = logging.getLogger("demo-api")
+app = FastAPI()
+
+
+@app.get("/")
+def root():
+    return {"ok": True}
+
+
+@app.get("/work")
+def work():
+    time.sleep(random.uniform(0.02, 0.3))
+    if random.random() < 0.1:  # NOTE: fixed 10% error rate, enough to light up RED panels
+        log.error("work failed: upstream flaked")
+        raise HTTPException(status_code=500, detail="upstream flaked")
+    log.info("work done")
+    return {"ok": True}

justfile

@@ -14,6 +14,14 @@ up-tunnel:
 down:
     docker compose down --remove-orphans
 
+# Core stack + a demo telemetry source (see compose.demo.yml), then look at
+# Grafana: http://localhost:3000
+demo:
+    docker compose -f compose.yml -f compose.demo.yml up -d --build
+
+demo-down:
+    docker compose -f compose.yml -f compose.demo.yml down
+
 logs service="":
     docker compose logs -f {{service}}
 
@@ -29,3 +37,4 @@ pull:
 # Tail a service's logs as JSON, decoded. Useful before Grafana is set up.
 tail service:
     docker compose logs -f --no-log-prefix {{service}} | jq -R 'fromjson? // .'
+