@cnpinsight/cnpclawinsights 2.0.0

package/README.md

@@ -0,0 +1,246 @@
+# @cnpinsight/cnpclawinsights
+
+`@cnpinsight/cnpclawinsights` 是一个 OpenClaw 插件，用于把 OpenClaw 产生的 trace、log、metrics 指标通过 OTLP HTTP/Protobuf 导出到 `otel-collector`。
+
+插件读取 `openclaw.json` 中的 `cnpclawinsights` 配置，配置结构参考 `diagnostics`。
+
+## 安装
+
+通过 OpenClaw 安装插件：
+
+```bash
+openclaw plugins install @cnpinsight/cnpclawinsights
+```
+
+如果需要指定版本：
+
+```bash
+openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
+```
+
+## 最小配置
+
+在 `openclaw.json` 中添加：
+
+```json
+{
+  "cnpclawinsights": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "endpoint": "http://127.0.0.1:4318"
+    }
+  }
+}
+```
+
+这个最小配置下：
+
+- `traces` 默认开启
+- `metrics` 默认开启
+- `logs` 默认关闭
+- OTLP 协议默认使用 `http/protobuf`
+
+## 完整配置示例
+
+```json
+{
+  "cnpclawinsights": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "protocol": "http/protobuf",
+      "endpoint": "http://127.0.0.1:4318",
+      "traces": true,
+      "metrics": true,
+      "logs": true,
+      "serviceName": "openclaw",
+      "sampleRate": 1,
+      "flushIntervalMs": 5000,
+      "headers": {
+        "Authorization": "Bearer <token>"
+      },
+      "captureContent": {
+        "enabled": true,
+        "inputMessages": true,
+        "outputMessages": true,
+        "toolInputs": false,
+        "toolOutputs": false,
+        "systemPrompt": false
+      }
+    }
+  }
+}
+```
+
+如果你希望按信号单独配置 endpoint，也可以这样写：
+
+```json
+{
+  "cnpclawinsights": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "tracesEndpoint": "http://127.0.0.1:4318/v1/traces",
+      "metricsEndpoint": "http://127.0.0.1:4318/v1/metrics",
+      "logsEndpoint": "http://127.0.0.1:4318/v1/logs",
+      "logs": true
+    }
+  }
+}
+```
+
+## 配置说明
+
+`cnpclawinsights.enabled`
+
+- 是否启用插件本身
+- 必须为 `true`
+
+`cnpclawinsights.otel.enabled`
+
+- 是否启用 OTel 导出
+- 必须为 `true`
+
+`cnpclawinsights.otel.protocol`
+
+- 目前只支持 `http/protobuf`
+- 不配置时默认也是 `http/protobuf`
+
+`cnpclawinsights.otel.endpoint`
+
+- 通用 OTLP endpoint
+- 例如 `http://127.0.0.1:4318`
+- 如果不带 `/v1/traces`、`/v1/metrics`、`/v1/logs`，插件会自动补全对应路径
+
+`cnpclawinsights.otel.traces`
+
+- 是否导出 traces
+- 默认 `true`
+
+`cnpclawinsights.otel.metrics`
+
+- 是否导出 metrics
+- 默认 `true`
+
+`cnpclawinsights.otel.logs`
+
+- 是否导出 logs
+- 默认 `false`
+
+`cnpclawinsights.otel.tracesEndpoint`
+
+- 单独指定 traces 导出地址
+- 优先级高于 `endpoint`
+
+`cnpclawinsights.otel.metricsEndpoint`
+
+- 单独指定 metrics 导出地址
+- 优先级高于 `endpoint`
+
+`cnpclawinsights.otel.logsEndpoint`
+
+- 单独指定 logs 导出地址
+- 优先级高于 `endpoint`
+
+`cnpclawinsights.otel.serviceName`
+
+- OpenTelemetry service name
+- 不配置时优先读取环境变量 `OTEL_SERVICE_NAME`
+- 如果环境变量也没有，默认值是 `openclaw`
+
+`cnpclawinsights.otel.sampleRate`
+
+- trace 采样率
+- 取值范围 `0` 到 `1`
+
+`cnpclawinsights.otel.flushIntervalMs`
+
+- metrics 周期导出间隔
+- 也用于 logs 批量刷新间隔
+- 最小值为 `1000`
+
+`cnpclawinsights.otel.headers`
+
+- OTLP 请求头
+- 适合传认证信息
+
+`cnpclawinsights.otel.captureContent`
+
+- 控制是否导出消息内容
+- 默认不采集正文内容
+
+`cnpclawinsights.otel.captureContent = true`
+
+- 开启后会采集：
+- `inputMessages`
+- `outputMessages`
+- `toolInputs`
+- `toolOutputs`
+- `systemPrompt` 仍默认不采集
+
+`cnpclawinsights.otel.captureContent = { ... }`
+
+- 可以按字段精细控制：
+- `enabled`
+- `inputMessages`
+- `outputMessages`
+- `toolInputs`
+- `toolOutputs`
+- `systemPrompt`
+
+## 环境变量回退
+
+如果部分配置未写入 `openclaw.json`，插件还会回退读取这些标准 OTel 环境变量：
+
+- `OTEL_EXPORTER_OTLP_PROTOCOL`
+- `OTEL_EXPORTER_OTLP_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`
+- `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`
+- `OTEL_SERVICE_NAME`
+
+## 常见问题
+
+### 1. 插件安装时报 package not found
+
+请确认安装名使用的是：
+
+```bash
+@cnpinsight/cnpclawinsights
+```
+
+不要写成其他名字。
+
+### 2. 为什么没有日志
+
+`logs` 默认关闭，需要显式配置：
+
+```json
+{
+  "cnpclawinsights": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "endpoint": "http://127.0.0.1:4318",
+      "logs": true
+    }
+  }
+}
+```
+
+### 3. 为什么配置了但没有导出
+
+请同时确认下面两个开关都为 `true`：
+
+```json
+{
+  "cnpclawinsights": {
+    "enabled": true,
+    "otel": {
+      "enabled": true
+    }
+  }
+}
+```
+

package/dist/api.js

@@ -0,0 +1,4 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/plugin-entry";
+import { createChildDiagnosticTraceContext, createDiagnosticTraceContext, emitDiagnosticEvent, formatDiagnosticTraceparent, isValidDiagnosticSpanId, isValidDiagnosticTraceFlags, isValidDiagnosticTraceId, onDiagnosticEvent, parseDiagnosticTraceparent } from "openclaw/plugin-sdk/diagnostic-runtime";
+import { redactSensitiveText } from "openclaw/plugin-sdk/security-runtime";
+export { createChildDiagnosticTraceContext, createDiagnosticTraceContext, emitDiagnosticEvent, emptyPluginConfigSchema, formatDiagnosticTraceparent, isValidDiagnosticSpanId, isValidDiagnosticTraceFlags, isValidDiagnosticTraceId, onDiagnosticEvent, parseDiagnosticTraceparent, redactSensitiveText };