dance-lessons-coach/documentation/OBSERVABILITY.md

Observability — OpenTelemetry & Jaeger Integration

Tracing setup for dance-lessons-coach. Extracted from the original AGENTS.md (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.

The application supports OpenTelemetry for distributed tracing with Jaeger compatibility.

Configuration

Enable OpenTelemetry in your config.yaml:

telemetry:
  enabled: true
  otlp_endpoint: "localhost:4317"
  service_name: "dance-lessons-coach"
  insecure: true
  sampler:
    type: "parentbased_always_on"
    ratio: 1.0

Or via environment variables:

export DLC_TELEMETRY_ENABLED=true
export DLC_TELEMETRY_OTLP_ENDPOINT="localhost:4317"
export DLC_TELEMETRY_SERVICE_NAME="dance-lessons-coach"
export DLC_TELEMETRY_INSECURE=true
export DLC_TELEMETRY_SAMPLER_TYPE="parentbased_always_on"
export DLC_TELEMETRY_SAMPLER_RATIO=1.0

Testing with Jaeger

1. Start Jaeger in Docker:

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

2. Start the server with OpenTelemetry enabled:

# Using config file
./scripts/start-server.sh start

# Or with environment variables
DLC_TELEMETRY_ENABLED=true ./scripts/start-server.sh start

3. Make API requests:

curl http://localhost:8080/api/v1/greet/John

4. View traces in Jaeger UI:

Open http://localhost:16686 and select the dance-lessons-coach service.

Sampler Types

Sampler	Behavior
always_on	Sample all traces
always_off	Sample no traces
traceidratio	Sample based on trace ID ratio
parentbased_always_on	Sample based on parent span (always on)
parentbased_always_off	Sample based on parent span (always off)
parentbased_traceidratio	Sample based on parent span with ratio

Testing Script

A convenience script is provided:

./scripts/test-opentelemetry.sh

This script:

1. Starts Jaeger container
2. Starts the server with OpenTelemetry
3. Makes test API calls
4. Shows Jaeger UI URL
5. Cleans up on exit

ADR Reference

See ADR-0007 — OpenTelemetry Integration for the full architectural decision and rationale (middleware-only approach, sampling strategy, OTLP/gRPC choice).