English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Exportação do OpenTelemetry

OpenClaw exporta diagnósticos por meio do plugin oficial diagnostics-otel usando OTLP/HTTP (protobuf). Qualquer coletor ou backend que aceite OTLP/HTTP funciona sem alterações de código. Para logs em arquivo locais e como lê-los, consulte Logging.

Como tudo se encaixa

  • Eventos de diagnóstico são registros estruturados, em processo, emitidos pelo Gateway e pelos plugins incluídos para execuções de modelo, fluxo de mensagens, sessões, filas e exec.
  • O plugin diagnostics-otel assina esses eventos e os exporta como métricas, traces e logs do OpenTelemetry via OTLP/HTTP.
  • Chamadas de provedor recebem um cabeçalho W3C traceparent do contexto de span confiável de chamada de modelo do OpenClaw quando o transporte do provedor aceita cabeçalhos personalizados. O contexto de trace emitido por plugin não é propagado.
  • Exportadores só são anexados quando a superfície de diagnóstico e o plugin estão habilitados, então o custo em processo permanece próximo de zero por padrão.

Início rápido

Para instalações empacotadas, instale o plugin primeiro:

openclaw plugins install clawhub:@openclaw/diagnostics-otel

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

Você também pode habilitar o plugin pela CLI:

openclaw plugins enable diagnostics-otel

Sinais exportados

Sinal O que entra nele
Métricas Contadores e histogramas para uso de tokens, custo, duração de execução, fluxo de mensagens, eventos Talk, lanes de fila, estado/recuperação de sessão, exec e pressão de memória.
Traces Spans para uso de modelo, chamadas de modelo, ciclo de vida do harness, execução de ferramentas, exec, processamento de webhook/mensagens, montagem de contexto e loops de ferramentas.
Logs Registros estruturados de logging.file exportados via OTLP quando diagnostics.otel.logs está habilitado.

Alterne traces, metrics e logs de forma independente. Todos os três ficam ativados por padrão quando diagnostics.otel.enabled é verdadeiro.

Referência de configuração

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },
  },
}

Variáveis de ambiente

Variável Finalidade
OTEL_EXPORTER_OTLP_ENDPOINT Substitui diagnostics.otel.endpoint. Se o valor já contiver /v1/traces, /v1/metrics ou /v1/logs, ele será usado como está.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT / OTEL_EXPORTER_OTLP_LOGS_ENDPOINT Substituições de endpoint específicas por sinal usadas quando a chave de configuração diagnostics.otel.*Endpoint correspondente não está definida. A configuração específica por sinal vence o env específico por sinal, que vence o endpoint compartilhado.
OTEL_SERVICE_NAME Substitui diagnostics.otel.serviceName.
OTEL_EXPORTER_OTLP_PROTOCOL Substitui o protocolo de transmissão (hoje, apenas http/protobuf é respeitado).
OTEL_SEMCONV_STABILITY_OPT_IN Defina como gen_ai_latest_experimental para emitir o atributo de span GenAI experimental mais recente (gen_ai.provider.name) em vez do legado gen_ai.system. Métricas GenAI sempre usam atributos semânticos limitados e de baixa cardinalidade, independentemente disso.
OPENCLAW_OTEL_PRELOADED Defina como 1 quando outro preload ou processo host já tiver registrado o SDK global do OpenTelemetry. O plugin então ignora seu próprio ciclo de vida NodeSDK, mas ainda conecta listeners de diagnóstico e respeita traces/metrics/logs.

Privacidade e captura de conteúdo

Conteúdo bruto de modelo/ferramenta não é exportado por padrão. Spans carregam identificadores limitados (canal, provedor, modelo, categoria de erro, ids de solicitação apenas com hash) e nunca incluem texto de prompt, texto de resposta, entradas de ferramenta, saídas de ferramenta ou chaves de sessão. Métricas Talk exportam apenas metadados de evento limitados, como modo, transporte, provedor e tipo de evento. Elas não incluem transcrições, payloads de áudio, ids de sessão, ids de turno, ids de chamada, ids de sala ou tokens de handoff.

Solicitações de modelo de saída podem incluir um cabeçalho W3C traceparent. Esse cabeçalho é gerado apenas a partir do contexto de trace de diagnóstico pertencente ao OpenClaw para a chamada de modelo ativa. Cabeçalhos traceparent existentes fornecidos pelo chamador são substituídos, então plugins ou opções personalizadas de provedor não podem forjar ancestralidade de trace entre serviços.

Defina diagnostics.otel.captureContent.* como true apenas quando seu coletor e sua política de retenção estiverem aprovados para texto de prompt, resposta, ferramenta ou prompt de sistema. Cada subchave é opt-in de forma independente:

  • inputMessages - conteúdo do prompt do usuário.
  • outputMessages - conteúdo da resposta do modelo.
  • toolInputs - payloads de argumentos de ferramenta.
  • toolOutputs - payloads de resultados de ferramenta.
  • systemPrompt - prompt de sistema/desenvolvedor montado.

Quando qualquer subchave está habilitada, spans de modelo e ferramenta recebem atributos openclaw.content.* limitados e redigidos apenas para aquela classe.

Amostragem e flush

  • Traces: diagnostics.otel.sampleRate (apenas root-span, 0.0 descarta tudo, 1.0 mantém tudo).
  • Métricas: diagnostics.otel.flushIntervalMs (mínimo 1000).
  • Logs: logs OTLP respeitam logging.level (nível de log em arquivo). Eles usam o caminho de redação de registro de log de diagnóstico, não a formatação de console. Instalações de alto volume devem preferir amostragem/filtragem no coletor OTLP em vez de amostragem local.
  • Correlação de logs em arquivo: logs JSONL em arquivo incluem traceId, spanId, parentSpanId e traceFlags de nível superior quando a chamada de log carrega um contexto de trace de diagnóstico válido, o que permite que processadores de log juntem linhas de log locais com spans exportados.
  • Correlação de solicitação: solicitações HTTP do Gateway e frames WebSocket criam um escopo interno de trace de solicitação. Logs e eventos de diagnóstico dentro desse escopo herdam o trace da solicitação por padrão, enquanto spans de execução de agente e chamada de modelo são criados como filhos para que cabeçalhos traceparent do provedor permaneçam no mesmo trace.

Métricas exportadas

Uso de modelo

  • openclaw.tokens (contador, attrs: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
  • openclaw.cost.usd (contador, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.run.duration_ms (histograma, attrs: openclaw.channel, openclaw.provider, openclaw.model)
  • openclaw.context.tokens (histograma, attrs: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
  • gen_ai.client.token.usage (histograma, métrica de convenções semânticas GenAI, attrs: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
  • gen_ai.client.operation.duration (histograma, segundos, métrica de convenções semânticas GenAI, attrs: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, error.type opcional)
  • openclaw.model_call.duration_ms (histograma, attrs: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, mais openclaw.errorCategory e openclaw.failureKind em erros classificados)
  • openclaw.model_call.request_bytes (histograma, tamanho em bytes UTF-8 do payload final da solicitação de modelo; sem conteúdo bruto do payload)
  • openclaw.model_call.response_bytes (histograma, tamanho em bytes UTF-8 de eventos de resposta de modelo em streaming; sem conteúdo bruto da resposta)
  • openclaw.model_call.time_to_first_byte_ms (histograma, tempo decorrido antes do primeiro evento de resposta em streaming)

Fluxo de mensagens

  • openclaw.webhook.received (contador, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.error (contador, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.webhook.duration_ms (histograma, attrs: openclaw.channel, openclaw.webhook)
  • openclaw.message.queued (contador, attrs: openclaw.channel, openclaw.source)
  • openclaw.message.processed (contador, attrs: openclaw.channel, openclaw.outcome)
  • openclaw.message.duration_ms (histograma, attrs: openclaw.channel, openclaw.outcome)
  • openclaw.message.delivery.started (contador, attrs: openclaw.channel, openclaw.delivery.kind)
  • openclaw.message.delivery.duration_ms (histograma, attrs: openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

Talk

  • openclaw.talk.event (contador, attrs: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
  • openclaw.talk.event.duration_ms (histograma, attrs: os mesmos de openclaw.talk.event; emitido quando um evento Talk relata duração)
  • openclaw.talk.audio.bytes (histograma, attrs: os mesmos de openclaw.talk.event; emitido para eventos de frame de áudio Talk que relatam tamanho em bytes)

Filas e sessões

  • openclaw.queue.lane.enqueue (contador, atributos: openclaw.lane)
  • openclaw.queue.lane.dequeue (contador, atributos: openclaw.lane)
  • openclaw.queue.depth (histograma, atributos: openclaw.lane ou openclaw.channel=heartbeat)
  • openclaw.queue.wait_ms (histograma, atributos: openclaw.lane)
  • openclaw.session.state (contador, atributos: openclaw.state, openclaw.reason)
  • openclaw.session.stuck (contador, atributos: openclaw.state; emitido apenas para escrituração de sessões obsoletas sem trabalho ativo)
  • openclaw.session.stuck_age_ms (histograma, atributos: openclaw.state; emitido apenas para escrituração de sessões obsoletas sem trabalho ativo)
  • openclaw.session.recovery.requested (contador, atributos: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
  • openclaw.session.recovery.completed (contador, atributos: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
  • openclaw.session.recovery.age_ms (histograma, atributos: iguais aos do contador de recuperação correspondente)
  • openclaw.run.attempt (contador, atributos: openclaw.attempt)

Telemetria de atividade da sessão

diagnostics.stuckSessionWarnMs é o limite de idade sem progresso para diagnósticos de atividade da sessão. Uma sessão processing não avança em direção a esse limite enquanto o OpenClaw observa progresso de resposta, ferramenta, status, bloco ou runtime ACP. Keepalives de digitação não contam como progresso, portanto um modelo ou harness silencioso ainda pode ser detectado.

O OpenClaw classifica as sessões pelo trabalho que ainda consegue observar:

  • session.long_running: trabalho incorporado ativo, chamadas de modelo ou chamadas de ferramenta ainda estão avançando.
  • session.stalled: há trabalho ativo, mas a execução ativa não relatou progresso recente. Execuções incorporadas paralisadas permanecem inicialmente apenas em observação e, em seguida, abortam e drenam após diagnostics.stuckSessionAbortMs sem progresso para que os turnos enfileirados atrás da lane possam retomar. Quando não definido, o limite de aborto assume como padrão a janela estendida mais segura de pelo menos 10 minutos e 5x diagnostics.stuckSessionWarnMs.
  • session.stuck: escrituração de sessão obsoleta sem trabalho ativo. Isso libera imediatamente a lane da sessão afetada.

A recuperação emite eventos estruturados session.recovery.requested e session.recovery.completed. O estado de sessão de diagnóstico é marcado como ocioso somente após um resultado de recuperação mutável (aborted ou released) e somente se a mesma geração de processamento ainda for a atual.

Somente session.stuck emite o contador openclaw.session.stuck, o histograma openclaw.session.stuck_age_ms e o span openclaw.session.stuck. Diagnósticos session.stuck repetidos recuam enquanto a sessão permanece inalterada, então dashboards devem alertar sobre aumentos sustentados em vez de cada tick de heartbeat. Para o controle de configuração e os padrões, consulte a Referência de configuração.

Ciclo de vida do harness

  • openclaw.harness.duration_ms (histograma, atributos: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.harness.phase em erros)

Execução

  • openclaw.exec.duration_ms (histograma, atributos: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

Detalhes internos de diagnóstico (memória e loop de ferramentas)

  • openclaw.memory.heap_used_bytes (histograma, atributos: openclaw.memory.kind)
  • openclaw.memory.rss_bytes (histograma)
  • openclaw.memory.pressure (contador, atributos: openclaw.memory.level)
  • openclaw.tool.loop.iterations (contador, atributos: openclaw.toolName, openclaw.outcome)
  • openclaw.tool.loop.duration_ms (histograma, atributos: openclaw.toolName, openclaw.outcome)

Spans exportados

  • openclaw.model.usage
    • openclaw.channel, openclaw.provider, openclaw.model
    • openclaw.tokens.* (input/output/cache_read/cache_write/total)
    • gen_ai.system por padrão, ou gen_ai.provider.name quando as convenções semânticas GenAI mais recentes são habilitadas
    • gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.*
  • openclaw.run
    • openclaw.outcome, openclaw.channel, openclaw.provider, openclaw.model, openclaw.errorCategory
  • openclaw.model.call
    • gen_ai.system por padrão, ou gen_ai.provider.name quando as convenções semânticas GenAI mais recentes são habilitadas
    • gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
    • openclaw.errorCategory e openclaw.failureKind opcional em erros
    • openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
    • openclaw.provider.request_id_hash (hash limitado baseado em SHA do id de solicitação do provedor upstream; ids brutos não são exportados)
  • openclaw.harness.run
    • openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
    • Na conclusão: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
    • Em erro: openclaw.harness.phase, openclaw.errorCategory, openclaw.harness.cleanup_failed opcional
  • openclaw.tool.execution
    • gen_ai.tool.name, openclaw.toolName, openclaw.errorCategory, openclaw.tool.params.*
  • openclaw.exec
    • openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.timed_out
  • openclaw.webhook.processed
    • openclaw.channel, openclaw.webhook
  • openclaw.webhook.error
    • openclaw.channel, openclaw.webhook, openclaw.error
  • openclaw.message.processed
    • openclaw.channel, openclaw.outcome, openclaw.reason
  • openclaw.message.delivery
    • openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory, openclaw.delivery.result_count
  • openclaw.session.stuck
    • openclaw.state, openclaw.ageMs, openclaw.queueDepth
  • openclaw.context.assembled
    • openclaw.prompt.size, openclaw.history.size, openclaw.context.tokens, openclaw.errorCategory (sem conteúdo de prompt, histórico, resposta ou chave de sessão)
  • openclaw.tool.loop
    • openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (sem mensagens de loop, parâmetros ou saída de ferramenta)
  • openclaw.memory.pressure
    • openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

Quando a captura de conteúdo é habilitada explicitamente, spans de modelo e ferramenta também podem incluir atributos openclaw.content.* limitados e redigidos para as classes de conteúdo específicas que você habilitou.

Catálogo de eventos de diagnóstico

Os eventos abaixo sustentam as métricas e os spans acima. Plugins também podem se inscrever diretamente neles sem exportação OTLP.

Uso do modelo

  • model.usage - tokens, custo, duração, contexto, provedor/modelo/canal, ids de sessão. usage é a contabilidade de provedor/turno para custo e telemetria; context.used é o snapshot atual de prompt/contexto e pode ser menor que usage.total do provedor quando input em cache ou chamadas de loop de ferramentas estão envolvidos.

Fluxo de mensagens

  • webhook.received / webhook.processed / webhook.error
  • message.queued / message.processed
  • message.delivery.started / message.delivery.completed / message.delivery.error

Fila e sessão

  • queue.lane.enqueue / queue.lane.dequeue
  • session.state / session.long_running / session.stalled / session.stuck
  • run.attempt / run.progress
  • diagnostic.heartbeat (contadores agregados: webhooks/fila/sessão)

Ciclo de vida do harness

  • harness.run.started / harness.run.completed / harness.run.error - ciclo de vida por execução para o harness do agente. Inclui harnessId, pluginId opcional, provedor/modelo/canal e id da execução. A conclusão adiciona durationMs, outcome, resultClassification opcional, yieldDetected e contagens de itemLifecycle. Erros adicionam phase (prepare/start/send/resolve/cleanup), errorCategory e cleanupFailed opcional.

Execução

  • exec.process.completed - resultado terminal, duração, destino, modo, código de saída e tipo de falha. O texto do comando e diretórios de trabalho não são incluídos.

Sem um exportador

Você pode manter eventos de diagnóstico disponíveis para Plugins ou coletores personalizados sem executar diagnostics-otel:

{
  diagnostics: { enabled: true },
}

Para saída de depuração direcionada sem elevar logging.level, use flags de diagnóstico. Flags não diferenciam maiúsculas de minúsculas e aceitam curingas (por exemplo, telegram.* ou *):

{
  diagnostics: { flags: ["telegram.http"] },
}

Ou como uma sobrescrita pontual de env:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

A saída de flags vai para o arquivo de log padrão (logging.file) e ainda é redigida por logging.redactSensitive. Guia completo: Flags de diagnóstico.

Desabilitar

{
  diagnostics: { otel: { enabled: false } },
}

Você também pode deixar diagnostics-otel fora de plugins.allow ou executar openclaw plugins disable diagnostics-otel.

Relacionado