Guía de Observabilidad

Flowker emite trazas, métricas y logs estructurados usando el estándar OpenTelemetry. Esta guía explica qué está disponible, cómo habilitarlo y cómo interpretar los datos en tu stack de observabilidad.

Descripción general

La telemetría de Flowker está construida sobre tres señales:

Señal	Backend	Qué cubre
Trazas	Tempo	Spans distribuidos a través de ejecuciones de workflows y pasos
Métricas	Prometheus	Tasas de solicitudes HTTP, latencia y uso de recursos del sistema
Logs	Loki	Logs JSON estructurados para cada operación

Todas las señales se exportan vía OTLP (OpenTelemetry Protocol) a un colector de tu elección.

Configuración

La telemetría se controla mediante variables de entorno.

# Habilitar telemetría (requerido para activar la exportación OTLP)
ENABLE_TELEMETRY=true

# Endpoint del colector OTLP (requerido cuando ENABLE_TELEMETRY=true)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Identidad del servicio
OTEL_RESOURCE_SERVICE_NAME=flowker
OTEL_RESOURCE_SERVICE_VERSION=1.0.0
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=production
OTEL_LIBRARY_NAME=flowker

# Verbosidad de logs: debug | info | warn | error
LOG_LEVEL=info

Si ENABLE_TELEMETRY=true está configurado sin OTEL_EXPORTER_OTLP_ENDPOINT, Flowker fallará al iniciar.

Trazado distribuido

Cada solicitud HTTP y operación interna crea un span de OpenTelemetry. Los spans se propagan a través de toda la cadena de ejecución, por lo que una sola ejecución de workflow produce una traza conectada desde el HTTP handler hasta los pasos individuales del executor.

Convención de nombres de spans

Los spans siguen el patrón <capa>.<recurso>.<operación>: Spans de ejecución

Nombre del span	Descripción
`command.execution.execute`	Span raíz para una ejecución de workflow
`command.execution.execute_executor_node`	Span para cada nodo executor procesado
`command.execution.execute_with_provider_config`	Span para un nodo resuelto con una configuración de provider específica
`command.execution.recover`	Span para la recuperación de ejecuciones incompletas al inicio

Spans de comandos de workflow

Nombre del span	Descripción
`command.workflow.create`	Crear un nuevo workflow
`command.workflow.update`	Actualizar un workflow existente
`command.workflow.activate`	Activar un workflow
`command.workflow.deactivate`	Desactivar un workflow
`command.workflow.clone`	Clonar un workflow
`command.workflow.delete`	Eliminar un workflow

Spans de configuración de executor

Nombre del span	Descripción
`command.executor_config.create`	Crear configuración de executor
`command.executor_config.update`	Actualizar configuración de executor
`command.executor_config.activate`	Activar configuración de executor
`command.executor_config.enable`	Habilitar configuración de executor
`command.executor_config.disable`	Deshabilitar configuración de executor
`command.executor_config.mark_configured`	Marcar executor como configurado
`command.executor_config.mark_tested`	Marcar executor como probado
`command.executor_config.test_connectivity`	Probar conectividad del executor
`command.executor_config.delete`	Eliminar configuración de executor

Spans de configuración de provider

Nombre del span	Descripción
`command.provider_config.create`	Crear configuración de provider
`command.provider_config.update`	Actualizar configuración de provider
`command.provider_config.enable`	Habilitar configuración de provider
`command.provider_config.disable`	Deshabilitar configuración de provider
`command.provider_config.test_connectivity`	Probar conectividad del provider
`command.provider_config.delete`	Eliminar configuración de provider

Spans de consultas

Nombre del span	Descripción
`query.execution.get`	Obtener ejecución por ID
`query.execution.list`	Listar ejecuciones
`query.execution.get_results`	Obtener resultados de ejecución
`query.workflow.get`	Obtener workflow por ID
`query.workflow.get_by_name`	Obtener workflow por nombre
`query.workflow.list`	Listar workflows
`query.executor_config.get`	Obtener configuración de executor por ID
`query.executor_config.get_by_name`	Obtener configuración de executor por nombre
`query.executor_config.list`	Listar configuraciones de executor
`query.executor_config.exists`	Verificar existencia de configuración de executor
`query.executor_config.exists_by_name`	Verificar existencia de configuración de executor por nombre
`query.provider_config.get`	Obtener configuración de provider por ID
`query.provider_config.list`	Listar configuraciones de provider

En Grafana Tempo, busca por nombre de servicio (flowker) y filtra por nombre de span para aislar operaciones específicas. Usa command.execution.execute como punto de entrada para ver una traza completa del workflow.

Métricas

Flowker expone métricas HTTP y del sistema automáticamente a través del SDK de OpenTelemetry. No se necesita configuración adicional más allá de habilitar la telemetría.

Métricas HTTP (vía otelfiber)

Recopiladas por ruta mediante el middleware otelfiber:

Métrica	Tipo	Descripción
`http.server.duration`	Histograma	Duración de la solicitud en milisegundos
`http.server.request.size`	Histograma	Tamaño del payload de la solicitud en bytes
`http.server.response.size`	Histograma	Tamaño del payload de la respuesta en bytes
`http.server.active_requests`	UpDownCounter	Número de solicitudes en curso

Cada métrica incluye las etiquetas: http.method, http.route, http.status_code.

Métricas del sistema

Métrica	Tipo	Unidad	Descripción
`system.cpu.usage`	Gauge	porcentaje	Uso de CPU del host del proceso
`system.mem.usage`	Gauge	porcentaje	Uso de memoria del host del proceso

Buckets de histograma

Los histogramas de latencia usan los siguientes límites de bucket (en segundos):

0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10

Flowker no expone un endpoint de scraping de Prometheus (/metrics) directamente. Las métricas se exportan vía OTLP a tu colector, que luego las reenvía a Prometheus. Configura tu colector OTLP para incluir un exportador prometheusremotewrite.

Logging estructurado

Flowker usa logging JSON estructurado a través de Zap. Cada entrada de log se enriquece con campos contextuales que pueden indexarse y consultarse en Loki.

Referencia de campos de log

Campo	Descripción	Ejemplo
`operation`	Nombre del span/operación	`command.execution.execute`
`workflow.id`	Identificador del workflow	`wf_abc123`
`execution.id`	Identificador de la ejecución	`exec_xyz789`
`node.id`	Identificador del nodo dentro de un workflow	`node-payment`
`executor.id`	Identificador del executor	`exec_cfg_001`
`error.message`	Descripción del error cuando aplica	`database ping failed: ...`

Niveles de log

Nivel	Cuándo se usa
`debug`	Estado interno detallado — solo para desarrollo
`info`	Hitos normales de operación (ejecución iniciada, recuperada, etc.)
`warn`	Problemas recuperables o condiciones inesperadas pero no fatales
`error`	Fallos de operación que requieren atención

Configura la variable de entorno LOG_LEVEL para controlar la verbosidad.

Ejemplos de entradas de log

Ejecución de workflow iniciada:

{
  "level": "info",
  "operation": "command.execution.execute",
  "workflow.id": "wf_abc123",
  "message": "Starting workflow execution"
}

Recuperación de ejecución incompleta:

{
  "level": "info",
  "operation": "command.execution.recover",
  "count": 3,
  "message": "Recovering incomplete executions"
}

Ejecución fallida:

{
  "level": "error",
  "execution.id": "exec_xyz789",
  "workflow.id": "wf_abc123",
  "execution.status": "failed",
  "error.message": "executor node missing providerConfigId",
  "message": "Workflow execution failed"
}

Endpoints de salud

Flowker expone tres endpoints de salud para monitoreo operacional y configuración de sondas de Kubernetes.

GET /health

Verificación de salud combinada. Retorna el estado del servicio, versión, tiempo de actividad y verificaciones de dependencias. Respuesta (saludable):

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": "4h32m15s",
  "timestamp": "2024-11-01T14:32:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "database connection ok"
    }
  }
}

Respuesta (no saludable — status 503):

{
  "status": "unhealthy",
  "timestamp": "2024-11-01T14:32:00Z",
  "checks": {
    "database": {
      "status": "unhealthy",
      "message": "database ping failed: connection refused"
    }
  }
}

GET /health/live

Sonda de liveness de Kubernetes. Retorna 200 OK si el proceso está en ejecución. No verifica dependencias.

{
  "status": "alive",
  "timestamp": "2024-11-01T14:32:00Z"
}

GET /health/ready

Sonda de readiness de Kubernetes. Retorna 200 OK cuando todas las dependencias están saludables. Retorna 503 Service Unavailable cuando la base de datos no está disponible.

{
  "status": "ready",
  "timestamp": "2024-11-01T14:32:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "database connection ok"
    }
  }
}

Configuración de sondas de Kubernetes

livenessProbe:
  httpGet:
    path: /health/live
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10

Usa /health/live para la sonda de liveness (reiniciar ante procesos bloqueados) y /health/ready para la sonda de readiness (remover del load balancer cuando la base de datos no está disponible). Usa /health para verificaciones manuales y dashboards de monitoreo.

Dashboards de Grafana

La telemetría de Flowker se integra directamente con el stack de observabilidad de Lerian. Los dashboards pre-configurados están disponibles a través de la instancia de Grafana administrada por Lerian.

Paneles recomendados

Throughput de solicitudes

Query: sum(rate(http_server_duration_count{service_name="flowker"}[5m])) by (http_route)
Muestra solicitudes por segundo, desglosadas por ruta

Latencia P95

Query: histogram_quantile(0.95, sum(rate(http_server_duration_bucket{service_name="flowker"}[5m])) by (le, http_route))
Muestra el percentil 95 del tiempo de respuesta por ruta

Tasa de errores

Query: sum(rate(http_server_duration_count{service_name="flowker", http_status_code=~"5.."}[5m])) / sum(rate(http_server_duration_count{service_name="flowker"}[5m]))
Muestra la proporción de respuestas 5xx

Ejecuciones activas (vía logs)

Loki query: {service_name="flowker"} |= "Starting workflow execution" | count_over_time([1m])

Para la configuración completa del stack de observabilidad, consulta Plataforma → Observabilidad.

​Descripción general

​Configuración

​Trazado distribuido

​Convención de nombres de spans

​Métricas

​Métricas HTTP (vía otelfiber)

​Métricas del sistema

​Buckets de histograma

​Logging estructurado

​Referencia de campos de log

​Niveles de log

​Ejemplos de entradas de log

​Endpoints de salud

​GET /health

​GET /health/live

​GET /health/ready

​Configuración de sondas de Kubernetes

​Dashboards de Grafana

​Paneles recomendados

Descripción general

Configuración

Trazado distribuido

Convención de nombres de spans

Métricas

Métricas HTTP (vía otelfiber)

Métricas del sistema

Buckets de histograma

Logging estructurado

Referencia de campos de log

Niveles de log

Ejemplos de entradas de log

Endpoints de salud

GET /health

GET /health/live

GET /health/ready

Configuración de sondas de Kubernetes

Dashboards de Grafana

Paneles recomendados