@latitude-data/openclaw-telemetry 0.0.7 → 0.0.8
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/LICENSE +21 -157
- package/README.md +79 -94
- package/dist/plugin.js +1 -1
- package/openclaw.plugin.json +4 -5
- package/package.json +1 -1
package/LICENSE
CHANGED
|
@@ -1,157 +1,21 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
than an Application or a Combined Work as defined below.
|
|
23
|
-
|
|
24
|
-
An "Application" is any work that makes use of an interface provided
|
|
25
|
-
by the Library, but which is not otherwise based on the Library.
|
|
26
|
-
Defining a subclass of a class defined by the Library is deemed a mode
|
|
27
|
-
of using an interface provided by the Library.
|
|
28
|
-
|
|
29
|
-
A "Combined Work" is a work produced by combining or linking an
|
|
30
|
-
Application with the Library. The particular version of the Library
|
|
31
|
-
with which the Combined Work was made is also called the "Linked
|
|
32
|
-
Version".
|
|
33
|
-
|
|
34
|
-
The "Minimal Corresponding Source" for a Combined Work means the
|
|
35
|
-
Corresponding Source for the Combined Work, excluding any source code
|
|
36
|
-
for portions of the Combined Work that, considered in isolation, are
|
|
37
|
-
based on the Application, and not on the Linked Version.
|
|
38
|
-
|
|
39
|
-
The "Corresponding Application Code" for a Combined Work means the
|
|
40
|
-
object code and/or source code for the Application, including any data
|
|
41
|
-
and utility programs needed for reproducing the Combined Work from the
|
|
42
|
-
Application, but excluding the System Libraries of the Combined Work.
|
|
43
|
-
|
|
44
|
-
## 1. Exception to Section 3 of the GNU GPL.
|
|
45
|
-
|
|
46
|
-
You may convey a covered work under sections 3 and 4 of this License
|
|
47
|
-
without being bound by section 3 of the GNU GPL.
|
|
48
|
-
|
|
49
|
-
## 2. Conveying Modified Versions.
|
|
50
|
-
|
|
51
|
-
If you modify a copy of the Library, and, in your modifications, a
|
|
52
|
-
facility refers to a function or data to be supplied by an Application
|
|
53
|
-
that uses the facility (other than as an argument passed when the
|
|
54
|
-
facility is invoked), then you may convey a copy of the modified
|
|
55
|
-
version:
|
|
56
|
-
|
|
57
|
-
- a) under this License, provided that you make a good faith effort
|
|
58
|
-
to ensure that, in the event an Application does not supply the
|
|
59
|
-
function or data, the facility still operates, and performs
|
|
60
|
-
whatever part of its purpose remains meaningful, or
|
|
61
|
-
- b) under the GNU GPL, with none of the additional permissions of
|
|
62
|
-
this License applicable to that copy.
|
|
63
|
-
|
|
64
|
-
## 3. Object Code Incorporating Material from Library Header Files.
|
|
65
|
-
|
|
66
|
-
The object code form of an Application may incorporate material from a
|
|
67
|
-
header file that is part of the Library. You may convey such object
|
|
68
|
-
code under terms of your choice, provided that, if the incorporated
|
|
69
|
-
material is not limited to numerical parameters, data structure
|
|
70
|
-
layouts and accessors, or small macros, inline functions and templates
|
|
71
|
-
(ten or fewer lines in length), you do both of the following:
|
|
72
|
-
|
|
73
|
-
- a) Give prominent notice with each copy of the object code that
|
|
74
|
-
the Library is used in it and that the Library and its use are
|
|
75
|
-
covered by this License.
|
|
76
|
-
- b) Accompany the object code with a copy of the GNU GPL and this
|
|
77
|
-
license document.
|
|
78
|
-
|
|
79
|
-
## 4. Combined Works.
|
|
80
|
-
|
|
81
|
-
You may convey a Combined Work under terms of your choice that, taken
|
|
82
|
-
together, effectively do not restrict modification of the portions of
|
|
83
|
-
the Library contained in the Combined Work and reverse engineering for
|
|
84
|
-
debugging such modifications, if you also do each of the following:
|
|
85
|
-
|
|
86
|
-
- a) Give prominent notice with each copy of the Combined Work that
|
|
87
|
-
the Library is used in it and that the Library and its use are
|
|
88
|
-
covered by this License.
|
|
89
|
-
- b) Accompany the Combined Work with a copy of the GNU GPL and this
|
|
90
|
-
license document.
|
|
91
|
-
- c) For a Combined Work that displays copyright notices during
|
|
92
|
-
execution, include the copyright notice for the Library among
|
|
93
|
-
these notices, as well as a reference directing the user to the
|
|
94
|
-
copies of the GNU GPL and this license document.
|
|
95
|
-
- d) Do one of the following:
|
|
96
|
-
- 0) Convey the Minimal Corresponding Source under the terms of
|
|
97
|
-
this License, and the Corresponding Application Code in a form
|
|
98
|
-
suitable for, and under terms that permit, the user to
|
|
99
|
-
recombine or relink the Application with a modified version of
|
|
100
|
-
the Linked Version to produce a modified Combined Work, in the
|
|
101
|
-
manner specified by section 6 of the GNU GPL for conveying
|
|
102
|
-
Corresponding Source.
|
|
103
|
-
- 1) Use a suitable shared library mechanism for linking with
|
|
104
|
-
the Library. A suitable mechanism is one that (a) uses at run
|
|
105
|
-
time a copy of the Library already present on the user's
|
|
106
|
-
computer system, and (b) will operate properly with a modified
|
|
107
|
-
version of the Library that is interface-compatible with the
|
|
108
|
-
Linked Version.
|
|
109
|
-
- e) Provide Installation Information, but only if you would
|
|
110
|
-
otherwise be required to provide such information under section 6
|
|
111
|
-
of the GNU GPL, and only to the extent that such information is
|
|
112
|
-
necessary to install and execute a modified version of the
|
|
113
|
-
Combined Work produced by recombining or relinking the Application
|
|
114
|
-
with a modified version of the Linked Version. (If you use option
|
|
115
|
-
4d0, the Installation Information must accompany the Minimal
|
|
116
|
-
Corresponding Source and Corresponding Application Code. If you
|
|
117
|
-
use option 4d1, you must provide the Installation Information in
|
|
118
|
-
the manner specified by section 6 of the GNU GPL for conveying
|
|
119
|
-
Corresponding Source.)
|
|
120
|
-
|
|
121
|
-
## 5. Combined Libraries.
|
|
122
|
-
|
|
123
|
-
You may place library facilities that are a work based on the Library
|
|
124
|
-
side by side in a single library together with other library
|
|
125
|
-
facilities that are not Applications and are not covered by this
|
|
126
|
-
License, and convey such a combined library under terms of your
|
|
127
|
-
choice, if you do both of the following:
|
|
128
|
-
|
|
129
|
-
- a) Accompany the combined library with a copy of the same work
|
|
130
|
-
based on the Library, uncombined with any other library
|
|
131
|
-
facilities, conveyed under the terms of this License.
|
|
132
|
-
- b) Give prominent notice with the combined library that part of it
|
|
133
|
-
is a work based on the Library, and explaining where to find the
|
|
134
|
-
accompanying uncombined form of the same work.
|
|
135
|
-
|
|
136
|
-
## 6. Revised Versions of the GNU Lesser General Public License.
|
|
137
|
-
|
|
138
|
-
The Free Software Foundation may publish revised and/or new versions
|
|
139
|
-
of the GNU Lesser General Public License from time to time. Such new
|
|
140
|
-
versions will be similar in spirit to the present version, but may
|
|
141
|
-
differ in detail to address new problems or concerns.
|
|
142
|
-
|
|
143
|
-
Each version is given a distinguishing version number. If the Library
|
|
144
|
-
as you received it specifies that a certain numbered version of the
|
|
145
|
-
GNU Lesser General Public License "or any later version" applies to
|
|
146
|
-
it, you have the option of following the terms and conditions either
|
|
147
|
-
of that published version or of any later version published by the
|
|
148
|
-
Free Software Foundation. If the Library as you received it does not
|
|
149
|
-
specify a version number of the GNU Lesser General Public License, you
|
|
150
|
-
may choose any version of the GNU Lesser General Public License ever
|
|
151
|
-
published by the Free Software Foundation.
|
|
152
|
-
|
|
153
|
-
If the Library as you received it specifies that a proxy can decide
|
|
154
|
-
whether future versions of the GNU Lesser General Public License shall
|
|
155
|
-
apply, that proxy's public statement of acceptance of any version is
|
|
156
|
-
permanent authorization for you to choose that version for the
|
|
157
|
-
Library.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Latitude Data SL
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,30 +1,41 @@
|
|
|
1
1
|
# @latitude-data/openclaw-telemetry
|
|
2
2
|
|
|
3
|
-
OpenClaw plugin that streams every agent run to [Latitude](https://latitude.so) as OTLP traces
|
|
3
|
+
OpenClaw plugin that streams every agent run to [Latitude](https://latitude.so) as OTLP traces — full system prompt, message history, assistant output, token usage, tool I/O, and the running agent's name on every span.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- **OpenClaw 2026.4.25 or newer** on PATH.
|
|
8
|
+
- A **Latitude API key** from `https://console.latitude.so/projects/<your-slug>/settings/keys` and the matching **project slug**.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
## Install
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
### Recommended — one-shot CLI
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
The companion CLI handles every step (install, config, validate, restart) in one command:
|
|
12
15
|
|
|
13
16
|
```bash
|
|
14
|
-
|
|
17
|
+
npx -y @latitude-data/openclaw-telemetry-cli@0.0.8 install
|
|
15
18
|
```
|
|
16
19
|
|
|
17
|
-
|
|
20
|
+
It prompts for your API key and project slug, runs `openclaw plugins install` for you, writes the plugin entry into `openclaw.json`, adds the plugin to `plugins.allow`, validates the result, and (on TTY) offers to restart the gateway. See the [CLI README](https://github.com/latitude-dev/latitude-llm/tree/main/packages/telemetry/openclaw-cli#readme) for the full flag matrix, dry-run mode, custom config dir, and CI usage.
|
|
21
|
+
|
|
22
|
+
### Manual install
|
|
18
23
|
|
|
19
|
-
|
|
24
|
+
If you'd rather not use the CLI, do exactly what it does, in four steps:
|
|
25
|
+
|
|
26
|
+
#### 1. Install the runtime
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
openclaw plugins install @latitude-data/openclaw-telemetry@0.0.8
|
|
30
|
+
```
|
|
20
31
|
|
|
21
|
-
|
|
32
|
+
Pin to an exact version. OpenClaw's `security audit --deep` warns about unpinned install specs, so always include the `@<version>` suffix.
|
|
22
33
|
|
|
23
|
-
|
|
34
|
+
OpenClaw fetches from npm, runs its security scan, copies files into `~/.openclaw/extensions/<id>/`, and creates a (disabled) `plugins.entries["@latitude-data/openclaw-telemetry"]` entry in `~/.openclaw/openclaw.json`.
|
|
24
35
|
|
|
25
|
-
|
|
36
|
+
#### 2. Configure and enable
|
|
26
37
|
|
|
27
|
-
Run these `openclaw config set` commands (use bracket notation so the scoped package name parses correctly). Substitute your real API key and project slug
|
|
38
|
+
Run these `openclaw config set` commands (use bracket notation so the scoped package name parses correctly). Substitute your real API key and project slug:
|
|
28
39
|
|
|
29
40
|
```bash
|
|
30
41
|
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.apiKey' "lat_xxx"
|
|
@@ -34,19 +45,19 @@ openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].hooks.
|
|
|
34
45
|
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].enabled' true
|
|
35
46
|
```
|
|
36
47
|
|
|
37
|
-
|
|
48
|
+
Both `allowConversationAccess` writes are required — see [The two flags](#the-two-flags).
|
|
38
49
|
|
|
39
|
-
|
|
50
|
+
#### 3. Add to `plugins.allow` (optional but recommended)
|
|
40
51
|
|
|
41
|
-
OpenClaw warns at every gateway restart about non-bundled plugins that auto-load without provenance via `plugins.allow`. Silence the warning
|
|
52
|
+
OpenClaw warns at every gateway restart about non-bundled plugins that auto-load without provenance via `plugins.allow`. Silence the warning:
|
|
42
53
|
|
|
43
54
|
```bash
|
|
44
|
-
# `config set` can't append to arrays — set the whole list.
|
|
45
|
-
#
|
|
55
|
+
# `config set` can't append to arrays — set the whole list. Include any other
|
|
56
|
+
# plugins you already have in `plugins.allow`.
|
|
46
57
|
openclaw config set 'plugins.allow' '["@latitude-data/openclaw-telemetry"]'
|
|
47
58
|
```
|
|
48
59
|
|
|
49
|
-
|
|
60
|
+
#### 4. Restart the gateway
|
|
50
61
|
|
|
51
62
|
```bash
|
|
52
63
|
openclaw gateway restart
|
|
@@ -63,11 +74,11 @@ grep -E "blocked|plugin not found|latitude" /tmp/openclaw/openclaw-*.log | tail
|
|
|
63
74
|
# → no "blocked", no "plugin not found"
|
|
64
75
|
```
|
|
65
76
|
|
|
66
|
-
Send a message to one of your OpenClaw agents — within
|
|
77
|
+
Send a message to one of your OpenClaw agents — within seconds, traces appear at `https://console.latitude.so/projects/<your-slug>`.
|
|
67
78
|
|
|
68
|
-
|
|
79
|
+
#### Or: hand-edit `~/.openclaw/openclaw.json`
|
|
69
80
|
|
|
70
|
-
|
|
81
|
+
Equivalent to steps 2 + 3 in one paste:
|
|
71
82
|
|
|
72
83
|
```jsonc
|
|
73
84
|
{
|
|
@@ -90,43 +101,54 @@ If you'd rather paste a JSON block than run six commands, the equivalent edit is
|
|
|
90
101
|
}
|
|
91
102
|
```
|
|
92
103
|
|
|
93
|
-
Merge
|
|
104
|
+
Merge with whatever else is in `openclaw.json`. Then run `openclaw config validate` and `openclaw gateway restart`.
|
|
94
105
|
|
|
95
|
-
|
|
106
|
+
## Uninstall
|
|
96
107
|
|
|
97
|
-
|
|
108
|
+
If you installed via the CLI:
|
|
98
109
|
|
|
99
110
|
```bash
|
|
100
|
-
|
|
101
|
-
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' "https://staging-ingest.latitude.so"
|
|
102
|
-
|
|
103
|
-
# Local dev:
|
|
104
|
-
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' "http://localhost:3002"
|
|
111
|
+
npx -y @latitude-data/openclaw-telemetry-cli@0.0.8 uninstall
|
|
105
112
|
```
|
|
106
113
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
If you want trace metadata (timings, token usage, model name, agent name, ids) without the prompt/response content, keep `hooks.allowConversationAccess` at `true` (so OpenClaw still dispatches events to us) and set only `config.allowConversationAccess` to `false`:
|
|
114
|
+
Manual uninstall:
|
|
110
115
|
|
|
111
116
|
```bash
|
|
112
|
-
openclaw
|
|
113
|
-
openclaw
|
|
117
|
+
openclaw plugins uninstall @latitude-data/openclaw-telemetry --force
|
|
118
|
+
openclaw gateway restart
|
|
114
119
|
```
|
|
115
120
|
|
|
116
|
-
|
|
121
|
+
OpenClaw removes the extension files, install record, plugin entry, and the `plugins.allow` entry.
|
|
117
122
|
|
|
118
|
-
##
|
|
123
|
+
## Targeting staging or local dev
|
|
124
|
+
|
|
125
|
+
By default the plugin sends to production (`https://ingest.latitude.so`). Override `baseUrl` to point elsewhere:
|
|
119
126
|
|
|
120
127
|
```bash
|
|
121
|
-
|
|
128
|
+
# Staging
|
|
129
|
+
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' \
|
|
130
|
+
"https://staging-ingest.latitude.so"
|
|
131
|
+
|
|
132
|
+
# Local dev
|
|
133
|
+
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' \
|
|
134
|
+
"http://localhost:3002"
|
|
122
135
|
```
|
|
123
136
|
|
|
124
|
-
|
|
137
|
+
The CLI handles this with `--staging` / `--dev` flags.
|
|
138
|
+
|
|
139
|
+
## Structural-only telemetry (no content capture)
|
|
140
|
+
|
|
141
|
+
To get trace metadata (timings, token usage, model name, agent name, ids) without prompt/response content, keep `hooks.allowConversationAccess` at `true` so events still dispatch, and set only `config.allowConversationAccess` to `false`:
|
|
125
142
|
|
|
126
143
|
```bash
|
|
127
|
-
openclaw
|
|
144
|
+
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.allowConversationAccess' false
|
|
145
|
+
openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].hooks.allowConversationAccess' true
|
|
128
146
|
```
|
|
129
147
|
|
|
148
|
+
Setting `hooks.allowConversationAccess=false` would block dispatch entirely — see [The two flags](#the-two-flags). With this config the plugin still emits the full span tree, just with content attributes (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`, tool args/results) scrubbed. Each span carries `latitude.captured.content: false` so the gate state is visible in the Latitude UI.
|
|
149
|
+
|
|
150
|
+
The CLI handles this with `--no-content`.
|
|
151
|
+
|
|
130
152
|
## What gets sent
|
|
131
153
|
|
|
132
154
|
For each agent run, the plugin emits one trace shaped like the actual run:
|
|
@@ -147,15 +169,13 @@ agent (root, traceId = hash(runId))
|
|
|
147
169
|
|
|
148
170
|
Five span kinds:
|
|
149
171
|
|
|
150
|
-
- **`agent`** — root of the run. Carries `openclaw.session.key`, `openclaw.agent.id`, `openclaw.agent.name`, aggregated token usage across all generations, run duration, success/error status, the first user prompt, and the full final message list.
|
|
151
|
-
- **`model_call`** — one per
|
|
172
|
+
- **`agent`** — root of the run. Carries `openclaw.session.key`, `openclaw.agent.id`, `openclaw.agent.name`, aggregated token usage across all generations, run duration, success/error status, the first user prompt, and the full final message list. Attempt-aggregate `gen_ai.*` lands here.
|
|
173
|
+
- **`model_call`** — one per provider API call inside the run. Carries provider, request/response model, `openclaw.api`, `openclaw.transport`, per-call duration, outcome, error category, time-to-first-byte, request payload bytes, response stream bytes, upstream request id hash, and `gen_ai.input.messages` snapshotted at the moment that generation started. Per-call output messages and per-call token usage aren't surfaced by OpenClaw today (attempt-aggregate only); those stay on `agent`.
|
|
152
174
|
- **`tool_call:<name>`** — one per tool invocation. Canonical `gen_ai.tool.*` attributes: `name`, `call.id`, `call.arguments`, `call.result`. Sibling of `agent`, NOT child of `model_call` — tools run between generations, not during them.
|
|
153
175
|
- **`compaction`** — rare; fires when OpenClaw hits the message budget mid-run. Records before/after message counts and the compacted-out count.
|
|
154
176
|
- **`subagent`** — one per child run spawned by this agent. The child's entire `agent` subtree (its own `model_call`s, `tool_call`s, even further-nested `subagent`s) parents itself underneath via cross-runId trace propagation, so a spawn tree is one waterfall in one trace.
|
|
155
177
|
|
|
156
|
-
Every span carries `openclaw.agent.id` and `openclaw.agent.name
|
|
157
|
-
|
|
158
|
-
All spans share the same `traceId` so they group as one trace per agent run (and one trace per spawn tree, by virtue of the subagent linkage).
|
|
178
|
+
Every span carries `openclaw.agent.id` and `openclaw.agent.name` — multi-agent setups produce spans tagged with the invoking agent's id, letting you filter and group by agent in the Latitude UI. All spans share the same `traceId`, so they group as one trace per agent run (and one trace per spawn tree, by virtue of the subagent linkage).
|
|
159
179
|
|
|
160
180
|
### Backend caveat: Codex / Claude-Code-style providers
|
|
161
181
|
|
|
@@ -175,13 +195,13 @@ We subscribe to OpenClaw's typed plugin hooks (`src/plugins/hook-types.ts` upstr
|
|
|
175
195
|
|
|
176
196
|
Two more hooks (`llm_input`, `llm_output`) are subscribed to for **content only** — they don't open or close spans, they just enrich the `agent` span with attempt-aggregate data and seed the rolling history snapshot used by per-call `model_call.gen_ai.input.messages`.
|
|
177
197
|
|
|
178
|
-
The hook system runs handlers fire-and-forget
|
|
198
|
+
The hook system runs handlers fire-and-forget, so nothing we do here can slow the agent loop. The one exception is `before_tool_call`, which is a `runModifyingHook` — our handler returns `undefined` so OpenClaw dispatches the tool normally. Returning anything else (e.g. `{block: true}`) would block every tool call.
|
|
179
199
|
|
|
180
|
-
**No runtime wrapping.**
|
|
200
|
+
**No runtime wrapping.** We stay inside the supported plugin API rather than monkey-patching `@mariozechner/pi-ai`. The hooks give us everything, at lower risk of breaking on OpenClaw updates.
|
|
181
201
|
|
|
182
202
|
## Configuration reference
|
|
183
203
|
|
|
184
|
-
|
|
204
|
+
Two blocks live under `plugins.entries["@latitude-data/openclaw-telemetry"]`:
|
|
185
205
|
|
|
186
206
|
### `.config` — read by the plugin's runtime
|
|
187
207
|
|
|
@@ -189,8 +209,8 @@ The installer writes two blocks to `plugins.entries["@latitude-data/openclaw-tel
|
|
|
189
209
|
| --- | --- | --- | --- |
|
|
190
210
|
| `apiKey` | yes | — | Bearer token for Latitude ingestion. |
|
|
191
211
|
| `project` | yes | — | Slug of the project to route traces into. |
|
|
192
|
-
| `baseUrl` | no | `https://ingest.latitude.so` | Override OTLP ingest origin.
|
|
193
|
-
| `allowConversationAccess` | no | `false` | When `true`, attach raw prompts, assistant responses, system instructions, and tool I/O to spans. When `false`, emit only timing, token usage, model name, agent id, and structural ids — same span tree, scrubbed payloads. **Must match `hooks.allowConversationAccess` below — see
|
|
212
|
+
| `baseUrl` | no | `https://ingest.latitude.so` | Override OTLP ingest origin. The CLI sets this only when `--staging` or `--dev` is passed. |
|
|
213
|
+
| `allowConversationAccess` | no | `false` | When `true`, attach raw prompts, assistant responses, system instructions, and tool I/O to spans. When `false`, emit only timing, token usage, model name, agent id, and structural ids — same span tree, scrubbed payloads. **Must match `hooks.allowConversationAccess` below — see [The two flags](#the-two-flags).** |
|
|
194
214
|
| `enabled` | no | `true` | Set to `false` to pause emission without uninstalling. |
|
|
195
215
|
| `debug` | no | `false` | Log diagnostic lines to stderr (visible in the gateway log). |
|
|
196
216
|
|
|
@@ -207,66 +227,31 @@ The installer writes two blocks to `plugins.entries["@latitude-data/openclaw-tel
|
|
|
207
227
|
- **`hooks.*`** is the **dispatch gate**. `false` → OpenClaw never forwards events to us. No traces.
|
|
208
228
|
- **`config.*`** is the **payload-content gate**. `false` → we emit spans normally but scrub message content from them. Structural-only telemetry.
|
|
209
229
|
|
|
210
|
-
For *this* plugin
|
|
230
|
+
For *this* plugin we always couple them — the CLI writes both from the same source. If you hand-edit:
|
|
211
231
|
|
|
212
232
|
- **Both `true`**: full content capture (the default).
|
|
213
|
-
-
|
|
214
|
-
-
|
|
233
|
+
- `hooks: true` + `config: false`: structural-only telemetry (set via `--no-content`).
|
|
234
|
+
- `hooks: false` + anything: no traces. Don't.
|
|
215
235
|
|
|
216
|
-
### Environment
|
|
236
|
+
### Environment-variable fallbacks
|
|
217
237
|
|
|
218
|
-
If a `config.*` key isn't set, the runtime falls back to env vars on the gateway process: `LATITUDE_API_KEY`, `LATITUDE_PROJECT`, `LATITUDE_BASE_URL`, `LATITUDE_DEBUG`, `LATITUDE_OPENCLAW_ENABLED`.
|
|
219
|
-
|
|
220
|
-
### Manual installation
|
|
221
|
-
|
|
222
|
-
If you can't run the installer, do exactly what it does:
|
|
223
|
-
|
|
224
|
-
1. **Hand placement to OpenClaw** with `openclaw plugins install <path-to-extracted-package> --force`. This is what populates `~/.openclaw/extensions/`, writes the install record, and creates the (initially empty) `plugins.entries[id]` block. Don't hand-place files into the extensions directory — the persisted plugin index won't see them.
|
|
225
|
-
2. **Add the config + hooks block** to `~/.openclaw/openclaw.json`:
|
|
226
|
-
|
|
227
|
-
```jsonc
|
|
228
|
-
{
|
|
229
|
-
"plugins": {
|
|
230
|
-
"allow": ["@latitude-data/openclaw-telemetry"],
|
|
231
|
-
"entries": {
|
|
232
|
-
"@latitude-data/openclaw-telemetry": {
|
|
233
|
-
"enabled": true,
|
|
234
|
-
"hooks": {
|
|
235
|
-
"allowConversationAccess": true
|
|
236
|
-
},
|
|
237
|
-
"config": {
|
|
238
|
-
"apiKey": "lat_xxx",
|
|
239
|
-
"project": "my-openclaw-project",
|
|
240
|
-
"allowConversationAccess": true
|
|
241
|
-
}
|
|
242
|
-
}
|
|
243
|
-
}
|
|
244
|
-
}
|
|
245
|
-
}
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
Run `openclaw config validate` — should print `valid: true`. Then `openclaw gateway restart`.
|
|
238
|
+
If a `config.*` key isn't set, the runtime falls back to env vars on the gateway process: `LATITUDE_API_KEY`, `LATITUDE_PROJECT`, `LATITUDE_BASE_URL`, `LATITUDE_DEBUG`, `LATITUDE_OPENCLAW_ENABLED`. Useful for flipping `debug` without editing `openclaw.json`.
|
|
249
239
|
|
|
250
240
|
## Privacy
|
|
251
241
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
- **Installer default**: when you run `npx -y @latitude-data/openclaw-telemetry install` without `--no-content`, the installer writes `allowConversationAccess: true` to both the `hooks` and `config` blocks. **You get full content capture** — prompts, assistant responses, system instructions, tool I/O — shipped to Latitude alongside structural telemetry.
|
|
255
|
-
- **Runtime default for absent keys**: if you hand-write `openclaw.json` and leave `allowConversationAccess` out entirely, `config.allowConversationAccess` falls back to `false` at the plugin's runtime (privacy-preserving) and `hooks.allowConversationAccess` falls back to OpenClaw's default (also `false`, which means dispatch is blocked and you get nothing). **Manual installs without those keys produce no traces, not "structural-only traces".**
|
|
256
|
-
|
|
257
|
-
The installer always writes both keys to the same value, so the installer-driven path is unambiguous. The runtime-default trap only matters for hand-rolled configs.
|
|
242
|
+
The CLI's first-install default writes `allowConversationAccess: true` to both blocks → full content capture. Pass `--no-content` for structural-only telemetry.
|
|
258
243
|
|
|
259
|
-
|
|
244
|
+
For hand-edited configs, leaving `allowConversationAccess` out entirely produces **no traces** (not "structural-only traces") because `hooks.allowConversationAccess` defaults to `false` at OpenClaw's level and dispatch is blocked. Always set both keys explicitly.
|
|
260
245
|
|
|
261
|
-
To pause emission
|
|
246
|
+
To pause emission without uninstalling, set `enabled: false` on the plugin entry, or `LATITUDE_OPENCLAW_ENABLED=0` in the gateway environment.
|
|
262
247
|
|
|
263
248
|
## Supported OpenClaw versions
|
|
264
249
|
|
|
265
|
-
Requires
|
|
250
|
+
Requires **2026.4.25 or newer**. Earlier versions either reject `hooks.allowConversationAccess` outright (≤ 2026.4.21) or have unverified dispatch gating (2026.4.22 – 2026.4.24). The CLI's version check aborts on older versions; manual installs run into validation errors. Run `npm install -g openclaw@latest` to upgrade.
|
|
266
251
|
|
|
267
252
|
## How it fails
|
|
268
253
|
|
|
269
|
-
Fail-open by design. If the API is unreachable, your key is wrong, or a hook payload is malformed, the plugin logs to stderr (when `
|
|
254
|
+
Fail-open by design. If the API is unreachable, your key is wrong, or a hook payload is malformed, the plugin logs to stderr (when `debug: true`) and the agent run continues unaffected.
|
|
270
255
|
|
|
271
256
|
## License
|
|
272
257
|
|
package/dist/plugin.js
CHANGED
|
@@ -85,7 +85,7 @@ function createLogger(debugEnabled) {
|
|
|
85
85
|
//#endregion
|
|
86
86
|
//#region src/otlp.ts
|
|
87
87
|
const SCOPE_NAME = "@latitude-data/openclaw-telemetry";
|
|
88
|
-
const SCOPE_VERSION = "0.0.
|
|
88
|
+
const SCOPE_VERSION = "0.0.8";
|
|
89
89
|
/** Build an OTLP export request for a single completed agent run. */
|
|
90
90
|
function buildOtlpRequest(result, options) {
|
|
91
91
|
const spans = result.spans.map((span) => toOtlpSpan(span, options));
|
package/openclaw.plugin.json
CHANGED
|
@@ -2,18 +2,18 @@
|
|
|
2
2
|
"id": "@latitude-data/openclaw-telemetry",
|
|
3
3
|
"name": "Latitude Telemetry",
|
|
4
4
|
"description": "Streams every OpenClaw agent run to Latitude as OTLP traces — full prompt, message history, assistant output, tool I/O, token usage, and agent name.",
|
|
5
|
-
"version": "0.0.
|
|
5
|
+
"version": "0.0.8",
|
|
6
6
|
"configSchema": {
|
|
7
7
|
"type": "object",
|
|
8
8
|
"additionalProperties": true,
|
|
9
9
|
"properties": {
|
|
10
10
|
"apiKey": {
|
|
11
11
|
"type": "string",
|
|
12
|
-
"description": "Latitude bearer token.
|
|
12
|
+
"description": "Latitude bearer token. Needed for the plugin to emit; when absent the plugin stays inactive (it does not error). The installer writes it after `openclaw plugins install` creates the entry, so it is intentionally not schema-required."
|
|
13
13
|
},
|
|
14
14
|
"project": {
|
|
15
15
|
"type": "string",
|
|
16
|
-
"description": "Latitude project slug to route traces into.
|
|
16
|
+
"description": "Latitude project slug to route traces into. Needed for the plugin to emit; when absent the plugin stays inactive. Not schema-required for the same reason as apiKey."
|
|
17
17
|
},
|
|
18
18
|
"baseUrl": {
|
|
19
19
|
"type": "string",
|
|
@@ -34,7 +34,6 @@
|
|
|
34
34
|
"default": true,
|
|
35
35
|
"description": "Set to false to pause emission without uninstalling."
|
|
36
36
|
}
|
|
37
|
-
}
|
|
38
|
-
"required": ["apiKey", "project"]
|
|
37
|
+
}
|
|
39
38
|
}
|
|
40
39
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@latitude-data/openclaw-telemetry",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.8",
|
|
4
4
|
"description": "OpenClaw plugin that streams LLM calls, tool executions, and agent runs to Latitude as OTLP traces",
|
|
5
5
|
"author": "Latitude Data SL <hello@latitude.so>",
|
|
6
6
|
"license": "MIT",
|