promtail_vector

Configura agentes de recolección de logs como Promtail o Vector para capturar y enviar los logs generados por todos los microservicios del pipeline de verificación de identidad hacia Grafana Loki. Esto permite centralizar logs de módulos como liveness detection, OCR, face_match y antifraud en un único sistema consultable. Soporta etiquetado automático por servicio, entorno y nivel de severidad.

When to use

Usar este skill cuando el observability_agent necesite configurar la recolección y envío centralizado de logs desde los servicios del pipeline KYC hacia Loki. Aplica tanto para despliegues Docker Compose como Kubernetes.

Instructions

1. Elegir el agente de recolección según el entorno. Promtail es nativo de Loki; Vector es más flexible y soporta múltiples destinos:

``yaml # docker-compose.yml - Promtail promtail: image: grafana/promtail:2.9.0 volumes: - /var/log:/var/log - ./promtail-config.yml:/etc/promtail/config.yml command: -config.file=/etc/promtail/config.yml ``

1. Configurar Promtail para descubrir y etiquetar logs de los contenedores del pipeline KYC:

``yaml # promtail-config.yml server: httplistenport: 9080 positions: filename: /tmp/positions.yaml clients: - url: http://loki:3100/loki/api/v1/push scrapeconfigs: - jobname: kyc-pipeline dockersdconfigs: - host: unix:///var/run/docker.sock relabelconfigs: - sourcelabels: ['__metadockercontainername'] targetlabel: 'service' - source_labels: ['__metadockercontainerlabelmodule'] target_label: 'module' ``

1. Alternativamente, configurar Vector como agente de recolección con transformaciones:

```toml # vector.toml [sources.kyclogs] type = "dockerlogs" includecontainers = ["liveness", "ocr", "facematch", "antifraud", "decision"]

[transforms.parsejson] type = "remap" inputs = ["kyclogs"] source = ''' . = parsejson!(.message) .service = .containername '''

[sinks.loki] type = "loki" inputs = ["parse_json"] endpoint = "http://loki:3100"; labels.service = "{{ service }}" labels.level = "{{ level }}" ```

1. Asegurar que todos los servicios FastAPI del pipeline emitan logs en formato JSON estructurado:

```python import logging import json_logging

jsonlogging.initfastapi(enable_json=True) logger = logging.getLogger("kyc-pipeline") logger.setLevel(logging.INFO) ```

1. Configurar labels diferenciados por módulo KYC para facilitar filtrado en Loki:

``yaml labels: service: "face_match" module: "biometric" environment: "production" pipeline: "kyc" ``

1. Verificar la conectividad y el flujo de logs consultando Loki directamente:

``bash curl -G "http://loki:3100/loki/api/v1/query"; \ --data-urlencode 'query={service="liveness"}' | jq . ``

1. En Kubernetes, desplegar Promtail como DaemonSet para capturar logs de todos los nodos:

``bash helm install promtail grafana/promtail \ --set config.clients[0].url=http://loki:3100/loki/api/v1/push \ --set config.snippets.extraScrapeConfigs=$(cat promtail-k8s-scrape.yaml) ``

Notes

• Promtail es la opción más sencilla si el destino es exclusivamente Loki; Vector ofrece mayor flexibilidad si se necesitan múltiples destinos (Loki + Elasticsearch, por ejemplo).
• Los logs del pipeline KYC pueden contener datos sensibles (session_id, resultados biométricos); asegurarse de que el transporte entre agente y Loki use TLS y que no se logueen imágenes ni embeddings.
• Monitorizar el propio agente de recolección con métricas de bytes enviados, errores de push y lag de posición para evitar pérdida silenciosa de logs.