@arnilo/prism-observability-opentelemetry 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.4] - 2026-07-14
+
+- Added session attachment, metadata-only provider/tool spans, low-cardinality metrics, in-memory telemetry, disabled no-op mode, and exporter-failure isolation.
+
+## [0.0.3]
+
+- Initial release: `createOpenTelemetryInstrumentation`, mockable tracer/meter interfaces, and optional `@opentelemetry/api` bridge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prism contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @arnilo/prism-observability-opentelemetry
+
+Optional OpenTelemetry bridge for Prism `AgentEvent` streams. Core Prism emits metadata-only provider and tool timing events; this package maps them to spans and low-cardinality metrics without pulling OpenTelemetry into `@arnilo/prism`.
+
+## Install
+
+```bash
+npm install @arnilo/prism @arnilo/prism-observability-opentelemetry @opentelemetry/api
+```
+
+`@opentelemetry/api` is an optional peer dependency. Pass mockable `PrismTracer` / `PrismMeter` interfaces when you want tests without the OpenTelemetry SDK.
+
+## Usage
+
+```ts
+import { trace, metrics } from "@opentelemetry/api";
+import { createOpenTelemetryInstrumentation, wrapOpenTelemetryApi } from "@arnilo/prism-observability-opentelemetry";
+
+const { tracer, meter } = wrapOpenTelemetryApi(trace.getTracer("my-app"), metrics.getMeter("my-app"));
+const telemetry = createOpenTelemetryInstrumentation({ tracer, meter });
+
+const detach = telemetry.attachSession(session);
+await session.run("hello");
+detach();
+```
+
+Or handle events from an existing subscriber:
+
+```ts
+for await (const event of session.subscribe()) telemetry.handleAgentEvent(event);
+```
+
+Set `enabled: false` or omit both `tracer` and `meter` for a no-op adapter.
+
+## Defaults
+
+- Metadata-only spans: no prompts, tool arguments, or credentials.
+- High-cardinality IDs (`sessionId`, `runId`, `requestId`, `toolCallId`) are span attributes, not metric labels.
+- Metric labels are limited to `provider_id`, `outcome`, `status`, and token `kind`.
+- Exporter failures are isolated: instrumentation catches errors and forwards them to `onExporterError` without affecting the run.
+
+## Profile inclusion
+
+This optional package is installed by `@arnilo/prism-sdk` and `@arnilo/prism-all`. Installation does not enable instrumentation; hosts still provide and configure telemetry APIs/exporters.
+
+## Related
+
+- [Observability](../../docs/observability.md)
+- [Agent events](../../docs/agent-events.md)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createInMemoryTelemetry, createOpenTelemetryInstrumentation, wrapOpenTelemetryApi, } from "./instrumentation.js";
+export type { InMemoryTelemetry, OpenTelemetryInstrumentation, OpenTelemetryInstrumentationOptions, PrismCounter, PrismHistogram, PrismMeter, PrismSpan, PrismSpanStatus, PrismTracer, RecordedMetric, RecordedSpan, } from "./instrumentation.js";
+export declare const packageName = "@arnilo/prism-observability-opentelemetry";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createInMemoryTelemetry, createOpenTelemetryInstrumentation, wrapOpenTelemetryApi, } from "./instrumentation.js";
+export const packageName = "@arnilo/prism-observability-opentelemetry";
+//# sourceMappingURL=index.js.map

package/dist/instrumentation.d.ts

@@ -0,0 +1,95 @@
+import type { AgentEvent, AgentSession } from "@arnilo/prism";
+export type PrismSpanStatus = "ok" | "error";
+export interface PrismSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(code: PrismSpanStatus, message?: string): void;
+    end(): void;
+}
+export interface PrismTracer {
+    startSpan(name: string, options?: {
+        readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+    }): PrismSpan;
+}
+export interface PrismCounter {
+    add(value: number, attributes?: Readonly<Record<string, string>>): void;
+}
+export interface PrismHistogram {
+    record(value: number, attributes?: Readonly<Record<string, string>>): void;
+}
+export interface PrismMeter {
+    createCounter(name: string, options?: {
+        readonly description?: string;
+    }): PrismCounter;
+    createHistogram(name: string, options?: {
+        readonly description?: string;
+        readonly unit?: string;
+    }): PrismHistogram;
+}
+export interface OpenTelemetryInstrumentationOptions {
+    readonly enabled?: boolean;
+    readonly tracer?: PrismTracer;
+    readonly meter?: PrismMeter;
+    readonly onExporterError?: (error: unknown) => void;
+}
+export interface OpenTelemetryInstrumentation {
+    readonly enabled: boolean;
+    handleAgentEvent(event: AgentEvent): void;
+    attachSession(session: Pick<AgentSession, "subscribe">): () => void;
+}
+export interface RecordedSpan {
+    readonly name: string;
+    readonly attributes: Record<string, string | number | boolean>;
+    readonly status?: {
+        readonly code: PrismSpanStatus;
+        readonly message?: string;
+    };
+    readonly ended: boolean;
+}
+export interface RecordedMetric {
+    readonly name: string;
+    readonly kind: "counter" | "histogram";
+    readonly value: number;
+    readonly attributes: Record<string, string>;
+}
+export interface InMemoryTelemetry {
+    readonly tracer: PrismTracer;
+    readonly meter: PrismMeter;
+    readonly spans: readonly RecordedSpan[];
+    readonly metrics: readonly RecordedMetric[];
+    clear(): void;
+}
+export declare function createInMemoryTelemetry(): InMemoryTelemetry;
+export declare function createOpenTelemetryInstrumentation(options?: OpenTelemetryInstrumentationOptions): OpenTelemetryInstrumentation;
+interface OpenTelemetrySpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    end(): void;
+}
+interface OpenTelemetryTracer {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): OpenTelemetrySpan;
+}
+interface OpenTelemetryCounter {
+    add(value: number, attributes?: Record<string, string>): void;
+}
+interface OpenTelemetryHistogram {
+    record(value: number, attributes?: Record<string, string>): void;
+}
+interface OpenTelemetryMeter {
+    createCounter(name: string, options?: {
+        description?: string;
+    }): OpenTelemetryCounter;
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OpenTelemetryHistogram;
+}
+export declare function wrapOpenTelemetryApi(tracer: OpenTelemetryTracer, meter?: OpenTelemetryMeter): {
+    tracer: PrismTracer;
+    meter?: PrismMeter;
+};
+export {};

package/dist/instrumentation.js

@@ -0,0 +1,275 @@
+function spanKey(...parts) {
+    return parts.join(":");
+}
+function metricAttrs(attrs) {
+    return attrs;
+}
+export function createInMemoryTelemetry() {
+    const spans = [];
+    const metrics = [];
+    const tracer = {
+        startSpan(name, options) {
+            const record = { name, attributes: { ...(options?.attributes ?? {}) }, ended: false };
+            spans.push(record);
+            return {
+                setAttribute(key, value) {
+                    record.attributes[key] = value;
+                },
+                setStatus(code, message) {
+                    record.status = { code, message };
+                },
+                end() {
+                    record.ended = true;
+                },
+            };
+        },
+    };
+    const meter = {
+        createCounter(name) {
+            return {
+                add(value, attributes) {
+                    metrics.push({ name, kind: "counter", value, attributes: { ...(attributes ?? {}) } });
+                },
+            };
+        },
+        createHistogram(name) {
+            return {
+                record(value, attributes) {
+                    metrics.push({ name, kind: "histogram", value, attributes: { ...(attributes ?? {}) } });
+                },
+            };
+        },
+    };
+    return {
+        tracer,
+        meter,
+        get spans() {
+            return spans;
+        },
+        get metrics() {
+            return metrics;
+        },
+        clear() {
+            spans.length = 0;
+            metrics.length = 0;
+        },
+    };
+}
+export function createOpenTelemetryInstrumentation(options = {}) {
+    const enabled = options.enabled !== false && Boolean(options.tracer ?? options.meter);
+    const onExporterError = options.onExporterError ?? (() => { });
+    const tracer = options.tracer;
+    const meter = options.meter;
+    const providerDuration = meter?.createHistogram("prism.provider.turn.duration_ms", {
+        description: "Provider turn latency",
+        unit: "ms",
+    });
+    const toolDuration = meter?.createHistogram("prism.tool.execution.duration_ms", {
+        description: "Tool execution latency",
+        unit: "ms",
+    });
+    const tokenCounter = meter?.createCounter("prism.provider.tokens", { description: "Provider token usage" });
+    const activeSpans = new Map();
+    const safe = (fn) => {
+        if (!enabled)
+            return;
+        try {
+            fn();
+        }
+        catch (error) {
+            onExporterError(error);
+        }
+    };
+    const endSpan = (key, status, message) => {
+        const span = activeSpans.get(key);
+        if (!span)
+            return;
+        span.setStatus(status, message);
+        span.end();
+        activeSpans.delete(key);
+    };
+    const handleAgentEvent = (event) => {
+        if (!enabled)
+            return;
+        switch (event.type) {
+            case "agent_started":
+                safe(() => {
+                    if (!tracer)
+                        return;
+                    const key = spanKey("agent", event.runId);
+                    activeSpans.set(key, tracer.startSpan("prism.agent.run", {
+                        attributes: {
+                            "prism.session_id": event.sessionId,
+                            "prism.run_id": event.runId,
+                        },
+                    }));
+                });
+                break;
+            case "agent_finished":
+                safe(() => {
+                    endSpan(spanKey("agent", event.runId), "ok");
+                    if (!event.usage || !tokenCounter)
+                        return;
+                    tokenCounter.add(event.usage.inputTokens ?? 0, metricAttrs({ kind: "input", scope: "agent" }));
+                    tokenCounter.add(event.usage.outputTokens ?? 0, metricAttrs({ kind: "output", scope: "agent" }));
+                });
+                break;
+            case "provider_turn_started":
+                safe(() => {
+                    if (!tracer)
+                        return;
+                    const attempt = event.metadata.attempt ?? 1;
+                    const key = spanKey("provider", event.runId, event.turn, attempt);
+                    activeSpans.set(key, tracer.startSpan("prism.provider.turn", {
+                        attributes: {
+                            "prism.session_id": event.sessionId,
+                            "prism.run_id": event.runId,
+                            "prism.turn": event.turn,
+                            "prism.provider_id": event.metadata.providerId,
+                            "prism.model": event.metadata.model.model,
+                            ...(event.metadata.requestId ? { "prism.request_id": event.metadata.requestId } : {}),
+                            ...(event.metadata.attempt ? { "prism.attempt": event.metadata.attempt } : {}),
+                        },
+                    }));
+                });
+                break;
+            case "provider_turn_finished":
+                safe(() => {
+                    const attempt = event.metadata.attempt ?? 1;
+                    const key = spanKey("provider", event.runId, event.turn, attempt);
+                    const span = activeSpans.get(key);
+                    if (span) {
+                        if (event.metadata.latencyMs !== undefined)
+                            span.setAttribute("prism.latency_ms", event.metadata.latencyMs);
+                        if (event.metadata.httpStatus !== undefined)
+                            span.setAttribute("http.status_code", event.metadata.httpStatus);
+                        if (event.error)
+                            span.setStatus("error", event.error.message);
+                        else
+                            span.setStatus("ok");
+                        span.end();
+                        activeSpans.delete(key);
+                    }
+                    providerDuration?.record(event.metadata.latencyMs ?? 0, metricAttrs({
+                        provider_id: event.metadata.providerId,
+                        outcome: event.error ? "error" : "success",
+                    }));
+                    if (!event.usage || !tokenCounter)
+                        return;
+                    tokenCounter.add(event.usage.inputTokens ?? 0, metricAttrs({ provider_id: event.metadata.providerId, kind: "input" }));
+                    tokenCounter.add(event.usage.outputTokens ?? 0, metricAttrs({ provider_id: event.metadata.providerId, kind: "output" }));
+                    if (event.usage.cacheReadTokens) {
+                        tokenCounter.add(event.usage.cacheReadTokens, metricAttrs({ provider_id: event.metadata.providerId, kind: "cache_read" }));
+                    }
+                    if (event.usage.cacheWriteTokens) {
+                        tokenCounter.add(event.usage.cacheWriteTokens, metricAttrs({ provider_id: event.metadata.providerId, kind: "cache_write" }));
+                    }
+                });
+                break;
+            case "tool_execution_started":
+                safe(() => {
+                    if (!tracer)
+                        return;
+                    const key = spanKey("tool", event.call.id);
+                    activeSpans.set(key, tracer.startSpan("prism.tool.execute", {
+                        attributes: {
+                            "prism.session_id": event.sessionId,
+                            "prism.run_id": event.runId,
+                            "prism.tool_call_id": event.call.id,
+                            "prism.tool_name": event.call.name,
+                        },
+                    }));
+                });
+                break;
+            case "tool_execution_finished":
+            case "tool_execution_error":
+            case "tool_execution_blocked":
+                safe(() => {
+                    const toolCallId = event.type === "tool_execution_finished"
+                        ? event.result.toolCallId
+                        : event.type === "tool_execution_error"
+                            ? event.call.id
+                            : event.toolCallId;
+                    const key = spanKey("tool", toolCallId);
+                    const span = activeSpans.get(key);
+                    if (span) {
+                        span.setAttribute("prism.tool_status", event.metadata.status);
+                        span.setAttribute("prism.duration_ms", event.metadata.durationMs);
+                        if (event.type === "tool_execution_finished")
+                            span.setStatus("ok");
+                        else
+                            span.setStatus("error", event.error.message);
+                        span.end();
+                        activeSpans.delete(key);
+                    }
+                    toolDuration?.record(event.metadata.durationMs, metricAttrs({ status: event.metadata.status }));
+                });
+                break;
+            default:
+                break;
+        }
+    };
+    return {
+        enabled,
+        handleAgentEvent,
+        attachSession(session) {
+            if (!enabled)
+                return () => { };
+            const subscription = session.subscribe();
+            const iterator = subscription[Symbol.asyncIterator]();
+            let active = true;
+            void (async () => {
+                try {
+                    while (active) {
+                        const next = await iterator.next();
+                        if (next.done)
+                            break;
+                        handleAgentEvent(next.value);
+                    }
+                }
+                catch {
+                    // subscriber closed
+                }
+            })();
+            return () => {
+                active = false;
+                void iterator.return?.();
+            };
+        },
+    };
+}
+const OTEL_STATUS_OK = 1;
+const OTEL_STATUS_ERROR = 2;
+export function wrapOpenTelemetryApi(tracer, meter) {
+    return {
+        tracer: {
+            startSpan(name, options) {
+                const span = tracer.startSpan(name, options);
+                return {
+                    setAttribute(key, value) {
+                        span.setAttribute(key, value);
+                    },
+                    setStatus(code, message) {
+                        span.setStatus({ code: code === "ok" ? OTEL_STATUS_OK : OTEL_STATUS_ERROR, message });
+                    },
+                    end() {
+                        span.end();
+                    },
+                };
+            },
+        },
+        meter: meter
+            ? {
+                createCounter(name, options) {
+                    const counter = meter.createCounter(name, options);
+                    return { add: (value, attributes) => counter.add(value, attributes) };
+                },
+                createHistogram(name, options) {
+                    const histogram = meter.createHistogram(name, options);
+                    return { record: (value, attributes) => histogram.record(value, attributes) };
+                },
+            }
+            : undefined,
+    };
+}
+//# sourceMappingURL=instrumentation.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@arnilo/prism-observability-opentelemetry",
+  "version": "0.0.4",
+  "description": "Optional OpenTelemetry adapter for Prism agent events.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/**/*.map",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/__tests__/*.test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@arnilo/prism": "0.0.4"
+  },
+  "devDependencies": {
+    "@arnilo/prism": "file:../..",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashiqrniloy/prism.git",
+    "directory": "packages/observability-opentelemetry"
+  },
+  "bugs": {
+    "url": "https://github.com/ashiqrniloy/prism/issues"
+  },
+  "homepage": "https://github.com/ashiqrniloy/prism/tree/main/packages/observability-opentelemetry#readme",
+  "keywords": [
+    "prism",
+    "opentelemetry",
+    "observability",
+    "tracing",
+    "metrics",
+    "agent"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}