@latitude-data/openclaw-telemetry 0.0.5 → 0.0.7

package/README.md

@@ -4,45 +4,128 @@ OpenClaw plugin that streams every agent run to [Latitude](https://latitude.so)
 
 ## Install
 
-Requires OpenClaw **2026.4.25 or newer** on PATH. Older versions are detected up-front and the installer aborts with an upgrade message.
+Requires OpenClaw **2026.4.25 or newer**. Get a Latitude API key + project slug from `https://console.latitude.so/settings/api-keys` first.
+
+> **One-shot installer coming soon.** A separate `@latitude-data/openclaw-telemetry-cli` package is in flight that will collapse the steps below into `npx -y @latitude-data/openclaw-telemetry-cli install`. For now, the manual flow below is the supported path.
+
+### Step 1 — Install the plugin runtime
+
+```bash
+openclaw plugins install @latitude-data/openclaw-telemetry@0.0.7
+```
+
+Pin to an exact version. OpenClaw 2026.4.26's `openclaw security audit --deep` warns about unpinned install specs (`Pin install specs to exact versions … for higher supply-chain stability`), so always include the `@<version>` suffix when installing or upgrading.
+
+OpenClaw fetches the package 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`. The gateway will print:
+
+> Plugin installed but disabled. Configure it, then run `openclaw plugins enable @latitude-data/openclaw-telemetry`.
+
+That's expected — the next step does the configure-and-enable.
+
+### Step 2 — Configure and enable
+
+Run these `openclaw config set` commands (use bracket notation so the scoped package name parses correctly). Substitute your real API key and project slug in the first two:
+
+```bash
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.apiKey' "lat_xxx"
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.project' "my-project-slug"
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.allowConversationAccess' true
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].hooks.allowConversationAccess' true
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].enabled' true
+```
+
+Why two `allowConversationAccess` writes? They mean different things — `hooks.*` is OpenClaw's dispatch gate (without it the plugin's hook handlers never fire), `config.*` is the plugin's payload-content gate (without it the plugin emits structural-only spans). For full content capture they must both be `true`. See [The two flags](#the-two-flags) for details.
+
+### Step 3 — Add to `plugins.allow` (optional but loud)
+
+OpenClaw warns at every gateway restart about non-bundled plugins that auto-load without provenance via `plugins.allow`. Silence the warning by adding the id:
+
+```bash
+# `config set` can't append to arrays — set the whole list. If you already have
+# entries in `plugins.allow`, include them here too:
+openclaw config set 'plugins.allow' '["@latitude-data/openclaw-telemetry"]'
+```
+
+### Step 4 — Restart the gateway
 
 ```bash
-npx -y @latitude-data/openclaw-telemetry install
 openclaw gateway restart
 ```
 
-The installer prompts for your Latitude API key and project slug, then:
+Verify everything's wired:
+
+```bash
+openclaw config validate --json
+# → {"valid": true, ...}
+
+grep -E "blocked|plugin not found|latitude" /tmp/openclaw/openclaw-*.log | tail
+# → ready (N plugins: ..., @latitude-data/openclaw-telemetry, ...)
+# → no "blocked", no "plugin not found"
+```
+
+Send a message to one of your OpenClaw agents — within a few seconds, traces appear at `https://console.latitude.so/projects/<your-slug>`.
+
+### Alternative: hand-edit `~/.openclaw/openclaw.json`
+
+If you'd rather paste a JSON block than run six commands, the equivalent edit is:
+
+```jsonc
+{
+  "plugins": {
+    "allow": ["@latitude-data/openclaw-telemetry"],
+    "entries": {
+      "@latitude-data/openclaw-telemetry": {
+        "enabled": true,
+        "hooks": {
+          "allowConversationAccess": true
+        },
+        "config": {
+          "apiKey": "lat_xxx",
+          "project": "my-project-slug",
+          "allowConversationAccess": true
+        }
+      }
+    }
+  }
+}
+```
+
+Merge this with whatever else is in `openclaw.json`. Then `openclaw config validate` and `openclaw gateway restart` as above.
 
-1. Verifies your OpenClaw version (aborts on `< 2026.4.25`).
-2. Hands plugin placement to OpenClaw via `openclaw plugins install <package-path> --force`. OpenClaw copies files into `~/.openclaw/extensions/<id>/`, writes the install record to `~/.openclaw/plugins/installs.json`, and creates the `plugins.entries[id]` block.
-3. Layers our config on top in `~/.openclaw/openclaw.json`:
-   - **`config.*`** — credentials, baseUrl, and `allowConversationAccess` (the payload-content gate the plugin's runtime reads).
-   - **`hooks.allowConversationAccess`** — the dispatch gate OpenClaw's runtime checks before forwarding LLM/tool/agent events to non-bundled plugins. Always mirrored to the same value as `config.allowConversationAccess`.
-4. Adds the plugin id to `plugins.allow` (running `npx install` is the trust signal). Pass `--no-trust` to opt out.
+### Targeting a different environment
 
-Traces show up at `https://console.latitude.so/projects/<your-slug>` once the gateway restarts.
+For staging or local-dev, also set `baseUrl`:
 
-### Install flags
+```bash
+# Staging:
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' "https://staging-ingest.latitude.so"
+
+# Local dev:
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.baseUrl' "http://localhost:3002"
+```
 
-| Flag | What it does |
-| --- | --- |
-| `--api-key=<key>` | Pass the API key instead of being prompted. |
-| `--project=<slug>` | Pass the project slug instead of being prompted. |
-| `--staging` | Target `https://staging.latitude.so` / `https://staging-ingest.latitude.so`. |
-| `--dev` | Target `http://localhost:3000` / `http://localhost:3002`. |
-| `--yes` / `--no-prompt` | Skip all prompts. Required for non-TTY / CI invocations. |
-| `--no-content` | Skip raw prompt/response/tool I/O capture. Spans still emit with timing, token usage, model name, and ids. Mirrored into both `config.allowConversationAccess` and `hooks.allowConversationAccess`. |
-| `--no-trust` | Skip auto-adding the plugin id to `plugins.allow`. OpenClaw will keep printing `plugins.allow is empty` warnings until you add it manually. |
+### Structural-only telemetry (no content capture)
 
-Re-running `install` is idempotent — credentials/baseUrl are overwritten from prompts, but hand-edited `enabled`, `debug`, and `allowConversationAccess` values in `openclaw.json` are preserved unless you pass the corresponding flag.
+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`:
+
+```bash
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].config.allowConversationAccess' false
+openclaw config set 'plugins.entries["@latitude-data/openclaw-telemetry"].hooks.allowConversationAccess' true
+```
+
+Setting `hooks.allowConversationAccess=false` would block dispatch entirely — see [The two flags](#the-two-flags). The plugin still emits the full span tree; just the content attributes (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`, tool args/results) are scrubbed. Each span carries a `latitude.captured.content: false` boolean so the gate state is visible in the Latitude UI.
 
 ## Uninstall
 
 ```bash
-npx -y @latitude-data/openclaw-telemetry uninstall
+openclaw plugins uninstall @latitude-data/openclaw-telemetry --force
 ```
 
-Shows a plan, asks for confirmation, then runs `openclaw plugins uninstall @latitude-data/openclaw-telemetry --force` (which removes files, the install record, the plugin entry, and the `plugins.allow` entry). Defensive cleanup follows for any leftover keys, with a backup at `openclaw.json.latitude-bak`.
+OpenClaw removes the files, install record, plugin entry, and the `plugins.allow` entry. After that, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
 
 ## What gets sent
 

package/dist/plugin.js

@@ -1,7 +1,4 @@
-import { readFileSync } from "node:fs";
 import { arch, hostname, platform, release } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/client.ts
 async function postTraces({ baseUrl, apiKey, project, payload, logger, timeoutMs = 1e4 }) {
@@ -35,21 +32,32 @@ async function postTraces({ baseUrl, apiKey, project, payload, logger, timeoutMs
 //#region src/config.ts
 const DEFAULT_BASE_URL = "https://ingest.latitude.so";
 /**
-* Build a `Config` from OpenClaw's per-plugin config bucket plus environment
-* variables. The plugin SDK passes `api.pluginConfig` (the user's
-* `plugins.entries[id].config` block) to the registration function — that's
-* the primary source. Env vars are kept as a fallback so existing deployments
-* with `LATITUDE_*` already exported in the gateway environment keep working,
-* and so that `LATITUDE_DEBUG=1` can be flipped without editing openclaw.json.
+* Build a `Config` from OpenClaw's per-plugin config bucket. The plugin SDK
+* passes `api.pluginConfig` (the user's `plugins.entries[id].config` block)
+* to the registration function — that's the only source.
+*
+* Earlier 0.0.x versions also fell back to environment variables when keys
+* were missing from pluginConfig. That fallback is gone deliberately:
+* OpenClaw 2026.4.25's `openclaw plugins install` runs a static-analysis
+* security scan that flags any runtime source combining environment-variable
+* access with a network-send call (we have `fetch(` in postTraces). With
+* the fallback our bundled runtime tripped the scanner. The installer
+* writes credentials to `plugins.entries[id].config` anyway, so the
+* fallback was polish-not-feature — its removal also gives a cleaner
+* privacy story (the runtime can't pick up credentials the operator
+* didn't put in openclaw.json).
+*
+* For dev-time testing with debug logs, set `config.debug = true` in
+* openclaw.json directly.
 */
-function loadConfig(pluginConfig = void 0, env = process.env) {
+function loadConfig(pluginConfig = void 0) {
 	const fromOpts = pluginConfig ?? {};
-	const apiKey = pickString(fromOpts.apiKey) ?? env.LATITUDE_API_KEY ?? "";
-	const project = pickString(fromOpts.project) ?? env.LATITUDE_PROJECT ?? "";
-	const baseUrl = pickString(fromOpts.baseUrl) ?? env.LATITUDE_BASE_URL ?? DEFAULT_BASE_URL;
-	const debug = pickBool(fromOpts.debug) ?? env.LATITUDE_DEBUG === "1";
+	const apiKey = pickString(fromOpts.apiKey) ?? "";
+	const project = pickString(fromOpts.project) ?? "";
+	const baseUrl = pickString(fromOpts.baseUrl) ?? DEFAULT_BASE_URL;
+	const debug = pickBool(fromOpts.debug) ?? false;
 	const allowConversationAccess = pickBool(fromOpts.allowConversationAccess) ?? false;
-	const explicitlyDisabled = pickBool(fromOpts.enabled) === false || (env.LATITUDE_OPENCLAW_ENABLED ?? "1") === "0";
+	const explicitlyDisabled = pickBool(fromOpts.enabled) === false;
 	return {
 		apiKey,
 		baseUrl,
@@ -77,7 +85,7 @@ function createLogger(debugEnabled) {
 //#endregion
 //#region src/otlp.ts
 const SCOPE_NAME = "@latitude-data/openclaw-telemetry";
-const SCOPE_VERSION = readScopeVersion();
+const SCOPE_VERSION = "0.0.7";
 /** Build an OTLP export request for a single completed agent run. */
 function buildOtlpRequest(result, options) {
 	const spans = result.spans.map((span) => toOtlpSpan(span, options));
@@ -167,22 +175,6 @@ function safeJson$1(value) {
 		return "";
 	}
 }
-/**
-* Runtime-read package version, so OTLP `scope.version` and `service.version`
-* always reflect what's actually installed. Read once at module load and
-* cached. Falls back to `"unknown"` if the read fails.
-*
-* Same import.meta.url + ../package.json pattern used by `cli.ts` for the
-* `--version` flag — single source of truth in package.json.
-*/
-function readScopeVersion() {
-	try {
-		const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-		return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "unknown";
-	} catch {
-		return "unknown";
-	}
-}
 //#endregion
 //#region src/messages.ts
 const ALLOWED_ROLES = new Set([
@@ -437,6 +429,7 @@ var SpanBuilder = class {
 			attrs: {
 				...flattenCtx(ctx),
 				...latitudeAttrs(ctx),
+				...sessionAttrs(ctx),
 				"openclaw.run.id": runId,
 				"before_agent_start.prompt:gated": evt.prompt,
 				"before_agent_start.messages:gated": evt.messages ? normalizeMessages(evt.messages) : void 0
@@ -505,6 +498,7 @@ var SpanBuilder = class {
 			endMs: void 0,
 			attrs: {
 				...latitudeAttrs(ctx),
+				...sessionAttrs(ctx),
 				"openclaw.run.id": evt.runId,
 				"openclaw.call.id": evt.callId,
 				"gen_ai.system": evt.provider,
@@ -562,6 +556,7 @@ var SpanBuilder = class {
 			endMs: void 0,
 			attrs: {
 				...latitudeAttrs(ctx),
+				...sessionAttrs(ctx),
 				"openclaw.run.id": evt.runId,
 				"gen_ai.tool.name": evt.toolName,
 				"gen_ai.tool.call.id": toolCallId,
@@ -622,6 +617,7 @@ var SpanBuilder = class {
 			endMs: void 0,
 			attrs: {
 				...latitudeAttrs(ctx),
+				...sessionAttrs(ctx),
 				"openclaw.run.id": runId,
 				"openclaw.compaction.message_count.before": evt.messageCount,
 				"openclaw.compaction.session_file": evt.sessionFile,
@@ -663,6 +659,7 @@ var SpanBuilder = class {
 			endMs: void 0,
 			attrs: {
 				...latitudeAttrs(ctx),
+				...sessionAttrs(ctx),
 				"openclaw.parent.run.id": parentRunId,
 				"openclaw.run.id": evt.runId,
 				"openclaw.subagent.child_session_key": evt.childSessionKey,
@@ -819,6 +816,21 @@ function flattenCtx(ctx) {
 	};
 }
 /**
+* Mirror OpenClaw's session id onto the OTEL-standard keys Latitude's
+* resolver looks for. `gen_ai.session.id` and `session.id` are both in
+* `sessionIdCandidates` (domain/spans/src/otlp/resolvers/identity.ts), so
+* traces can be grouped by session in the Latitude UI without an
+* openclaw-specific code path. Emitted on every span, not just `agent`,
+* so child spans (model_call / tool_call / etc.) inherit the same grouping.
+*/
+function sessionAttrs(ctx) {
+	if (!ctx.sessionId) return {};
+	return {
+		"session.id": ctx.sessionId,
+		"gen_ai.session.id": ctx.sessionId
+	};
+}
+/**
 * Build `latitude.tags` and `latitude.metadata` attrs from the hook context.
 * The OTLP encoder JSON-stringifies arrays/objects, which is the encoding
 * Latitude's resolver expects:
@@ -937,19 +949,25 @@ function registerLatitudePlugin(api, opts = {}) {
 		builder.onLlmOutput(evt, ctx);
 	}));
 	api.on("agent_end", wrap("agent_end", (evt, ctx) => {
-		const result = builder.onAgentEnd(evt, ctx);
-		if (!result) {
-			logger.debug("agent_end fired without a matching run in flight");
-			return;
-		}
-		opts.onEmit?.(result);
-		const payload = buildOtlpRequest(result, { allowConversationAccess: config.allowConversationAccess });
-		postTraces({
-			baseUrl: config.baseUrl,
-			apiKey: config.apiKey,
-			project: config.project,
-			payload,
-			logger
+		queueMicrotask(() => {
+			try {
+				const result = builder.onAgentEnd(evt, ctx);
+				if (!result) {
+					logger.debug("agent_end fired without a matching run in flight");
+					return;
+				}
+				opts.onEmit?.(result);
+				const payload = buildOtlpRequest(result, { allowConversationAccess: config.allowConversationAccess });
+				postTraces({
+					baseUrl: config.baseUrl,
+					apiKey: config.apiKey,
+					project: config.project,
+					payload,
+					logger
+				});
+			} catch (err) {
+				logger.warn(`agent_end finalize failed: ${String(err)}`);
+			}
 		});
 	}));
 }