Implementando observabilidade no Flowker

O Flowker emite traces, métricas e logs estruturados usando o padrão OpenTelemetry. Este guia explica o que está disponível, como habilitar e como interpretar os dados na sua stack de observabilidade.

Visão geral

A telemetria do Flowker é construída sobre três sinais:

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

Todos os sinais são exportados via OTLP (OpenTelemetry Protocol) para um collector de sua escolha.

Configuração

A telemetria é controlada por variáveis de ambiente.

# 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 ENABLE_TELEMETRY=true estiver definido sem OTEL_EXPORTER_OTLP_ENDPOINT, o Flowker falhará ao iniciar.

Rastreamento distribuído

Cada requisição HTTP e operação interna cria um span OpenTelemetry. Os spans são propagados por toda a cadeia de execução, de modo que uma única execução de workflow produz um trace conectado desde o handler HTTP até as etapas individuais do executor.

Convenção de nomenclatura dos 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ó executor processado
`command.execution.execute_with_provider_config`	Span para um nó resolvido com uma configuração de provider específica
`command.execution.recover`	Span para recuperação de execuções incompletas na inicialização

Spans de comandos de workflow

Nome do span	Descrição
`command.workflow.create`	Criar um novo workflow
`command.workflow.update`	Atualizar um workflow existente
`command.workflow.activate`	Ativar um workflow
`command.workflow.deactivate`	Desativar um workflow
`command.workflow.clone`	Clonar um workflow
`command.workflow.delete`	Excluir um workflow

Spans de configuração de executor

Nome do span	Descrição
`command.executor_config.create`	Criar configuração de executor
`command.executor_config.update`	Atualizar configuração de executor
`command.executor_config.activate`	Ativar configuração de executor
`command.executor_config.enable`	Habilitar configuração de executor
`command.executor_config.disable`	Desabilitar configuração de executor
`command.executor_config.mark_configured`	Marcar executor como configurado
`command.executor_config.mark_tested`	Marcar executor como testado
`command.executor_config.test_connectivity`	Testar conectividade do executor
`command.executor_config.delete`	Excluir configuração de executor

Spans de configuração de provider

Nome do span	Descrição
`command.provider_config.create`	Criar configuração de provider
`command.provider_config.update`	Atualizar configuração de provider
`command.provider_config.enable`	Habilitar configuração de provider
`command.provider_config.disable`	Desabilitar configuração de provider
`command.provider_config.test_connectivity`	Testar conectividade do provider
`command.provider_config.delete`	Excluir configuração de provider

Spans de consulta

Nome do span	Descrição
`query.execution.get`	Obter execução por ID
`query.execution.list`	Listar execuções
`query.execution.get_results`	Obter resultados da execução
`query.workflow.get`	Obter workflow por ID
`query.workflow.get_by_name`	Obter workflow por nome
`query.workflow.list`	Listar workflows
`query.executor_config.get`	Obter configuração de executor por ID
`query.executor_config.get_by_name`	Obter configuração de executor por nome
`query.executor_config.list`	Listar configurações de executor
`query.executor_config.exists`	Verificar existência de configuração de executor
`query.executor_config.exists_by_name`	Verificar existência de configuração de executor por nome
`query.provider_config.get`	Obter configuração de provider por ID
`query.provider_config.list`	Listar configurações de provider

No Grafana Tempo, pesquise 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 um trace completo de workflow.

Métricas

O Flowker expõe métricas HTTP e de sistema automaticamente via o SDK OpenTelemetry. Nenhuma configuração adicional é necessária além de 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 possui os labels: http.method, http.route, http.status_code.

Métricas de 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

Os histogramas de latência utilizam os seguintes limites de bucket (em segundos):

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

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

Logs estruturados

O Flowker utiliza logs JSON estruturados via Zap. Cada entrada de log é enriquecida com campos contextuais que podem ser indexados e consultados 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 é utilizado
`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 requerem 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ções incompletas:

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

Execução com falha:

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

Probes de saúde

O Flowker expõe probes de liveness e readiness compatíveis com Kubernetes para monitoramento operacional. Liveness indica se o processo está em execução; readiness indica se as dependências (notadamente o banco de dados) estão acessíveis. Configure ambos no nível do cluster, como parte dos seus manifestos de deployment, para que a orquestração possa reiniciar pods não saudáveis e remover instâncias degradadas dos load balancers.

Dashboards do Grafana

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

Painéis recomendados

Throughput de requisições

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

Latência P95

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

Taxa de erros

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]))
Mostra a proporção de respostas 5xx

Execuções ativas (via logs)

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

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

Primeiros passos

API de Catálogo

API de Workflows

API de Execuções

API de Dashboards

API de Configurações de Executor

API de Configurações de Provider

API de Auditoria

API de Webhooks

Tratamento de erros

Implementando observabilidade no Flowker

Visão geral

Configuração

Rastreamento distribuído

Convenção de nomenclatura dos spans

Métricas

Métricas HTTP (via otelfiber)

Métricas de sistema

Buckets de histograma

Logs estruturados

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

​Rastreamento distribuído

​Convenção de nomenclatura dos spans

​Métricas

​Métricas HTTP (via otelfiber)

​Métricas de sistema

​Buckets de histograma

​Logs estruturados

​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

Rastreamento distribuído

Convenção de nomenclatura dos spans

Métricas

Métricas HTTP (via otelfiber)

Métricas de sistema

Buckets de histograma

Logs estruturados

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