# 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`:

```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:

```bash
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:**

```bash
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:**

```bash
# 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:**

```bash
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:

```bash
./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](../adr/0007-opentelemetry-integration.md) for the full architectural decision and rationale (middleware-only approach, sampling strategy, OTLP/gRPC choice).