openclaw-apm-tracing 0.5.0-beta.2
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.
- package/README.md +118 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +1404 -0
- package/dist/index.js.map +1 -0
- package/openclaw.plugin.json +14 -0
- package/package.json +59 -0
package/README.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# openclaw-apm-tracing
|
|
2
|
+
|
|
3
|
+
OpenClaw APM 链路追踪插件（2026.6.5+ beta）—— 通过 lifecycle hooks 构建 parent-child span 树，配合 `diagnostics-otel` 导出到任意 OTLP 后端。
|
|
4
|
+
|
|
5
|
+
> npm 包名：`openclaw-apm-tracing`（beta）
|
|
6
|
+
> 插件 ID：`openclaw-apm-tracing`
|
|
7
|
+
|
|
8
|
+
## 功能
|
|
9
|
+
|
|
10
|
+
- **自动追踪**：Hook 19 个 OpenClaw 生命周期事件，自动生成完整的链路追踪
|
|
11
|
+
- **Span 树结构**：`openclaw.message` → `openclaw.session` → `openclaw.agent` → `chat {model}` / `openclaw.tool.{name}` 等
|
|
12
|
+
- **APM 兼容**：支持 GenAI / Traceloop 语义，适配常见 APM LLM Tab
|
|
13
|
+
- **智能截断**：自动截断超长 span 属性，保证 JSON 合法性
|
|
14
|
+
|
|
15
|
+
## 前置条件
|
|
16
|
+
|
|
17
|
+
- OpenClaw 版本 ≥ 2026.6.5
|
|
18
|
+
- 已安装并启用 `@openclaw/diagnostics-otel` 插件（负责注册全局 OTel SDK 并导出到 OTLP 端点）
|
|
19
|
+
- 已在 `diagnostics.otel` 中配置 OTLP endpoint（可对接任意兼容后端，包括腾讯云 APM）
|
|
20
|
+
|
|
21
|
+
> **关于 diagnostics-otel**：从 OpenClaw 2026.5+ 起独立为 npm 包 `@openclaw/diagnostics-otel`，插件 ID 仍为 `diagnostics-otel`。本插件通过 `@opentelemetry/api` 挂载到 diagnostics-otel 注册的全局 `TracerProvider`，无需代码级耦合。
|
|
22
|
+
|
|
23
|
+
## 安装
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
openclaw plugins install openclaw-apm-tracing@beta
|
|
27
|
+
openclaw plugins install @openclaw/diagnostics-otel
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
若曾安装过旧包名，先卸载：
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
openclaw plugins uninstall openclaw-tencent-plugin
|
|
34
|
+
openclaw plugins uninstall openclaw-apm-tracing
|
|
35
|
+
openclaw plugins install openclaw-apm-tracing@beta
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## 启用插件
|
|
39
|
+
|
|
40
|
+
编辑 `~/.openclaw/openclaw.json`：
|
|
41
|
+
|
|
42
|
+
**重要（OpenClaw 2026.6+）**：本插件订阅了 `llm_input` / `llm_output` / `before_model_resolve` / `agent_end` 等 conversation hooks，必须配置 `allowConversationAccess`。
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"plugins": {
|
|
47
|
+
"allow": ["diagnostics-otel", "openclaw-apm-tracing"],
|
|
48
|
+
"entries": {
|
|
49
|
+
"diagnostics-otel": {
|
|
50
|
+
"enabled": true
|
|
51
|
+
},
|
|
52
|
+
"openclaw-apm-tracing": {
|
|
53
|
+
"enabled": true,
|
|
54
|
+
"hooks": {
|
|
55
|
+
"allowConversationAccess": true
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
},
|
|
60
|
+
"diagnostics": {
|
|
61
|
+
"enabled": true,
|
|
62
|
+
"otel": {
|
|
63
|
+
"enabled": true,
|
|
64
|
+
"endpoint": "http://your-otlp-endpoint:90/otlp",
|
|
65
|
+
"protocol": "http/protobuf",
|
|
66
|
+
"headers": {
|
|
67
|
+
"Authorization": "<YOUR_OTLP_TOKEN>"
|
|
68
|
+
},
|
|
69
|
+
"serviceName": "openclaw",
|
|
70
|
+
"traces": true,
|
|
71
|
+
"metrics": true
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## 重启并验证
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
openclaw gateway restart
|
|
81
|
+
openclaw plugins list
|
|
82
|
+
openclaw plugins inspect openclaw-apm-tracing --runtime
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
启动后日志中应出现：
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
[openclaw-apm-tracing] Plugin registered (service mode)
|
|
89
|
+
[openclaw-apm-tracing] Attaching to global TracerProvider
|
|
90
|
+
[openclaw-apm-tracing] Registered 19 hook handlers. Active tracer: yes
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## 开发
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npm install
|
|
97
|
+
npm run build
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
发布 beta（npm 公网 registry.npmjs.org）：
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
npm login # 首次需登录
|
|
104
|
+
npm run publish:beta
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
云服务器安装（无需 git，默认从 npmjs 拉取）：
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
openclaw plugins install openclaw-apm-tracing@beta
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## 版本
|
|
114
|
+
|
|
115
|
+
- **v0.5.0-beta.2** — 去掉 scope，npm 包名 `openclaw-apm-tracing`
|
|
116
|
+
- **v0.5.0-beta.1** — scoped 包 `@klauslin/openclaw-apm-tracing` / 插件 ID `openclaw-apm-tracing`
|
|
117
|
+
- **v0.5.0-beta.0** — 初版 beta（旧名 `@klauslin/openclaw-tencent-plugin`）
|
|
118
|
+
- **v0.4.0** — 上游初始版本（仅 TS 源码，不兼容 2026.6+ install）
|
package/dist/index.d.ts
ADDED