Implementando observabilidade no Flowker

O Flowker emite traces, métricas e logs estruturados usando o padrão OpenTelemetry.

Visão geral

A telemetria do Flowker usa três sinais:

Sinal	Backend	O que cobre
Traces	Tempo	Spans distribuídos entre execuções de workflow e etapas
Metrics	Prometheus	Taxas de requisições HTTP, latência e uso de recursos do sistema
Logs	Loki	Logs JSON estruturados para cada operação

O Flowker exporta todos os sinais via OTLP (OpenTelemetry Protocol) para um collector de sua escolha.

Configuração

Variáveis de ambiente controlam a telemetria.

# 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

Se você definir ENABLE_TELEMETRY=true sem OTEL_EXPORTER_OTLP_ENDPOINT, o Flowker não vai iniciar.

Tracing distribuído

Toda requisição HTTP e operação interna cria um span do OpenTelemetry. Os spans se propagam por toda a cadeia de execução. Uma única execução de workflow produz um trace conectado, do handler HTTP até as etapas individuais do executor.

Convenção de nomenclatura de spans

Os spans seguem o padrão <layer>.<resource>.<operation>: Spans de execução

Nome do span	Descrição
`command.execution.execute`	Span raiz para uma execução de workflow
`command.execution.execute_executor_node`	Span para cada nó de executor processado
`command.execution.execute_with_provider_config`	Span para um nó resolvido com uma configuração de provedor específica
`command.execution.recover`	Span para recuperação de execução incompleta na inicialização

Spans de comando de workflow

Nome do span	Descrição
`command.workflow.create`	Cria um novo workflow
`command.workflow.update`	Atualiza um workflow existente
`command.workflow.activate`	Ativa um workflow
`command.workflow.deactivate`	Desativa um workflow
`command.workflow.move_to_draft`	Move um workflow de volta para rascunho
`command.workflow.clone`	Clona um workflow
`command.workflow.delete`	Exclui um workflow

Spans de configuração de executor

Nome do span	Descrição
`command.executor_config.update`	Atualiza a configuração de executor
`command.executor_config.delete`	Exclui a configuração de executor

Spans de configuração de provedor

Nome do span	Descrição
`command.provider_config.create`	Cria a configuração de provedor
`command.provider_config.update`	Atualiza a configuração de provedor
`command.provider_config.enable`	Habilita a configuração de provedor
`command.provider_config.disable`	Desabilita a configuração de provedor
`command.provider_config.delete`	Exclui a configuração de provedor

Spans de consulta

Nome do span	Descrição
`query.execution.get`	Obtém a execução pelo ID
`query.execution.list`	Lista execuções
`query.execution.get_results`	Obtém os resultados da execução
`query.workflow.get`	Obtém o workflow pelo ID
`query.workflow.list`	Lista workflows
`query.executor_config.get`	Obtém a configuração de executor pelo ID
`query.executor_config.list`	Lista configurações de executor
`query.provider_config.get`	Obtém a configuração de provedor pelo ID
`query.provider_config.list`	Lista configurações de provedor

No Grafana Tempo, busque pelo nome do serviço (flowker) e filtre pelo nome do span para isolar operações específicas. Use command.execution.execute como ponto de entrada para ver o trace completo de um workflow.

Métricas

O Flowker expõe métricas HTTP e do sistema automaticamente via o SDK do OpenTelemetry. Você apenas precisa habilitar a telemetria.

Métricas HTTP (via otelfiber)

Coletadas por rota pelo middleware otelfiber:

Métrica	Tipo	Descrição
`http.server.duration`	Histogram	Duração da requisição em milissegundos
`http.server.request.size`	Histogram	Tamanho do payload da requisição em bytes
`http.server.response.size`	Histogram	Tamanho do payload da resposta em bytes
`http.server.active_requests`	UpDownCounter	Número de requisições em andamento

Cada métrica carrega labels: http.request.method, http.route, http.response.status_code.

Métricas do sistema

Métrica	Tipo	Unidade	Descrição
`system.cpu.usage`	Gauge	porcentagem	Uso de CPU do host do processo
`system.mem.usage`	Gauge	porcentagem	Uso de memória do host do processo

Buckets de histograma

Histogramas de latência usam os limites de bucket padrão do SDK do OpenTelemetry. Os valores de http.server.duration estão em milissegundos, então os limites são:

0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000

O Flowker não expõe diretamente um endpoint de scrape do Prometheus (/metrics). O Flowker exporta métricas via OTLP para seu collector, que então encaminha ao Prometheus. Configure seu collector OTLP para incluir um exporter prometheusremotewrite.

Logging estruturado

O Flowker usa logging JSON estruturado via Zap. Toda entrada de log carrega campos contextuais. Você pode indexar e consultar esses campos no Loki.

Referência de campos de log

Campo	Descrição	Exemplo
`operation`	Nome do span/operação	`command.execution.execute`
`workflow.id`	Identificador do workflow	`wf_abc123`
`execution.id`	Identificador da execução	`exec_xyz789`
`node.id`	Identificador do nó dentro de um workflow	`node-payment`
`executor.id`	Identificador do executor	`exec_cfg_001`
`error.message`	Descrição do erro, quando aplicável	`database ping failed: ...`

Níveis de log

Nível	Quando é usado
`debug`	Estado interno detalhado — apenas para desenvolvimento
`info`	Marcos de operação normal (execução iniciada, recuperada, etc.)
`warn`	Problemas recuperáveis ou condições inesperadas, mas não fatais
`error`	Falhas de operação que exigem atenção

Defina a variável de ambiente LOG_LEVEL para controlar a verbosidade.

Exemplos de entradas de log

Execução de workflow iniciada:

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

Recuperação de execução incompleta:

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

Nó de executor mal configurado:

{
  "level": "error",
  "node.id": "node-payment",
  "execution.id": "exec_xyz789",
  "message": "Executor node missing providerConfigId"
}

Probes de saúde

O Flowker expõe probes de liveness e readiness compatíveis com Kubernetes para monitoramento operacional. Liveness sinaliza se o processo ainda está em execução. Readiness sinaliza se as dependências (principalmente o banco de dados) estão acessíveis. Configure ambas no nível do cluster como parte dos seus manifestos de deploy. A orquestração pode então reiniciar pods não saudáveis e remover instâncias degradadas dos balanceadores de carga.

Dashboards do Grafana

A telemetria do Flowker se integra diretamente à stack de observabilidade da Lerian. Dashboards pré-configurados estão disponíveis por meio da instância do Grafana gerenciada pela Lerian.

Painéis recomendados

Throughput de requisições

Consulta: sum(rate(http_server_duration_count{service_name="flowker"}[5m])) by (http_route)
Mostra requisições por segundo, detalhadas por rota

Latência P95

Consulta: histogram_quantile(0.95, sum(rate(http_server_duration_bucket{service_name="flowker"}[5m])) by (le, http_route))
Mostra o tempo de resposta no percentil 95 por rota

Taxa de erro

Consulta: sum(rate(http_server_duration_count{service_name="flowker", http_response_status_code=~"5.."}[5m])) / sum(rate(http_server_duration_count{service_name="flowker"}[5m]))
Mostra a proporção de respostas 5xx

Execuções ativas (via logs)

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

Para a configuração completa da stack de observabilidade, veja Plataforma → Observabilidade.

Primeiros passos

API de Catálogo

API de Workflows

API de Agendamento

API de Execuções

API de Dashboards

API de Configurações de Executor

API de Configurações de Provider

API de Registro de Esquemas

API de Esquemas OpenAPI

API de Esquemas XSD

API de Webhooks

Tratamento de erros

Implementando observabilidade no Flowker

Visão geral

Configuração

Tracing distribuído

Convenção de nomenclatura de spans

Métricas

Métricas HTTP (via otelfiber)

Métricas do sistema

Buckets de histograma

Logging estruturado

Referência de campos de log

Níveis de log

Exemplos de entradas de log

Probes de saúde

Dashboards do Grafana

Painéis recomendados

​Visão geral

​Configuração

​Tracing distribuído

​Convenção de nomenclatura de spans

​Métricas

​Métricas HTTP (via otelfiber)

​Métricas do sistema

​Buckets de histograma

​Logging estruturado

​Referência de campos de log

​Níveis de log

​Exemplos de entradas de log

​Probes de saúde

​Dashboards do Grafana

​Painéis recomendados

Visão geral

Configuração

Tracing distribuído

Convenção de nomenclatura de spans

Métricas

Métricas HTTP (via otelfiber)

Métricas do sistema

Buckets de histograma

Logging estruturado

Referência de campos de log

Níveis de log

Exemplos de entradas de log

Probes de saúde

Dashboards do Grafana

Painéis recomendados