Implementando observabilidad en Flowker

Flowker emite trazas, métricas y logs estructurados utilizando 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 se basa en tres señales:

Señal	Backend	Qué cubre
Trazas	Tempo	Spans distribuidos a través de ejecuciones y pasos de workflows
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 via OTLP (OpenTelemetry Protocol) a un collector de tu elección.

Configuración

La telemetría se controla mediante variables de entorno.

# Enable telemetry (required to activate OTLP export)
ENABLE_TELEMETRY=true

# OTLP collector endpoint (required when ENABLE_TELEMETRY=true)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Service identity
OTEL_RESOURCE_SERVICE_NAME=flowker
OTEL_RESOURCE_SERVICE_VERSION=1.0.0
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=production
OTEL_LIBRARY_NAME=flowker

# Log verbosity: debug | info | warn | error
LOG_LEVEL=info

Si ENABLE_TELEMETRY=true está configurado sin OTEL_EXPORTER_OTLP_ENDPOINT, Flowker no podrá iniciarse.

Trazabilidad distribuida

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 handler HTTP hasta los pasos individuales del executor.

Convención de nombres de spans

Los spans siguen un patrón <layer>.<resource>.<operation>: Spans de ejecución

Nombre del span	Descripción
`command.execution.execute`	Span raíz para la ejecución de un workflow
`command.execution.execute_executor_node`	Span para cada nodo de 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 consulta

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 de 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 (via otelfiber)

Recopiladas por ruta mediante el middleware otelfiber:

Métrica	Tipo	Descripción
`http.server.duration`	Histogram	Duración de la solicitud en milisegundos
`http.server.request.size`	Histogram	Tamaño del payload de la solicitud en bytes
`http.server.response.size`	Histogram	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 utilizan 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 scrape de Prometheus (/metrics) directamente. Las métricas se exportan via OTLP a tu collector, que luego las envía a Prometheus. Configura tu collector OTLP para incluir un exportador prometheusremotewrite.

Logging estructurado

Flowker utiliza logging JSON estructurado via Zap. Cada entrada de log se enriquece con campos contextuales que pueden ser indexados y consultados 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 de operación normal (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 ejecuciones incompletas:

{
  "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"
}

Sondas de salud

Flowker expone sondas de liveness y readiness compatibles con Kubernetes para monitoreo operacional. Liveness indica si el proceso está en ejecución; readiness indica si las dependencias (notablemente la base de datos) están accesibles. Configura ambas a nivel del cluster, como parte de tus manifiestos de despliegue, para que la orquestación pueda reiniciar pods no saludables y remover instancias degradadas de los balanceadores de carga.

Dashboards de Grafana

La telemetría de Flowker se integra directamente con el stack de observabilidad de Lerian. Los dashboards preconfigurados 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 tiempo de respuesta del percentil 95 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 (via 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.

Primeros pasos

API de Catálogo

API de Workflows

API de Ejecuciones

API de Dashboards

API de Configuraciones de Executor

API de Configuraciones de Provider

API de Auditoría

API de Webhooks

Manejo de errores

Implementando observabilidad en Flowker

Descripción general

Configuración

Trazabilidad distribuida

Convención de nombres de spans

Métricas

Métricas HTTP (via otelfiber)

Métricas del sistema

Buckets de histograma

Logging estructurado

Referencia de campos de log

Niveles de log

Ejemplos de entradas de log

Sondas de salud

Dashboards de Grafana

Paneles recomendados

​Descripción general

​Configuración

​Trazabilidad distribuida

​Convención de nombres de spans

​Métricas

​Métricas HTTP (via otelfiber)

​Métricas del sistema

​Buckets de histograma

​Logging estructurado

​Referencia de campos de log

​Niveles de log

​Ejemplos de entradas de log

​Sondas de salud

​Dashboards de Grafana

​Paneles recomendados

Descripción general

Configuración

Trazabilidad distribuida

Convención de nombres de spans

Métricas

Métricas HTTP (via otelfiber)

Métricas del sistema

Buckets de histograma

Logging estructurado

Referencia de campos de log

Niveles de log

Ejemplos de entradas de log

Sondas de salud

Dashboards de Grafana

Paneles recomendados