本页内容
本页内容
网关
OpenTelemetry配置
导出的信号
| Signal | 里面有什么 |
|---|---|
| 指标 | Counters/histograms 用于令牌使用、成本、运行持续时间、故障转移、技能使用、消息流、Talk 事件、队列通道、会话 state/recovery、工具执行、执行、内存、活跃度和导出器运行状况。 |
| 痕迹 | 涵盖模型使用、模型调用、harness生命周期、技能使用、工具执行、执行、webhook/message 处理、上下文组装和工具循环。 |
| 日志 | 当启用 diagnostics.otel.logs 时，通过 OTLP 或标准输出 JSONL 导出结构化 logging.file 记录；除非明确启用内容捕获，否则日志正文将被保留。 |
可分别切换 traces、metrics 和 logs。当 diagnostics.otel.enabled 为 true 时，traces 和 metrics 默认开启；logs 默认关闭，仅在 diagnostics.otel.logs 显式设为 true 时才导出。日志导出默认使用 OTLP；将 diagnostics.otel.logsExporter 设置为 stdout 可在 stdout 输出 JSONL，设置为 both 则两者都输出。
配置参考
metricNamePrefix 仅在 OpenClaw- 拥有的指标上替换默认的 openclaw. 前缀。例如，"acme." 将 openclaw.tokens 导出为 acme.tokens；将其设置为 "" 以导出不带前缀的 tokens。非空值必须以 ASCII 字母开头，只能使用字母、数字、下划线、点、连字符和斜杠，并且最多包含 128 个字符。如果您想要 acme.openclaw.tokens，请将其设置为 "acme.openclaw."。标准语义约定指标（例如 gen_ai.client.token.usage 和 gen_ai.client.operation.duration）保留其原始名称。保留该选项未设置以保留每个当前指标名称。启用或更改此选项会重命名受影响的指标系列，因此请更新查询旧名称的仪表板、警报和记录规则。
环境变量
| 变量 | 用途 |
|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
当配置键未设置时，作为 diagnostics.otel.endpoint 的回退值。 |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT / OTEL_EXPORTER_OTLP_LOGS_ENDPOINT |
当匹配的 diagnostics.otel.*Endpoint 配置密钥未设置时，使用 Signal- 特定端点回退。 Signal-特定配置胜过信号特定环境，后者胜过共享端点。 |
OTEL_SERVICE_NAME |
当配置键未设置时，作为 diagnostics.otel.serviceName 的回退值。默认服务名称为 openclaw。 |
OTEL_EXPORTER_OTLP_PROTOCOL |
当 diagnostics.otel.protocol 和信号专用协议变量均未设置时使用的共享进程环境回退值。只有 http/protobuf 才会启用插件自有的 OTLP 导出器。 |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL / OTEL_EXPORTER_OTLP_METRICS_PROTOCOL / OTEL_EXPORTER_OTLP_LOGS_PROTOCOL |
当 diagnostics.otel.protocol 未设置时使用 Signal- 特定协议回退。非空信号特定值胜过共享协议值。不支持的值仅禁用插件拥有的 OTLP 信号。 |
OTEL_PROPAGATORS |
为每个插件自有的生成注册的传播器，包括 OTEL_SDK_DISABLED=true 时。默认为 tracecontext,baggage；none 会禁用自动传播。值不区分大小写。不可用的值以及已弃用的 jaeger 用法会发出插件警告。 |
OTEL_SDK_DISABLED |
不区分大小写的 true 会在端点、协议或 TLS 设置之前禁用所有插件自有的追踪、指标、日志和 stdout 路由。任何其他值都会使 SDK 保持启用；无法识别的值会发出插件警告并回退为 false。异步上下文和 OTEL_PROPAGATORS 仍保持活动状态。 |
OTEL_NODE_RESOURCE_DETECTORS |
为插件拥有的跟踪和指标提供程序选择资源检测器。支持的代币为env、host、os、process和serviceinstance； all 按主机、OS、服务实例、进程、环境顺序运行它们，而 none 禁用检测。默认是环境、进程、然后是主机。显式 OpenClaw 服务配置赢得检测器属性。 |
OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG |
当 diagnostics.otel.sampleRate 未设置时使用的标准 OpenTelemetry 采样器选择。显式的 sampleRate 仍然是优先级更高的 OpenClaw 采样器。 |
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT / OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT / OTEL_SPAN_EVENT_COUNT_LIMIT / OTEL_SPAN_LINK_COUNT_LIMIT / OTEL_SPAN_ATTRIBUTE_PER_EVENT_COUNT_LIMIT / OTEL_SPAN_ATTRIBUTE_PER_LINK_COUNT_LIMIT |
每个插件自有的追踪提供程序所应用的标准 OpenTelemetry span 限制。 |
OTEL_BSP_MAX_QUEUE_SIZE / OTEL_BSP_MAX_EXPORT_BATCH_SIZE / OTEL_BSP_SCHEDULE_DELAY / OTEL_BSP_EXPORT_TIMEOUT |
插件自有追踪导出的批处理 span 处理器设置。值必须为正数；无效值使用 OpenTelemetry 默认值。导出批次大小不会超过队列大小。 |
OTEL_METRIC_EXPORT_INTERVAL / OTEL_METRIC_EXPORT_TIMEOUT |
插件自有指标的周期性导出间隔和超时时间。值必须为正数；无效值使用 OpenTelemetry 默认值，并且超时时间不会超过当前活动间隔。diagnostics.otel.flushIntervalMs 会覆盖该间隔。 |
OTEL_NODE_EXPERIMENTAL_SDK_METRICS |
设置为 true 时，为私有 meter、tracer 和批处理 span 处理器启用 OpenTelemetry SDK 自观测指标。 |
OTEL_LOG_LEVEL |
拥有模式不会取代进程全局 OpenTelemetry 诊断记录器，因为公共 SDK API 不公开生成私有等效项。预加载或主机可以在 OpenClaw 启动之前配置此变量；该插件保留该外部诊断所有者。 |
OTEL_SEMCONV_STABILITY_OPT_IN |
设置为 gen_ai_latest_experimental 时，发出最新的 GenAI 推理 span 形态：使用 {gen_ai.operation.name} {gen_ai.request.model} 作为 span 名称、使用 CLIENT span 类型，并使用 gen_ai.provider.name 替代旧版的 gen_ai.system。无论如何，GenAI 指标始终使用有界的低基数属性。 |
OPENCLAW_OTEL_PRELOADED |
当其他 preload 或宿主进程已经注册全局 OpenTelemetry 提供程序时设置为 1。插件会使用外部的追踪、指标、上下文、传播和日志记录器所有权，而不会注册、替换、禁用、注销或关闭它们。当 OTEL_SDK_DISABLED=true 时，外部所有权仍保持活动状态，而插件自有日志会保持禁用。 |
如果没有 OPENCLAW_OTEL_PRELOADED=1，跟踪、指标和日志提供程序都是生成私有的。该插件仅通过公共 OpenTelemetry API 发布其异步上下文管理器和传播器，并在服务停止时删除它安装的注册。在用另一台主机 SDK 替换这些全局变量之前停止服务；在运行时更换它们是最好的努力。
采样和刷新
- 跟踪：
diagnostics.otel.sampleRate会仅在根 span 上设置TraceIdRatioBasedSampler（0.0丢弃全部，1.0保留全部）。未设置时使用 OpenTelemetry SDK 默认值（始终开启）。 - 指标：
diagnostics.otel.flushIntervalMs（最小值会被限制为1000）；未设置时使用 SDK 的周期导出默认值。 - Logs： OTLP 日志遵循
logging.level（文件日志级别）并使用诊断日志记录编辑路径，而不是控制台格式。大批量安装应优先选择 OTLP 收集器 sampling/filtering 而不是本地采样。当您的平台已将 stdout/stderr 发送到日志处理器并且您没有 OTLP 日志收集器时，请设置diagnostics.otel.logsExporter: "stdout"。标准输出记录是每行一个 JSON 对象，包含ts、signal、service.name、严重性、正文、编辑属性和可信跟踪字段（如果可用）。 - 文件日志关联： 当日志调用携带有效的诊断 trace 上下文时，JSONL 文件日志会包含顶层的
traceId、spanId、parentSpanId和traceFlags，使日志处理器能够将本地日志行与导出的 spans 关联起来。 - 请求关联： Gateway HTTP 请求和 WebSocket 帧会创建一个内部请求 trace 作用域。该作用域内的日志和诊断事件默认继承请求 trace，而 agent run 和 model-call spans 会作为子 span 创建，因此 provider 的
traceparent头会保留在同一条 trace 上。 - 模型调用关联：
openclaw.model.callspans 默认包含安全的 prompt 组件大小，并在 provider 结果暴露 usage 时包含每次调用的 token 属性。openclaw.model.usage仍然是用于汇总成本、上下文和 channel 仪表板的 run 级计费 span，并且当发出它的运行时具有受信任的 trace 上下文时，会保持在同一条诊断 trace 上。
本页有帮助吗？