Pular para o conteúdo principal
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:
SinalBackendO que cobre
TracesTempoSpans distribuídos entre execuções e etapas de workflows
MétricasPrometheusTaxas de requisições HTTP, latência e uso de recursos do sistema
LogsLokiLogs 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 spanDescrição
command.execution.executeSpan raiz para uma execução de workflow
command.execution.execute_executor_nodeSpan para cada nó executor processado
command.execution.execute_with_provider_configSpan para um nó resolvido com uma configuração de provider específica
command.execution.recoverSpan para recuperação de execuções incompletas na inicialização
Spans de comandos de workflow
Nome do spanDescrição
command.workflow.createCriar um novo workflow
command.workflow.updateAtualizar um workflow existente
command.workflow.activateAtivar um workflow
command.workflow.deactivateDesativar um workflow
command.workflow.cloneClonar um workflow
command.workflow.deleteExcluir um workflow
Spans de configuração de executor
Nome do spanDescrição
command.executor_config.createCriar configuração de executor
command.executor_config.updateAtualizar configuração de executor
command.executor_config.activateAtivar configuração de executor
command.executor_config.enableHabilitar configuração de executor
command.executor_config.disableDesabilitar configuração de executor
command.executor_config.mark_configuredMarcar executor como configurado
command.executor_config.mark_testedMarcar executor como testado
command.executor_config.test_connectivityTestar conectividade do executor
command.executor_config.deleteExcluir configuração de executor
Spans de configuração de provider
Nome do spanDescrição
command.provider_config.createCriar configuração de provider
command.provider_config.updateAtualizar configuração de provider
command.provider_config.enableHabilitar configuração de provider
command.provider_config.disableDesabilitar configuração de provider
command.provider_config.test_connectivityTestar conectividade do provider
command.provider_config.deleteExcluir configuração de provider
Spans de consulta
Nome do spanDescrição
query.execution.getObter execução por ID
query.execution.listListar execuções
query.execution.get_resultsObter resultados da execução
query.workflow.getObter workflow por ID
query.workflow.get_by_nameObter workflow por nome
query.workflow.listListar workflows
query.executor_config.getObter configuração de executor por ID
query.executor_config.get_by_nameObter configuração de executor por nome
query.executor_config.listListar configurações de executor
query.executor_config.existsVerificar existência de configuração de executor
query.executor_config.exists_by_nameVerificar existência de configuração de executor por nome
query.provider_config.getObter configuração de provider por ID
query.provider_config.listListar 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étricaTipoDescrição
http.server.durationHistogramDuração da requisição em milissegundos
http.server.request.sizeHistogramTamanho do payload da requisição em bytes
http.server.response.sizeHistogramTamanho do payload da resposta em bytes
http.server.active_requestsUpDownCounterNúmero de requisições em andamento
Cada métrica possui os labels: http.method, http.route, http.status_code.

​
Métricas de sistema

MétricaTipoUnidadeDescrição
system.cpu.usageGaugeporcentagemUso de CPU do host do processo
system.mem.usageGaugeporcentagemUso 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

CampoDescriçãoExemplo
operationNome do span/operaçãocommand.execution.execute
workflow.idIdentificador do workflowwf_abc123
execution.idIdentificador da execuçãoexec_xyz789
node.idIdentificador do nó dentro de um workflownode-payment
executor.idIdentificador do executorexec_cfg_001
error.messageDescrição do erro quando aplicáveldatabase ping failed: ...

​
Níveis de log

NívelQuando é utilizado
debugEstado interno detalhado - apenas para desenvolvimento
infoMarcos de operação normal (execução iniciada, recuperada, etc.)
warnProblemas recuperáveis ou condições inesperadas mas não fatais
errorFalhas 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"
}

​
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, tempo de atividade 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á inacessí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 o probe de liveness (reiniciar em caso de travamento do processo) e /health/ready para o probe de readiness (remover do load balancer quando o banco de dados estiver indisponível). Use /health para verificações manuais e dashboards de monitoramento.

​
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.