OpenTelemetry 내보내기

OpenClaw은 공식 diagnostics-otel Plugin을 통해 **OTLP/HTTP (protobuf)**를 사용하여 진단 데이터를 내보냅니다. 컨테이너 및 샌드박스 로그 파이프라인을 위해 로그를 stdout JSONL로 기록할 수도 있습니다. OTLP/HTTP를 수신하는 모든 수집기 또는 백엔드는 코드 변경 없이 작동합니다. 로컬 파일 로그는 로깅을 참조하세요.

• 진단 이벤트는 모델 실행, 메시지 흐름, 세션, 대기열 및 exec를 위해 Gateway와 번들 Plugin이 내보내는 구조화된 프로세스 내 레코드입니다.
• **diagnostics-otel**은 이러한 이벤트를 구독하고 OTLP/HTTP를 통해 OpenTelemetry 메트릭, 트레이스, 로그로 내보내며, 로그 레코드를 stdout JSONL로 미러링할 수도 있습니다.
• 제공자 호출은 제공자 전송 계층이 사용자 지정 헤더를 허용할 때 OpenClaw의 신뢰할 수 있는 모델 호출 스팬 컨텍스트에서 W3C traceparent 헤더를 받습니다. Plugin이 내보낸 트레이스 컨텍스트는 전파되지 않습니다.
• 내보내기는 진단 기능과 Plugin이 모두 활성화된 경우에만 연결되므로, 기본적으로 프로세스 내 비용은 거의 0으로 유지됩니다.

빠른 시작

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,    },  },}

또는 CLI에서 Plugin을 활성화하세요: openclaw plugins enable diagnostics-otel.

내보내는 신호

traces, metrics, logs를 각각 독립적으로 전환할 수 있습니다. diagnostics.otel.enabled가 true이면 트레이스와 메트릭은 기본적으로 활성화됩니다. 로그는 기본적으로 비활성화되며 diagnostics.otel.logs가 명시적으로 true인 경우에만 내보냅니다. 로그 내보내기는 기본적으로 OTLP를 사용합니다. stdout에 JSONL로 출력하려면 diagnostics.otel.logsExporter를 stdout으로, 둘 다 사용하려면 both로 설정하세요.

구성 참조

{  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는 OTLP 내보내기를 비활성화함      serviceName: "openclaw-gateway", // 설정하지 않으면 OTEL_SERVICE_NAME을 사용하고, 그다음 "openclaw"를 사용함      headers: { "x-collector-token": "..." },      traces: true,      metrics: true,      logs: true,      logsExporter: "otlp", // otlp | stdout | both      sampleRate: 0.2, // 루트 스팬 샘플러, 0.0..1.0      flushIntervalMs: 60000, // 메트릭 내보내기 간격(최소 1000ms)      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: false,      },    },  },}

환경 변수

개인정보 보호 및 콘텐츠 캡처

원시 모델/도구 콘텐츠는 기본적으로 내보내지 않습니다. 스팬은 범위가 제한된 식별자(채널, 제공자, 모델, 오류 범주, 해시만 포함하는 요청 ID, 도구 소스, 도구 소유자, Skills 이름/소스)를 전달하며 프롬프트 텍스트, 응답 텍스트, 도구 입력, 도구 출력, Skills 파일 경로 또는 세션 키를 절대 포함하지 않습니다. 범위가 지정된 에이전트 세션 키처럼 보이는 값(예: agent:로 시작하는 값)은 저카디널리티 속성에서 unknown으로 대체됩니다. OTLP 로그 레코드는 기본적으로 심각도, 로거, 코드 위치, 신뢰할 수 있는 트레이스 컨텍스트 및 정제된 속성을 유지합니다. 원시 로그 메시지 본문은 diagnostics.otel.captureContent가 불리언 true인 경우에만 내보냅니다. 세분화된 captureContent.* 하위 키는 로그 본문을 활성화하지 않습니다. Talk 메트릭은 범위가 제한된 이벤트 메타데이터(모드, 전송 계층, 제공자, 이벤트 유형)만 내보내며, 대화 기록, 오디오 페이로드, 세션 ID, 턴 ID, 호출 ID, 방 ID 또는 핸드오프 토큰은 내보내지 않습니다.

외부로 전송되는 모델 요청에는 활성 모델 호출에 대해 OpenClaw이 소유한 진단 트레이스 컨텍스트에서만 생성된 W3C traceparent 헤더가 포함될 수 있습니다. 호출자가 기존에 제공한 traceparent 헤더는 대체되므로 Plugin이나 사용자 지정 제공자 옵션이 서비스 간 트레이스 계보를 위조할 수 없습니다.

수집기 및 보존 정책이 프롬프트, 응답, 도구 또는 시스템 프롬프트 텍스트를 처리하도록 승인된 경우에만 diagnostics.otel.captureContent.*를 true로 설정하세요. 각 하위 키는 독립적입니다.

• inputMessages - 사용자 프롬프트 콘텐츠입니다.
• outputMessages - 모델 응답 콘텐츠입니다.
• toolInputs - 도구 인수 페이로드입니다.
• toolOutputs - 도구 결과 페이로드입니다.
• systemPrompt - 구성된 시스템/개발자 프롬프트입니다.
• toolDefinitions - 모델 도구 이름, 설명 및 스키마입니다.

하위 키를 하나라도 활성화하면 모델 및 도구 스팬에 해당 클래스에 한정된, 범위가 제한되고 민감 정보가 제거된 openclaw.content.* 속성이 추가됩니다.

toolInputs/toolOutputs 콘텐츠는 기본 제공 에이전트 런타임의 도구 실행에서 캡처됩니다(완료/오류 스팬의 openclaw.content.tool_input 및 gen_ai.tool.call.arguments, 완료 스팬의 openclaw.content.tool_output 및 gen_ai.tool.call.result). openclaw.content.* 이름은 안정적인 OpenClaw 속성 이름으로 유지되며, gen_ai.tool.call.* 사본은 의미 규칙을 기본 지원하는 뷰어를 위해 이를 미러링합니다. 외부 하네스 도구 호출(Codex, Claude CLI)은 콘텐츠 페이로드 없이 tool.execution.* 스팬을 내보냅니다. 캡처된 콘텐츠는 신뢰할 수 있는 리스너 전용 채널을 통해 전달되며 공개 진단 이벤트 버스에는 절대 배치되지 않습니다.

샘플링 및 플러시

• 트레이스: diagnostics.otel.sampleRate는 루트 스팬에만 TraceIdRatioBasedSampler를 설정합니다(0.0은 모두 삭제하고, 1.0은 모두 유지). 설정하지 않으면 OpenTelemetry SDK 기본값(항상 활성화)을 사용합니다.
• 메트릭: diagnostics.otel.flushIntervalMs(최솟값 1000으로 제한됨). 설정하지 않으면 SDK의 주기적 내보내기 기본값을 사용합니다.
• 로그: OTLP 로그는 logging.level(파일 로그 수준)을 따르며 콘솔 포맷이 아닌 진단 로그 레코드 교정 경로를 사용합니다. 트래픽이 많은 설치 환경에서는 로컬 샘플링보다 OTLP 수집기 샘플링/필터링을 사용하는 것이 좋습니다. 플랫폼에서 이미 stdout/stderr를 로그 처리기로 전송하고 OTLP 로그 수집기가 없다면 diagnostics.otel.logsExporter: "stdout"를 설정하세요. stdout 레코드는 줄마다 하나의 JSON 객체이며, 사용 가능한 경우 ts, signal, service.name, 심각도, 본문, 교정된 속성 및 신뢰할 수 있는 트레이스 필드를 포함합니다.
• 파일 로그 상관관계: 로그 호출에 유효한 진단 트레이스 컨텍스트가 포함된 경우 JSONL 파일 로그는 최상위 traceId, spanId, parentSpanId, traceFlags를 포함하므로 로그 처리기가 로컬 로그 줄을 내보낸 스팬과 연결할 수 있습니다.
• 요청 상관관계: Gateway HTTP 요청과 WebSocket 프레임은 내부 요청 트레이스 범위를 생성합니다. 해당 범위 내의 로그와 진단 이벤트는 기본적으로 요청 트레이스를 상속하며, 에이전트 실행 및 모델 호출 스팬은 하위 항목으로 생성되므로 제공자 traceparent 헤더가 동일한 트레이스에 유지됩니다.
• 모델 호출 상관관계: openclaw.model.call 스팬은 기본적으로 안전한 프롬프트 구성 요소 크기를 포함하며, 제공자 결과에서 사용량이 노출되면 호출별 토큰 속성도 포함합니다. openclaw.model.usage는 집계 비용, 컨텍스트 및 채널 대시보드를 위한 실행 수준의 사용량 계산 스팬으로 유지되며, 이벤트를 발생시키는 런타임에 신뢰할 수 있는 트레이스 컨텍스트가 있으면 동일한 진단 트레이스에 유지됩니다.

내보낸 메트릭

모델 사용량

• openclaw.tokens(카운터, 속성: openclaw.token, openclaw.channel, openclaw.provider, openclaw.model, openclaw.agent)
• openclaw.cost.usd(카운터, 속성: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.run.duration_ms(히스토그램, 속성: openclaw.channel, openclaw.provider, openclaw.model)
• openclaw.context.tokens(히스토그램, 속성: openclaw.context, openclaw.channel, openclaw.provider, openclaw.model)
• gen_ai.client.token.usage(히스토그램, GenAI 의미 규칙 메트릭, 속성: gen_ai.token.type = input/output, gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model)
• gen_ai.client.operation.duration(히스토그램, 초, GenAI 의미 규칙 메트릭, 속성: gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, 선택적 error.type)
• openclaw.model_call.duration_ms(히스토그램, 속성: openclaw.provider, openclaw.model, openclaw.api, openclaw.transport, 분류된 오류의 경우 추가로 openclaw.errorCategory 및 openclaw.failureKind)
• openclaw.model_call.request_bytes(히스토그램, 최종 모델 요청 페이로드의 UTF-8 바이트 크기, 원시 페이로드 내용 없음)
• openclaw.model_call.response_bytes(히스토그램, 스트리밍 응답 청크 페이로드의 UTF-8 바이트 크기, 빈도가 높은 텍스트, 사고 및 도구 호출 델타는 증분 delta 바이트만 계산, 원시 응답 내용 없음)
• openclaw.model_call.time_to_first_byte_ms(히스토그램, 첫 번째 스트리밍 응답 이벤트 전까지 경과한 시간)
• openclaw.model.failover(카운터, 속성: openclaw.provider, openclaw.model, openclaw.failover.to_provider, openclaw.failover.to_model, openclaw.failover.reason, openclaw.failover.suspended, openclaw.lane)
• openclaw.skill.used(카운터, 속성: openclaw.skill.name, openclaw.skill.source, openclaw.skill.activation, 선택적 openclaw.agent, 선택적 openclaw.toolName)

메시지 흐름

• openclaw.webhook.received(카운터, 속성: openclaw.channel, openclaw.webhook)
• openclaw.webhook.error(카운터, 속성: openclaw.channel, openclaw.webhook)
• openclaw.webhook.duration_ms(히스토그램, 속성: openclaw.channel, openclaw.webhook)
• openclaw.message.queued(카운터, 속성: openclaw.channel, openclaw.source)
• openclaw.message.received(카운터, 속성: openclaw.channel, openclaw.source)
• openclaw.message.dispatch.started(카운터, 속성: openclaw.channel, openclaw.source)
• openclaw.message.dispatch.completed(카운터, 속성: openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
• openclaw.message.dispatch.duration_ms(히스토그램, 속성: openclaw.channel, openclaw.outcome, openclaw.reason, openclaw.source)
• openclaw.message.processed(카운터, 속성: openclaw.channel, openclaw.outcome)
• openclaw.message.duration_ms(히스토그램, 속성: openclaw.channel, openclaw.outcome)
• openclaw.message.delivery.started(카운터, 속성: openclaw.channel, openclaw.delivery.kind)
• openclaw.message.delivery.duration_ms(히스토그램, 속성: openclaw.channel, openclaw.delivery.kind, openclaw.outcome, openclaw.errorCategory)

대화

• openclaw.talk.event(카운터, 속성: openclaw.talk.event_type, openclaw.talk.mode, openclaw.talk.transport, openclaw.talk.brain, openclaw.talk.provider)
• openclaw.talk.event.duration_ms(히스토그램, 속성: openclaw.talk.event와 동일, 대화 이벤트가 지속 시간을 보고할 때 발생)
• openclaw.talk.audio.bytes(히스토그램, 속성: openclaw.talk.event와 동일, 바이트 길이를 보고하는 대화 오디오 프레임 이벤트에서 발생)

큐 및 세션

• openclaw.queue.lane.enqueue(카운터, 속성: openclaw.lane)
• openclaw.queue.lane.dequeue(카운터, 속성: openclaw.lane)
• openclaw.queue.depth(히스토그램, 속성: openclaw.lane 또는 openclaw.channel=heartbeat)
• openclaw.queue.wait_ms(히스토그램, 속성: openclaw.lane)
• openclaw.session.state(카운터, 속성: openclaw.state, openclaw.reason)
• openclaw.session.stuck(카운터, 속성: openclaw.state, 복구 가능한 오래된 세션 장부 상태에 대해 발생)
• openclaw.session.stuck_age_ms(히스토그램, 속성: openclaw.state, 복구 가능한 오래된 세션 장부 상태에 대해 발생)
• openclaw.session.turn.created(카운터, 속성: openclaw.agent, openclaw.channel, openclaw.trigger)
• openclaw.session.recovery.requested(카운터, 속성: openclaw.state, openclaw.action, openclaw.active_work_kind, openclaw.reason)
• openclaw.session.recovery.completed(카운터, 속성: openclaw.state, openclaw.action, openclaw.status, openclaw.active_work_kind, openclaw.reason)
• openclaw.session.recovery.age_ms(히스토그램, 속성: 해당 복구 카운터와 동일)
• openclaw.run.attempt(카운터, 속성: openclaw.attempt)

세션 활성 상태 텔레메트리

diagnostics.stuckSessionWarnMs는 세션 활성 상태 진단에서 진행 없음으로 간주하는 경과 시간 임계값입니다. OpenClaw가 응답, 도구, 상태, 블록 또는 ACP 런타임 진행을 관찰하는 동안에는 processing 세션이 이 임계값에 가까워지지 않습니다. 입력 중 상태 유지 신호는 진행으로 계산되지 않으므로 응답이 없는 모델이나 하네스도 계속 감지할 수 있습니다.

OpenClaw는 여전히 관찰할 수 있는 작업을 기준으로 세션을 분류합니다.

• session.long_running: 활성 임베디드 작업, 모델 호출 또는 도구 호출이 여전히 진행 중입니다. diagnostics.stuckSessionWarnMs가 지난 뒤에도 응답이 없는 소유 모델 호출은 diagnostics.stuckSessionAbortMs 이전에는 장기 실행으로 보고되므로, 중단 여부를 관찰할 수 있는 동안 느리거나 스트리밍하지 않는 모델 제공자가 정지된 Gateway 세션처럼 보이지 않습니다.
• session.stalled: 활성 작업이 존재하지만 활성 실행에서 최근 진행을 보고하지 않았습니다. 소유 모델 호출은 diagnostics.stuckSessionAbortMs에 도달하거나 이를 지난 시점에 session.long_running에서 session.stalled로 전환됩니다. 소유자가 없는 오래된 모델/도구 활동은 무해한 장기 실행 작업으로 취급되지 않습니다. 정지된 임베디드 실행은 처음에는 관찰만 유지하다가 diagnostics.stuckSessionAbortMs 동안 진행이 없으면 중단 후 드레이닝하여 해당 레인 뒤에 대기 중인 턴이 재개될 수 있게 합니다. 설정하지 않으면 중단 임계값은 최소 5분이면서 diagnostics.stuckSessionWarnMs의 3배인 더 안전한 확장 시간 범위를 기본값으로 사용합니다.
• session.stuck: 활성 작업이 없는 오래된 세션 장부 상태이거나, 소유자가 없는 오래된 모델/도구 활동이 있는 유휴 대기 세션입니다. 복구 게이트를 통과하면 영향을 받는 세션 레인을 즉시 해제합니다.

복구는 구조화된 session.recovery.requested 및 session.recovery.completed 이벤트를 발생시킵니다. 진단 세션 상태는 상태를 변경하는 복구 결과(aborted 또는 released) 이후에만, 그리고 동일한 처리 세대가 여전히 현재 상태인 경우에만 유휴로 표시됩니다.

openclaw.session.stuck 카운터, openclaw.session.stuck_age_ms 히스토그램 및 openclaw.session.stuck 스팬은 session.stuck에서만 발생합니다. 세션이 변경되지 않은 상태에서는 반복되는 session.stuck 진단의 발생 간격이 점차 늘어나므로, 대시보드에서는 각 Heartbeat 틱이 아니라 지속적인 증가를 기준으로 경고해야 합니다. 구성 옵션과 기본값은 구성 참조를 참고하세요.

활성 상태 경고는 다음 항목도 발생시킵니다.

• openclaw.liveness.warning(카운터, 속성: openclaw.liveness.reason)
• openclaw.liveness.event_loop_delay_p99_ms(히스토그램, 속성: openclaw.liveness.reason)
• openclaw.liveness.event_loop_delay_max_ms(히스토그램, 속성: openclaw.liveness.reason)
• openclaw.liveness.event_loop_utilization(히스토그램, 속성: openclaw.liveness.reason)
• openclaw.liveness.cpu_core_ratio(히스토그램, 속성: openclaw.liveness.reason)

하네스 수명 주기

• openclaw.harness.duration_ms(히스토그램, 속성: openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, 오류 발생 시 openclaw.harness.phase)

도구 실행 및 루프 감지

• openclaw.tool.execution.duration_ms(히스토그램, 속성: gen_ai.tool.name, openclaw.toolName, openclaw.tool.source, openclaw.tool.owner, openclaw.tool.params.kind, 오류 발생 시 추가로 openclaw.errorCategory)
• openclaw.tool.execution.blocked(카운터, 속성: gen_ai.tool.name, openclaw.toolName, openclaw.tool.source, openclaw.tool.owner, openclaw.tool.params.kind, openclaw.deniedReason)
• openclaw.tool.loop(카운터, 속성: openclaw.toolName, openclaw.loop.level, openclaw.loop.action, openclaw.loop.detector, openclaw.loop.count, 선택적 openclaw.loop.paired_tool, 반복적인 도구 호출 루프가 감지될 때 발생)

실행

• openclaw.exec.duration_ms(히스토그램, 속성: openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind)

진단 내부 항목(메모리, 페이로드, 내보내기 도구 상태)

• openclaw.payload.large(카운터, 속성: openclaw.payload.surface, openclaw.payload.action, openclaw.channel, openclaw.plugin, openclaw.reason)
• openclaw.payload.large_bytes(히스토그램, 속성: openclaw.payload.large와 동일)
• openclaw.memory.rss_bytes / openclaw.memory.heap_used_bytes / openclaw.memory.heap_total_bytes / openclaw.memory.external_bytes / openclaw.memory.array_buffers_bytes(히스토그램, 속성 없음, 프로세스 메모리 샘플)
• openclaw.memory.pressure(카운터, 속성: openclaw.memory.level, openclaw.memory.reason)
• openclaw.diagnostic.async_queue.dropped(카운터, 속성: openclaw.diagnostic.async_queue.drop_class, 내부 진단 큐의 역압력으로 인한 삭제)
• openclaw.telemetry.exporter.events(카운터, 속성: openclaw.exporter, openclaw.signal, openclaw.status, 선택적 openclaw.reason, 선택적 openclaw.errorCategory, 내보내기 도구 수명 주기/실패 자체 텔레메트리)

내보낸 스팬

• openclaw.model.usage
  • openclaw.channel, openclaw.provider, openclaw.model
  • openclaw.tokens.*(input/output/cache_read/cache_write/total)
  • 기본적으로 gen_ai.system, 또는 최신 GenAI 의미 체계 규칙을 사용하도록 선택한 경우 gen_ai.provider.name
  • 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, 또는 최신 GenAI 의미 체계 규칙을 사용하도록 선택한 경우 gen_ai.provider.name
  • gen_ai.request.model, gen_ai.operation.name, openclaw.provider, openclaw.model, openclaw.api, openclaw.transport
  • 오류 발생 시 openclaw.errorCategory, error.type 및 선택적 openclaw.failureKind
  • openclaw.model_call.request_bytes, openclaw.model_call.response_bytes, openclaw.model_call.time_to_first_byte_ms
  • openclaw.model_call.prompt.input_messages_count, openclaw.model_call.prompt.input_messages_chars, openclaw.model_call.prompt.system_prompt_chars, openclaw.model_call.prompt.tool_definitions_count, openclaw.model_call.prompt.tool_definitions_chars, openclaw.model_call.prompt.total_chars(안전한 구성 요소 크기만 포함하며 프롬프트 텍스트는 제외)
  • 모델 호출 결과에 해당 개별 호출의 제공자 사용량이 포함된 경우 openclaw.model_call.usage.* 및 gen_ai.usage.*
  • 업스트림 제공자 결과에 요청 ID가 노출된 경우 openclaw.upstreamRequestIdHash 속성(크기가 제한된 해시 기반)을 포함하는 스팬 이벤트 openclaw.provider.request; 원시 ID는 절대 내보내지 않음
  • OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental을 설정하면 모델 호출 스팬은 openclaw.model.call 대신 최신 GenAI 추론 스팬 이름 {gen_ai.operation.name} {gen_ai.request.model}과 CLIENT 스팬 종류를 사용합니다.
• openclaw.harness.run
  • openclaw.harness.id, openclaw.harness.plugin, openclaw.outcome, openclaw.provider, openclaw.model, openclaw.channel
  • 완료 시: openclaw.harness.result_classification, openclaw.harness.yield_detected, openclaw.harness.items.started, openclaw.harness.items.completed, openclaw.harness.items.active
  • 오류 발생 시: openclaw.harness.phase, openclaw.errorCategory, 선택적 openclaw.harness.cleanup_failed
• openclaw.tool.execution
  • gen_ai.tool.name, gen_ai.operation.name(execute_tool), openclaw.toolName, openclaw.tool.source, 선택적 gen_ai.tool.call.id, openclaw.tool.owner, openclaw.tool.params.*
  • 오류 발생 시 선택적 openclaw.errorCategory/openclaw.errorCode, 정책 또는 샌드박스에 의해 거부된 경우 openclaw.deniedReason 및 openclaw.outcome=blocked
• openclaw.exec
  • openclaw.exec.target, openclaw.exec.mode, openclaw.outcome, openclaw.failureKind, openclaw.exec.command_length, openclaw.exec.exit_code, openclaw.exec.exit_signal, 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(프롬프트, 기록, 응답 또는 세션 키 콘텐츠는 제외)
• openclaw.tool.loop
  • openclaw.toolName, openclaw.loop.level, openclaw.loop.action, openclaw.loop.detector, openclaw.loop.count, 선택적 openclaw.loop.paired_tool(루프 메시지, 매개변수 또는 도구 출력은 제외)
• openclaw.memory.pressure
  • openclaw.memory.level, openclaw.memory.reason, openclaw.memory.rss_bytes, openclaw.memory.heap_used_bytes, openclaw.memory.heap_total_bytes, openclaw.memory.external_bytes, openclaw.memory.array_buffers_bytes, 선택적 openclaw.memory.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms

콘텐츠 캡처가 명시적으로 활성화된 경우 모델 및 도구 스팬에는 사용하도록 선택한 특정 콘텐츠 클래스에 대해 크기가 제한되고 민감 정보가 삭제된 openclaw.content.* 속성도 포함될 수 있습니다.

진단 이벤트 카탈로그

아래 이벤트는 위의 메트릭과 스팬을 지원합니다. Plugin은 OTLP로 내보내지 않고도 이를 직접 구독할 수 있습니다.

모델 사용량

• model.usage - 토큰, 비용, 소요 시간, 컨텍스트, 제공자/모델/채널, 세션 ID. usage는 비용 및 원격 측정을 위한 제공자/턴 단위 집계이며, context.used는 현재 프롬프트/컨텍스트 스냅샷입니다. 캐시된 입력이나 도구 루프 호출이 포함된 경우 context.used는 제공자의 usage.total보다 작을 수 있습니다.

메시지 흐름

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

대기열 및 세션

• queue.lane.enqueue / queue.lane.dequeue
• session.state / session.long_running / session.stalled / session.stuck
• run.attempt / run.progress
• diagnostic.heartbeat(집계 카운터: Webhook/대기열/세션)

하네스 수명 주기

• harness.run.started / harness.run.completed / harness.run.error - 에이전트 하네스의 실행별 수명 주기입니다. harnessId, 선택적 pluginId, 제공자/모델/채널 및 실행 ID를 포함합니다. 완료 이벤트에는 durationMs, outcome, 선택적 resultClassification, yieldDetected 및 itemLifecycle 개수가 추가됩니다. 오류 이벤트에는 phase(prepare/start/send/resolve/cleanup), errorCategory 및 선택적 cleanupFailed가 추가됩니다.

실행

• exec.process.completed - 터미널 결과, 소요 시간, 대상, 모드, 종료 코드 및 실패 종류입니다. 명령 텍스트와 작업 디렉터리는 포함되지 않습니다.
• exec.approval.followup_suppressed - 세션이 다시 연결된 후 오래된 승인 후속 처리를 삭제합니다. approvalId, reason(session_rebound), phase(direct_delivery 또는 gateway_preflight) 및 디스패처 타임스탬프를 포함합니다. 세션 키, 경로 및 명령 텍스트는 포함되지 않습니다.

내보내기 도구 없이 사용

diagnostics-otel을 실행하지 않고도 Plugin 또는 사용자 지정 싱크에서 진단 이벤트를 사용할 수 있도록 유지합니다.

{  diagnostics: { enabled: true },}

logging.level을 높이지 않고 특정 디버그 출력을 활성화하려면 진단 플래그를 사용합니다. 플래그는 대소문자를 구분하지 않으며 와일드카드(telegram.* 또는 *)를 지원합니다.

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

또는 일회성 환경 변수 재정의로 설정합니다.

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

플래그 출력은 표준 로그 파일(logging.file)에 기록되며, 여전히 logging.redactSensitive에 의해 민감 정보가 삭제됩니다. 전체 안내서: 진단 플래그.

비활성화

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

또는 plugins.allow에서 diagnostics-otel을 제외하거나 openclaw plugins disable diagnostics-otel을 실행합니다.

관련 항목

• 로깅 - 파일 로그, 콘솔 출력, CLI 테일링 및 Control UI 로그 탭
• Gateway 로깅 내부 구조 - WS 로그 스타일, 하위 시스템 접두사 및 콘솔 캡처
• 진단 플래그 - 특정 디버그 로그 플래그
• 진단 내보내기 - 운영자 지원 번들 도구(OTEL 내보내기와 별개)
• 구성 참조 - 전체 diagnostics.* 필드 참조