Files

Gabriel Radureau 41ee8c56ac 📝 docs(restructure): split AGENTS.md into focused guides (Tâche 6 Phase B)

Création de 9 fichiers neufs pour décharger AGENTS.md (1296 lignes →
~130) en documents lazy-loadables, compatibles avec la limite de
contexte 128k de Mistral Vibe (cf. ARCODANGE migration Phase 1,
Tâche 6 du curriculum).

Sept guides ciblés sous documentation/ :
- HISTORY.md            : phases historiques 1-9 du développement
- CLI.md                : commandes CLI, server lifecycle, config DLC_*
- API.md                : endpoints REST, OpenAPI, Greet v1/v2
- OBSERVABILITY.md      : OpenTelemetry + Jaeger, sampler types, test
- TROUBLESHOOTING.md    : issues connues + pointeurs vers guides spé
- CODE_EXAMPLES.md      : snippets endpoint/logging/context, pointeurs ADR
- ROADMAP.md            : potential features, architectural improvements

Deux fichiers racine :
- CHANGELOG.md          : user-facing, format Keep a Changelog
- AGENT_CHANGELOG.md    : décisions structurantes des agents AI
                          (référencé par AGENTS.md, n'existait pas)

Le contenu est extrait fidèlement d'AGENTS.md sans réinterprétation.
Phase C (réécriture AGENTS.md court) suit dans le commit suivant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-02 23:28:10 +02:00

2.3 KiB

Raw Permalink Blame History

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:

Starts Jaeger container
Starts the server with OpenTelemetry
Makes test API calls
Shows Jaeger UI URL
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).

2.3 KiB Raw Permalink Blame History