OpenTelemetry 내보내기

​

전체 구성 방식

• 진단 이벤트는 Gateway와 번들 Plugin이 모델 실행, 메시지 흐름, 세션, 큐, exec에 대해 내보내는 구조화된 프로세스 내부 레코드입니다.
• diagnostics-otel Plugin은 해당 이벤트를 구독하고 OTLP/HTTP를 통해 OpenTelemetry 메트릭, 트레이스, 로그로 내보냅니다. 진단 로그 레코드를 stdout JSONL로 미러링할 수도 있습니다.
• Provider 호출은 provider 전송이 사용자 지정 헤더를 허용할 때 OpenClaw의 신뢰된 모델 호출 span 컨텍스트에서 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,
    },
  },
}

openclaw plugins enable diagnostics-otel

​

내보내는 신호

​

구성 참조

{
  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,
      logsExporter: "otlp", // otlp | stdout | both
      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,
        toolDefinitions: false,
      },
    },
  },
}

​

환경 변수

​

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

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

​

샘플링 및 플러시

• 추적: diagnostics.otel.sampleRate(루트 span만 해당, 0.0은 모두 버리고, 1.0은 모두 유지).
• 메트릭: diagnostics.otel.flushIntervalMs(최소 1000).
• 로그: OTLP 로그는 logging.level(파일 로그 수준)을 따릅니다. 콘솔 포맷팅이 아니라 진단 로그 레코드 수정 경로를 사용합니다. 대용량 설치 환경에서는 로컬 샘플링보다 OTLP collector 샘플링/필터링을 선호해야 합니다. 플랫폼이 이미 stdout/stderr를 로그 프로세서로 보내고 OTLP logs collector가 없는 경우 diagnostics.otel.logsExporter: "stdout"을 설정하세요. Stdout 레코드는 줄마다 하나의 JSON 객체이며, 사용 가능한 경우 ts, signal, service.name, 심각도, 본문, 수정된 속성, 신뢰할 수 있는 추적 필드를 포함합니다.
• 파일 로그 상관관계: JSONL 파일 로그는 로그 호출에 유효한 진단 추적 컨텍스트가 포함된 경우 최상위 traceId, spanId, parentSpanId, traceFlags를 포함하므로 로그 프로세서가 로컬 로그 줄을 내보낸 span과 결합할 수 있습니다.
• 요청 상관관계: Gateway HTTP 요청과 WebSocket 프레임은 내부 요청 추적 범위를 만듭니다. 해당 범위 안의 로그와 진단 이벤트는 기본적으로 요청 추적을 상속하며, 에이전트 실행 및 모델 호출 span은 자식으로 생성되어 provider traceparent 헤더가 같은 추적에 유지됩니다.
• 모델 호출 상관관계: openclaw.model.call span은 기본적으로 안전한 프롬프트 구성 요소 크기를 포함하며, provider 결과가 사용량을 노출할 때 호출별 토큰 속성을 포함합니다. openclaw.model.usage는 집계 비용, 컨텍스트, 채널 대시보드를 위한 실행 수준 회계 span으로 유지되며, 내보내는 런타임에 신뢰할 수 있는 추적 컨텍스트가 있을 때 같은 진단 추적에 유지됩니다.

​

내보낸 메트릭

​

모델 사용량

• 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는 증분 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)

​

Talk

• 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와 동일, Talk 이벤트가 지속 시간을 보고할 때 내보냄)
• openclaw.talk.audio.bytes(히스토그램, 속성: openclaw.talk.event와 동일, 바이트 길이를 보고하는 Talk 오디오 프레임 이벤트에 대해 내보냄)

​

큐 및 세션

• 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)

​

세션 활성 상태 텔레메트리

• session.long_running: 활성 임베디드 작업, 모델 호출 또는 도구 호출이 여전히 진행 중입니다. diagnostics.stuckSessionWarnMs를 지나도록 조용한 소유된 모델 호출도 diagnostics.stuckSessionAbortMs 전에는 long-running으로 보고되므로, 느리거나 스트리밍하지 않는 모델 provider가 abort 관찰 가능한 상태로 남아 있는 동안 중단된 gateway 세션처럼 보이지 않습니다.
• session.stalled: 활성 작업은 있지만, 활성 실행이 최근 진행 상황을 보고하지 않았습니다. 소유된 모델 호출은 diagnostics.stuckSessionAbortMs 시점 또는 이후에 session.long_running에서 session.stalled로 전환됩니다. 소유자 없는 오래된 모델/도구 활동은 무해한 장기 실행 작업으로 취급되지 않습니다. 중단된 임베디드 실행은 처음에는 관찰 전용으로 유지된 뒤, 진행 없이 diagnostics.stuckSessionAbortMs가 지난 후 abort-drain되어 해당 lane 뒤의 대기 중인 turn이 재개될 수 있습니다. 설정되지 않은 경우 abort 임계값은 최소 5분 및 diagnostics.stuckSessionWarnMs의 3배인 더 안전한 확장 창으로 기본 설정됩니다.
• session.stuck: 활성 작업이 없는 오래된 세션 장부 기록, 또는 소유자 없는 오래된 모델/도구 활동이 있는 유휴 대기 세션입니다. 이는 복구 게이트를 통과한 직후 영향을 받는 세션 lane을 해제합니다.

• 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)

​

Harness 수명 주기

• 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)

​

Exec

• 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.heap_used_bytes(히스토그램, 속성: openclaw.memory.kind)
• openclaw.memory.rss_bytes(히스토그램)
• openclaw.memory.pressure(카운터, 속성: openclaw.memory.level)
• openclaw.tool.loop.iterations(카운터, 속성: openclaw.toolName, openclaw.outcome)
• openclaw.tool.loop.duration_ms(히스토그램, 속성: openclaw.toolName, openclaw.outcome)

​

내보낸 span

• 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 및 선택적 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.*
  • openclaw.provider.request_id_hash (업스트림 제공자 요청 ID의 제한된 SHA 기반 해시; 원시 ID는 내보내지 않음)
  • OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental를 사용하면 모델 호출 span은 openclaw.model.call 대신 최신 GenAI 추론 span 이름 {gen_ai.operation.name} {gen_ai.request.model} 및 CLIENT span 종류를 사용합니다.
• 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, 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 (프롬프트, 기록, 응답 또는 세션 키 내용 없음)
• openclaw.tool.loop
  • openclaw.toolName, openclaw.outcome, openclaw.iterations, openclaw.errorCategory (루프 메시지, 매개변수 또는 도구 출력 없음)
• openclaw.memory.pressure
  • openclaw.memory.level, openclaw.memory.heap_used_bytes, openclaw.memory.rss_bytes

​

진단 이벤트 카탈로그

• model.usage - 토큰, 비용, 기간, 컨텍스트, 제공자/모델/채널, 세션 ID. usage는 비용 및 원격 측정을 위한 제공자/턴 계정이며, 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: { enabled: true },
}

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

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

​

비활성화

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

​

관련 문서

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