OpenMetrics

23 min

Observability — Métricas de Flows

A Fluid expõe métricas de execução em tempo real para o seu workspace através de um endpoint compatível com Prometheus. Você pode coletar essas métricas com Prometheus, Datadog Agent, Grafana Agent ou qualquer coletor compatível com OpenMetrics.

Métricas disponíveis

Métrica	Tipo	Descrição
fluid_flow_executions_total	Counter	Total de execuções de flow, por flow e status
fluid_flow_execution_duration_seconds	Histogram	Tempo de execução de flow em segundos
fluid_flow_active_executions	Gauge	Execuções de flow em andamento no momento
fluid_engine_pods_healthy	Gauge	Pods da engine em estado Ready no seu workspace
fluid_engine_pods_total	Gauge	Total de pods da engine alocados no seu workspace

Labels

fluid_flow_executions_total e fluid_flow_execution_duration_seconds:

Label	Valores	Descrição
organization_id	slug da organização	Identificador da sua organização na Fluid
workspace_id	ID do workspace	O workspace ao qual essa métrica pertence
flow_name	nome do flow ou _other	Flow executado. Veja Cardinalidade.
status	success, warning, fail	Apenas em fluid_flow_executions_total

fluid_flow_active_executions, fluid_engine_pods_healthy e fluid_engine_pods_total têm os labels organization_id e workspace_id.

Quando as métricas são consultadas no Prometheus ou Grafana, também podem aparecer labels adicionados pelo scrape, como job, instance, environment e organization. Esses labels vêm da configuração do coletor; as labels emitidas pela Fluid são organization_id e workspace_id.

Exemplo de saída

# HELP fluid_flow_executions_total Total de execuções de flow por org, workspace, flow e status.
# TYPE fluid_flow_executions_total counter
fluid_flow_executions_total{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota",status="success"} 1482
fluid_flow_executions_total{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota",status="fail"} 3
fluid_flow_executions_total{organization_id="acme",workspace_id="acme-abc123",flow_name="_other",status="success"} 9201

# HELP fluid_flow_execution_duration_seconds Duração de execução de flow em segundos.
# TYPE fluid_flow_execution_duration_seconds histogram
fluid_flow_execution_duration_seconds_bucket{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota",le="1"} 890
fluid_flow_execution_duration_seconds_bucket{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota",le="5"} 1460
fluid_flow_execution_duration_seconds_bucket{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota",le="+Inf"} 1485
fluid_flow_execution_duration_seconds_sum{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota"} 2341.7
fluid_flow_execution_duration_seconds_count{organization_id="acme",workspace_id="acme-abc123",flow_name="enviar-nota"} 1485

# HELP fluid_flow_active_executions Execuções de flow em andamento (zera em restart).
# TYPE fluid_flow_active_executions gauge
fluid_flow_active_executions{organization_id="acme",workspace_id="acme-abc123"} 7

# HELP fluid_engine_pods_healthy Pods da engine em estado Ready por workspace.
# TYPE fluid_engine_pods_healthy gauge
fluid_engine_pods_healthy{organization_id="acme",workspace_id="acme-abc123"} 3

# HELP fluid_engine_pods_total Total de pods da engine por workspace.
# TYPE fluid_engine_pods_total gauge
fluid_engine_pods_total{organization_id="acme",workspace_id="acme-abc123"} 3

Endpoints

Há dois endpoints disponíveis. Escolha o que melhor se encaixa na sua configuração de scrape.

Por workspace

GET https://telemetry.api.fluidapi.io/v1/observability/organizations/{org_id}/workspaces/{workspace_id}/metrics

Retorna métricas de um único workspace. Use quando quiser controle granular por ambiente (ex: produção e staging em jobs de scrape separados com alertas independentes).

Por organização

GET https://telemetry.api.fluidapi.io/v1/observability/organizations/{org_id}/metrics

Retorna métricas de todos os workspaces da sua organização em um único scrape. Use quando quiser um job único que cubra todos os ambientes. As métricas retornadas incluem o label workspace_id em cada série, permitindo filtrar por workspace nas suas queries.

Se você tiver múltiplos workspaces e quiser alertas isolados por workspace, prefira o endpoint por workspace.

Autenticação

Ambos os endpoints exigem autenticação OAuth2 client credentials. O coletor obtém um access token no endpoint de identidade da Fluid e envia esse token como Bearer em cada scrape.

Use as credenciais OAuth2 fornecidas pela Fluid para sua organização. Não coloque um Bearer token fixo no arquivo de configuração do Prometheus ou do Datadog Agent.

Endpoint de token de produção:

https://id.api.fluidapi.io/oauth2/token-fluid-legacy

Configurando seu coletor

Prometheus — endpoint por workspace

Configure um job de scrape por workspace no seu prometheus.yml:

scrape_configs:
  - job_name: "fluid-observability-prod"
    scrape_interval: 60s
    scheme: https
    metrics_path: "/v1/observability/organizations/acme/workspaces/acme-prod-abc123/metrics"
    static_configs:
      - targets:
          - "telemetry.api.fluidapi.io"
    oauth2:
      client_id: "<client-id>"
      client_secret: "<client-secret>"
      token_url: "https://id.api.fluidapi.io/oauth2/token-fluid-legacy"

Prometheus — endpoint por organização

Configure um único job para cobrir todos os workspaces:

scrape_configs:
  - job_name: "fluid-observability"
    scrape_interval: 60s
    scheme: https
    metrics_path: "/v1/observability/organizations/acme/metrics"
    static_configs:
      - targets:
          - "telemetry.api.fluidapi.io"
    oauth2:
      client_id: "<client-id>"
      client_secret: "<client-secret>"
      token_url: "https://id.api.fluidapi.io/oauth2/token-fluid-legacy"
    relabel_configs:
      # opcional: adiciona um label de ambiente a todas as séries
      - target_label: environment
        replacement: producao

Queries úteis com o endpoint de organização:

# Taxa de erro por workspace
sum by (workspace_id) (
  rate(fluid_flow_executions_total{status="fail"}[5m])
)
  /
sum by (workspace_id) (
  rate(fluid_flow_executions_total[5m])
)

# Execuções por workspace — visão consolidada
sum by (workspace_id) (rate(fluid_flow_executions_total[5m]))

Queries úteis com o endpoint por workspace:

# Taxa de execuções sem sucesso nos últimos 5 minutos
sum by (flow_name) (
  rate(fluid_flow_executions_total{status=~"warning|fail"}[5m])
)
  /
sum by (flow_name) (
  rate(fluid_flow_executions_total[5m])
)

# Percentual de sucesso por flow
100 *
sum by (flow_name) (
  rate(fluid_flow_executions_total{status="success"}[5m])
)
  /
sum by (flow_name) (
  rate(fluid_flow_executions_total[5m])
)

# Flows com mais execuções na última hora
topk(10,
  sum by (flow_name) (
    increase(fluid_flow_executions_total[1h])
  )
)

# Tempo médio de execução por flow (últimos 30 min)
sum by (flow_name) (rate(fluid_flow_execution_duration_seconds_sum[30m]))
  /
sum by (flow_name) (rate(fluid_flow_execution_duration_seconds_count[30m]))

# P95 de duração por flow
histogram_quantile(0.95,
  sum by (flow_name, le) (
    rate(fluid_flow_execution_duration_seconds_bucket[30m])
  )
)

# Execuções ativas em andamento agora
fluid_flow_active_executions

# Pods da engine prontos / total
sum(fluid_engine_pods_healthy) / sum(fluid_engine_pods_total)

Datadog Agent

Crie um arquivo de configuração em /etc/datadog-agent/conf.d/openmetrics.d/fluid.yaml:

instances:
  - openmetrics_endpoint: "https://telemetry.api.fluidapi.io/v1/observability/organizations/acme/metrics"
    namespace: fluid
    metrics:
      - "^fluid_.*"
    collect_histogram_buckets: true
    histogram_buckets_as_distributions: true
    auth_token:
      reader:
        type: oauth
        url: "https://id.api.fluidapi.io/oauth2/token-fluid-legacy"
        client_id: "<client-id>"
        client_secret: "<client-secret>"
        options:
          include_client_id: true
      writer:
        type: header
        name: Authorization
        value: "Bearer <TOKEN>"
    min_collection_interval: 60

O writer do auth_token é necessário no Datadog Agent: ele define o header onde o Agent injeta o token obtido pelo reader. O valor <TOKEN> é um placeholder substituído pelo próprio Agent, não um token fixo.

Reinicie o agent: sudo systemctl restart datadog-agent

Após alguns minutos, as métricas aparecem no Datadog sob o namespace fluid.*.

Monitores sugeridos:

Alerta sobre fluid.fluid_flow_executions_total com status diferente de success acima de um limiar.

Alerta sobre fluid.fluid_flow_execution_duration_seconds.95percentile excedendo o SLA esperado.

Dashboard Grafana — getting started

Disponibilizamos um dashboard pré-configurado com os painéis mais úteis para começar. Para importar:

Baixe o arquivo JSON: fluid-telemetry-dashboard.json

No Grafana, acesse Dashboards → Import

Faça upload do arquivo JSON ou cole o conteúdo

Selecione o datasource Prometheus configurado com a Fluid

Clique em Import

O dashboard inclui:

Taxa de execuções por flow e status

Taxa de execuções sem sucesso (%)

Execuções ativas em andamento

Disponibilidade dos pods da engine

Cardinalidade

A Fluid protege o seu sistema de monitoramento contra explosão de métricas. Se o seu workspace tiver mais de 100 flows distintos, apenas os 100 com maior volume de execuções recebem label individual. Os demais são agrupados sob o label flow_name="_other".

Isso significa que:

Os 100 flows com mais execuções são sempre visíveis individualmente.

Flows fora do top 100 contribuem para os contadores de _other, permitindo acompanhar o volume total e a taxa de falha do workspace como um todo.

Conforme os padrões de tráfego mudam, flows podem entrar e sair do top 100. O bucket _other se ajusta automaticamente.

Se você precisar acompanhar um flow específico que aparece em _other, entre em contato com o suporte da Fluid para discutir opções de cardinalidade para o seu workspace.

Staleness e resets

Contadores de execução (fluid_flow_executions_total) são atualizados em segundos após cada execução. São contadores em memória: se o serviço de telemetria da Fluid for reiniciado, os contadores zeram. Use rate() e increase() no Prometheus — essas funções tratam resets de contador de forma transparente.

Histogramas de duração (fluid_flow_execution_duration_seconds) seguem o mesmo comportamento: zeram em restart. Use rate() sobre _bucket, _sum e _count para calcular percentis e médias.

fluid_flow_active_executions é um gauge que representa execuções em andamento no momento. Em caso de restart do serviço, o gauge retorna a zero. Se execuções estavam ativas no momento do restart, o valor pode mostrar temporariamente um número negativo enquanto os eventos de término das execuções chegam — esse comportamento é transitório e se autocorrige em poucos segundos conforme o serviço normaliza.

Rate limits e cache

Intervalo mínimo de scrape: 60 segundos. Scrapes mais frequentes que 60s são limitados no API gateway.

Intervalo recomendado: 60–300 segundos, dependendo dos requisitos de alertas.

Respostas podem ser cacheadas por até 10 segundos no API gateway. Scrapes consecutivos dentro dessa janela podem retornar dados idênticos.

Perguntas frequentes

Por que os contadores às vezes caem para zero?

Resets de contador acontecem quando o serviço de telemetria da Fluid é reimplantado. Isso é normal e esperado. As funções rate() e increase() do Prometheus tratam isso automaticamente ao detectar o reset. Configure suas regras de alerta usando rate() em vez de valores brutos de contador.

fluid_flow_active_executions mostrou um valor negativo. Algo está errado?

Não. Isso acontece transitoriamente após um restart do serviço: o gauge zera, e os eventos de término de execuções que estavam ativas antes do restart chegam e decrementam o valor. O gauge se normaliza em poucos segundos assim que o estado em memória é restabelecido. Configure seus alertas com max_over_time ou com um threshold negativo para evitar alarmes falsos durante reimplantações.

Qual endpoint devo usar: por workspace ou por organização?

Use o endpoint por organização se você tem múltiplos workspaces (ex: produção e staging) e quer simplificar a configuração com um único job de scrape. Use o endpoint por workspace se quiser alertas completamente isolados por ambiente ou rate limits independentes por workspace.

Tenho múltiplos workspaces. Preciso de múltiplos jobs de scrape?

Não necessariamente. O endpoint por organização retorna métricas de todos os workspaces da sua org em um único scrape, já com o label workspace_id em cada série. Você pode filtrar por workspace nas suas queries com {workspace_id="acme-prod-abc123"}.

Meu flow aparece como _other. Como faço para tê-lo com label individual?

Os 100 flows com maior volume de execuções recebem label individual. Se um flow tem volume baixo em relação aos outros no seu workspace, ele aparecerá em _other. Com o tempo, à medida que o flow executa com mais frequência, ele naturalmente entrará no top 100. Se você precisar de visibilidade garantida para um flow específico, entre em contato com o suporte.

Os pods da engine mostram 0. Algo está errado?

Se fluid_engine_pods_total mostra 0, pode significar que o seu workspace não tem flows agendados ou execuções recentes que tenham ativado a alocação da engine. Verifique o painel da Fluid. Se flows estão sendo executados ativamente mas os pods mostram 0, entre em contato com o suporte.

O endpoint retorna 403.

Verifique que:

O client_id e o client_secret estão corretos.

A credencial OAuth2 tem permissão de leitura de observability.

O org_id e workspace_id na URL correspondem aos acessos dessa credencial.

O token_url aponta para o ambiente correto.

Roadmap de métricas

Métrica	Descrição	Previsão
fluid_step_executions_total	Total de execuções por step, flow e status	Próximas versões
fluid_step_execution_duration_seconds	Tempo de execução de step em segundos	Próximas versões
fluid_connector_requests_total	Chamadas por conector externo (HubSpot, Salesforce…)	Aguardando campo connector_slug na engine
fluid_connector_request_duration_seconds	Latência por conector externo	Aguardando campo connector_slug na engine
fluid_credits_consumed_total	Créditos consumidos pelo workspace	v2

Última atualização: maio de 2026. Dúvidas? Fale com [email protected].