jaeger
Despliega y configura Jaeger como backend de trazas distribuidas para el pipeline de verificación de identidad. Almacena, indexa y visualiza los spans generados por los microservicios KYC, permitiendo analizar el flujo completo de una verificación desde la captura de selfie hasta la decisión final. Este skill se centra en Jaeger como infraestructura de trazas, separada de la instrumentación con OpenTelemetry SDK.
When to use
Usar este skill cuando el observability_agent necesite desplegar o configurar Jaeger para recibir, almacenar y visualizar trazas distribuidas del pipeline KYC, o cuando se necesite optimizar el almacenamiento y la consulta de spans.
Instructions
- Desplegar Jaeger all-in-one para desarrollo o con componentes separados para producción:
# docker-compose.yml - Desarrollo jaeger: image: jaegertracing/all-in-one:1.52 ports: - "16686:16686" # UI - "4317:4317" # OTLP gRPC - "4318:4318" # OTLP HTTP - "14250:14250" # gRPC collector environment: - COLLECTOR_OTLP_ENABLED=true - SPAN_STORAGE_TYPE=badger - BADGER_EPHEMERAL=false - BADGER_DIRECTORY_VALUE=/badger/data - BADGER_DIRECTORY_KEY=/badger/key volumes: - jaeger_data:/badger - Para producción, desplegar Jaeger con Elasticsearch como backend de almacenamiento:
# docker-compose-prod.yml jaeger-collector: image: jaegertracing/jaeger-collector:1.52 environment: - SPAN_STORAGE_TYPE=elasticsearch - ES_SERVER_URLS=http://elasticsearch:9200 - ES_USERNAME=elastic - ES_PASSWORD=${ELASTIC_PASSWORD} - ES_INDEX_PREFIX=jaeger-kyc ports: - "4317:4317" - "14250:14250" jaeger-query: image: jaegertracing/jaeger-query:1.52 environment: - SPAN_STORAGE_TYPE=elasticsearch - ES_SERVER_URLS=http://elasticsearch:9200 - ES_USERNAME=elastic - ES_PASSWORD=${ELASTIC_PASSWORD} - ES_INDEX_PREFIX=jaeger-kyc ports: - "16686:16686" - Configurar el OpenTelemetry Collector como intermediario entre los servicios KYC y Jaeger:
# otel-collector-config.yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 5s send_batch_size: 1024 attributes: actions: - key: kyc.pipeline value: "identity-verification" action: upsert exporters: jaeger: endpoint: jaeger-collector:14250 tls: insecure: true service: pipelines: traces: receivers: [otlp] processors: [batch, attributes] exporters: [jaeger] - Configurar sampling adaptativo para controlar el volumen de trazas del pipeline KYC:
{"service_strategies": [{"service": "kyc-liveness", "type": "probabilistic", "param": 1.0}, {"service": "kyc-face-match", "type": "probabilistic", "param": 1.0}, {"service": "kyc-ocr", "type": "probabilistic", "param": 0.5}], "default_strategy": {"type": "probabilistic", "param": 0.1}} - Configurar retención y limpieza de spans en Elasticsearch:
# Crear ILM policy para spans de Jaeger curl -X PUT "http://elasticsearch:9200/_ilm/policy/jaeger-kyc-span-policy" \ -H 'Content-Type: application/json' -d '{"policy": {"phases": {"hot": {"actions": {"rollover": {"max_age": "1d", "max_size": "5GB"}}}, "delete": {"min_age": "14d", "actions": {"delete": {}}}}}}' # Ejecutar limpieza manual de spans antiguos jaeger-es-rollover init http://elasticsearch:9200 jaeger-es-rollover rollover http://elasticsearch:9200 - Configurar Jaeger como datasource en Grafana para correlación con métricas y logs:
# grafana/provisioning/datasources/jaeger.yml apiVersion: 1 datasources: - name: Jaeger type: jaeger access: proxy url: http://jaeger-query:16686 jsonData: tracesToLogsV2: datasourceUid: loki filterByTraceID: true filterBySpanID: true tracesToMetrics: datasourceUid: prometheus queries: - name: "Request duration" query: "kyc_verification_duration_seconds_bucket{$$__tags}" - Verificar que Jaeger está recibiendo trazas del pipeline KYC:
# Verificar servicios registrados curl -s "http://localhost:16686/api/services" | jq. # Buscar trazas de un servicio específico curl -s "http://localhost:16686/api/traces?service=kyc-face-match&limit=5" | jq '.data[0].spans | length' # Buscar una traza por trace_id curl -s "http://localhost:16686/api/traces/{trace_id}" | jq '.data[0].spans[] | {operationName, duration}'
Notes
- En producción, usar sampling rate de 1.0 (100%) para los módulos críticos de seguridad (liveness, face_match) para garantizar trazabilidad completa de decisiones; módulos menos críticos como OCR pueden usar sampling reducido.
- La retención de 14 días para spans es adecuada para debugging operacional; para requisitos de auditoría, los datos relevantes deben extraerse y almacenarse en el sistema de logs de auditoría con retención de 1 año.
- Jaeger UI permite visualizar el flujo completo de una verificación KYC como un trace waterfall, mostrando la latencia de cada módulo (liveness, OCR, face_match, antifraud, decision) y facilitando la identificación de cuellos de botella.