Gabriel Radureau
41ee8c56ac
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>
95 lines
2.3 KiB
Markdown
95 lines
2.3 KiB
Markdown
# 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).
|