diff --git a/docs/zh-CN/gateway/opentelemetry.md b/docs/zh-CN/gateway/opentelemetry.md index ba8c23d31..f6522d03d 100644 --- a/docs/zh-CN/gateway/opentelemetry.md +++ b/docs/zh-CN/gateway/opentelemetry.md @@ -3,25 +3,31 @@ read_when: - 你想将 OpenClaw 模型使用情况、消息流或会话指标发送到 OpenTelemetry 收集器 - 你正在将追踪、指标或日志接入 Grafana、Datadog、Honeycomb、New Relic、Tempo 或其他 OTLP 后端 - 你需要确切的指标名称、span 名称或属性结构来构建仪表板或告警 -summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断数据导出到任意 OpenTelemetry 收集器 +summary: 通过 diagnostics-otel 插件（OTLP/HTTP）将 OpenClaw 诊断信息导出到任何 OpenTelemetry 收集器 title: OpenTelemetry 导出 x-i18n: - generated_at: "2026-04-26T19:56:12Z" + generated_at: "2026-04-26T20:47:25Z" model: gpt-5.4 provider: openai - source_hash: 379e0cada90888a3703785147d62ebe418f48216169577443cc8c95dc2a9fff8 + source_hash: 4c0462a19d5eebde92f87fef3d26dfe7338c3d446caf4b8c7097eb1a13a278fe source_path: gateway/opentelemetry.md workflow: 15 --- -OpenClaw 通过内置的 `diagnostics-otel` 插件使用 **OTLP/HTTP（protobuf）** 导出诊断数据。任何接受 OTLP/HTTP 的收集器或后端都可以直接使用，无需修改代码。关于本地文件日志及其读取方式，请参见 [日志](/zh-CN/logging)。 +OpenClaw 通过内置的 `diagnostics-otel` 插件导出诊断信息， +使用 **OTLP/HTTP（protobuf）**。任何接受 OTLP/HTTP 的收集器或后端 +都可以直接使用，无需修改代码。有关本地文件日志及其读取方式，请参阅 +[日志记录](/zh-CN/logging)。 -## 工作原理 +## 它如何协同工作 -- **诊断事件** 是由 Gateway 网关和内置插件发出的结构化进程内记录，用于模型运行、消息流、会话、队列和 exec。 -- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将其导出为 OpenTelemetry **指标**、**追踪** 和 **日志**。 -- 当提供商传输支持自定义请求头时，**提供商调用** 会从 OpenClaw 受信任的模型调用 span 上下文中接收一个 W3C `traceparent` 请求头。插件发出的追踪上下文不会被传播。 -- 只有在诊断功能面和插件都启用时，导出器才会附加，因此默认情况下进程内开销几乎为零。 +- **诊断事件** 是由 Gateway 网关和内置插件发出的结构化进程内记录， + 用于模型运行、消息流、会话、队列和 exec。 +- **`diagnostics-otel` 插件** 订阅这些事件，并通过 OTLP/HTTP 将其导出为 + OpenTelemetry **指标**、**追踪** 和 **日志**。 +- **提供商调用** 会从 OpenClaw 受信任的模型调用 span 上下文接收一个 W3C + `traceparent` 请求头，前提是提供商传输层接受自定义请求头。插件发出的追踪上下文不会被传播。 +- 只有在诊断表面和插件都启用时，导出器才会附加，因此默认情况下进程内开销几乎为零。 ## 快速开始 @@ -60,15 +66,16 @@ openclaw plugins enable diagnostics-otel `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。 -## 导出的信号 +## 已导出的信号 -| 信号 | 包含内容 | +| 信号 | 其中包含的内容 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **指标** | 用于 token 使用量、成本、运行时长、消息流、队列通道、会话状态、exec 和内存压力的计数器与直方图。 | -| **追踪** | 用于模型使用、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 span。 | +| **追踪** | 用于模型使用、模型调用、harness 生命周期、工具执行、exec、webhook/消息处理、上下文组装和工具循环的 spans。 | | **日志** | 当启用 `diagnostics.otel.logs` 时，通过 OTLP 导出的结构化 `logging.file` 记录。 | -可以分别切换 `traces`、`metrics` 和 `logs`。当 `diagnostics.otel.enabled` 为 true 时，这三者默认都会开启。 +你可以独立切换 `traces`、`metrics` 和 `logs`。当 +`diagnostics.otel.enabled` 为 true 时，这三者默认都开启。 ## 配置参考 @@ -107,20 +114,26 @@ openclaw plugins enable diagnostics-otel | 变量 | 用途 | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果该值已包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则按原样使用。 | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当对应的 `diagnostics.otel.*Endpoint` 配置键未设置时，用作按信号区分的 endpoint 覆盖。按信号区分的配置优先于按信号区分的环境变量，后者优先于共享 endpoint。 | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | 覆盖 `diagnostics.otel.endpoint`。如果该值已经包含 `/v1/traces`、`/v1/metrics` 或 `/v1/logs`，则按原样使用。 | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | 当对应的 `diagnostics.otel.*Endpoint` 配置键未设置时，使用按信号区分的端点覆盖。信号专用配置优先于信号专用环境变量，后者优先于共享端点。 | | `OTEL_SERVICE_NAME` | 覆盖 `diagnostics.otel.serviceName`。 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线协议（当前仅 `http/protobuf` 会生效）。 | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental`，以发出最新的实验性 GenAI span 属性 `gen_ai.provider.name`，而不是旧版的 `gen_ai.system`。GenAI 指标始终使用有界、低基数的语义属性。 | -| `OPENCLAW_OTEL_PRELOADED` | 当另一个预加载项或宿主进程已注册全局 OpenTelemetry SDK 时，将其设置为 `1`。这样插件会跳过自身的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | 覆盖线协议（当前仅支持 `http/protobuf`）。 | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | 设置为 `gen_ai_latest_experimental` 时，会发出最新的实验性 GenAI span 属性（`gen_ai.provider.name`），而不是旧版的 `gen_ai.system`。无论如何，GenAI 指标始终使用有界、低基数的语义属性。 | +| `OPENCLAW_OTEL_PRELOADED` | 当另一个预加载项或宿主进程已经注册了全局 OpenTelemetry SDK 时，将其设置为 `1`。这样插件会跳过自身的 NodeSDK 生命周期，但仍会连接诊断监听器并遵循 `traces`/`metrics`/`logs`。 | -## 隐私与内容采集 +## 隐私与内容捕获 -默认**不会**导出原始模型/工具内容。span 携带的是有界标识符（渠道、提供商、模型、错误类别、仅哈希的请求 id），绝不包含提示词文本、响应文本、工具输入、工具输出或会话键。 +默认情况下，原始模型/工具内容 **不会** 被导出。Spans 仅携带有界 +标识符（渠道、提供商、模型、错误类别、仅哈希的请求 id）， +绝不会包含提示文本、响应文本、工具输入、工具输出或会话键。 -出站模型请求可能包含 W3C `traceparent` 请求头。该请求头仅根据 OpenClaw 自有的活动模型调用诊断追踪上下文生成。现有的调用方提供的 `traceparent` 请求头会被替换，因此插件或自定义提供商选项无法伪造跨服务追踪祖先关系。 +出站模型请求可能包含 W3C `traceparent` 请求头。该请求头 +仅根据 OpenClaw 自有的活动模型调用诊断追踪上下文生成。 +现有调用方提供的 `traceparent` 请求头会被替换，因此插件或 +自定义提供商选项无法伪造跨服务追踪祖先关系。 -仅当你的收集器和保留策略已获准存储提示词、响应、工具或系统提示文本时，才将 `diagnostics.otel.captureContent.*` 设为 `true`。每个子键都需要单独选择加入： +仅当你的收集器和保留策略已获批准，可用于提示词、响应、工具或系统提示 +文本时，才将 `diagnostics.otel.captureContent.*` 设为 `true`。每个子键都需要单独选择启用： - `inputMessages` — 用户提示内容。 - `outputMessages` — 模型响应内容。 @@ -128,16 +141,22 @@ openclaw plugins enable diagnostics-otel - `toolOutputs` — 工具结果负载。 - `systemPrompt` — 组装后的 system/developer 提示词。 -当任一子键启用时，模型和工具 span 会仅针对该类内容附加有界、已脱敏的 `openclaw.content.*` 属性。 +启用任意子键后，模型和工具 spans 将仅为该类别附加有界、已脱敏的 +`openclaw.content.*` 属性。 ## 采样与刷新 -- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 表示全部丢弃，`1.0` 表示全部保留）。 -- **指标：** `diagnostics.otel.flushIntervalMs`（最小值为 `1000`）。 -- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用诊断日志记录脱敏路径，而不是控制台格式化。高流量部署应优先使用 OTLP 收集器采样/过滤，而不是本地采样。 -- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层的 `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`，这样日志处理器就可以将本地日志行与导出的 span 关联起来。 +- **追踪：** `diagnostics.otel.sampleRate`（仅根 span，`0.0` 全部丢弃， + `1.0` 全部保留）。 +- **指标：** `diagnostics.otel.flushIntervalMs`（最小值 `1000`）。 +- **日志：** OTLP 日志遵循 `logging.level`（文件日志级别）。它们使用 + 诊断日志记录脱敏路径，而不是控制台格式化。高流量安装应优先使用 + OTLP 收集器采样/过滤，而不是本地采样。 +- **文件日志关联：** 当日志调用携带有效的诊断追踪上下文时，JSONL 文件日志会包含顶层 + `traceId`、`spanId`、`parentSpanId` 和 `traceFlags`， + 这使日志处理器能够将本地日志行与导出的 spans 关联起来。 -## 导出的指标 +## 已导出的指标 ### 模型使用情况 @@ -146,7 +165,11 @@ openclaw plugins enable diagnostics-otel - `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`） +- `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.model_call.request_bytes`（直方图，最终模型请求负载的 UTF-8 字节大小；不包含原始负载内容） +- `openclaw.model_call.response_bytes`（直方图，流式模型响应事件的 UTF-8 字节大小；不包含原始响应内容） +- `openclaw.model_call.time_to_first_byte_ms`（直方图，第一个流式响应事件到达前的耗时） ### 消息流 @@ -172,13 +195,13 @@ openclaw plugins enable diagnostics-otel ### Harness 生命周期 -- `openclaw.harness.duration_ms`（直方图，属性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，出错时还包括 `openclaw.harness.phase`） +- `openclaw.harness.duration_ms`（直方图，属性：`openclaw.harness.id`、`openclaw.harness.plugin`、`openclaw.outcome`，错误时包含 `openclaw.harness.phase`） ### Exec - `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） -### 诊断内部指标（内存与工具循环） +### 诊断内部机制（内存和工具循环） - `openclaw.memory.heap_used_bytes`（直方图，属性：`openclaw.memory.kind`） - `openclaw.memory.rss_bytes`（直方图） @@ -186,19 +209,20 @@ openclaw plugins enable diagnostics-otel - `openclaw.tool.loop.iterations`（计数器，属性：`openclaw.toolName`、`openclaw.outcome`） - `openclaw.tool.loop.duration_ms`（直方图，属性：`openclaw.toolName`、`openclaw.outcome`） -## 导出的 span +## 已导出的 spans - `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.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.system`，或者在选择启用最新的 GenAI 语义约定时使用 `gen_ai.provider.name` - `gen_ai.request.model`、`gen_ai.operation.name`、`openclaw.provider`、`openclaw.model`、`openclaw.api`、`openclaw.transport` - - `openclaw.provider.request_id_hash`（上游提供商请求 id 的有界 SHA 哈希；不会导出原始 id） + - `openclaw.model_call.request_bytes`、`openclaw.model_call.response_bytes`、`openclaw.model_call.time_to_first_byte_ms` + - `openclaw.provider.request_id_hash`（上游提供商请求 id 的有界、基于 SHA 的哈希；不会导出原始 id） - `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` @@ -224,15 +248,20 @@ openclaw plugins enable diagnostics-otel - `openclaw.memory.pressure` - `openclaw.memory.level`、`openclaw.memory.heap_used_bytes`、`openclaw.memory.rss_bytes` -当显式启用内容采集时，模型和工具 span 还可以包含你选择加入的特定内容类别对应的有界、已脱敏 `openclaw.content.*` 属性。 +当明确启用内容捕获时，模型和工具 spans 还可以为你选择启用的特定 +内容类别包含有界、已脱敏的 `openclaw.content.*` 属性。 ## 诊断事件目录 -下列事件为上述指标和 span 提供支撑。插件也可以在不进行 OTLP 导出的情况下直接订阅这些事件。 +以下事件为上述指标和 spans 提供基础。插件也可以直接订阅 +这些事件，而无需 OTLP 导出。 **模型使用情况** -- `model.usage` — token、成本、时长、上下文、提供商/模型/渠道、会话 id。`usage` 是用于成本和遥测的提供商/轮次统计；`context.used` 是当前提示词/上下文快照，在涉及缓存输入或工具循环调用时，可能低于提供商的 `usage.total`。 +- `model.usage` — token、成本、时长、上下文、提供商/模型/渠道、 + 会话 id。`usage` 是提供商/轮次维度的成本和遥测统计； + `context.used` 是当前提示词/上下文快照，在涉及缓存输入或工具循环调用时， + 其值可能低于提供商 `usage.total`。 **消息流** @@ -249,15 +278,22 @@ openclaw plugins enable diagnostics-otel **Harness 生命周期** -- `harness.run.started` / `harness.run.completed` / `harness.run.error` — 智能体 harness 的每次运行生命周期。包含 `harnessId`、可选的 `pluginId`、provider/model/channel 以及 run id。完成事件会新增 `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` 和 `itemLifecycle` 计数。错误事件会新增 `phase`（`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 以及可选的 `cleanupFailed`。 +- `harness.run.started` / `harness.run.completed` / `harness.run.error` — + 智能体 harness 的单次运行生命周期。包括 `harnessId`、可选的 + `pluginId`、提供商/模型/渠道以及运行 id。完成事件会附加 + `durationMs`、`outcome`、可选的 `resultClassification`、`yieldDetected` + 和 `itemLifecycle` 计数。错误事件会附加 `phase` + （`prepare`/`start`/`send`/`resolve`/`cleanup`）、`errorCategory` 以及 + 可选的 `cleanupFailed`。 **Exec** -- `exec.process.completed` — 最终结果、时长、目标、模式、退出码和失败类型。不包含命令文本和工作目录。 +- `exec.process.completed` — 最终结果、时长、目标、模式、退出 + 码和失败类型。不包含命令文本和工作目录。 ## 不使用导出器 -你可以在不运行 `diagnostics-otel` 的情况下，仍然让诊断事件可供插件或自定义接收端使用： +你可以在不运行 `diagnostics-otel` 的情况下，仍让诊断事件可供插件或自定义接收器使用： ```json5 { @@ -265,7 +301,9 @@ openclaw plugins enable diagnostics-otel } ``` -如果想在不提高 `logging.level` 的情况下输出定向调试信息，请使用诊断标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）： +若想在不提高 `logging.level` 的情况下获得定向调试输出，请使用诊断 +标志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 +`*`）： ```json5 { @@ -279,7 +317,8 @@ openclaw plugins enable diagnostics-otel OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -标志输出会进入标准日志文件（`logging.file`），并且仍会由 `logging.redactSensitive` 进行脱敏。完整指南： +标志输出会进入标准日志文件（`logging.file`），并且仍会受到 +`logging.redactSensitive` 的脱敏处理。完整指南： [诊断标志](/zh-CN/diagnostics/flags)。 ## 禁用 @@ -290,13 +329,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway } ``` -你也可以不在 `plugins.allow` 中加入 `diagnostics-otel`，或者运行 +你也可以不将 `diagnostics-otel` 加入 `plugins.allow`，或者运行 `openclaw plugins disable diagnostics-otel`。 ## 相关内容 -- [日志](/zh-CN/logging) — 文件日志、控制台输出、CLI tail，以及 Control UI 的日志标签页 -- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 +- [日志记录](/zh-CN/logging) — 文件日志、控制台输出、CLI tail 和 Control UI 日志标签页 +- [Gateway 网关日志记录内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 - [诊断标志](/zh-CN/diagnostics/flags) — 定向调试日志标志 -- [诊断导出](/zh-CN/gateway/diagnostics) — 面向运维的支持包工具（与 OTEL 导出分开） +- [诊断导出](/zh-CN/gateway/diagnostics) — 面向运维人员的支持包工具（与 OTEL 导出分开） - [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考 diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index 28c039bda..41f2d789f 100644 --- a/docs/zh-CN/logging.md +++ b/docs/zh-CN/logging.md @@ -1,37 +1,35 @@ --- read_when: - 你需要一份适合初学者的 OpenClaw 日志概览 - - 你想要配置日志级别、格式或敏感信息脱敏处理 + - 你想配置日志级别、格式或脱敏处理 - 你正在进行故障排除，需要快速找到日志 -summary: 文件日志、控制台输出、CLI 尾部输出，以及 Control UI 的“日志”选项卡 +summary: 文件日志、控制台输出、CLI 尾部日志，以及 Control UI 的日志标签页 title: 日志 x-i18n: - generated_at: "2026-04-26T19:56:09Z" + generated_at: "2026-04-26T20:47:22Z" model: gpt-5.4 provider: openai - source_hash: b4846f17e911e6fc2c202ec78ce83c8d0fc8e567942f88324ffc1ba230c0b8b0 + source_hash: 2a6e363818e1d48b8b265bf18214772f40ffd55c423acd50dee7659f37b44bfa source_path: logging.md workflow: 15 --- -OpenClaw 有两个主要的日志界面： +OpenClaw 有两个主要的日志表面： -- 由 Gateway 网关写入的**文件日志**（JSON 行）。 +- 由 Gateway 网关写入的**文件日志**（JSON Lines）。 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。 -Control UI 的**日志**选项卡会尾随 Gateway 网关文件日志。本页说明日志位于哪里、如何阅读日志，以及如何配置日志级别和格式。 +Control UI 的**日志**标签页会实时跟踪 gateway 文件日志。此页面说明日志位于哪里、如何读取它们，以及如何配置日志级别和格式。 -## 日志位于哪里 +## 日志位置 -默认情况下，Gateway 网关会在以下位置写入滚动日志文件： +默认情况下，Gateway 网关会在以下路径写入滚动日志文件： `/tmp/openclaw/openclaw-YYYY-MM-DD.log` -日期使用 Gateway 网关主机的本地时区。 +日期使用 gateway 主机的本地时区。 -每个文件在达到 `logging.maxFileBytes` 时轮转（默认值：100 MB）。 -OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件，例如 -`openclaw-YYYY-MM-DD.1.log`，并继续写入新的活动日志文件，而不是抑制诊断信息。 +每个文件在达到 `logging.maxFileBytes`（默认：100 MB）时轮转。OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件，例如 `openclaw-YYYY-MM-DD.1.log`，并继续写入一个新的活动日志文件，而不是抑制诊断信息。 你可以在 `~/.openclaw/openclaw.json` 中覆盖此设置： @@ -43,11 +41,11 @@ OpenClaw 会在活动文件旁边最多保留五个带编号的归档文件， } ``` -## 如何阅读日志 +## 如何读取日志 -### CLI：实时尾随（推荐） +### CLI：实时 tail（推荐） -使用 CLI 通过 RPC 尾随 Gateway 网关日志文件： +使用 CLI 通过 RPC 实时跟踪 gateway 日志文件： ```bash openclaw logs --follow @@ -67,27 +65,27 @@ openclaw logs --follow - `--plain`：在 TTY 会话中强制使用纯文本。 - `--no-color`：禁用 ANSI 颜色。 -当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要认证，请自行包含 `--token`。 +当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量中的凭证；如果目标 Gateway 网关需要身份验证，请自行包含 `--token`。 -在 JSON 模式下，CLI 会输出带 `type` 标签的对象： +在 JSON 模式下，CLI 会输出带有 `type` 标签的对象： - `meta`：流元数据（文件、游标、大小） - `log`：已解析的日志条目 - `notice`：截断 / 轮转提示 -- `raw`：未解析的原始日志行 +- `raw`：未解析的日志行 -如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式 `--url` 目标不会使用此回退。 +如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式的 `--url` 目标不会使用此回退。 -如果 Gateway 网关不可访问，CLI 会打印一条简短提示，建议运行： +如果 Gateway 网关无法访问，CLI 会打印一个简短提示，建议运行： ```bash openclaw doctor ``` -### Control UI（网页） +### Control UI（Web） -Control UI 的**日志**选项卡会使用 `logs.tail` 尾随同一个文件。 -有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 +Control UI 的**日志**标签页会使用 `logs.tail` 实时跟踪同一个文件。 +关于如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 ### 仅渠道日志 @@ -101,14 +99,14 @@ openclaw channels logs --channel whatsapp ### 文件日志（JSONL） -日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以呈现结构化输出（时间、级别、子系统、消息）。 +日志文件中的每一行都是一个 JSON 对象。CLI 和 Control UI 会解析这些条目，以渲染结构化输出（时间、级别、子系统、消息）。 ### 控制台输出 -控制台日志会**感知 TTY**，并以便于阅读的方式格式化： +控制台日志**感知 TTY**，并针对可读性进行了格式化： - 子系统前缀（例如 `gateway/channels/whatsapp`） -- 级别着色（info/warn/error） +- 级别颜色区分（info/warn/error） - 可选的紧凑或 JSON 模式 控制台格式由 `logging.consoleStyle` 控制。 @@ -117,9 +115,9 @@ openclaw channels logs --channel whatsapp `openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志： -- 普通模式：仅记录值得关注的结果（错误、解析错误、慢调用） -- `--verbose`：记录所有请求/响应流量 -- `--ws-log auto|compact|full`：选择详细输出的渲染样式 +- 普通模式：仅显示重要结果（错误、解析错误、慢调用） +- `--verbose`：显示所有请求/响应流量 +- `--ws-log auto|compact|full`：选择详细日志的渲染样式 - `--compact`：`--ws-log compact` 的别名 示例： @@ -130,7 +128,7 @@ openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` -## 配置日志记录 +## 配置日志 所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。 @@ -152,50 +150,54 @@ openclaw gateway --verbose --ws-log full - `logging.level`：**文件日志**（JSONL）级别。 - `logging.consoleLevel`：**控制台**详细程度级别。 -你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level `**（例如 `openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。该环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅为单次运行提高详细程度。你也可以传递全局 CLI 选项 **`--log-level `**（例如 `openclaw --log-level debug gateway run`），它会为该命令覆盖环境变量。 -`--verbose` 仅影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 +`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 -### 追踪关联 +### 跟踪关联 -文件日志采用 JSONL 格式。当一次日志调用携带有效的诊断追踪上下文时， -OpenClaw 会将追踪字段写为顶层 JSON 键（`traceId`、`spanId`、 -`parentSpanId`、`traceFlags`），以便外部日志处理器能够将该行与 OTEL span 以及 provider `traceparent` 传播关联起来。 +文件日志是 JSONL。当一次日志调用携带有效的诊断跟踪上下文时，OpenClaw 会将跟踪字段写为顶层 JSON 键（`traceId`、`spanId`、`parentSpanId`、`traceFlags`），以便外部日志处理器将该行与 OTEL span 以及 provider 的 `traceparent` 传播关联起来。 + +### 模型调用大小与时序 + +模型调用诊断会记录有界的请求/响应测量数据，而不会捕获原始提示词或响应内容： + +- `requestPayloadBytes`：最终模型请求负载的 UTF-8 字节大小 +- `responseStreamBytes`：流式模型响应事件的 UTF-8 字节大小 +- `timeToFirstByteMs`：首个流式响应事件之前经过的时间 +- `durationMs`：模型调用总时长 + +启用诊断导出后，这些字段可用于诊断快照、模型调用插件钩子，以及 OTEL 模型调用 span / 指标。 ### 控制台样式 `logging.consoleStyle`： -- `pretty`：适合人类阅读、带颜色、包含时间戳。 +- `pretty`：适合人类阅读，带颜色和时间戳。 - `compact`：更紧凑的输出（最适合长时间会话）。 - `json`：每行一个 JSON（用于日志处理器）。 -### 脱敏处理 +### 脱敏 -OpenClaw 可以在敏感令牌写入控制台输出、文件日志、OTLP 日志记录或持久化会话转录文本之前，对其进行脱敏处理： +OpenClaw 可以在敏感令牌写入控制台输出、文件日志、OTLP 日志记录或持久化的会话转录文本之前对其进行脱敏： -- `logging.redactSensitive`：`off` | `tools`（默认值：`tools`） +- `logging.redactSensitive`：`off` | `tools`（默认：`tools`） - `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表 -文件日志和会话转录仍保持为 JSONL，但匹配到的敏感值会在该行或消息写入磁盘之前被遮蔽。脱敏处理是尽力而为的：它适用于承载文本的消息内容和日志字符串，而不是每个标识符或二进制负载字段。 +文件日志和会话转录仍然保持为 JSONL，但匹配到的敏感值会在该行或消息写入磁盘前被屏蔽。脱敏属于尽力而为：它适用于承载文本的消息内容和日志字符串，而不是每一个标识符或二进制负载字段。 ## 诊断与 OpenTelemetry -诊断是结构化、机器可读的事件，用于模型运行和消息流遥测（webhook、排队、会话状态）。它们**不会**替代日志——它们为指标、追踪和导出器提供数据。无论你是否导出它们，这些事件都会在进程内发出。 +诊断是针对模型运行和消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志——它们用于提供指标、跟踪和导出器。无论你是否导出它们，这些事件都会在进程内发出。 -两个相邻界面： +两个相邻的表面： -- **OpenTelemetry 导出**——通过 OTLP/HTTP 将指标、追踪和日志发送到任何兼容 OpenTelemetry 的收集器或后端（Grafana、Datadog、 - Honeycomb、New Relic、Tempo 等）。完整配置、信号目录、 - 指标 / span 名称、环境变量以及隐私模型位于专门页面： - [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。 -- **诊断标志**——有针对性的调试日志标志，可将额外日志路由到 - `logging.file`，而无需提高 `logging.level`。标志不区分大小写， - 并支持通配符（`telegram.*`、`*`）。可在 `diagnostics.flags` - 下配置，或通过 `OPENCLAW_DIAGNOSTICS=...` 环境变量覆盖。完整指南： - [Diagnostics flags](/zh-CN/diagnostics/flags)。 +- **OpenTelemetry 导出** —— 通过 OTLP/HTTP 将指标、跟踪和日志发送到任何兼容 OpenTelemetry 的收集器或后端（Grafana、Datadog、Honeycomb、New Relic、Tempo 等）。完整配置、信号目录、指标 / span 名称、环境变量和隐私模型位于专门页面中： + [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 +- **诊断标志** —— 有针对性的调试日志标志，可将额外日志路由到 `logging.file`，而无需提高 `logging.level`。标志不区分大小写，并支持通配符（`telegram.*`、`*`）。可在 `diagnostics.flags` 下配置，或通过 `OPENCLAW_DIAGNOSTICS=...` 环境变量覆盖。完整指南： + [诊断标志](/zh-CN/diagnostics/flags)。 -要为插件或自定义接收器启用诊断事件，而不使用 OTLP 导出： +如果你想为插件或自定义 sink 启用诊断事件，而不使用 OTLP 导出： ```json5 { @@ -203,17 +205,17 @@ OpenClaw 可以在敏感令牌写入控制台输出、文件日志、OTLP 日志 } ``` -要将 OTLP 导出到收集器，请参见 [OpenTelemetry export](/zh-CN/gateway/opentelemetry)。 +如需将 OTLP 导出到收集器，请参见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。 ## 故障排除提示 -- **Gateway 网关不可访问？** 先运行 `openclaw doctor`。 -- **日志为空？** 检查 Gateway 网关是否正在运行，并且是否正在写入 `logging.file` 中的文件路径。 -- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace`，然后重试。 +- **Gateway 网关无法访问？** 先运行 `openclaw doctor`。 +- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在写入 `logging.file` 中的文件路径。 +- **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。 ## 相关内容 -- [OpenTelemetry export](/zh-CN/gateway/opentelemetry) — OTLP/HTTP 导出、指标 / span 目录、隐私模型 -- [Diagnostics flags](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志 -- [Gateway logging internals](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 -- [Configuration reference](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考 +- [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry) — OTLP/HTTP 导出、指标 / span 目录、隐私模型 +- [诊断标志](/zh-CN/diagnostics/flags) — 有针对性的调试日志标志 +- [Gateway 网关日志内部机制](/zh-CN/gateway/logging) — WS 日志样式、子系统前缀和控制台捕获 +- [配置参考](/zh-CN/gateway/configuration-reference#diagnostics) — 完整的 `diagnostics.*` 字段参考