clawpro-diagnostics-metrics-cls 2.0.3 → 3.0.0

package/README.md

@@ -49,6 +49,7 @@ OpenClaw 诊断指标导出插件，提供以下核心能力：
   - [CLS 配置](#cls-配置)
   - [Prometheus 配置](#prometheus-配置可选)
   - [Trace 配置](#trace-配置可选)
+  - [Log 日志上报配置](#log-日志上报配置可选)
 - [功能说明](#功能说明)
   - [Prometheus 指标列表](#prometheus-指标列表)
   - [全链路 Trace 追踪](#全链路-trace-追踪)
@@ -102,6 +103,12 @@ npx --yes clawpro-diagnostics-metrics-cls-onboard-cli install
 | `--externalLabels <labels>` | Prometheus 自定义标签（格式：`key1=value1,key2=value2`） | 可选 |
 | `--traceEnabled <bool>` | 是否启用 Trace 链路追踪功能（`true`/`false`，默认 `true`） | 可选 |
 | `--traceTopicId <id>` | Trace 数据上报使用的 CLS 日志主题 ID | 可选（可在配置文件中动态更新） |
+| `--enableLogReport <bool>` | 是否启用日志上报（`true`/`false`，默认 `false`） | 可选 |
+| `--logTopicId <id>` | 日志上报使用的 CLS 日志主题 ID | 可选（可在配置文件中动态更新） |
+| `--logSource <source>` | 日志来源标识，写入每条日志的 `source` 字段（默认 `openclaw`） | 可选 |
+| `--enableGatewayLog <bool>` | 是否启用 gateway 运行日志上报（`true`/`false`，默认 `true`） | 可选 |
+| `--enableSessionLog <bool>` | 是否启用会话日志上报（`true`/`false`，默认 `true`） | 可选 |
+| `--logMinLevel <level>` | 最低上报日志级别，仅对 gateway 运行日志生效（默认 `info`） | 可选 |
 | `--instanceId <id>` | 显式指定实例 ID，写入配置文件后插件启动时直接使用，跳过腾讯云 metadata 接口请求 | 可选 |
 | `--instanceName <name>` | 显式指定实例名称，仅覆盖 `cvm_instance_name`，不影响 `host_name`（后者始终取 `os.hostname()`） | 可选 |
 | `--localIpv4 <ip>` | 显式指定内网 IPv4 | 可选 |
@@ -373,7 +380,7 @@ Prometheus 功能通过插件的 `config.prometheus` 配置项控制，与 `cls`
                 "url": "http://prometheus:9090/api/v1/write"
               }
             ],
-            "push_interval_ms": 15000
+            "push_interval_ms": 30000
           }
         }
       }
@@ -391,7 +398,7 @@ Prometheus 功能通过插件的 `config.prometheus` 配置项控制，与 `cls`
 | `pull` | boolean | `true` | 是否启用 `/metrics` HTTP Pull 端点 |
 | `default_metrics` | boolean | `true` | 是否采集 Node.js 默认指标（GC、事件循环等） |
 | `external_labels` | object | `{}` | 附加到所有指标的自定义标签 |
-| `push_interval_ms` | number | `15000` | Remote Write 推送间隔（毫秒） |
+| `push_interval_ms` | number | `30000` | Remote Write 推送间隔（毫秒） |
 
 > **说明**：当部署在腾讯云环境时，插件会自动注入实例元数据作为标签（`cvm_instance_id`、`cvm_instance_name`、`cvm_instance_intra_ip`）。若在 `external_labels` 中手动配置了同名标签，则以手动配置的值为准。
 
@@ -494,7 +501,142 @@ Trace 功能通过插件的 `config.trace` 配置项控制，与 `cls` 和 `prom
 
 ---
 
-## 功能说明
+### Log 日志上报配置（可选）
+
+Log 日志上报功能通过插件的 `config.log` 配置项控制，与 `cls`、`prometheus` 和 `trace` 配置并列放在 `plugins.entries["clawpro-diagnostics-metrics-cls"].config` 下。
+
+**Log 模块复用 `cls` 配置中的 `secretId` / `secretKey` / `endpoint` 凭证**，只需在 `log` 中独立配置 `enableLogReport` 和 `logTopicId`。
+
+> **默认关闭**：`enableLogReport` 默认为 `false`，需显式设置为 `true` 才会启用日志上报。
+
+#### Log 模块与 Trace 模块的区别
+
+| 维度 | Log 模块 | Trace 模块 |
+|------|---------|-----------|
+| **数据来源** | Gateway 运行日志 + 会话消息（session JSONL） | Agent 执行过程中的 Span 事件 |
+| **数据格式** | 扁平化 KV 字段（`log_type`、`level`、`message`、`role`、`content` 等） | OTel GenAI 标准 Span 格式（`traceID`、`spanID`、`parentSpanID`、`kind` 等） |
+| **查询场景** | 运维排障、会话内容审计、日志级别过滤 | 全链路调用追踪、LLM 耗时分析、工具调用链路 |
+| **日志主题** | `logTopicId`（独立配置） | `traceTopicId`（独立配置） |
+| **默认状态** | 默认关闭（`enableLogReport=false`） | 默认关闭（`enabled=false`） |
+
+#### 上报的日志类型
+
+1. **Gateway 运行日志**（`log_type=gateway`）：OpenClaw gateway 进程的运行日志，通过 `registerLogTransport` 实时 flush 流上报，不读取本地日志文件
+2. **会话日志**（`log_type=session`）：每条写入会话 JSONL 的消息，通过 `before_message_write` hook 实时上报，与 session JSONL 文件内容完全一致
+
+在 `~/.openclaw/openclaw.json` 中添加：
+
+```json
+{
+  "plugins": {
+    "allow": ["clawpro-diagnostics-metrics-cls"],
+    "entries": {
+      "clawpro-diagnostics-metrics-cls": {
+        "enabled": true,
+        "config": {
+          "cls": {
+            "secretId": "your-secret-id",
+            "secretKey": "your-secret-key",
+            "endpoint": "ap-guangzhou.cls.tencentcs.com"
+          },
+          "log": {
+            "enableLogReport": true,
+            "logTopicId": "your-log-topic-id",
+            "enableGatewayLog": true,
+            "enableSessionLog": true,
+            "minLevel": "info"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### Log 基础配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enableLogReport` | boolean | `false` | **是否启用日志上报**，默认关闭，需显式设置为 `true` |
+| `logTopicId` | string | — | **必填**（启用时）。日志上报使用的 CLS 日志主题 ID |
+| `source` | string | `"openclaw"` | 日志来源标识，写入每条日志的 `source` 字段 |
+| `enableGatewayLog` | boolean | `true` | 是否启用 gateway 运行日志上报 |
+| `enableSessionLog` | boolean | `true` | 是否启用会话日志上报（session JSONL） |
+| `minLevel` | string | `"info"` | 最低上报日志级别（仅对 gateway 运行日志生效），可选值：`trace`、`debug`、`info`、`warn`、`error`、`fatal` |
+| `sendTimeThreshold` | number | `2` | 异步发送时间阈值（秒） |
+| `sendCountThreshold` | number | `1000` | 异步发送条数阈值 |
+
+> **注意**：
+> - Log 功能复用 `cls` 配置中的 `secretId` / `secretKey` / `endpoint` / `token`，无需在 `log` 中重复配置凭证
+> - Log 功能使用独立的 CLS 日志主题（`logTopicId`），与 Prometheus 指标（`metricTopicId`）和 Trace（`traceTopicId`）分开
+> - 所有日志均通过实时 flush 流上报，**不读取本地日志文件**
+> - `enableLogReport` 默认为 `false`，避免在未配置 `logTopicId` 时意外上报
+
+#### CLS 日志字段说明
+
+每条上报到 CLS 的日志均包含以下字段（以 CLS LogItem KV 格式存储）：
+
+**Gateway 运行日志（`log_type=gateway`）公共字段：**
+
+| 字段名 | 说明 | 示例值 |
+|--------|------|--------|
+| `log_type` | 日志类型，固定为 `gateway` | `gateway` |
+| `level` | 日志级别 | `info`、`warn`、`error` |
+| `message` | 日志消息内容 | `Plugin started successfully` |
+| `source` | 日志来源标识（对应 `log.source` 配置） | `openclaw` |
+| `subsystem` | 子系统名称（来自 tslog bindings，可选） | `cls-service`、`trace-service` |
+| `logger` | logger 实例名称（可选） | `openclaw` |
+| `args` | 额外参数（JSON 序列化，可选） | `[{"key":"value"}]` |
+| `cvm_instance_id` | CVM 实例 ID（仅在腾讯云 CVM 环境下注入） | `ins-xxxxxxxx` |
+| `cvm_instance_name` | CVM 实例名称（仅在腾讯云 CVM 环境下注入） | `my-cvm-instance` |
+| `cvm_instance_intra_ip` | CVM 内网 IPv4（仅在腾讯云 CVM 环境下注入） | `10.0.0.1` |
+
+**会话日志（`log_type=session`）公共字段：**
+
+| 字段名 | 说明 | 示例值 |
+|--------|------|--------|
+| `log_type` | 日志类型，固定为 `session` | `session` |
+| `role` | 消息角色 | `user`、`assistant`、`toolResult` |
+| `content` | 完整消息 JSON（与写入 session JSONL 文件的行内容一致） | `{"role":"user","content":"..."}` |
+| `source` | 日志来源标识 | `openclaw` |
+| `session_key` | 会话标识 | `feishu_xxxxxxxx` |
+| `agent_id` | Agent 标识 | `default` |
+| `tool_call_id` | 工具调用 ID（仅 `role=toolResult` 时存在） | `toolu_xxxxxxxx` |
+| `tool_name` | 工具名称（仅 `role=toolResult` 时存在） | `web_search` |
+| `stop_reason` | 停止原因（仅 `role=assistant` 时存在） | `tool_use`、`end_turn` |
+| `tool_calls` | 工具调用数量（仅 `role=assistant` 且包含工具调用时存在） | `2` |
+| `cvm_instance_id` | CVM 实例 ID（仅在腾讯云 CVM 环境下注入） | `ins-xxxxxxxx` |
+| `cvm_instance_name` | CVM 实例名称（仅在腾讯云 CVM 环境下注入） | `my-cvm-instance` |
+| `cvm_instance_intra_ip` | CVM 内网 IPv4（仅在腾讯云 CVM 环境下注入） | `10.0.0.1` |
+
+#### CLS 日志查询示例
+
+在腾讯云 CLS 控制台，选择 `logTopicId` 对应的日志主题，使用以下检索语句：
+
+**查询所有 gateway 运行日志（warn 及以上级别）：**
+```
+log_type:gateway AND (level:warn OR level:error OR level:fatal)
+```
+
+**查询指定会话的所有消息：**
+```
+log_type:session AND session_key:feishu_xxxxxxxx
+```
+
+**查询包含工具调用的 assistant 消息：**
+```
+log_type:session AND role:assistant AND tool_calls:*
+```
+
+**查询指定工具的执行结果：**
+```
+log_type:session AND role:toolResult AND tool_name:web_search
+```
+
+**查询指定时间段内的 error 日志：**
+```
+log_type:gateway AND level:error
+```
 
 ### Prometheus 指标列表
 
@@ -1113,6 +1255,12 @@ npx --yes clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter [选项]
 | `--externalLabels <labels>` | Prometheus 自定义标签（格式：`key1=value1,key2=value2`） | ✅ 需要重启网关 |
 | `--traceEnabled <bool>` | 是否启用 Trace 链路追踪功能（`true`/`false`） | ❌ 热加载（约 10 秒内生效） |
 | `--traceTopicId <id>` | Trace 数据上报使用的 CLS 日志主题 ID | ❌ 热加载（约 10 秒内生效） |
+| `--enableLogReport <bool>` | 是否启用日志上报（`true`/`false`） | ❌ 热加载（约 10 秒内生效） |
+| `--logTopicId <id>` | 日志上报使用的 CLS 日志主题 ID | ❌ 热加载（约 10 秒内生效） |
+| `--logSource <source>` | 日志来源标识，写入每条日志的 `source` 字段（默认 `openclaw`） | ❌ 热加载（约 10 秒内生效） |
+| `--enableGatewayLog <bool>` | 是否启用 gateway 运行日志上报（`true`/`false`） | ❌ 热加载（约 10 秒内生效） |
+| `--enableSessionLog <bool>` | 是否启用会话日志上报（`true`/`false`） | ❌ 热加载（约 10 秒内生效） |
+| `--logMinLevel <level>` | 最低上报日志级别，仅对 gateway 运行日志生效（`trace`/`debug`/`info`/`warn`/`error`/`fatal`） | ❌ 热加载（约 10 秒内生效） |
 | `--instanceId <id>` | 显式指定实例 ID，写入配置文件后插件启动时直接使用，跳过腾讯云 metadata 接口请求 | ❌ 热加载（约 10 秒内生效） |
 | `--instanceName <name>` | 显式指定实例名称，仅覆盖 `cvm_instance_name`（不影响 `host_name`） | ❌ 热加载（约 10 秒内生效） |
 | `--localIpv4 <ip>` | 显式指定内网 IPv4 | ❌ 热加载（约 10 秒内生效） |
@@ -1248,6 +1396,12 @@ npx clawpro-diagnostics-metrics-cls-onboard-cli UpdateParameter \
 | `trace.traceTopicId` | 自动切换 Trace 数据上报的 CLS 日志主题 |
 | `trace.debug` | 动态开启/关闭 Trace 调试日志，无需重启即可在运行时排查问题 |
 | `trace.enabledHooks` | 动态调整启用的 hook 列表，可在运行时按需启用/禁用特定 hook，无需重启 |
+| `log.enableLogReport` | 动态启用/禁用日志上报。`false` 时立即停止上报并释放 Producer；`true` 时（需同时配置 `logTopicId`）约 10 秒内自动恢复 |
+| `log.logTopicId` | 自动切换日志上报的 CLS 日志主题，切换后立即重建 Producer 使新主题生效 |
+| `log.source` | 动态更新写入每条日志的 `source` 字段标识 |
+| `log.enableGatewayLog` | 动态开启/关闭 gateway 运行日志上报（注意：关闭后需重启网关才能重新注册 transport） |
+| `log.enableSessionLog` | 动态开启/关闭会话日志上报（session JSONL） |
+| `log.minLevel` | 动态调整 gateway 运行日志的最低上报级别，无需重启即可在运行时过滤噪音日志 |
 
 > **注意**：`credentialMode`、`roleName` 等凭证模式相关字段，以及 `prometheusEnabled`、`pushIntervalMs`、`externalLabels` 等 Prometheus 配置字段变更后需要重启网关才能生效。可通过 `UpdateParameter` 命令更新，CLI 会自动判断是否需要重启。
 >
@@ -1722,11 +1876,11 @@ npx clawpro-diagnostics-metrics-cls-onboard-cli install --credentialMode cvmRole
                 }
               }
             ],
-            "push_interval_ms": 15000
+            "push_interval_ms": 30000
           },
           "cls": {
             "metricTopicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
-            "secretId": "ENC:dGhpcyBpcyBhIGJhc2U2NCBleGFtcGxl...",
+            "secretId": "ENC:            "secretId": "ENC:dGhpcyBpcyBhIGJhc2U2NCBleGFtcGxl...",
             "secretKey": "ENC:YW5vdGhlciBiYXNlNjQgZXhhbXBsZQ==",
             "endpoint": "ap-guangzhou.cls.tencentcs.com",
             "enableReport": true
@@ -1777,11 +1931,10 @@ npx clawpro-diagnostics-metrics-cls-onboard-cli install --credentialMode cvmRole
                 }
               }
             ],
-            "push_interval_ms": 15000
+            "push_interval_ms": 30000
           },
           "cls": {
-            "credentialMode": "cvmRole",
-            "roleName": "CVM",
+            "credentialMode": "cvmRole"            "roleName": "CVM",
             "metricTopicId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
             "endpoint": "ap-guangzhou.cls.tencentcs.com",
             "enableReport": true

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: string;
+        properties: {
+            prometheus: {
+                type: string;
+                description: string;
+                properties: {
+                    enabled: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    metric_prefix: {
+                        type: string;
+                        default: string;
+                        description: string;
+                    };
+                    pull: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    default_metrics: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    push_interval_ms: {
+                        type: string;
+                        default: number;
+                        description: string;
+                    };
+                };
+            };
+            cls: {
+                type: string;
+                description: string;
+                properties: {
+                    endpoint: {
+                        type: string;
+                        description: string;
+                    };
+                    secretId: {
+                        type: string;
+                        description: string;
+                    };
+                    secretKey: {
+                        type: string;
+                        description: string;
+                    };
+                    metricTopicId: {
+                        type: string;
+                        description: string;
+                    };
+                    credentialMode: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    roleName: {
+                        type: string;
+                        description: string;
+                    };
+                    enableReport: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                };
+            };
+            log: {
+                type: string;
+                description: string;
+                properties: {
+                    enableLogReport: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    logTopicId: {
+                        type: string;
+                        description: string;
+                    };
+                    source: {
+                        type: string;
+                        description: string;
+                    };
+                    enableGatewayLog: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    enableSessionLog: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    minLevel: {
+                        type: string;
+                        description: string;
+                    };
+                    sendTimeThreshold: {
+                        type: string;
+                        default: number;
+                        description: string;
+                    };
+                    sendCountThreshold: {
+                        type: string;
+                        default: number;
+                        description: string;
+                    };
+                };
+            };
+            trace: {
+                type: string;
+                description: string;
+                properties: {
+                    enabled: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    traceTopicId: {
+                        type: string;
+                        description: string;
+                    };
+                    serviceName: {
+                        type: string;
+                        default: string;
+                        description: string;
+                    };
+                    debug: {
+                        type: string;
+                        default: boolean;
+                        description: string;
+                    };
+                    batchSize: {
+                        type: string;
+                        default: number;
+                        description: string;
+                    };
+                    flushIntervalMs: {
+                        type: string;
+                        default: number;
+                        description: string;
+                    };
+                    enabledHooks: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                };
+            };
+        };
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;