@datacules/agent-identity-otel 0.9.0 → 0.11.0

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 (2) hide show
  1. package/README.md +45 -36
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,58 +1,67 @@
1
+ <p align="center">
2
+ <img src="../../../assets/logo.svg" alt="Agent Identity — by Datacules LLC" width="360"/>
3
+ </p>
4
+
1
5
  # `@datacules/agent-identity-otel`
2
6
 
3
- OpenTelemetry-native tracing for [`@datacules/agent-identity`](../../core). Auto-instruments every `resolve()`, `resolveAsync()`, and `resolvePair()` call with OTEL spans — zero changes to your existing routing code.
7
+ OpenTelemetry tracing wrapper for the agent-identity framework. Wraps any `CredentialRouter` and emits spans on every `resolve()`, `resolveAsync()`, `resolvePair()`, and `resolvePairAsync()` call so credential resolution appears in your existing distributed traces.
4
8
 
5
9
  ## Install
6
10
 
7
11
  ```bash
8
- npm install @datacules/agent-identity-otel @opentelemetry/api
12
+ npm install @datacules/agent-identity-otel
13
+ # peer dependencies:
14
+ npm install @opentelemetry/api
9
15
  ```
10
16
 
11
17
  ## Usage
12
18
 
13
19
  ```typescript
20
+ import { withOtel } from '@datacules/agent-identity-otel';
14
21
  import { createRouter } from '@datacules/agent-identity';
15
- import { withOtel } from '@datacules/agent-identity-otel';
16
- import { trace } from '@opentelemetry/api';
17
-
18
- const baseRouter = createRouter(credentials, rules, logger);
22
+ import { trace } from '@opentelemetry/api';
19
23
 
20
- // Wrap with OTEL — one line, zero config changes to your rules or credentials
21
- const router = withOtel(baseRouter, {
22
- tracer: trace.getTracer('agent-identity'),
23
- });
24
+ const router = withOtel(
25
+ createRouter(credentials, rules, logger),
26
+ { tracer: trace.getTracer('agent-identity') }
27
+ );
24
28
 
25
- // All resolve calls now emit spans automatically
29
+ // Use exactly as before — spans are emitted transparently
26
30
  const resolved = await router.resolveAsync(ctx);
27
31
  ```
28
32
 
33
+ The spans nest inside your existing application traces in **Datadog APM, Honeycomb, Jaeger, or AWS X-Ray** — no extra configuration required beyond your existing OTEL SDK setup.
34
+
29
35
  ## Span schema
30
36
 
31
- | Span name | When |
32
- |-----------|------|
33
- | `agent-identity.resolve` | Synchronous resolve() |
34
- | `agent-identity.resolve_async` | Async resolveAsync() (includes approval + budget checks) |
35
- | `agent-identity.resolve_pair` | Migration pair resolvePair() |
37
+ | Span name | Operation |
38
+ |-----------|----------|
39
+ | `agent_identity.resolve` | `router.resolve()` |
40
+ | `agent_identity.resolve_async` | `router.resolveAsync()` |
41
+ | `agent_identity.resolve_pair` | `router.resolvePair()` |
42
+ | `agent_identity.resolve_pair_async` | `router.resolvePairAsync()` |
43
+ | `agent_identity.store.get` | `CredentialStore.findByRef()` |
44
+ | `agent_identity.audit.emit` | `AuditLogger.log()` |
36
45
 
37
46
  ## Span attributes
38
47
 
39
- | Attribute | Type | Description |
40
- |-----------|------|-------------|
41
- | `agent.user_id` | string | Calling user ID |
42
- | `agent.provider` | string | AI provider |
43
- | `agent.model` | string | Model name |
44
- | `agent.action` | string | Action being performed |
45
- | `credential.resource_id` | string | Target resource |
46
- | `credential.resource_kind` | string | `shared` or `personal` |
47
- | `credential.id` | string | Resolved credential ID |
48
- | `credential.kind` | string | `fixed` or `user-delegated` |
49
- | `routing.resolved` | boolean | Whether a credential matched |
50
- | `routing.canary` | boolean | Whether the canary ref was selected |
51
- | `routing.resolved_for` | string | `userId` or `service` |
52
- | `trace.id` | string | Agent trace ID |
53
- | `migration.id` | string | Migration ID (pair spans only) |
54
- | `migration.phase` | string | Migration phase (pair spans only) |
55
-
56
- ## Compatible backends
57
-
58
- Works with any OTEL-compatible backend: Datadog APM, Honeycomb, Jaeger, AWS X-Ray, Google Cloud Trace.
48
+ | Attribute | Example |
49
+ |-----------|--------|
50
+ | `agent_identity.provider` | `anthropic` |
51
+ | `agent_identity.user_id` | `user-abc` |
52
+ | `agent_identity.resource_id` | `knowledge-base` |
53
+ | `agent_identity.resource_kind` | `personal` |
54
+ | `agent_identity.action` | `read` |
55
+ | `agent_identity.credential_id` | `cred-anthropic-prod` |
56
+ | `agent_identity.resolved_for` | `user-abc` |
57
+ | `agent_identity.trace_id` | `<uuid>` |
58
+ | `agent_identity.is_canary` | `false` |
59
+ | `agent_identity.model` | `claude-sonnet-4-20250514` |
60
+
61
+ ## Dashboard tab
62
+
63
+ The **OTEL tracing** tab in the interactive dashboard at `localhost:3000` shows a live span emitter, span schema reference, attribute grid, and backend compatibility switcher.
64
+
65
+ ---
66
+
67
+ Part of the [agent-identity monorepo](https://github.com/hvrcharon1/agent-identity) by [Datacules LLC](https://datacules.com).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@datacules/agent-identity-otel",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "private": false,
5
5
  "description": "Zero-config OpenTelemetry tracing wrapper for @datacules/agent-identity",
6
6
  "author": "Datacules LLC",