clawpro-diagnostics-metrics-cls 2.0.1 → 2.0.2

package/README.md

@@ -8,8 +8,41 @@ OpenClaw 诊断指标导出插件，提供以下核心能力：
 
 ---
 
+## ⚠️ 数据访问声明（请务必阅读）
+
+> **本插件需要读取 LLM 会话内容才能产出 token / 长度 / 耗时类指标和 Trace 数据。**
+> 通过 onboard CLI 的 `install` / `UpdateParameter` 命令安装时，CLI 会自动在 `~/.openclaw/openclaw.json` 中为本插件写入 `plugins.entries["clawpro-diagnostics-metrics-cls"].hooks.allowConversationAccess = true`，以满足 OpenClaw 对 non-bundled 插件 typed hook 的安全策略。**安装即视为您授权本插件访问会话内容**，请在团队 / 公司合规要求允许的前提下使用。
+
+### 一、本插件会接触哪些数据
+
+| 数据类别 | 来源 hook | 是否上报到 CLS |
+|---|---|---|
+| 用户输入的 prompt 原文（含系统提示词、对话历史） | `llm_input` / `message_received` | ✅ 默认会通过 Trace 模块写入 CLS 的 **Trace 日志主题**（`traceTopicId`）字段 `gen_ai.input.messages` / `gen_ai.prompt`，未配置 `traceTopicId` 或 `trace.enabled=false` 时不上报 |
+| 模型生成的 completion 原文 | `llm_output` / `before_message_write` | ✅ 同上，写入字段 `gen_ai.output.messages` / `gen_ai.completion` |
+| Agent 最终输出 / 工具调用参数 / 工具返回结果 | `agent_end` / `before_tool_call` / `after_tool_call` | ✅ 同上，写入字段 `gen_ai.output.messages` / `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` |
+| Token 用量 / 耗时 / 模型名等元数据 | 全部 hook | ✅ 写入 **Prometheus 指标主题**（`metricTopicId`），**不含原文** |
+
+> Prometheus 指标主题（`metricTopicId`）只承载聚合后的数值类指标（counter / histogram / gauge），**不会包含 prompt 或 completion 原文**；会话原文仅出现在 Trace 主题（`traceTopicId`）中。
+
+### 二、如果您不希望插件读取会话原文
+
+可以选择以下任一方式，按需削减插件的数据访问范围：
+
+1. **完全禁用 Trace，仅保留指标**：`UpdateParameter --traceEnabled false`，或在 `openclaw.json` 中将 `plugins.entries["clawpro-diagnostics-metrics-cls"].config.trace.enabled` 设为 `false`。此时插件仍会保留 `allowConversationAccess=true` 以采集 token / 耗时类指标，但**不再向 CLS 写入任何 prompt / completion 原文**。
+2. **按 hook 粒度禁用**：在 `openclaw.json` 的 `config.trace.enabledHooks` 中只列出您允许的 hook（例如只保留 `["session_start", "session_end", "agent_end"]` 等不直接携带消息内容的 hook，不包含 `llm_input` / `before_message_write`），其余 hook 不会被注册到 OpenClaw runtime。
+3. **彻底拒绝插件访问会话内容**：在 `openclaw.json` 中手动将 `plugins.entries["clawpro-diagnostics-metrics-cls"].hooks.allowConversationAccess` 设为 `false`，OpenClaw 会拦截 `llm_input` / `llm_output` / `agent_end` 等 typed hook，本插件相关指标和 trace 将不可用，但其它非会话类指标（如 webhook、队列、会话状态等）仍正常工作。
+
+### 三、CLS 侧数据安全建议
+
+- 为 `traceTopicId` 单独创建日志主题，配置最严格的访问权限（仅运维 / SRE 可读），不要与业务日志主题混用。
+- 如需进一步限制原文长度，插件已内置**结构感知式渐进裁剪**（详见下文 Trace 章节"超长截断策略"），单字段最大 3,200,000 字符，APM 索引字段单条消息最长 4,096 字符。
+- 上报前可通过 `external_labels` 加上 `data_classification=internal` 等业务标签，便于在 CLS 侧做 RBAC / 脱敏策略。
+
+---
+
 ## 目录
 
+- [⚠️ 数据访问声明（请务必阅读）](#-数据访问声明请务必阅读)
 - [快速安装（推荐）](#快速安装推荐)
 - [手动安装](#手动安装)
 - [配置说明](#配置说明)

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
 "id": "clawpro-diagnostics-metrics-cls",
   "name": "Diagnostics Metrics CLS",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "CLS诊断指标导出插件：Prometheus 指标（pull/remote-write）+ 全链路 Trace 追踪",
   "type": "plugin",
   "configSchema": {

package/package.json

@@ -1,31 +1 @@
-{
-"name": "clawpro-diagnostics-metrics-cls",
-  "version": "2.0.1",
-  "description": "CLS OpenClaw diagnostics exporter: Prometheus metrics (pull/remote-write) + full-link Trace",
-  "type": "module",
-  "main": "index.ts",
-  "files": [
-    "index.ts",
-    "src/**/*.ts",
-    "openclaw.plugin.json"
-  ],
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "scripts": {
-    "build": "echo 'Plugin publishes .ts source files, no build needed.'",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsc --noEmit --watch"
-  },
-  "license": "MIT",
-  "dependencies": {
-    "prom-client": "^15.1.3",
-    "snappyjs": "^0.7.0",
-    "tencentcloud-cls-sdk-nodejs": "1.0.3"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0"
-  }
-}
+{"name":"clawpro-diagnostics-metrics-cls","version":"2.0.2","description":"CLS OpenClaw diagnostics exporter: Prometheus metrics (pull/remote-write) + full-link Trace","type":"module","main":"index.ts","files":["index.ts","src/**/*.ts","openclaw.plugin.json"],"openclaw":{"extensions":["./index.ts"]},"scripts":{"build":"echo 'Plugin publishes .ts source files, no build needed.'","typecheck":"tsc --noEmit","dev":"tsc --noEmit --watch"},"license":"MIT","dependencies":{"prom-client":"^15.1.3","snappyjs":"^0.7.0","tencentcloud-cls-sdk-nodejs":"1.0.3"},"devDependencies":{"typescript":"^5.0.0"}}