Guia de Observabilidade

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 no seu 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 por execuções de workflows e steps
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.

# Habilitar telemetria (obrigatório para ativar a exportação OTLP)
ENABLE_TELEMETRY=true

# Endpoint do collector OTLP (obrigatório quando ENABLE_TELEMETRY=true)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Identidade do serviço
OTEL_RESOURCE_SERVICE_NAME=flowker
OTEL_RESOURCE_SERVICE_VERSION=1.0.0
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=production
OTEL_LIBRARY_NAME=flowker

# Verbosidade dos logs: debug | info | warn | error
LOG_LEVEL=info

Se ENABLE_TELEMETRY=true estiver configurado sem OTEL_EXPORTER_OTLP_ENDPOINT, o Flowker falhará ao iniciar.

Rastreamento distribuído

Cada requisição HTTP e operação interna cria um span do 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 HTTP handler até os steps individuais do executor.

Convenção de nomes de spans

Os spans seguem o padrão <camada>.<recurso>.<operação>: 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 consultas

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 de 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, busque pelo nome do serviço (flowker) e filtre por nome do span para isolar operações específicas. Use command.execution.execute como ponto de entrada para ver um trace completo do workflow.

Métricas

O Flowker expõe métricas HTTP e do sistema automaticamente via SDK do 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`	Histograma	Duração da requisição em milissegundos
`http.server.request.size`	Histograma	Tamanho do payload da requisição em bytes
`http.server.response.size`	Histograma	Tamanho do payload da resposta em bytes
`http.server.active_requests`	UpDownCounter	Número de requisições em andamento

Cada métrica inclui os labels: http.method, http.route, http.status_code.

Métricas do sistema

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

Buckets de histograma

Histogramas de latência usam 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 scraping do Prometheus (/metrics) diretamente. As métricas são exportadas via OTLP para o seu collector, que as repassa ao Prometheus. Configure seu collector OTLP para incluir um exportador prometheusremotewrite.

Logging estruturado

O Flowker usa logging JSON estruturado 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 usado
`debug`	Estado interno detalhado — apenas para desenvolvimento
`info`	Marcos normais de operação (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

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

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

Endpoints de saúde

O Flowker expõe três endpoints de saúde para monitoramento operacional e configuração de probes do Kubernetes.

GET /health

Verificação de saúde combinada. Retorna o status do serviço, versão, uptime e verificações de dependências. Resposta (saudável):

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

Resposta (não saudável — status 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 do Kubernetes. Retorna 200 OK se o processo está em execução. Não verifica dependências.

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

GET /health/ready

Probe de readiness do Kubernetes. Retorna 200 OK quando todas as dependências estão saudáveis. Retorna 503 Service Unavailable quando o banco de dados está indisponível.

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

Configuração de probes do Kubernetes

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

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

Use /health/live para a probe de liveness (reiniciar em processos travados) e /health/ready para a probe de readiness (remover do load balancer quando o banco de dados está indisponível). Use /health para verificações manuais e dashboards de monitoramento.

Dashboards do Grafana

A telemetria do Flowker se integra diretamente com o stack de observabilidade da Lerian. Dashboards pré-configurados estão disponíveis através da instância do 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, 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 percentil 95 do tempo de resposta 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)

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

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

​Visão geral

​Configuração

​Rastreamento distribuído

​Convenção de nomes 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

​Endpoints de saúde

​GET /health

​GET /health/live

​GET /health/ready

​Configuração de probes do Kubernetes

​Dashboards do Grafana

​Painéis recomendados

Visão geral

Configuração

Rastreamento distribuído

Convenção de nomes 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

Endpoints de saúde

GET /health

GET /health/live

GET /health/ready

Configuração de probes do Kubernetes

Dashboards do Grafana

Painéis recomendados