{"_id":"@aigentsphere/openclaw-otel-observability","_rev":"4-4c004702da1404e7778b7e99148bb70f","name":"@aigentsphere/openclaw-otel-observability","dist-tags":{"latest":"0.3.1"},"versions":{"0.2.1":{"name":"@aigentsphere/openclaw-otel-observability","version":"0.2.1","keywords":["openclaw","opentelemetry","observability","llm","tracing","metrics","dynatrace","openllmetry"],"author":{"name":"Henrik Rexed"},"license":"Apache-2.0","_id":"@aigentsphere/openclaw-otel-observability@0.2.1","maintainers":[{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"}],"homepage":"https://github.com/aigentsphere/openclaw-observability-plugin#readme","bugs":{"url":"https://github.com/aigentsphere/openclaw-observability-plugin/issues"},"dist":{"shasum":"192aed05e79556642c476900075ad4f7034155f1","tarball":"https://registry.npmjs.org/@aigentsphere/openclaw-otel-observability/-/openclaw-otel-observability-0.2.1.tgz","fileCount":43,"integrity":"sha512-IJgEWxU+jP3lc864lUxG6i9dcG7Uv7XLTMrXEr/c9TQjKsUGNHv2Dk9ntdIvVHTIilzHwpv4Anbbf9vR4G+TEg==","signatures":[{"sig":"MEYCIQD7yoiK6dUhNgz5tVsNho4q+FsEwczQKeQXJMHNoCiRlQIhANT38AnP5snuTnYBdXIPodem57h2euVVky8KaiMgX0yZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":220119},"type":"module","gitHead":"737083f3a63293e07d79715da3922f19bbd6480b","scripts":{"lint":"eslint src/ index.ts","typecheck":"tsc --noEmit"},"_npmUser":{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"},"openclaw":{"extensions":["./index.ts"]},"repository":{"url":"git+https://github.com/aigentsphere/openclaw-observability-plugin.git","type":"git"},"_npmVersion":"10.9.4","description":"OpenTelemetry observability plugin for OpenClaw — traces, metrics, and logs for your AI agent using OpenLLMetry","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-node":"^0.203.0","@opentelemetry/resources":"^2.0.1","@opentelemetry/sdk-metrics":"^2.0.1","@traceloop/node-server-sdk":"^0.22.6","@opentelemetry/sdk-trace-node":"^2.0.1","@opentelemetry/semantic-conventions":"^1.30.0","@opentelemetry/exporter-trace-otlp-grpc":"^0.203.0","@opentelemetry/exporter-trace-otlp-http":"^0.203.0","@opentelemetry/exporter-metrics-otlp-grpc":"^0.203.0","@opentelemetry/exporter-metrics-otlp-http":"^0.203.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-otel-observability_0.2.1_1771231713955_0.18079722812010135","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@aigentsphere/openclaw-otel-observability","version":"0.2.2","keywords":["openclaw","opentelemetry","observability","llm","tracing","metrics","dynatrace","openllmetry"],"author":{"name":"Henrik Rexed"},"license":"Apache-2.0","_id":"@aigentsphere/openclaw-otel-observability@0.2.2","maintainers":[{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"}],"homepage":"https://github.com/aigentsphere/openclaw-observability-plugin#readme","bugs":{"url":"https://github.com/aigentsphere/openclaw-observability-plugin/issues"},"dist":{"shasum":"b0046cadf36f8bda9b50143d9576283c46faf398","tarball":"https://registry.npmjs.org/@aigentsphere/openclaw-otel-observability/-/openclaw-otel-observability-0.2.2.tgz","fileCount":33,"integrity":"sha512-jpM97EhSvZFCWzPZ7PvPuxmCQlbKgl4dF1kqFsUEijljtuXpXzxpqTpm07Mme6NSIU/NluJBOF7ZnKVNTDmTcQ==","signatures":[{"sig":"MEQCIFSaNIpZTRGY1NwwU6IUzfegxvTSWT+7xKSMXsX2cyh5AiBRswWGj8cY+MX4UjFdaHU4xxt509DGT1kzdHQ+IORLtA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":140965},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"775063b9623972ef6a32c1f617463626703588e5","scripts":{"lint":"eslint src/ index.ts","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"},"openclaw":{"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/aigentsphere/openclaw-observability-plugin.git","type":"git"},"_npmVersion":"10.9.4","description":"OpenTelemetry observability plugin for OpenClaw — traces, metrics, and logs for your AI agent using OpenLLMetry","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-node":"^0.203.0","@opentelemetry/resources":"^2.0.1","@opentelemetry/sdk-metrics":"^2.0.1","@traceloop/node-server-sdk":"^0.22.6","@opentelemetry/sdk-trace-node":"^2.0.1","@opentelemetry/semantic-conventions":"^1.30.0","@opentelemetry/exporter-trace-otlp-grpc":"^0.203.0","@opentelemetry/exporter-trace-otlp-http":"^0.203.0","@opentelemetry/exporter-metrics-otlp-grpc":"^0.203.0","@opentelemetry/exporter-metrics-otlp-http":"^0.203.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-otel-observability_0.2.2_1771232554266_0.20055092591390888","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@aigentsphere/openclaw-otel-observability","version":"0.3.0","keywords":["openclaw","opentelemetry","observability","llm","tracing","metrics","dynatrace","openllmetry"],"author":{"name":"Henrik Rexed"},"license":"Apache-2.0","_id":"@aigentsphere/openclaw-otel-observability@0.3.0","maintainers":[{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"}],"homepage":"https://github.com/aigentsphere/openclaw-observability-plugin#readme","bugs":{"url":"https://github.com/aigentsphere/openclaw-observability-plugin/issues"},"dist":{"shasum":"cba080d0c1fe64f5abef1ea16a2a080e3be3e7a2","tarball":"https://registry.npmjs.org/@aigentsphere/openclaw-otel-observability/-/openclaw-otel-observability-0.3.0.tgz","fileCount":33,"integrity":"sha512-ZtKDefzuj17Q0I8FWjzoMJW6WYRzj5Rgt8ibXkT3HP8bkr+HVdMdPqHI38z61ImleEmJdQLzOrrQYuspvBaEoQ==","signatures":[{"sig":"MEUCIQCr0CsooFxbUNx4cLIJJK3v62IZSNCUjEuLOq1cBrHk6wIgDFup1/FGq90MyMl4VPmj32b8tTWun01Iol+oS5MYIQM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":144745},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"6a4e0ea9a682054d606c7664283459db2cb26cd4","scripts":{"lint":"eslint src/ index.ts","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"},"openclaw":{"extensions":["./dist/index.js"]},"repository":{"url":"git+https://github.com/aigentsphere/openclaw-observability-plugin.git","type":"git"},"_npmVersion":"10.9.4","description":"OpenTelemetry observability plugin for OpenClaw — traces, metrics, and logs for your AI agent using OpenLLMetry","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-node":"^0.203.0","@opentelemetry/resources":"^2.0.1","@opentelemetry/sdk-metrics":"^2.0.1","@traceloop/node-server-sdk":"^0.22.6","@opentelemetry/sdk-trace-node":"^2.0.1","@opentelemetry/semantic-conventions":"^1.30.0","@opentelemetry/exporter-trace-otlp-grpc":"^0.203.0","@opentelemetry/exporter-trace-otlp-http":"^0.203.0","@opentelemetry/exporter-metrics-otlp-grpc":"^0.203.0","@opentelemetry/exporter-metrics-otlp-http":"^0.203.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-otel-observability_0.3.0_1771628242104_0.5758445154442848","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@aigentsphere/openclaw-otel-observability","version":"0.3.1","description":"OpenTelemetry observability plugin for OpenClaw — traces, metrics, and logs for your AI agent using OpenLLMetry","type":"module","main":"dist/index.js","types":"dist/index.d.ts","openclaw":{"extensions":["./dist/index.js"]},"repository":{"type":"git","url":"git+https://github.com/aigentsphere/openclaw-observability-plugin.git"},"publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"npm run build","lint":"eslint src/ index.ts"},"keywords":["openclaw","opentelemetry","observability","llm","tracing","metrics","dynatrace","openllmetry"],"author":{"name":"Henrik Rexed"},"license":"Apache-2.0","dependencies":{"@traceloop/node-server-sdk":"^0.22.6","@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-node":"^0.203.0","@opentelemetry/sdk-trace-node":"^2.0.1","@opentelemetry/sdk-metrics":"^2.0.1","@opentelemetry/exporter-trace-otlp-http":"^0.203.0","@opentelemetry/exporter-trace-otlp-grpc":"^0.203.0","@opentelemetry/exporter-metrics-otlp-http":"^0.203.0","@opentelemetry/exporter-metrics-otlp-grpc":"^0.203.0","@opentelemetry/resources":"^2.0.1","@opentelemetry/semantic-conventions":"^1.30.0"},"devDependencies":{"typescript":"^5.7.0"},"_id":"@aigentsphere/openclaw-otel-observability@0.3.1","gitHead":"c9a12c76aba79b56f29002f2150b3bbb79e977e0","bugs":{"url":"https://github.com/aigentsphere/openclaw-observability-plugin/issues"},"homepage":"https://github.com/aigentsphere/openclaw-observability-plugin#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-1PEAJmhF9EPyvrLLYS/+O3qDCuqfFIk7paK0NW0rwEVxN2n2YsjVDDoUN42uNR/zBwDEAkmzCJ+iGokvxSpijA==","shasum":"2f522a52c02c2a119f18002a9e571d6005488320","tarball":"https://registry.npmjs.org/@aigentsphere/openclaw-otel-observability/-/openclaw-otel-observability-0.3.1.tgz","fileCount":33,"unpackedSize":145920,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD2RqvKJaNjRC9ZdspHFQ107C43OTUouQvO1tQ3T284nAIgTVYOB0snvzC8wGOGUiq54tgKz/uaFzDv+AvRbZApxRc="}]},"_npmUser":{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"},"directories":{},"maintainers":[{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-otel-observability_0.3.1_1771989502659_0.15298926865852436"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-16T08:48:33.816Z","modified":"2026-02-25T03:18:22.947Z","0.2.1":"2026-02-16T08:48:34.129Z","0.2.2":"2026-02-16T09:02:34.414Z","0.3.0":"2026-02-20T22:57:22.271Z","0.3.1":"2026-02-25T03:18:22.814Z"},"bugs":{"url":"https://github.com/aigentsphere/openclaw-observability-plugin/issues"},"author":{"name":"Henrik Rexed"},"license":"Apache-2.0","homepage":"https://github.com/aigentsphere/openclaw-observability-plugin#readme","keywords":["openclaw","opentelemetry","observability","llm","tracing","metrics","dynatrace","openllmetry"],"repository":{"type":"git","url":"git+https://github.com/aigentsphere/openclaw-observability-plugin.git"},"description":"OpenTelemetry observability plugin for OpenClaw — traces, metrics, and logs for your AI agent using OpenLLMetry","maintainers":[{"name":"quinton_aigentsphere.com","email":"quinton@aigentsphere.com"}],"readme":"# OpenClaw Observability\n\n[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://henrikrexed.github.io/openclaw-observability-plugin/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nOpenTelemetry observability for [OpenClaw](https://github.com/openclaw/openclaw) AI agents.\n\n📖 **[Full Documentation](https://henrikrexed.github.io/openclaw-observability-plugin/)** — Setup guides, configuration reference, and backend examples.\n\n## Two Approaches to Observability\n\nThis repository documents **two complementary approaches** to monitoring OpenClaw:\n\n| Approach | Best For | Setup Complexity |\n|----------|----------|------------------|\n| **Official Plugin** | Operational metrics, Gateway health, cost tracking | Simple config |\n| **Custom Plugin** | Deep tracing, tool call visibility, request lifecycle | Plugin installation |\n\n**Recommendation:** Use both for complete observability.\n\n---\n\n## Approach 1: Official Diagnostics Plugin (Built-in)\n\nOpenClaw v2026.2+ includes **built-in OpenTelemetry support**. Just add to `openclaw.json`:\n\n```json\n{\n  \"diagnostics\": {\n    \"enabled\": true,\n    \"otel\": {\n      \"enabled\": true,\n      \"endpoint\": \"http://localhost:4318\",\n      \"serviceName\": \"openclaw-gateway\",\n      \"traces\": true,\n      \"metrics\": true,\n      \"logs\": true\n    }\n  }\n}\n```\n\nThen restart:\n\n```bash\nopenclaw gateway restart\n```\n\n### What It Captures\n\n**Metrics:**\n- `openclaw.tokens` — Token usage by type (input/output/cache)\n- `openclaw.cost.usd` — Estimated model cost\n- `openclaw.run.duration_ms` — Agent run duration\n- `openclaw.context.tokens` — Context window usage\n- `openclaw.webhook.*` — Webhook processing stats\n- `openclaw.message.*` — Message processing stats\n- `openclaw.queue.*` — Queue depth and wait times\n- `openclaw.session.*` — Session state transitions\n\n**Traces:** Model usage, webhook processing, message processing, stuck sessions\n\n**Logs:** All Gateway logs via OTLP with severity, subsystem, and code location\n\n---\n\n## Approach 2: Custom Hook-Based Plugin (This Repo)\n\nFor **deeper observability**, install the custom plugin from this repo. It uses OpenClaw's typed plugin hooks to capture the full agent lifecycle.\n\n### What It Adds\n\n**Connected Traces:**\n```\nopenclaw.request (root span)\n├── openclaw.agent.turn\n│   ├── tool.Read (file read)\n│   ├── tool.exec (shell command)  \n│   ├── tool.Write (file write)\n│   └── tool.web_search\n└── (child spans connected via trace context)\n```\n\n**Per-Tool Visibility:**\n- Individual spans for each tool call\n- Tool execution time\n- Result size (characters)\n- Error tracking per tool\n\n**Request Lifecycle:**\n- Full message → response tracing\n- Session context propagation\n- Agent turn duration with token breakdown\n\n### Installation\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/henrikrexed/openclaw-observability-plugin.git\n   ```\n\n2. Add to your `openclaw.json`:\n   ```json\n   {\n     \"plugins\": {\n       \"load\": {\n         \"paths\": [\"/path/to/openclaw-observability-plugin\"]\n       },\n       \"entries\": {\n         \"otel-observability\": {\n           \"enabled\": true,\n           \"config\": {\n             \"endpoint\": \"http://localhost:4318\",\n             \"serviceName\": \"openclaw-gateway\"\n           }\n         }\n       }\n     }\n   }\n   ```\n\n3. Clear cache and restart:\n   ```bash\n   rm -rf /tmp/jiti\n   systemctl --user restart openclaw-gateway\n   ```\n\n---\n\n## Comparing the Two Approaches\n\n| Feature | Official Plugin | Custom Plugin |\n|---------|-----------------|---------------|\n| Token metrics | ✅ Per model | ✅ Per session + model |\n| Cost tracking | ✅ Yes | ✅ Yes (from diagnostics) |\n| Gateway health | ✅ Webhooks, queues, sessions | ❌ Not focused |\n| Session state | ✅ State transitions | ❌ Not tracked |\n| **Tool call tracing** | ❌ No | ✅ Individual tool spans |\n| **Request lifecycle** | ❌ No | ✅ Full request → response |\n| **Connected traces** | ❌ Separate spans | ✅ Parent-child hierarchy |\n| Setup complexity | 🟢 Config only | 🟡 Plugin installation |\n\n---\n\n## Backend Examples\n\n### Dynatrace (Direct)\n\n```json\n{\n  \"diagnostics\": {\n    \"enabled\": true,\n    \"otel\": {\n      \"enabled\": true,\n      \"endpoint\": \"https://{env-id}.live.dynatrace.com/api/v2/otlp\",\n      \"headers\": {\n        \"Authorization\": \"Api-Token {your-token}\"\n      },\n      \"serviceName\": \"openclaw-gateway\",\n      \"traces\": true,\n      \"metrics\": true,\n      \"logs\": true\n    }\n  }\n}\n```\n\n### Grafana Cloud\n\n```json\n{\n  \"diagnostics\": {\n    \"enabled\": true,\n    \"otel\": {\n      \"enabled\": true,\n      \"endpoint\": \"https://otlp-gateway-{region}.grafana.net/otlp\",\n      \"headers\": {\n        \"Authorization\": \"Basic {base64-credentials}\"\n      },\n      \"serviceName\": \"openclaw-gateway\",\n      \"traces\": true,\n      \"metrics\": true\n    }\n  }\n}\n```\n\n### Local OTel Collector\n\n```json\n{\n  \"diagnostics\": {\n    \"enabled\": true,\n    \"otel\": {\n      \"enabled\": true,\n      \"endpoint\": \"http://localhost:4318\",\n      \"serviceName\": \"openclaw-gateway\",\n      \"traces\": true,\n      \"metrics\": true,\n      \"logs\": true\n    }\n  }\n}\n```\n\n---\n\n## Configuration Reference\n\n### Official Plugin Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `diagnostics.enabled` | boolean | false | Enable diagnostics system |\n| `diagnostics.otel.enabled` | boolean | false | Enable OTel export |\n| `diagnostics.otel.endpoint` | string | — | OTLP endpoint URL |\n| `diagnostics.otel.protocol` | string | \"http/protobuf\" | Protocol |\n| `diagnostics.otel.headers` | object | — | Custom headers |\n| `diagnostics.otel.serviceName` | string | \"openclaw\" | Service name |\n| `diagnostics.otel.traces` | boolean | true | Enable traces |\n| `diagnostics.otel.metrics` | boolean | true | Enable metrics |\n| `diagnostics.otel.logs` | boolean | false | Enable logs |\n| `diagnostics.otel.sampleRate` | number | 1.0 | Trace sampling (0-1) |\n\n### Custom Plugin Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `endpoint` | string | — | OTLP endpoint URL |\n| `serviceName` | string | \"openclaw-gateway\" | Service name |\n| `exporterType` | string | \"otlp\" | Exporter type |\n| `enableTraces` | boolean | true | Enable traces |\n| `enableMetrics` | boolean | true | Enable metrics |\n\n---\n\n## Documentation\n\n- [Getting Started](./docs/getting-started.md) — Setup guide\n- [Configuration](./docs/configuration.md) — All options\n- [Architecture](./docs/architecture.md) — How it works\n- [Limitations](./docs/limitations.md) — Known constraints\n- [Backends](./docs/backends/) — Backend-specific guides\n\n---\n\n## Optional: Kernel-Level Security with Tetragon\n\nFor **defense in depth**, add [Tetragon](https://tetragon.io) eBPF-based monitoring. While the plugins above capture application-level telemetry, Tetragon sees what happens at the kernel level — file access, process execution, network connections, and privilege changes.\n\n### Why Tetragon?\n\n- **Tamper-proof**: Even a compromised agent can't hide its kernel-level actions\n- **Sensitive file detection**: Alert when `.env`, SSH keys, or credentials are accessed\n- **Dangerous command detection**: Catch `rm`, `curl | sh`, `chmod 777`, etc.\n- **Privilege escalation**: Detect `setuid`/`setgid` attempts\n\n### Quick Setup\n\n```bash\n# Install Tetragon\ncurl -LO https://github.com/cilium/tetragon/releases/latest/download/tetragon-v1.6.0-amd64.tar.gz\ntar -xzf tetragon-v1.6.0-amd64.tar.gz && cd tetragon-v1.6.0-amd64\nsudo ./install.sh\n\n# Create OpenClaw policies directory\nsudo mkdir -p /etc/tetragon/tetragon.tp.d/openclaw\n\n# Add policies (see docs/security/tetragon.md for full examples)\n# Start Tetragon\nsudo systemctl enable --now tetragon\n```\n\nTetragon events are exported to `/var/log/tetragon/tetragon.log` and can be ingested by the OTel Collector using the `filelog` receiver.\n\n### Complete Observability Stack\n\n| Layer | Source | What It Shows |\n|-------|--------|---------------|\n| **Application** | Custom Plugin | Tool calls, tokens, request flow |\n| **Gateway** | Official Plugin | Session health, queues, costs |\n| **Kernel** | Tetragon | System calls, file access, network |\n\nSee [Security: Tetragon](./docs/security/tetragon.md) for full installation and configuration guide.\n\n---\n\n## Known Limitations\n\n**Auto-instrumentation not possible:** OpenLLMetry/IITM breaks `@mariozechner/pi-ai` named exports due to ESM/CJS module isolation. All telemetry is captured via hooks, not direct SDK instrumentation.\n\n**No per-LLM-call spans:** Individual API calls to Claude/OpenAI cannot be traced. Token usage is aggregated per agent turn.\n\nSee [Limitations](./docs/limitations.md) for details.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}