Pular para o conteúdo principal
O OpenClaw pode expor métricas de diagnóstico por meio do Plugin incluído diagnostics-prometheus. Ele escuta diagnósticos internos confiáveis e renderiza um endpoint de texto do Prometheus em: 
GET /api/diagnostics/prometheus
O tipo de conteúdo é text/plain; version=0.0.4; charset=utf-8, o formato padrão de exposição do Prometheus.
A rota usa a autenticação do Gateway (escopo de operador). Não a exponha como um endpoint público /metrics sem autenticação. Faça o scrape por meio do mesmo caminho de auth que você usa para outras APIs de operador.
Para traces, logs, push OTLP e atributos semânticos GenAI do OpenTelemetry, consulte Exportação OpenTelemetry.

​
Início rápido

1

Ativar o Plugin

{
  plugins: {
    allow: ["diagnostics-prometheus"],
    entries: {
      "diagnostics-prometheus": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
  },
}
2

Reiniciar o Gateway

A rota HTTP é registrada no startup do Plugin, então recarregue após ativá-lo.
3

Fazer scrape da rota protegida

Envie a mesma auth do Gateway que seus clientes de operador usam:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
4

Conectar o Prometheus

# prometheus.yml
scrape_configs:
  - job_name: openclaw
    scrape_interval: 30s
    metrics_path: /api/diagnostics/prometheus
    authorization:
      credentials_file: /etc/prometheus/openclaw-gateway-token
    static_configs:
      - targets: ["openclaw-gateway:18789"]
diagnostics.enabled: true é obrigatório. Sem isso, o Plugin ainda registra a rota HTTP, mas nenhum evento de diagnóstico flui para o exportador, então a resposta fica vazia.

​
Métricas exportadas

MétricaTipoLabels
openclaw_run_completed_totalcounterchannel, model, outcome, provider, trigger
openclaw_run_duration_secondshistogramchannel, model, outcome, provider, trigger
openclaw_model_call_totalcounterapi, error_category, model, outcome, provider, transport
openclaw_model_call_duration_secondshistogramapi, error_category, model, outcome, provider, transport
openclaw_model_tokens_totalcounteragent, channel, model, provider, token_type
openclaw_gen_ai_client_token_usagehistogrammodel, provider, token_type
openclaw_model_cost_usd_totalcounteragent, channel, model, provider
openclaw_tool_execution_totalcountererror_category, outcome, params_kind, tool
openclaw_tool_execution_duration_secondshistogramerror_category, outcome, params_kind, tool
openclaw_harness_run_totalcounterchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_harness_run_duration_secondshistogramchannel, error_category, harness, model, outcome, phase, plugin, provider
openclaw_message_processed_totalcounterchannel, outcome, reason
openclaw_message_processed_duration_secondshistogramchannel, outcome, reason
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnone
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternone

​
Política de labels

Labels do Prometheus permanecem limitados e de baixa cardinalidade. O exportador não emite identificadores brutos de diagnóstico, como runId, sessionKey, sessionId, callId, toolCallId, IDs de mensagem, IDs de chat ou IDs de requisição do provedor.Valores de label são redigidos e devem corresponder à política de caracteres de baixa cardinalidade do OpenClaw. Valores que não atendem à política são substituídos por unknown, other ou none, dependendo da métrica.
O exportador limita as séries temporais retidas em memória a 2048 séries no total, somando counters, gauges e histograms. Novas séries além desse limite são descartadas, e openclaw_prometheus_series_dropped_total é incrementada em um a cada vez.Monitore esse contador como um sinal forte de que um atributo upstream está vazando valores de alta cardinalidade. O exportador nunca aumenta o limite automaticamente; se ele crescer, corrija a origem em vez de desativar o limite.
  • texto de prompt, texto de resposta, entradas de ferramenta, saídas de ferramenta, prompts de sistema
  • IDs brutos de requisição do provedor (apenas hashes limitados, quando aplicável, em spans — nunca em métricas)
  • chaves de sessão e IDs de sessão
  • hostnames, caminhos de arquivo, valores secretos

​
Receitas PromQL

# Tokens por minuto, divididos por provedor
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Gasto (USD) na última hora, por modelo
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95º percentil de duração de execução de modelo
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# SLO de tempo de espera na fila (95p abaixo de 2 s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Séries Prometheus descartadas (alarme de cardinalidade)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Prefira gen_ai_client_token_usage para painéis entre provedores: ele segue as convenções semânticas GenAI do OpenTelemetry e é consistente com métricas de serviços GenAI não OpenClaw.

​
Escolhendo entre exportação Prometheus e OpenTelemetry

O OpenClaw oferece suporte a ambas as superfícies de forma independente. Você pode executar uma, ambas ou nenhuma.
  • Modelo de pull: o Prometheus faz scrape de /api/diagnostics/prometheus.
  • Nenhum coletor externo é necessário.
  • Autenticado por meio da auth normal do Gateway.
  • A superfície é somente de métricas (sem traces nem logs).
  • Ideal para stacks já padronizadas em Prometheus + Grafana.

​
Solução de problemas

  • Verifique diagnostics.enabled: true na configuração.
  • Confirme se o Plugin está ativado e carregado com openclaw plugins list --enabled.
  • Gere algum tráfego; counters e histograms só emitem linhas após pelo menos um evento.
O endpoint exige o escopo de operador do Gateway (auth: "gateway" com gatewayRuntimeScopeSurface: "trusted-operator"). Use o mesmo token ou senha que o Prometheus usa para qualquer outra rota de operador do Gateway. Não existe modo público sem autenticação.
Um novo atributo está excedendo o limite de 2048 séries. Inspecione as métricas recentes em busca de um label com cardinalidade inesperadamente alta e corrija isso na origem. O exportador descarta intencionalmente novas séries em vez de reescrever labels silenciosamente.
O Plugin mantém estado apenas em memória. Após um restart do Gateway, counters são redefinidos para zero e gauges reiniciam no próximo valor reportado. Use rate() e increase() em PromQL para lidar com resets corretamente.

​
Relacionado