@cnpinsight/cnpclawinsights 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +153 -68
  2. package/dist/index.js +5 -4
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  `@cnpinsight/cnpclawinsights` 是一个 OpenClaw 插件，用于把 OpenClaw 产生的 trace、log、metrics 指标通过 OTLP HTTP/Protobuf 导出到 `otel-collector`。
4
4
 
5
- 插件读取 `openclaw.json` 中的 `cnpclawinsights` 配置，配置结构参考 `diagnostics`。
5
+ 插件默认按 `plugins.entries.cnpclawinsights` 这个插件条目启用。
6
+
7
+ 最简配置只需要开启插件条目；如果你需要自定义 endpoint、日志导出、headers 等，再补 `config`。
6
8
 
7
9
  ## 安装
8
10
 
@@ -24,11 +26,11 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
24
26
 
25
27
  ```json
26
28
  {
27
- "cnpclawinsights": {
28
- "enabled": true,
29
- "otel": {
30
- "enabled": true,
31
- "endpoint": "http://127.0.0.1:4318"
29
+ "plugins": {
30
+ "entries": {
31
+ "cnpclawinsights": {
32
+ "enabled": true
33
+ }
32
34
  }
33
35
  }
34
36
  }
@@ -36,37 +38,65 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
36
38
 
37
39
  这个最小配置下：
38
40
 
41
+ - 默认 OTLP endpoint 是 `http://127.0.0.1:4318`
39
42
  - `traces` 默认开启
40
43
  - `metrics` 默认开启
41
44
  - `logs` 默认关闭
42
45
  - OTLP 协议默认使用 `http/protobuf`
43
46
 
47
+ ## 自定义配置
48
+
49
+ 如果你需要覆盖默认行为，可以继续加 `config`：
50
+
51
+ ```json
52
+ {
53
+ "plugins": {
54
+ "entries": {
55
+ "cnpclawinsights": {
56
+ "enabled": true,
57
+ "config": {
58
+ "otel": {
59
+ "endpoint": "http://127.0.0.1:4318",
60
+ "logs": true
61
+ }
62
+ }
63
+ }
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
44
69
  ## 完整配置示例
45
70
 
46
71
  ```json
47
72
  {
48
- "cnpclawinsights": {
49
- "enabled": true,
50
- "otel": {
51
- "enabled": true,
52
- "protocol": "http/protobuf",
53
- "endpoint": "http://127.0.0.1:4318",
54
- "traces": true,
55
- "metrics": true,
56
- "logs": true,
57
- "serviceName": "openclaw",
58
- "sampleRate": 1,
59
- "flushIntervalMs": 5000,
60
- "headers": {
61
- "Authorization": "Bearer <token>"
62
- },
63
- "captureContent": {
73
+ "plugins": {
74
+ "entries": {
75
+ "cnpclawinsights": {
64
76
  "enabled": true,
65
- "inputMessages": true,
66
- "outputMessages": true,
67
- "toolInputs": false,
68
- "toolOutputs": false,
69
- "systemPrompt": false
77
+ "config": {
78
+ "otel": {
79
+ "protocol": "http/protobuf",
80
+ "endpoint": "http://127.0.0.1:4318",
81
+ "traces": true,
82
+ "metrics": true,
83
+ "logs": true,
84
+ "serviceName": "openclaw",
85
+ "sampleRate": 1,
86
+ "flushIntervalMs": 5000,
87
+ "headers": {
88
+ "Authorization": "Bearer <token>"
89
+ },
90
+ "captureContent": {
91
+ "enabled": true,
92
+ "inputMessages": true,
93
+ "outputMessages": true,
94
+ "toolInputs": false,
95
+ "toolOutputs": false,
96
+ "systemPrompt": false
97
+ }
98
+ }
99
+ }
70
100
  }
71
101
  }
72
102
  }
@@ -77,14 +107,19 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
77
107
 
78
108
  ```json
79
109
  {
80
- "cnpclawinsights": {
81
- "enabled": true,
82
- "otel": {
83
- "enabled": true,
84
- "tracesEndpoint": "http://127.0.0.1:4318/v1/traces",
85
- "metricsEndpoint": "http://127.0.0.1:4318/v1/metrics",
86
- "logsEndpoint": "http://127.0.0.1:4318/v1/logs",
87
- "logs": true
110
+ "plugins": {
111
+ "entries": {
112
+ "cnpclawinsights": {
113
+ "enabled": true,
114
+ "config": {
115
+ "otel": {
116
+ "tracesEndpoint": "http://127.0.0.1:4318/v1/traces",
117
+ "metricsEndpoint": "http://127.0.0.1:4318/v1/metrics",
118
+ "logsEndpoint": "http://127.0.0.1:4318/v1/logs",
119
+ "logs": true
120
+ }
121
+ }
122
+ }
88
123
  }
89
124
  }
90
125
  }
@@ -92,85 +127,93 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
92
127
 
93
128
  ## 配置说明
94
129
 
95
- `cnpclawinsights.enabled`
130
+ `plugins.entries.cnpclawinsights.enabled`
96
131
 
97
- - 是否启用插件本身
132
+ - 是否启用这个插件条目
98
133
  - 必须为 `true`
99
134
 
100
- `cnpclawinsights.otel.enabled`
135
+ `plugins.entries.cnpclawinsights.config.enabled`
101
136
 
102
- - 是否启用 OTel 导出
103
- - 必须为 `true`
137
+ - 可选的插件内部总开关
138
+ - 不写时默认按启用处理
139
+ - 只有显式写成 `false` 才会关闭
140
+
141
+ `plugins.entries.cnpclawinsights.config.otel.enabled`
142
+
143
+ - 可选的 OTel 导出开关
144
+ - 不写时默认按启用处理
145
+ - 只有显式写成 `false` 才会关闭
104
146
 
105
- `cnpclawinsights.otel.protocol`
147
+ `plugins.entries.cnpclawinsights.config.otel.protocol`
106
148
 
107
149
  - 目前只支持 `http/protobuf`
108
150
  - 不配置时默认也是 `http/protobuf`
109
151
 
110
- `cnpclawinsights.otel.endpoint`
152
+ `plugins.entries.cnpclawinsights.config.otel.endpoint`
111
153
 
112
154
  - 通用 OTLP endpoint
113
155
  - 例如 `http://127.0.0.1:4318`
156
+ - 不配置时默认值是 `http://127.0.0.1:4318`
114
157
  - 如果不带 `/v1/traces`、`/v1/metrics`、`/v1/logs`，插件会自动补全对应路径
115
158
 
116
- `cnpclawinsights.otel.traces`
159
+ `plugins.entries.cnpclawinsights.config.otel.traces`
117
160
 
118
161
  - 是否导出 traces
119
162
  - 默认 `true`
120
163
 
121
- `cnpclawinsights.otel.metrics`
164
+ `plugins.entries.cnpclawinsights.config.otel.metrics`
122
165
 
123
166
  - 是否导出 metrics
124
167
  - 默认 `true`
125
168
 
126
- `cnpclawinsights.otel.logs`
169
+ `plugins.entries.cnpclawinsights.config.otel.logs`
127
170
 
128
171
  - 是否导出 logs
129
172
  - 默认 `false`
130
173
 
131
- `cnpclawinsights.otel.tracesEndpoint`
174
+ `plugins.entries.cnpclawinsights.config.otel.tracesEndpoint`
132
175
 
133
176
  - 单独指定 traces 导出地址
134
177
  - 优先级高于 `endpoint`
135
178
 
136
- `cnpclawinsights.otel.metricsEndpoint`
179
+ `plugins.entries.cnpclawinsights.config.otel.metricsEndpoint`
137
180
 
138
181
  - 单独指定 metrics 导出地址
139
182
  - 优先级高于 `endpoint`
140
183
 
141
- `cnpclawinsights.otel.logsEndpoint`
184
+ `plugins.entries.cnpclawinsights.config.otel.logsEndpoint`
142
185
 
143
186
  - 单独指定 logs 导出地址
144
187
  - 优先级高于 `endpoint`
145
188
 
146
- `cnpclawinsights.otel.serviceName`
189
+ `plugins.entries.cnpclawinsights.config.otel.serviceName`
147
190
 
148
191
  - OpenTelemetry service name
149
192
  - 不配置时优先读取环境变量 `OTEL_SERVICE_NAME`
150
193
  - 如果环境变量也没有，默认值是 `openclaw`
151
194
 
152
- `cnpclawinsights.otel.sampleRate`
195
+ `plugins.entries.cnpclawinsights.config.otel.sampleRate`
153
196
 
154
197
  - trace 采样率
155
198
  - 取值范围 `0` 到 `1`
156
199
 
157
- `cnpclawinsights.otel.flushIntervalMs`
200
+ `plugins.entries.cnpclawinsights.config.otel.flushIntervalMs`
158
201
 
159
202
  - metrics 周期导出间隔
160
203
  - 也用于 logs 批量刷新间隔
161
204
  - 最小值为 `1000`
162
205
 
163
- `cnpclawinsights.otel.headers`
206
+ `plugins.entries.cnpclawinsights.config.otel.headers`
164
207
 
165
208
  - OTLP 请求头
166
209
  - 适合传认证信息
167
210
 
168
- `cnpclawinsights.otel.captureContent`
211
+ `plugins.entries.cnpclawinsights.config.otel.captureContent`
169
212
 
170
213
  - 控制是否导出消息内容
171
214
  - 默认不采集正文内容
172
215
 
173
- `cnpclawinsights.otel.captureContent = true`
216
+ `plugins.entries.cnpclawinsights.config.otel.captureContent = true`
174
217
 
175
218
  - 开启后会采集：
176
219
  - `inputMessages`
@@ -179,7 +222,7 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
179
222
  - `toolOutputs`
180
223
  - `systemPrompt` 仍默认不采集
181
224
 
182
- `cnpclawinsights.otel.captureContent = { ... }`
225
+ `plugins.entries.cnpclawinsights.config.otel.captureContent = { ... }`
183
226
 
184
227
  - 可以按字段精细控制：
185
228
  - `enabled`
@@ -191,7 +234,15 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
191
234
 
192
235
  ## 环境变量回退
193
236
 
194
- 如果部分配置未写入 `openclaw.json`，插件还会回退读取这些标准 OTel 环境变量：
237
+ 如果部分配置未写入 `plugins.entries.cnpclawinsights.config`，插件会按下面的优先级取值：
238
+
239
+ 1. `config.otel` 里的显式配置
240
+ 2. 对应的标准 OTel 环境变量
241
+ 3. 插件内置默认值
242
+
243
+ 其中 endpoint 的内置默认值是 `http://127.0.0.1:4318`。
244
+
245
+ 相关环境变量包括：
195
246
 
196
247
  - `OTEL_EXPORTER_OTLP_PROTOCOL`
197
248
  - `OTEL_EXPORTER_OTLP_ENDPOINT`
@@ -218,29 +269,63 @@ openclaw plugins install @cnpinsight/cnpclawinsights@2.0.0
218
269
 
219
270
  ```json
220
271
  {
221
- "cnpclawinsights": {
222
- "enabled": true,
223
- "otel": {
224
- "enabled": true,
225
- "endpoint": "http://127.0.0.1:4318",
226
- "logs": true
272
+ "plugins": {
273
+ "entries": {
274
+ "cnpclawinsights": {
275
+ "enabled": true,
276
+ "config": {
277
+ "otel": {
278
+ "endpoint": "http://127.0.0.1:4318",
279
+ "logs": true
280
+ }
281
+ }
282
+ }
227
283
  }
228
284
  }
229
285
  }
230
286
  ```
231
287
 
232
- ### 3. 为什么配置了但没有导出
288
+ ### 3. 为什么只写了 `enabled: true` 也能工作
233
289
 
234
- 请同时确认下面两个开关都为 `true`：
290
+ 插件现在支持最简模式：
235
291
 
236
292
  ```json
237
293
  {
238
- "cnpclawinsights": {
239
- "enabled": true,
240
- "otel": {
241
- "enabled": true
294
+ "plugins": {
295
+ "entries": {
296
+ "cnpclawinsights": {
297
+ "enabled": true
298
+ }
242
299
  }
243
300
  }
244
301
  }
245
302
  ```
246
303
 
304
+ 这时会默认：
305
+
306
+ - 使用 `http/protobuf`
307
+ - 发往 `http://127.0.0.1:4318`
308
+ - 开启 traces 和 metrics
309
+ - 关闭 logs
310
+
311
+ ### 4. 为什么配置了但没有导出
312
+
313
+ 如果你显式写了下面任意一个值为 `false`，插件就不会导出：
314
+
315
+ ```json
316
+ {
317
+ "plugins": {
318
+ "entries": {
319
+ "cnpclawinsights": {
320
+ "enabled": true,
321
+ "config": {
322
+ "enabled": false,
323
+ "otel": {
324
+ "enabled": false
325
+ }
326
+ }
327
+ }
328
+ }
329
+ }
330
+ }
331
+ ```
package/dist/index.js CHANGED
@@ -44,6 +44,7 @@ const OTEL_EXPORTER_OTLP_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_ENDPOINT";
44
44
  const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
45
45
  const OTEL_EXPORTER_OTLP_METRICS_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT";
46
46
  const OTEL_EXPORTER_OTLP_LOGS_ENDPOINT_ENV = "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT";
47
+ const DEFAULT_OTLP_HTTP_ENDPOINT = "http://127.0.0.1:4318";
47
48
  const OTEL_SEMCONV_STABILITY_OPT_IN_ENV = "OTEL_SEMCONV_STABILITY_OPT_IN";
48
49
  const GEN_AI_LATEST_EXPERIMENTAL_OPT_IN = "gen_ai_latest_experimental";
49
50
  const GEN_AI_TOKEN_USAGE_BUCKETS = [
@@ -354,9 +355,9 @@ function createDiagnosticsOtelService() {
354
355
  id: "cnpclawinsights",
355
356
  async start(ctx) {
356
357
  await stopStarted();
357
- const cfg = ctx.config.cnpclawinsights;
358
- const otel = cfg?.otel;
359
- if (!cfg?.enabled || !otel?.enabled) return;
358
+ const cfg = ctx.config?.cnpclawinsights ?? ctx.config ?? {};
359
+ const otel = cfg?.otel ?? {};
360
+ if (cfg?.enabled === false || otel.enabled === false) return;
360
361
  const emitExporterEvent = (event) => {
361
362
  try {
362
363
  ctx.internalDiagnostics?.emit({
@@ -390,7 +391,7 @@ function createDiagnosticsOtelService() {
390
391
  ctx.logger.warn(`cnpclawinsights: unsupported protocol ${protocol}`);
391
392
  return;
392
393
  }
393
- const endpoint = normalizeEndpoint(otel.endpoint ?? process.env[OTEL_EXPORTER_OTLP_ENDPOINT_ENV]);
394
+ const endpoint = normalizeEndpoint(otel.endpoint ?? process.env[OTEL_EXPORTER_OTLP_ENDPOINT_ENV] ?? DEFAULT_OTLP_HTTP_ENDPOINT);
394
395
  const headers = otel.headers ?? void 0;
395
396
  const serviceName = otel.serviceName?.trim() || process.env.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME;
396
397
  const sampleRate = resolveSampleRate(otel.sampleRate);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cnpinsight/cnpclawinsights",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "OpenClaw insights OpenTelemetry exporter",
5
5
  "repository": {
6
6
  "type": "git",