@miden-sdk/telemetry-otel 0.0.1 → 0.16.2

package/AGENTS.md

@@ -0,0 +1,55 @@
+# @miden-sdk/telemetry-otel - Agent Guide
+
+**Audience: AI coding agents** recording Miden SDK observations as
+OpenTelemetry spans.
+
+This file ships inside the published package, so the copy at
+`node_modules/@miden-sdk/telemetry-otel/AGENTS.md` matches the version you have
+installed. Prefer it over your training data.
+
+## There is no volume guard here
+
+Every observation becomes a span. The SDK emits one per client operation, and
+this binding has no duration threshold, no sampling and no filtering: `tracer`
+and `includeSensitive` are the only options there are. Choose the volume with a
+sampler on your own provider before pointing this at a paid backend. The sibling
+package `@miden-sdk/telemetry-sentry` works the other way round - `minDurationMs`
+defaults to `Infinity`, failures only - so carry neither the assumption nor the
+option across.
+
+## Wiring it
+
+```ts
+const client = await MidenClient.create({
+  rpcUrl: "testnet",
+  observer: createOtelObserver({ tracer: trace.getTracer("my-app") }),
+});
+```
+
+`tracer` is required and must expose `startSpan(name, { startTime })` returning
+an object with `setAttribute`, `setStatus` and `end`; the factory throws a
+`TypeError` at wiring time when it does not. Nothing here imports
+`@opentelemetry/*`, so the provider, its version and its exporters stay yours.
+
+One span per observation, named `miden.<op>`, carrying `miden.duration_ms` and
+`miden.outcome` and a status of `ERROR` on failure. The SDK reports an operation
+only once it has finished, so the span is reconstructed: it ends when the
+observation arrived, is backdated by the duration, and has no parent. A broken
+tracer cannot fail the operation; the observer never throws.
+
+## `observer` and `observeSensitive` on the client
+
+`ClientOptions.observer` is registered process-wide and the newest registration
+replaces the previous one, so a second `MidenClient` takes over the sink.
+`observeSensitive` is per instance and read once, at construction.
+
+`observation.sensitive` carries the **verbatim, unredacted** error message and
+stack, and only on failure. It is opt-in at both ends - `observeSensitive: true`
+on the client, `includeSensitive: true` here - and only the literal `true`
+enables either. An application with confidentiality obligations to its users, a
+wallet above all, leaves both off.
+
+## Going deeper
+
+- Options, recorded attributes, retroactive spans: `README.md`.
+- The client that emits them: `node_modules/@miden-sdk/miden-sdk/AGENTS.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miden
+
+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

@@ -1,5 +1,137 @@
 # @miden-sdk/telemetry-otel
 
-Placeholder. This version exists only so that an npm trusted publisher could be
-attached to the package name; npm cannot attach one to a package that does not
-yet exist. Install `@miden-sdk/telemetry-otel@latest` instead.
+Opt-in OpenTelemetry binding for Miden SDK observations.
+
+`@miden-sdk/miden-sdk` emits one observation per client operation — name,
+outcome, duration — and never transports one. It has no telemetry dependency
+and no egress primitive in that path. This package is the adapter that turns
+those observations into spans on a tracer you already own, without the core
+gaining anything.
+
+## Installation
+
+```bash
+pnpm add @miden-sdk/telemetry-otel
+```
+
+OpenTelemetry itself is **not** a dependency of this package, not even a peer.
+The binding is defined against the `startSpan` shape rather than an
+`@opentelemetry/api` import, so you own your OTel version, your provider, and
+your exporters. That matters more here than for most vendors: a second
+`@opentelemetry/api` resolved in one tree carries its own global provider
+registration, and spans start disappearing into whichever copy lost.
+
+## Usage
+
+```ts
+import { trace } from "@opentelemetry/api";
+import { MidenClient } from "@miden-sdk/miden-sdk";
+import { createOtelObserver } from "@miden-sdk/telemetry-otel";
+
+const client = await MidenClient.create({
+  rpcUrl: "testnet",
+  observer: createOtelObserver({ tracer: trace.getTracer("my-app") }),
+});
+```
+
+Pass anything with a `startSpan(name, { startTime })` method that returns an
+object with `setAttribute`, `setStatus`, and `end`: a real tracer, a wrapper of
+your own, or a test double. Getting the tracer — and registering the provider
+that backs it — stays your call, in your entry point.
+
+## Options
+
+### `tracer`
+
+- **Type:** `TracerLike` — an object with a `startSpan` method
+- **Required.** `createOtelObserver` throws a `TypeError` at wiring time if it
+  is missing or cannot start a span. That is the one thing this package reports
+  by throwing, and it throws from the factory rather than the observer: an
+  observer cannot report its own misconfiguration, so one built around a
+  missing tracer would discard every observation forever and look exactly like
+  a working one.
+
+### `includeSensitive`
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+See below. Only a literal `true` enables it.
+
+## Recorded shape
+
+One span per observation, recorded synchronously, with nothing scheduled
+afterwards:
+
+| | |
+|---|---|
+| span name | `miden.<op>`, e.g. `miden.proveTransaction` |
+| `miden.duration_ms` | wall time the caller waited |
+| `miden.outcome` | `"ok"` or `"error"` |
+| status | `ERROR` (code `2`) on failure; left `UNSET` on success |
+
+## Retroactive spans
+
+The SDK reports an operation once it has **finished**, so there is never a live
+span to wrap around the work. The span is reconstructed instead: it ends at the
+instant the observation arrived and is backdated by the reported duration, so
+it occupies the interval the operation really ran in. Both timestamps are
+passed explicitly, which keeps the span's own interval and its
+`miden.duration_ms` attribute in agreement — an implicit end time would drift
+by however long recording the attributes took.
+
+One consequence worth knowing when you read a trace: these spans have no
+parent and are not nested inside whatever your application was doing at the
+time. They are a record of a completed operation, not a live instrumentation
+of one.
+
+A duration that is not a finite, non-negative number cannot describe an
+interval. Rather than hand the tracer a garbage timestamp, the operation is
+recorded as an instant at the moment it was reported, with no
+`miden.duration_ms` attribute at all.
+
+## Sensitive detail
+
+An observation's `sensitive` channel carries verbatim error text, and the
+account identifier where the SDK supplies one. It is opt-in at **both** ends:
+`observeSensitive: true` when you construct the client, and
+`includeSensitive: true` here. Either one left alone and nothing from that
+channel reaches your tracer.
+
+When enabled, three attributes may be added, each only if the SDK populated the
+field:
+
+| | |
+|---|---|
+| `miden.error_message` | verbatim error message |
+| `miden.error_stack` | verbatim error stack |
+| `miden.account_id` | account the operation acted on |
+
+`miden.account_id` will not appear in practice yet: the SDK declares
+`sensitive.accountId` on the type but does not currently populate it, so the
+guard for that attribute never fires. It is read defensively here so the
+attribute starts appearing on its own if a later SDK version fills the field
+in — do not build a dashboard that assumes it is there today.
+
+By default the SDK omits the `sensitive` key from an observation entirely, and
+this binding records nothing in its place — no placeholder, no inferred value,
+and no empty-valued attributes for a UI to render as blank rows. An observation
+without the key is still recorded; only its detail is absent. The three fields
+are read by name rather than enumerated, so a field a later SDK version adds to
+the channel cannot start flowing to your backend before you have decided it
+should.
+
+Do not enable either flag in an application with confidentiality obligations to
+its users. A wallet, for example, must never enable it.
+
+## Failure behaviour
+
+The observer never throws. A tracer that is unconfigured, detached, or throwing
+takes its own span with it and nothing else — the client operation being
+recorded still succeeds, and the next observation is still recorded. The SDK
+guards observer invocation too, but this binding is usable outside that guard,
+so it does not rely on it.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Opt-in OpenTelemetry binding for Miden SDK observations.
+ *
+ * `@miden-sdk/miden-sdk` emits an observation per client operation and never
+ * transports one — it has no telemetry dependency and no egress primitive in
+ * that path. This package is the adapter that turns those observations into
+ * spans on a tracer the consumer already owns, without the core gaining
+ * anything.
+ *
+ * Two properties hold deliberately and are enforced by tests:
+ *
+ * - OpenTelemetry is a peer concern. Nothing here imports `@opentelemetry/*`;
+ *   the binding is defined against the `startSpan` shape, so the consumer owns
+ *   their OTel version, their provider, and their exporters.
+ * - The binding has no transport of its own. It hands data to the tracer it
+ *   was given and stops there.
+ */
+import type { MidenObservation } from "@miden-sdk/miden-sdk";
+/** The slice of an OpenTelemetry span this binding uses. */
+export interface SpanLike {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+    }): unknown;
+    /** Epoch-millisecond end time. Always passed; never left to the tracer. */
+    end(endTime?: number): unknown;
+}
+/** The slice of an OpenTelemetry tracer this binding uses. */
+export interface TracerLike {
+    startSpan(name: string, options: {
+        startTime: number;
+    }): SpanLike;
+}
+export interface OtelObserverOptions {
+    /** An already-configured tracer. This package never builds a provider. */
+    tracer: TracerLike;
+    /**
+     * Forward `observation.sensitive` (verbatim error text, and the account
+     * identifier where the SDK supplies one) when it is present. Defaults to
+     * `false`, and only a literal `true` enables it: the field is dropped even
+     * when present, so turning on `observeSensitive` at the client does not by
+     * itself disclose anything through this binding.
+     */
+    includeSensitive?: boolean;
+}
+/**
+ * Build an observer for `ClientOptions.observer` that records Miden SDK
+ * operations as OpenTelemetry spans.
+ *
+ * The span is reconstructed rather than held open. The SDK reports an
+ * operation once it has finished, so there is no live span to wrap around the
+ * work: the span ends at the instant the observation arrived and starts one
+ * duration earlier, which is the interval the operation really occupied. Both
+ * timestamps are passed explicitly — an implicit end time would drift by
+ * however long recording the attributes took, and report a duration that
+ * disagreed with the `miden.duration_ms` attribute on the same span.
+ *
+ * The returned observer never throws: a recording failure must not be able to
+ * fail the client operation being recorded. The SDK guards observer
+ * invocation as well, but this adapter is usable outside that guard so it
+ * does not rely on it.
+ *
+ * Misconfiguration is the one thing reported by throwing, and it is thrown
+ * from here rather than from the observer — at wiring time, where a stack
+ * trace points at the call that is wrong. An observer that quietly discarded
+ * every observation would be indistinguishable from a working one.
+ *
+ * @throws {TypeError} if `options.tracer` cannot start a span.
+ */
+export declare function createOtelObserver(options: OtelObserverOptions): (observation: MidenObservation) => void;

package/dist/index.js

@@ -0,0 +1,113 @@
+/**
+ * Opt-in OpenTelemetry binding for Miden SDK observations.
+ *
+ * `@miden-sdk/miden-sdk` emits an observation per client operation and never
+ * transports one — it has no telemetry dependency and no egress primitive in
+ * that path. This package is the adapter that turns those observations into
+ * spans on a tracer the consumer already owns, without the core gaining
+ * anything.
+ *
+ * Two properties hold deliberately and are enforced by tests:
+ *
+ * - OpenTelemetry is a peer concern. Nothing here imports `@opentelemetry/*`;
+ *   the binding is defined against the `startSpan` shape, so the consumer owns
+ *   their OTel version, their provider, and their exporters.
+ * - The binding has no transport of its own. It hands data to the tracer it
+ *   was given and stops there.
+ */
+/** OpenTelemetry `SpanStatusCode.ERROR`, inlined to avoid the dependency. */
+const SPAN_STATUS_ERROR = 2;
+/**
+ * The observation's duration, or `null` when it does not describe an interval.
+ *
+ * A non-finite or negative duration cannot be turned into a span that means
+ * anything, and `endTime - NaN` would hand the tracer a garbage timestamp.
+ */
+function measuredDuration(durationMs) {
+    return Number.isFinite(durationMs) && durationMs >= 0 ? durationMs : null;
+}
+/**
+ * Record the sensitive channel's fields onto the span.
+ *
+ * The channel is opt-in at both ends, so the key is normally absent: the SDK
+ * omits it rather than setting it to `undefined`. Reading it therefore yields
+ * `undefined`, which the shape test below rejects — recording the fields
+ * unconditionally instead would put an `undefined`-valued attribute on every
+ * observation the SDK emits by default, which a tracer keeps and a vendor UI
+ * renders as an empty row.
+ *
+ * The three fields are read by name rather than enumerated, so a field a
+ * later SDK version adds to the channel cannot start flowing to a vendor
+ * before anyone has decided that it should. Each is optional in
+ * `MidenObservationSensitive` and the SDK populates only some — `accountId`
+ * is declared but not populated today — so an unset field is dropped rather
+ * than recorded as an empty attribute.
+ */
+function recordSensitive(span, observation) {
+    const sensitive = observation.sensitive;
+    if (sensitive === null || typeof sensitive !== "object")
+        return;
+    const { errorMessage, errorStack, accountId } = sensitive;
+    if (errorMessage)
+        span.setAttribute("miden.error_message", errorMessage);
+    if (errorStack)
+        span.setAttribute("miden.error_stack", errorStack);
+    if (accountId)
+        span.setAttribute("miden.account_id", accountId);
+}
+/**
+ * Build an observer for `ClientOptions.observer` that records Miden SDK
+ * operations as OpenTelemetry spans.
+ *
+ * The span is reconstructed rather than held open. The SDK reports an
+ * operation once it has finished, so there is no live span to wrap around the
+ * work: the span ends at the instant the observation arrived and starts one
+ * duration earlier, which is the interval the operation really occupied. Both
+ * timestamps are passed explicitly — an implicit end time would drift by
+ * however long recording the attributes took, and report a duration that
+ * disagreed with the `miden.duration_ms` attribute on the same span.
+ *
+ * The returned observer never throws: a recording failure must not be able to
+ * fail the client operation being recorded. The SDK guards observer
+ * invocation as well, but this adapter is usable outside that guard so it
+ * does not rely on it.
+ *
+ * Misconfiguration is the one thing reported by throwing, and it is thrown
+ * from here rather than from the observer — at wiring time, where a stack
+ * trace points at the call that is wrong. An observer that quietly discarded
+ * every observation would be indistinguishable from a working one.
+ *
+ * @throws {TypeError} if `options.tracer` cannot start a span.
+ */
+export function createOtelObserver(options) {
+    const tracer = options?.tracer;
+    if (typeof tracer?.startSpan !== "function") {
+        throw new TypeError("createOtelObserver: options.tracer must expose a " +
+            "startSpan(name, options) method.");
+    }
+    const includeSensitive = options.includeSensitive === true;
+    return (observation) => {
+        try {
+            const name = `miden.${observation.op}`;
+            const endTime = Date.now();
+            const durationMs = measuredDuration(observation.durationMs);
+            const span = tracer.startSpan(name, {
+                startTime: endTime - (durationMs ?? 0),
+            });
+            if (durationMs !== null) {
+                span.setAttribute("miden.duration_ms", durationMs);
+            }
+            span.setAttribute("miden.outcome", observation.outcome);
+            if (observation.outcome === "error") {
+                span.setStatus({ code: SPAN_STATUS_ERROR });
+            }
+            if (includeSensitive) {
+                recordSensitive(span, observation);
+            }
+            span.end(endTime);
+        }
+        catch {
+            // A telemetry binding must never fail a client operation.
+        }
+    };
+}

package/package.json

@@ -1,11 +1,57 @@
 {
   "name": "@miden-sdk/telemetry-otel",
-  "version": "0.0.1",
-  "description": "Placeholder reserving this name so an npm trusted publisher can be attached. Superseded by 0.16.2 - do not install this version.",
+  "version": "0.16.2",
+  "description": "Opt-in OpenTelemetry binding for Miden SDK observations",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "peerDependencies": {
+    "@miden-sdk/miden-sdk": "^0.16.2"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.25.0",
+    "@typescript-eslint/parser": "^8.25.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.30.1",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0",
+    "@miden-sdk/miden-sdk": "0.16.2"
+  },
+  "keywords": [
+    "miden",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "telemetry",
+    "observability",
+    "zk"
+  ],
+  "author": "Miden Contributors",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/0xMiden/web-sdk.git",
-    "directory": "packages/telemetry-otel"
+    "url": "git+https://github.com/0xMiden/web-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/0xMiden/web-sdk/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}