Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw pode expor métricas de diagnóstico por meio do plugin oficial diagnostics-prometheus. Ele escuta diagnósticos internos confiáveis e renderiza um endpoint de texto 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 autenticação do Gateway (escopo de operador). Não a exponha como um endpoint público não autenticado /metrics. Colete-a pelo mesmo caminho de autenticação que você usa para outras APIs de operador.
Para traces, logs, envio OTLP e atributos semânticos GenAI do OpenTelemetry, consulte exportação OpenTelemetry.

​
Início rápido

1

Install the plugin

openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
2

Enable the plugin

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

Restart the Gateway

A rota HTTP é registrada na inicialização do plugin, então recarregue após habilitar.
4

Scrape the protected route

Envie a mesma autenticação do Gateway que seus clientes operadores usam:
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/api/diagnostics/prometheus
5

Wire 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étricaTipoRótulos
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_started_totalcounterchannel, delivery_kind
openclaw_message_delivery_totalcounterchannel, delivery_kind, error_category, outcome
openclaw_message_delivery_duration_secondshistogramchannel, delivery_kind, error_category, outcome
openclaw_talk_event_totalcounterbrain, event_type, mode, provider, transport
openclaw_talk_event_duration_secondshistogrambrain, event_type, mode, provider, transport
openclaw_talk_audio_byteshistogrambrain, event_type, mode, provider, transport
openclaw_queue_lane_sizegaugelane
openclaw_queue_lane_wait_secondshistogramlane
openclaw_session_state_totalcounterreason, state
openclaw_session_queue_depthgaugestate
openclaw_session_recovery_totalcounteraction, active_work_kind, state, status
openclaw_session_recovery_age_secondshistogramaction, active_work_kind, state, status
openclaw_memory_bytesgaugekind
openclaw_memory_rss_byteshistogramnenhum
openclaw_memory_pressure_totalcounterlevel, reason
openclaw_telemetry_exporter_totalcounterexporter, reason, signal, status
openclaw_prometheus_series_dropped_totalcounternenhum

​
Política de rótulos

Os rótulos do Prometheus permanecem limitados e com baixa cardinalidade. O exportador não emite identificadores de diagnóstico brutos, como runId, sessionKey, sessionId, callId, toolCallId, IDs de mensagens, IDs de chat ou IDs de solicitação de provedores.Os valores dos rótulos são redigidos e devem corresponder à política de caracteres de baixa cardinalidade do OpenClaw. Valores que falham na política são substituídos por unknown, other ou none, dependendo da métrica.
O exportador limita as séries temporais mantidas na memória a 2048 séries no total entre contadores, medidores e histogramas. Novas séries além desse limite são descartadas, e openclaw_prometheus_series_dropped_total é incrementado 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 subir, corrija a origem em vez de desativar o limite.
  • texto de prompt, texto de resposta, entradas de ferramentas, saídas de ferramentas, prompts do sistema
  • transcrições de conversas, payloads de áudio, IDs de chamadas, IDs de salas, tokens de handoff, IDs de turnos e IDs brutos de sessão
  • IDs brutos de requisição de provedores (apenas hashes limitados, quando aplicável, em spans — nunca em métricas)
  • chaves de sessão e IDs de sessão
  • nomes de host, caminhos de arquivos, valores secretos

​
Receitas de PromQL

# Tokens per minute, split by provider
sum by (provider) (rate(openclaw_model_tokens_total[1m]))

# Spend (USD) over the last hour, by model
sum by (model) (increase(openclaw_model_cost_usd_total[1h]))

# 95th percentile model run duration
histogram_quantile(
  0.95,
  sum by (le, provider, model)
    (rate(openclaw_run_duration_seconds_bucket[5m]))
)

# Queue wait time SLO (95p under 2s)
histogram_quantile(
  0.95,
  sum by (le, lane) (rate(openclaw_queue_lane_wait_seconds_bucket[5m]))
) < 2

# Dropped Prometheus series (cardinality alarm)
increase(openclaw_prometheus_series_dropped_total[15m]) > 0
Prefira gen_ai_client_token_usage para dashboards entre provedores: ele segue as convenções semânticas GenAI do OpenTelemetry e é consistente com métricas de serviços GenAI que não são OpenClaw.

​
Escolhendo entre exportação para Prometheus e OpenTelemetry

O OpenClaw oferece suporte às duas superfícies de forma independente. Você pode executar uma, ambas ou nenhuma.
  • Modelo de pull: o Prometheus coleta /api/diagnostics/prometheus.
  • Nenhum coletor externo é necessário.
  • Autenticado pela autenticação normal do Gateway.
  • A superfície é apenas de métricas (sem traces nem logs).
  • Melhor para stacks já padronizadas em Prometheus + Grafana.

​
Solução de problemas

  • Verifique diagnostics.enabled: true na configuração.
  • Confirme que o plugin está habilitado e carregado com openclaw plugins list --enabled.
  • Gere algum tráfego; contadores e histogramas 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 há modo público não autenticado.
Um novo atributo está excedendo o limite de 2048 séries. Inspecione métricas recentes em busca de um rótulo com cardinalidade inesperadamente alta e corrija-o na origem. O exportador descarta intencionalmente novas séries em vez de reescrever rótulos silenciosamente.
O plugin mantém estado apenas na memória. Após uma reinicialização do Gateway, os contadores são redefinidos para zero e os medidores reiniciam no próximo valor relatado. Use rate() e increase() do PromQL para lidar com redefinições corretamente.

​
Relacionado