--- title: OpenMetrics slug: openmetrics docTags: createdAt: 2026-05-05T14:56:24.813Z --- # 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 ```javascript # 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 ```javascript 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 ```javascript 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: ```text 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`: ```yaml 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_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: ```yaml 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_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:** ```promql # 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:** ```promql # 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`: ```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_secret: "" options: include_client_id: true writer: type: header name: Authorization value: "Bearer " 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 `` é 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: 1. Baixe o arquivo JSON: [fluid-telemetry-dashboard.json](https://files.fluidapi.io/grafana/fluid-telemetry-dashboard.json) 2. No Grafana, acesse **Dashboards → Import** 3. Faça upload do arquivo JSON ou cole o conteúdo 4. Selecione o datasource Prometheus configurado com a Fluid 5. 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: 1. O `client_id` e o `client_secret` estão corretos. 2. A credencial OAuth2 tem permissão de leitura de observability. 3. O `org_id` e `workspace_id` na URL correspondem aos acessos dessa credencial. 4. 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 *[suporte@fluidapi.io](mailto\:suporte@fluidapi.io)*.*