Saltar al contenido principal
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ñalBackendQué cubre
TrazasTempoSpans distribuidos a través de ejecuciones y pasos de workflows
MétricasPrometheusTasas de solicitudes HTTP, latencia y uso de recursos del sistema
LogsLokiLogs 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 spanDescripción
command.execution.executeSpan raíz para la ejecución de un workflow
command.execution.execute_executor_nodeSpan para cada nodo de executor procesado
command.execution.execute_with_provider_configSpan para un nodo resuelto con una configuración de provider específica
command.execution.recoverSpan para la recuperación de ejecuciones incompletas al inicio
Spans de comandos de workflow
Nombre del spanDescripción
command.workflow.createCrear un nuevo workflow
command.workflow.updateActualizar un workflow existente
command.workflow.activateActivar un workflow
command.workflow.deactivateDesactivar un workflow
command.workflow.cloneClonar un workflow
command.workflow.deleteEliminar un workflow
Spans de configuración de executor
Nombre del spanDescripción
command.executor_config.createCrear configuración de executor
command.executor_config.updateActualizar configuración de executor
command.executor_config.activateActivar configuración de executor
command.executor_config.enableHabilitar configuración de executor
command.executor_config.disableDeshabilitar configuración de executor
command.executor_config.mark_configuredMarcar executor como configurado
command.executor_config.mark_testedMarcar executor como probado
command.executor_config.test_connectivityProbar conectividad del executor
command.executor_config.deleteEliminar configuración de executor
Spans de configuración de provider
Nombre del spanDescripción
command.provider_config.createCrear configuración de provider
command.provider_config.updateActualizar configuración de provider
command.provider_config.enableHabilitar configuración de provider
command.provider_config.disableDeshabilitar configuración de provider
command.provider_config.test_connectivityProbar conectividad del provider
command.provider_config.deleteEliminar configuración de provider
Spans de consulta
Nombre del spanDescripción
query.execution.getObtener ejecución por ID
query.execution.listListar ejecuciones
query.execution.get_resultsObtener resultados de ejecución
query.workflow.getObtener workflow por ID
query.workflow.get_by_nameObtener workflow por nombre
query.workflow.listListar workflows
query.executor_config.getObtener configuración de executor por ID
query.executor_config.get_by_nameObtener configuración de executor por nombre
query.executor_config.listListar configuraciones de executor
query.executor_config.existsVerificar existencia de configuración de executor
query.executor_config.exists_by_nameVerificar existencia de configuración de executor por nombre
query.provider_config.getObtener configuración de provider por ID
query.provider_config.listListar 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étricaTipoDescripción
http.server.durationHistogramDuración de la solicitud en milisegundos
http.server.request.sizeHistogramTamaño del payload de la solicitud en bytes
http.server.response.sizeHistogramTamaño del payload de la respuesta en bytes
http.server.active_requestsUpDownCounterNúmero de solicitudes en curso
Cada métrica incluye las etiquetas: http.method, http.route, http.status_code.

​
Métricas del sistema

MétricaTipoUnidadDescripción
system.cpu.usageGaugeporcentajeUso de CPU del host del proceso
system.mem.usageGaugeporcentajeUso 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

CampoDescripciónEjemplo
operationNombre del span/operacióncommand.execution.execute
workflow.idIdentificador del workflowwf_abc123
execution.idIdentificador de la ejecuciónexec_xyz789
node.idIdentificador del nodo dentro de un workflownode-payment
executor.idIdentificador del executorexec_cfg_001
error.messageDescripción del error cuando aplicadatabase ping failed: ...

​
Niveles de log

NivelCuándo se usa
debugEstado interno detallado — solo para desarrollo
infoHitos de operación normal (ejecución iniciada, recuperada, etc.)
warnProblemas recuperables o condiciones inesperadas pero no fatales
errorFallos 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"
}

​
Endpoints de salud

Flowker expone tres endpoints de salud para monitoreo operativo y configuración de probes 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 — estado 503): 
{
  "status": "unhealthy",
  "timestamp": "2024-11-01T14:32:00Z",
  "checks": {
    "database": {
      "status": "unhealthy",
      "message": "database ping failed: connection refused"
    }
  }
}

​
GET /health/live

Probe 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

Probe 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á accesible. 
{
  "status": "ready",
  "timestamp": "2024-11-01T14:32:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "message": "database connection ok"
    }
  }
}

​
Configuración de probes 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 el probe de liveness (reiniciar en caso de bloqueo del proceso) y /health/ready para el probe de readiness (remover del balanceador de carga 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 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.