Tempo — Traçage distribué¶
Dashboards Tempo est le backend de traçage distribué d'AKKO. Il reçoit les spans OpenTelemetry (OTLP) d'ADEN et des autres services instrumentés, les stocke localement ou sur S3, et expose une API de requête que Dashboards lit via la datasource Tempo. Cela permet une visibilité de bout en bout sur les traces du pipeline AKKO.
Architecture¶
ADEN / AI Service / Airflow
| (OTLP gRPC :4317 ou HTTP :4318)
|
+--v-----------+
| Tempo |
| (:3200 query|
| :4317 gRPC |
| :4318 HTTP)|
+--+-----------+
|
+--v-----------+
| Dashboards |
| (datasource |
| Tempo) |
+--------------+
- Récepteurs OTLP — gRPC sur le port 4317 et HTTP sur le port 4318 pour l'ingestion des spans
- API de requête sur le port 3200 consommée par la datasource Dashboards Tempo
- Stockage système de fichiers local pour le développement ; backend S3 pour la production
- Licence Apache 2.0 (conforme R27)
URLs¶
Tempo est un service interne uniquement (pas d'ingress). Les traces sont visualisées via Dashboards.
| Endpoint | Port | Protocole |
|---|---|---|
| OTLP gRPC | 4317 | gRPC |
| OTLP HTTP | 4318 | HTTP |
| API de requête | 3200 | HTTP |
Configuration (valeurs Helm)¶
akko-tempo:
enabled: true
image:
repository: grafana/tempo
tag: "2.6.1"
replicas: 1
service:
otlpGrpcPort: 4317
otlpHttpPort: 4318
queryPort: 3200
persistence:
enabled: true
size: 10Gi
retention:
blockRetention: 72h # 3 jours en dev local, 14-30j en production S3
serviceMonitor:
enabled: true
interval: 30s
resources:
requests:
cpu: 100m
memory: 256Mi
limits:
cpu: 1
memory: 1Gi
Healthcheck¶
Tempo expose les métriques et la santé sur le port de requête :
livenessProbe:
httpGet:
path: /ready
port: 3200
initialDelaySeconds: 15
periodSeconds: 30
readinessProbe:
httpGet:
path: /ready
port: 3200
initialDelaySeconds: 10
periodSeconds: 10
RBAC (qui peut accéder)¶
Tempo est un service interne uniquement sans ingress. L'accès est contrôlé par :
- NetworkPolicy — restreint les pods autorisés à envoyer des spans (OTLP) et interroger les traces
- Dashboards — les traces sont visualisées via les tableaux de bord Dashboards (Dashboards est authentifié via Keycloak)
Envoi de traces à Tempo¶
Les services envoient des spans OTLP à Tempo via des variables d'environnement :
OTEL_EXPORTER_OTLP_ENDPOINT=http://akko-akko-tempo:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_SERVICE_NAME=<nom-du-service>
Pour les services Python (ADEN, AI Service) :
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider()
exporter = OTLPSpanExporter(endpoint="http://akko-akko-tempo:4317", insecure=True)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
Fonctionnalités principales¶
| Fonctionnalité | Description |
|---|---|
| Ingestion OTLP | Reçoit les spans via gRPC (4317) et HTTP (4318) |
| Intégration Dashboards | Datasource Tempo native pour la visualisation des traces |
| Backend S3 | Les déploiements production stockent les traces sur object storage/S3 |
| Rétention configurable | 72h par défaut (local), ajustable pour la production |
| Métriques Prometheus | ServiceMonitor scrute /metrics sur le port 3200 |
| Trace-vers-logs | Lien entre les traces et les logs logs layer dans Dashboards |
Ressources requises¶
| Composant | RAM minimum | Recommandé |
|---|---|---|
| Tempo | 256 Mi | 1 Gi |
Dépannage¶
Aucune trace dans Dashboards¶
Symptômes : La datasource Dashboards Tempo ne retourne aucun résultat, ou affiche « No traces found ».
Cause : Les services n'envoient pas de spans, Tempo ne les reçoit pas, ou la datasource Dashboards est mal configurée.
Solution :
# Vérifier que le pod Tempo tourne et est prêt
kubectl get pods -n akko -l app.kubernetes.io/name=akko-tempo
# Vérifier la disponibilité de Tempo
kubectl exec -n akko deploy/akko-akko-tempo -- wget -qO- http://localhost:3200/ready
# Vérifier que l'endpoint OTLP est joignable depuis un pod de service
kubectl exec -n akko deploy/akko-akko-aden -- curl -s http://akko-akko-tempo:3200/ready
# Consulter les logs Tempo pour les erreurs d'ingestion
kubectl logs -n akko deploy/akko-akko-tempo --tail=50 | grep -i "error\|warn"
Disque Tempo plein¶
Symptômes : Le pod Tempo redémarre ou les traces sont silencieusement supprimées. Les logs affichent disk full ou WAL write failure.
Cause : Le PVC est plein à cause d'un volume de traces élevé ou d'un nettoyage de rétention insuffisant.
Solution :
# Vérifier l'utilisation du PVC
kubectl exec -n akko deploy/akko-akko-tempo -- df -h /var/tempo
# Réduire la rétention
# Dans les values : akko-tempo.retention.blockRetention: 24h
# Augmenter la taille du PVC (si supporté par la StorageClass)
kubectl edit pvc -n akko akko-akko-tempo
Connexion OTLP refusée¶
Symptômes : Les services journalisent OTLP exporter: connection refused ou failed to export spans.
Cause : Le pod Tempo n'est pas prêt, ou la NetworkPolicy bloque le trafic OTLP.
Solution :