prometheus_client

Cliente Python de Prometheus para instrumentar el codigo del pipeline de verificacion de identidad KYC con metricas custom. Permite definir contadores de verificaciones exitosas y fallidas, histogramas de latencia por modulo (liveness, OCR, face match), y gauges para monitorear el estado de modelos ML cargados en memoria.

When to use

Usa esta skill cuando necesites instrumentar los microservicios del pipeline KYC con metricas de Prometheus. Pertenece al observability_agent y se aplica cuando hay que exponer metricas custom desde el codigo Python (FastAPI) para que Prometheus las recolecte.

Instructions

1. Instalar la libreria del cliente de Prometheus para Python:

``bash pip install prometheus-client ``

1. Definir las metricas custom en un modulo compartido del backend:

```python from prometheus_client import Counter, Histogram, Gauge

VERIFICATIONTOTAL = Counter( 'kycverifications_total', 'Total de verificaciones KYC procesadas', ['status', 'module'] )

VERIFICATIONLATENCY = Histogram( 'kycverificationdurationseconds', 'Latencia de cada etapa de verificacion', ['stage'], buckets=[0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 8.0] )

MODELSLOADED = Gauge( 'kycmodelsloaded', 'Numero de modelos ML actualmente cargados', ['modelname'] ) ```

1. Instrumentar los endpoints de FastAPI con las metricas definidas:

```python from prometheusclient import starthttp_server

@app.onevent("startup") async def startup(): starthttp_server(9090) # Puerto dedicado para metricas ```

1. Registrar contadores en cada paso del pipeline de verificacion:

``python @app.post("/api/v1/verify") async def verifyidentity(session: VerificationSession): with VERIFICATIONLATENCY.labels(stage="liveness").time(): livenessresult = await livenessmodule.check(session) VERIFICATIONTOTAL.labels(status=livenessresult.status, module="liveness").inc() ``

1. Actualizar los gauges cuando se carguen o descarguen modelos de inferencia:

``python def loadmodel(modelname: str): model = loadinsightfacemodel(modelname) MODELSLOADED.labels(modelname=modelname).set(1) return model ``

1. Agregar metricas de negocio especificas del KYC como tasa de fraude detectado:

``python FRAUDDETECTED = Counter( 'kycfrauddetectedtotal', 'Intentos de fraude detectados', ['fraudtype'] # deepfake, printedphoto, screen_replay, mask ) ``

1. Configurar el scrape en Prometheus apuntando al puerto de metricas:

``yaml scrapeconfigs: - jobname: 'kyc-pipeline' scrapeinterval: 15s staticconfigs: - targets: ['kyc-backend:9090'] ``

1. Validar que las metricas se exponen correctamente accediendo al endpoint /metrics y verificando que los tipos (counter, histogram, gauge) son correctos.

Notes

• Los histogramas de latencia deben tener buckets alineados con el objetivo de respuesta total de 8 segundos definido en los criterios de calidad del sistema.
• Evitar alta cardinalidad en las labels; no usar sessionid como label ya que generaria series temporales ilimitadas. Usar labels categoricas como status, module o fraudtype.
• Las metricas deben exponerse en un puerto separado del API principal para no interferir con el trafico de verificacion y facilitar el acceso desde Prometheus sin exponer endpoints de negocio.