@idos-network/instrumentation 0.0.0-stage → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 idOS Network
+
+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,3 +1,125 @@
-# Temporary Holding Version
+# `@idos-network/instrumentation`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenTelemetry instrumentation for the idOS JavaScript SDK, modelled on
+[`@opentelemetry/instrumentation-pg`](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-pg).
+
+Patches the SDK's public methods so that every idOS operation shows up as a span,
+with the kwil round-trips it triggers nested underneath.
+
+## Install
+
+```sh
+pnpm add @idos-network/instrumentation @opentelemetry/api
+```
+
+## Setup
+
+Every target is a class method, which lives on a prototype or a constructor —
+ordinary mutable objects. So patching needs no module loader hook: import the
+idOS module and hand its namespace over, once per package you use.
+
+```ts
+import * as issuer from "@idos-network/issuer";
+import * as kwil from "@idos-network/kwil-infra";
+import { IdosInstrumentation } from "@idos-network/instrumentation";
+
+const instrumentation = new IdosInstrumentation();
+instrumentation.setTracerProvider(provider); // omit to use the global provider
+
+instrumentation.patchModuleExports("@idos-network/issuer", issuer);
+instrumentation.patchModuleExports("@idos-network/kwil-infra", kwil);
+```
+
+This is the same call in Node and in the browser, and it survives bundling.
+Patching a prototype also applies to instances that already exist, so there is
+no race with `idOSIssuer.init()`.
+
+In the browser, `new IdosInstrumentation({ requireParentSpan: true })` is worth
+it: without it, an idOS call made outside a user-interaction span produces a
+single-span orphan trace.
+
+### Automatic patching in Node (optional)
+
+`InstrumentationBase` can also patch on import, with no app code at all. The
+idOS packages are ESM-only, so that needs Node's loader hook — and two separate
+things have to happen before the app imports any idOS package:
+
+```ts
+// telemetry.mjs
+import { register } from "node:module";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { IdosInstrumentation } from "@idos-network/instrumentation";
+
+register("@opentelemetry/instrumentation/hook.mjs", import.meta.url); // installs the loader
+registerInstrumentations({ instrumentations: [new IdosInstrumentation()] }); // says what to patch
+```
+
+```sh
+node --import ./telemetry.mjs ./app.mjs
+```
+
+Worth it if you already launch with `--import`; otherwise prefer
+`patchModuleExports`, which has no launch-flag to forget in a Dockerfile.
+
+Two things that look like they should work and do not:
+
+- `--import @opentelemetry/instrumentation/hook.mjs` on its own. `hook.mjs` is a
+  loader module exporting `resolve`/`load`/`initialize`, so importing it
+  registers nothing — it has to be passed to `register()`.
+- `registerInstrumentations` called from inside your app. By then the idOS
+  modules are loaded and their namespaces are sealed.
+
+## What gets traced
+
+| Module                     | Spans                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `@idos-network/kwil-infra` | `KwilActionClient.call` / `.execute` — the idOS equivalent of `pg.Client.query` — and `.waitForTx` |
+| `@idos-network/client`     | `idOSClientConfiguration` / `Idle` / `WithUserSigner` / `LoggedIn` methods                         |
+| `@idos-network/issuer`     | `idOSIssuer` methods and `idOSIssuer.init`                                                         |
+| `@idos-network/consumer`   | `idOSConsumer` methods and `idOSConsumer.init`                                                     |
+
+The enclave is not traced: it is local key material and iframe/MPC work, not
+where request latency lives. `verifyCredential` is covered as
+`idOSConsumer.verifyCredential`, which delegates straight to it.
+
+Kwil spans carry `db.system.name=kwil`, `db.namespace=main` and
+`db.operation.name=<action>`; `execute` also records `idos.kwil.tx_hash`. Every
+span carries `idos.sdk.package`, `idos.sdk.class` and `idos.sdk.method`.
+
+A synchronous `execute` broadcasts the transaction and then polls until it is
+mined, which is usually where its latency goes. The wait is its own
+`idos.kwil.waitForTx` child span, carrying `idos.kwil.tx_hash`, so broadcast time
+and confirmation time show up separately. When it fails, `error.type` tells the
+two outcomes apart: `KwilTxFailedError` (the chain rejected the transaction)
+versus `KwilTxPollTimeoutError` (it was never mined inside the deadline).
+
+The HTTP calls underneath are _not_ covered here — use
+`@opentelemetry/instrumentation-undici` (Node) or
+`@opentelemetry/instrumentation-fetch` (browser) alongside this package, and
+they will nest under the spans above.
+
+## No arguments or return values are recorded
+
+idOS SDK arguments and return values are credentials, wallet identifiers and
+encryption keys. Nothing derived from them is put on a span by default — only
+fixed identifiers such as the kwil action name. If you need more, opt in per
+deployment with `requestHook` / `responseHook`:
+
+```ts
+new IdosInstrumentation({
+  requestHook: (span, { className, methodName, args }) => {
+    if (className === "idOSConsumer" && methodName === "getCredentialSharedFromIDOS") {
+      span.setAttribute("idos.credential.id", String(args[0]));
+    }
+  },
+});
+```
+
+## Config
+
+| Option              | Default | Meaning                                              |
+| ------------------- | ------- | ---------------------------------------------------- |
+| `enabled`           | `true`  | Whether the instrumentation patches on registration. |
+| `requireParentSpan` | `false` | Only create spans when one is already active.        |
+| `requestHook`       | –       | Add attributes from the call arguments.              |
+| `responseHook`      | –       | Add attributes from the resolved value.              |

package/dist/index.d.mts

@@ -0,0 +1,144 @@
+import { Attributes, Span, SpanKind } from "@opentelemetry/api";
+import { InstrumentationBase, InstrumentationConfig, InstrumentationNodeModuleDefinition } from "@opentelemetry/instrumentation";
+//#region src/types.d.ts
+/** Data about the call that is about to be made, passed to {@link IdosInstrumentationConfig.requestHook}. */
+type IdosRequestHookInformation = {
+  /** Module the traced method was exported from, e.g. `@idos-network/issuer`. */
+  moduleName: string;
+  /** Class the method lives on, or `undefined` for a bare function export. */
+  className: string | undefined;
+  /** Method name, e.g. `createUserProfile`. */
+  methodName: string;
+  /** The arguments the method was called with. May contain personal data — see README. */
+  args: readonly unknown[];
+};
+/** Data about the completed call, passed to {@link IdosInstrumentationConfig.responseHook}. */
+type IdosResponseHookInformation = {
+  moduleName: string;
+  className: string | undefined;
+  methodName: string;
+  /** The resolved return value. May contain personal data — see README. */
+  result: unknown;
+};
+type IdosInstrumentationRequestHook = (span: Span, info: IdosRequestHookInformation) => void;
+type IdosInstrumentationResponseHook = (span: Span, info: IdosResponseHookInformation) => void;
+interface IdosInstrumentationConfig extends InstrumentationConfig {
+  /**
+   * Hook for adding custom attributes from the call arguments, or renaming the span.
+   *
+   * Nothing derived from arguments is recorded by default: idOS SDK arguments carry
+   * credentials, wallet identifiers and encryption keys. Opt in here, per deployment.
+   *
+   * @default undefined
+   */
+  requestHook?: IdosInstrumentationRequestHook;
+  /**
+   * Hook for adding custom attributes from the resolved return value.
+   *
+   * Same caveat as {@link requestHook}: return values carry credential contents.
+   *
+   * @default undefined
+   */
+  responseHook?: IdosInstrumentationResponseHook;
+  /**
+   * If true, spans are only created when there is already an active span.
+   *
+   * Useful in the browser, where an idOS call outside a user-interaction span
+   * would otherwise produce a single-span orphan trace.
+   *
+   * @default false
+   */
+  requireParentSpan?: boolean;
+}
+//#endregion
+//#region src/instrumentation.d.ts
+/**
+ * Traces the idOS SDK: every public method of `@idos-network/client`,
+ * `/consumer`, `/issuer`, the enclave providers, `verifyCredential`, and the
+ * kwil `call`/`execute` round-trips they all bottom out in.
+ */
+export declare class IdosInstrumentation extends InstrumentationBase<IdosInstrumentationConfig> {
+  constructor(config?: IdosInstrumentationConfig);
+  protected init(): InstrumentationNodeModuleDefinition[];
+  /**
+   * Patch a module namespace you already imported.
+   *
+   * The automatic hooking in {@link InstrumentationBase} needs Node's module
+   * loader hook (`import-in-the-middle`), which has to be installed with
+   * `module.register()` before the import — and does not exist at all in a
+   * browser or a bundled app. This is the alternative everywhere: import the
+   * idOS module and hand its namespace over. Exports the module does not have
+   * are skipped.
+   */
+  patchModuleExports(moduleName: string, moduleExports: unknown): void;
+  /** Reverse of {@link patchModuleExports}. */
+  unpatchModuleExports(moduleName: string, moduleExports: unknown): void;
+  private findTarget;
+  private applyPatch;
+  private removePatch;
+  /** Resolves every target method to the object that owns it, skipping what is absent. */
+  private eachMember;
+  private traced;
+  private endSpan;
+  private failSpan;
+}
+//#endregion
+//#region src/semconv.d.ts
+/**
+ * Attributes emitted by this instrumentation that have no stable OpenTelemetry
+ * semantic convention. Stable ones (`db.*`, `error.type`) are imported from
+ * `@opentelemetry/semantic-conventions` at the call site.
+ */
+/** Package the traced method lives in, e.g. `@idos-network/issuer`. */
+export declare const ATTR_IDOS_SDK_PACKAGE = "idos.sdk.package";
+/** Class the traced method lives on, e.g. `idOSIssuer`. */
+export declare const ATTR_IDOS_SDK_CLASS = "idos.sdk.class";
+/** Traced method name, e.g. `createUserProfile`. */
+export declare const ATTR_IDOS_SDK_METHOD = "idos.sdk.method";
+/** `db.system.name` value for the idOS kwil network. */
+export declare const IDOS_KWIL_SYSTEM = "kwil";
+/** Kwil namespace every idOS action runs against. */
+export declare const IDOS_KWIL_NAMESPACE = "main";
+/** Transaction hash returned by a kwil `execute`. */
+export declare const ATTR_IDOS_KWIL_TX_HASH = "idos.kwil.tx_hash";
+/** Whether a kwil `execute` waited for the transaction to be mined. */
+export declare const ATTR_IDOS_KWIL_SYNCHRONOUS = "idos.kwil.synchronous";
+//#endregion
+//#region src/targets.d.ts
+/** A method to wrap. A bare string uses every default. */
+type MethodTarget = {
+  name: string;
+  /** Span name. Defaults to `<Class>.<method>`, or `<method>` for a function export. */
+  spanName?: (args: readonly unknown[]) => string;
+  /** Attributes derived from the arguments. Must not emit personal data. */
+  attributes?: (args: readonly unknown[]) => Attributes;
+  /** Attributes derived from the resolved value. Must not emit personal data. */
+  responseAttributes?: (result: unknown) => Attributes;
+  /** @default SpanKind.INTERNAL */
+  kind?: SpanKind;
+};
+type ClassTarget = {
+  /** Name of the class as exported by the module. */
+  className: string;
+  /** Instance methods, wrapped on the prototype. */
+  methods: (string | MethodTarget)[];
+  /** Static methods, wrapped on the constructor (`init`-style factories). */
+  staticMethods?: (string | MethodTarget)[];
+};
+type ModuleTarget = {
+  /** Module specifier. */
+  name: string;
+  supportedVersions: string[];
+  /**
+   * Only classes. Every method lives on a prototype or a constructor, both of
+   * which are ordinary mutable objects — that is what lets
+   * {@link IdosInstrumentation.patchModuleExports} work without a loader hook.
+   * A bare function export would sit on the sealed module namespace instead,
+   * and could only be reached via `import-in-the-middle`.
+   */
+  classes: ClassTarget[];
+};
+export declare const TARGETS: ModuleTarget[];
+//#endregion
+export type { ClassTarget, IdosInstrumentationConfig, IdosInstrumentationRequestHook, IdosInstrumentationResponseHook, IdosRequestHookInformation, IdosResponseHookInformation, MethodTarget, ModuleTarget };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/instrumentation.ts","../src/semconv.ts","../src/targets.ts"],"mappings":";;;;KAIY;;EAEV;;EAEA;;EAEA;;EAEA;;;KAIU;EACV;EACA;EACA;;EAEA;;KAGU,kCAAkC,MAAM,MAAM,MAAM;KAEpD,mCACV,MAAM,MACN,MAAM;UAGS,kCAAkC;;;;;;;;;EASjD,cAAc;;;;;;;;EASd,eAAe;;;;;;;;;EAUf;;;;;;;;;qBChCW,4BAA4B,oBAAoB;EAC3D,YAAY,SAAQ;YAIV,QAAQ;;;;;;;;;;;EAsBlB,mBAAmB,oBAAoB;;EAMvC,qBAAqB,oBAAoB;UAKjC;UAMA;UAUA;;UAQA;UAmDA;UA+DA;UAmBA;;;;;;;;;;qBCvNG;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;;;KCRD;EACV;;EAEA,YAAY;;EAEZ,cAAc,6BAA6B;;EAE3C,sBAAsB,oBAAoB;;EAE1C,OAAO;;KAGG;;EAEV;;EAEA,mBAAmB;;EAEnB,0BAA0B;;KAGhB;;EAEV;EACA;;;;;;;;EAQA,SAAS;;qBAyDE,SAAS"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{SpanKind as e,SpanStatusCode as t,trace as n}from"@opentelemetry/api";import{InstrumentationBase as r,InstrumentationNodeModuleDefinition as i,isWrapped as a}from"@opentelemetry/instrumentation";import{ATTR_DB_NAMESPACE as o,ATTR_DB_OPERATION_NAME as s,ATTR_DB_SYSTEM_NAME as c,ATTR_ERROR_TYPE as l}from"@opentelemetry/semantic-conventions";const u=`idos.sdk.package`,d=`idos.sdk.class`,f=`idos.sdk.method`,p=`kwil`,m=`main`,h=`idos.kwil.tx_hash`,g=`idos.kwil.synchronous`,_=[`>=2.0.0 <3`],v=e=>{let t=e[0];return{[c]:p,[o]:m,...typeof t?.name==`string`?{[s]:t.name}:{}}},y=e=>t=>{let n=t[0];return typeof n?.name==`string`?`idos.kwil.${e} ${n.name}`:`idos.kwil.${e}`},b=[{name:`@idos-network/kwil-infra`,supportedVersions:_,classes:[{className:`KwilActionClient`,methods:[{name:`call`,kind:e.CLIENT,spanName:y(`call`),attributes:v},{name:`execute`,kind:e.CLIENT,spanName:y(`execute`),attributes:e=>({...v(e),[g]:e[2]===void 0||!!e[2]}),responseAttributes:e=>typeof e==`string`?{[h]:e}:{}},{name:`waitForTx`,kind:e.CLIENT,spanName:()=>`idos.kwil.waitForTx`,attributes:e=>({[c]:p,[o]:m,...typeof e[0]==`string`?{[h]:e[0]}:{}})}]}]},{name:`@idos-network/client`,supportedVersions:_,classes:[{className:`idOSClientConfiguration`,methods:[`createClient`]},{className:`idOSClientIdle`,methods:[`addressHasProfile`,`withUserSigner`,`logOut`],staticMethods:[`fromConfig`]},{className:`idOSClientWithUserSigner`,methods:[`hasProfile`,`createUserEncryptionProfile`,`logIn`,`logOut`]},{className:`idOSClientLoggedIn`,methods:[`requestDWGMessage`,`createCredential`,`removeCredential`,`getCredentialById`,`shareCredential`,`getAllCredentials`,`getAccessGrantsOwned`,`getAttributes`,`createAttribute`,`getCredentialContentSha256Hash`,`getCredentialContent`,`getCredentialWithEncryptedContent`,`getCredentialSharedContent`,`getGrants`,`getGrantsCount`,`getCredentialShared`,`revokeAccessGrant`,`addWallet`,`addWallets`,`getWallets`,`removeWallet`,`removeWallets`,`filterCredentials`,`requestAccessGrant`,`logOut`]}]},{name:`@idos-network/issuer`,supportedVersions:_,classes:[{className:`idOSIssuer`,staticMethods:[`init`],methods:[`hasProfile`,`createUserProfile`,`upsertWalletAsInserter`,`createUser`,`getUser`,`requestDelegatedWriteGrantMessage`,`createCredentialByDelegatedWriteGrant`,`editCredentialAsIssuer`,`getCredentialIdByContentHash`,`getCredentialShared`]}]},{name:`@idos-network/consumer`,supportedVersions:_,classes:[{className:`idOSConsumer`,staticMethods:[`init`],methods:[`getCredentialSharedFromIDOS`,`getCredentialSharedContentDecrypted`,`rescindSharedCredential`,`getGrantsCount`,`getAccessGrantsForCredential`,`getCredentialsSharedByUser`,`getAccessGrants`,`verifyCredential`]}]}],x=e=>typeof e?.then==`function`;var S=class extends r{constructor(e={}){super(`@idos-network/instrumentation`,`2.0.1`,e)}init(){return b.map(e=>new i(e.name,e.supportedVersions,t=>this.applyPatch(e.name,e,t),t=>this.removePatch(e.name,e,t)))}patchModuleExports(e,t){let n=this.findTarget(e);n&&this.applyPatch(e,n,t)}unpatchModuleExports(e,t){let n=this.findTarget(e);n&&this.removePatch(e,n,t)}findTarget(e){let t=b.find(t=>t.name===e);return t||this._diag.warn(`No instrumentation targets known for "${e}"`),t}applyPatch(e,t,n){return this.eachMember(e,t,n,(t,n,r,i)=>{a(t[n])&&this._unwrap(t,n),this._wrap(t,n,t=>this.traced(t,e,i,r))}),n}removePatch(e,t,n){return this.eachMember(e,t,n,(e,t)=>{a(e[t])&&this._unwrap(e,t)}),n}eachMember(e,t,n,r){if(typeof n!=`object`||!n)return;let i=n,a=(t,n,i)=>{let a=typeof n==`string`?{name:n}:n,o=`${i?`${i}.`:``}${a.name}`;if(typeof t[a.name]!=`function`){this._diag.debug(`${e}: ${o} is not a function, skipping`);return}try{r(t,a.name,a,i)}catch(t){this._diag.warn(`${e}: could not patch ${o}: ${String(t)}`)}};for(let n of t.classes){let t=i[n.className];if(typeof t!=`function`){this._diag.debug(`${e}: class ${n.className} not exported, skipping`);continue}let r=t.prototype;if(typeof r==`object`&&r)for(let e of n.methods)a(r,e,n.className);for(let e of n.staticMethods??[])a(t,e,n.className)}}traced(t,r,i,a){let o=this,s=`${i?`${i}.`:``}${a.name}`;return function(...c){let l=o.getConfig();if(l.requireParentSpan&&n.getActiveSpan()===void 0)return t.apply(this,c);let p={[u]:r,[f]:a.name,...i?{[d]:i}:{},...a.attributes?.(c)},m=a.spanName?.(c)??s,h={kind:a.kind??e.INTERNAL,attributes:p};return o.tracer.startActiveSpan(m,h,e=>{o._runSpanCustomizationHook(l.requestHook,`requestHook`,e,{moduleName:r,className:i,methodName:a.name,args:c});let n;try{n=t.apply(this,c)}catch(t){throw o.failSpan(e,t),t}return x(n)?n.then(t=>(o.endSpan(e,r,i,a,t),t),t=>{throw o.failSpan(e,t),t}):(o.endSpan(e,r,i,a,n),n)})}}endSpan(e,t,n,r,i){let a=r.responseAttributes?.(i);a&&e.setAttributes(a),this._runSpanCustomizationHook(this.getConfig().responseHook,`responseHook`,e,{moduleName:t,className:n,methodName:r.name,result:i}),e.end()}failSpan(e,n){n instanceof Error?(e.recordException(n),e.setAttribute(l,n.name),e.setStatus({code:t.ERROR,message:n.message})):(e.setAttribute(l,typeof n),e.setStatus({code:t.ERROR,message:String(n)})),e.end()}};export{g as ATTR_IDOS_KWIL_SYNCHRONOUS,h as ATTR_IDOS_KWIL_TX_HASH,d as ATTR_IDOS_SDK_CLASS,f as ATTR_IDOS_SDK_METHOD,u as ATTR_IDOS_SDK_PACKAGE,m as IDOS_KWIL_NAMESPACE,p as IDOS_KWIL_SYSTEM,S as IdosInstrumentation,b as TARGETS};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/semconv.ts","../src/targets.ts","../src/version.ts","../src/instrumentation.ts"],"sourcesContent":["/**\n * Attributes emitted by this instrumentation that have no stable OpenTelemetry\n * semantic convention. Stable ones (`db.*`, `error.type`) are imported from\n * `@opentelemetry/semantic-conventions` at the call site.\n */\n\n/** Package the traced method lives in, e.g. `@idos-network/issuer`. */\nexport const ATTR_IDOS_SDK_PACKAGE = \"idos.sdk.package\";\n\n/** Class the traced method lives on, e.g. `idOSIssuer`. */\nexport const ATTR_IDOS_SDK_CLASS = \"idos.sdk.class\";\n\n/** Traced method name, e.g. `createUserProfile`. */\nexport const ATTR_IDOS_SDK_METHOD = \"idos.sdk.method\";\n\n/** `db.system.name` value for the idOS kwil network. */\nexport const IDOS_KWIL_SYSTEM = \"kwil\";\n\n/** Kwil namespace every idOS action runs against. */\nexport const IDOS_KWIL_NAMESPACE = \"main\";\n\n/** Transaction hash returned by a kwil `execute`. */\nexport const ATTR_IDOS_KWIL_TX_HASH = \"idos.kwil.tx_hash\";\n\n/** Whether a kwil `execute` waited for the transaction to be mined. */\nexport const ATTR_IDOS_KWIL_SYNCHRONOUS = \"idos.kwil.synchronous\";\n","import type { Attributes } from \"@opentelemetry/api\";\n\nimport { SpanKind } from \"@opentelemetry/api\";\nimport {\n  ATTR_DB_NAMESPACE,\n  ATTR_DB_OPERATION_NAME,\n  ATTR_DB_SYSTEM_NAME,\n} from \"@opentelemetry/semantic-conventions\";\n\nimport {\n  ATTR_IDOS_KWIL_SYNCHRONOUS,\n  ATTR_IDOS_KWIL_TX_HASH,\n  IDOS_KWIL_NAMESPACE,\n  IDOS_KWIL_SYSTEM,\n} from \"./semconv\";\n\n/** A method to wrap. A bare string uses every default. */\nexport type MethodTarget = {\n  name: string;\n  /** Span name. Defaults to `<Class>.<method>`, or `<method>` for a function export. */\n  spanName?: (args: readonly unknown[]) => string;\n  /** Attributes derived from the arguments. Must not emit personal data. */\n  attributes?: (args: readonly unknown[]) => Attributes;\n  /** Attributes derived from the resolved value. Must not emit personal data. */\n  responseAttributes?: (result: unknown) => Attributes;\n  /** @default SpanKind.INTERNAL */\n  kind?: SpanKind;\n};\n\nexport type ClassTarget = {\n  /** Name of the class as exported by the module. */\n  className: string;\n  /** Instance methods, wrapped on the prototype. */\n  methods: (string | MethodTarget)[];\n  /** Static methods, wrapped on the constructor (`init`-style factories). */\n  staticMethods?: (string | MethodTarget)[];\n};\n\nexport type ModuleTarget = {\n  /** Module specifier. */\n  name: string;\n  supportedVersions: string[];\n  /**\n   * Only classes. Every method lives on a prototype or a constructor, both of\n   * which are ordinary mutable objects — that is what lets\n   * {@link IdosInstrumentation.patchModuleExports} work without a loader hook.\n   * A bare function export would sit on the sealed module namespace instead,\n   * and could only be reached via `import-in-the-middle`.\n   */\n  classes: ClassTarget[];\n};\n\nconst SUPPORTED = [\">=2.0.0 <3\"];\n\n/**\n * Kwil `call`/`execute` are the idOS equivalent of `pg.Client.query`: every SDK\n * operation bottoms out here. The action name is a fixed identifier from the\n * action schema, so it is safe to record; the inputs are not.\n */\nconst kwilAttributes = (args: readonly unknown[]): Attributes => {\n  const params = args[0] as { name?: unknown } | undefined;\n  return {\n    [ATTR_DB_SYSTEM_NAME]: IDOS_KWIL_SYSTEM,\n    [ATTR_DB_NAMESPACE]: IDOS_KWIL_NAMESPACE,\n    ...(typeof params?.name === \"string\" ? { [ATTR_DB_OPERATION_NAME]: params.name } : {}),\n  };\n};\n\nconst kwilSpanName =\n  (operation: string) =>\n  (args: readonly unknown[]): string => {\n    const params = args[0] as { name?: unknown } | undefined;\n    return typeof params?.name === \"string\"\n      ? `idos.kwil.${operation} ${params.name}`\n      : `idos.kwil.${operation}`;\n  };\n\n/** Methods shared by every logged-out-capable client state. */\nconst CLIENT_LOGGED_IN_METHODS = [\n  \"requestDWGMessage\",\n  \"createCredential\",\n  \"removeCredential\",\n  \"getCredentialById\",\n  \"shareCredential\",\n  \"getAllCredentials\",\n  \"getAccessGrantsOwned\",\n  \"getAttributes\",\n  \"createAttribute\",\n  \"getCredentialContentSha256Hash\",\n  \"getCredentialContent\",\n  \"getCredentialWithEncryptedContent\",\n  \"getCredentialSharedContent\",\n  \"getGrants\",\n  \"getGrantsCount\",\n  \"getCredentialShared\",\n  \"revokeAccessGrant\",\n  \"addWallet\",\n  \"addWallets\",\n  \"getWallets\",\n  \"removeWallet\",\n  \"removeWallets\",\n  \"filterCredentials\",\n  \"requestAccessGrant\",\n  \"logOut\",\n];\n\nexport const TARGETS: ModuleTarget[] = [\n  {\n    name: \"@idos-network/kwil-infra\",\n    supportedVersions: SUPPORTED,\n    classes: [\n      {\n        className: \"KwilActionClient\",\n        methods: [\n          {\n            name: \"call\",\n            kind: SpanKind.CLIENT,\n            spanName: kwilSpanName(\"call\"),\n            attributes: kwilAttributes,\n          },\n          {\n            name: \"execute\",\n            kind: SpanKind.CLIENT,\n            spanName: kwilSpanName(\"execute\"),\n            attributes: (args) => ({\n              ...kwilAttributes(args),\n              // `synchronous` defaults to true and also decides whether the span\n              // covers the tx-confirmation polling loop.\n              [ATTR_IDOS_KWIL_SYNCHRONOUS]: args[2] === undefined ? true : Boolean(args[2]),\n            }),\n            responseAttributes: (result) =>\n              typeof result === \"string\" ? { [ATTR_IDOS_KWIL_TX_HASH]: result } : {},\n          },\n          {\n            // Usually the bulk of an `execute`: polling the node until the tx is\n            // mined. A tx hash is a public chain identifier, so it is safe to record.\n            name: \"waitForTx\",\n            kind: SpanKind.CLIENT,\n            spanName: () => \"idos.kwil.waitForTx\",\n            attributes: (args) => ({\n              [ATTR_DB_SYSTEM_NAME]: IDOS_KWIL_SYSTEM,\n              [ATTR_DB_NAMESPACE]: IDOS_KWIL_NAMESPACE,\n              ...(typeof args[0] === \"string\" ? { [ATTR_IDOS_KWIL_TX_HASH]: args[0] } : {}),\n            }),\n          },\n        ],\n      },\n    ],\n  },\n  {\n    name: \"@idos-network/client\",\n    supportedVersions: SUPPORTED,\n    classes: [\n      { className: \"idOSClientConfiguration\", methods: [\"createClient\"] },\n      {\n        className: \"idOSClientIdle\",\n        methods: [\"addressHasProfile\", \"withUserSigner\", \"logOut\"],\n        staticMethods: [\"fromConfig\"],\n      },\n      {\n        className: \"idOSClientWithUserSigner\",\n        methods: [\"hasProfile\", \"createUserEncryptionProfile\", \"logIn\", \"logOut\"],\n      },\n      { className: \"idOSClientLoggedIn\", methods: CLIENT_LOGGED_IN_METHODS },\n    ],\n  },\n  {\n    name: \"@idos-network/issuer\",\n    supportedVersions: SUPPORTED,\n    classes: [\n      {\n        className: \"idOSIssuer\",\n        staticMethods: [\"init\"],\n        methods: [\n          \"hasProfile\",\n          \"createUserProfile\",\n          \"upsertWalletAsInserter\",\n          \"createUser\",\n          \"getUser\",\n          \"requestDelegatedWriteGrantMessage\",\n          \"createCredentialByDelegatedWriteGrant\",\n          \"editCredentialAsIssuer\",\n          \"getCredentialIdByContentHash\",\n          \"getCredentialShared\",\n        ],\n      },\n    ],\n  },\n  {\n    name: \"@idos-network/consumer\",\n    supportedVersions: SUPPORTED,\n    classes: [\n      {\n        className: \"idOSConsumer\",\n        staticMethods: [\"init\"],\n        methods: [\n          \"getCredentialSharedFromIDOS\",\n          \"getCredentialSharedContentDecrypted\",\n          \"rescindSharedCredential\",\n          \"getGrantsCount\",\n          \"getAccessGrantsForCredential\",\n          \"getCredentialsSharedByUser\",\n          \"getAccessGrants\",\n          \"verifyCredential\",\n        ],\n      },\n    ],\n  },\n];\n","// Keep in sync with package.json — it is the `otel.scope.version` of every emitted span.\nexport const PACKAGE_NAME = \"@idos-network/instrumentation\";\nexport const PACKAGE_VERSION = \"2.0.1\";\n","import type { Attributes, Span } from \"@opentelemetry/api\";\n\nimport { SpanKind, SpanStatusCode, trace } from \"@opentelemetry/api\";\nimport {\n  InstrumentationBase,\n  InstrumentationNodeModuleDefinition,\n  isWrapped,\n} from \"@opentelemetry/instrumentation\";\nimport { ATTR_ERROR_TYPE } from \"@opentelemetry/semantic-conventions\";\n\nimport type { MethodTarget, ModuleTarget } from \"./targets\";\nimport type { IdosInstrumentationConfig } from \"./types\";\n\nimport { ATTR_IDOS_SDK_CLASS, ATTR_IDOS_SDK_METHOD, ATTR_IDOS_SDK_PACKAGE } from \"./semconv\";\nimport { TARGETS } from \"./targets\";\nimport { PACKAGE_NAME, PACKAGE_VERSION } from \"./version\";\n\ntype AnyMethod = (...args: unknown[]) => unknown;\n\nconst isThenable = (value: unknown): value is PromiseLike<unknown> =>\n  typeof (value as PromiseLike<unknown> | null)?.then === \"function\";\n\n/**\n * Traces the idOS SDK: every public method of `@idos-network/client`,\n * `/consumer`, `/issuer`, the enclave providers, `verifyCredential`, and the\n * kwil `call`/`execute` round-trips they all bottom out in.\n */\nexport class IdosInstrumentation extends InstrumentationBase<IdosInstrumentationConfig> {\n  constructor(config: IdosInstrumentationConfig = {}) {\n    super(PACKAGE_NAME, PACKAGE_VERSION, config);\n  }\n\n  protected init(): InstrumentationNodeModuleDefinition[] {\n    return TARGETS.map(\n      (target) =>\n        new InstrumentationNodeModuleDefinition(\n          target.name,\n          target.supportedVersions,\n          (moduleExports: unknown) => this.applyPatch(target.name, target, moduleExports),\n          (moduleExports: unknown) => this.removePatch(target.name, target, moduleExports),\n        ),\n    );\n  }\n\n  /**\n   * Patch a module namespace you already imported.\n   *\n   * The automatic hooking in {@link InstrumentationBase} needs Node's module\n   * loader hook (`import-in-the-middle`), which has to be installed with\n   * `module.register()` before the import — and does not exist at all in a\n   * browser or a bundled app. This is the alternative everywhere: import the\n   * idOS module and hand its namespace over. Exports the module does not have\n   * are skipped.\n   */\n  patchModuleExports(moduleName: string, moduleExports: unknown): void {\n    const target = this.findTarget(moduleName);\n    if (target) this.applyPatch(moduleName, target, moduleExports);\n  }\n\n  /** Reverse of {@link patchModuleExports}. */\n  unpatchModuleExports(moduleName: string, moduleExports: unknown): void {\n    const target = this.findTarget(moduleName);\n    if (target) this.removePatch(moduleName, target, moduleExports);\n  }\n\n  private findTarget(moduleName: string): ModuleTarget | undefined {\n    const target = TARGETS.find((t) => t.name === moduleName);\n    if (!target) this._diag.warn(`No instrumentation targets known for \"${moduleName}\"`);\n    return target;\n  }\n\n  private applyPatch(moduleName: string, target: ModuleTarget, moduleExports: unknown): unknown {\n    this.eachMember(moduleName, target, moduleExports, (owner, name, method, className) => {\n      if (isWrapped(owner[name])) this._unwrap(owner, name);\n      this._wrap(owner, name, (original) =>\n        this.traced(original as AnyMethod, moduleName, className, method),\n      );\n    });\n    return moduleExports;\n  }\n\n  private removePatch(moduleName: string, target: ModuleTarget, moduleExports: unknown): unknown {\n    this.eachMember(moduleName, target, moduleExports, (owner, name) => {\n      if (isWrapped(owner[name])) this._unwrap(owner, name);\n    });\n    return moduleExports;\n  }\n\n  /** Resolves every target method to the object that owns it, skipping what is absent. */\n  private eachMember(\n    moduleName: string,\n    target: ModuleTarget,\n    moduleExports: unknown,\n    visit: (\n      owner: Record<string, unknown>,\n      name: string,\n      method: MethodTarget,\n      className: string | undefined,\n    ) => void,\n  ): void {\n    if (typeof moduleExports !== \"object\" || moduleExports === null) return;\n    const namespace = moduleExports as Record<string, unknown>;\n\n    const visitOne = (\n      owner: Record<string, unknown>,\n      member: string | MethodTarget,\n      className: string | undefined,\n    ): void => {\n      const method: MethodTarget = typeof member === \"string\" ? { name: member } : member;\n      const label = `${className ? `${className}.` : \"\"}${method.name}`;\n      if (typeof owner[method.name] !== \"function\") {\n        this._diag.debug(`${moduleName}: ${label} is not a function, skipping`);\n        return;\n      }\n      try {\n        visit(owner, method.name, method, className);\n      } catch (error) {\n        // An ESM namespace object is read-only unless an import hook made it writable.\n        this._diag.warn(`${moduleName}: could not patch ${label}: ${String(error)}`);\n      }\n    };\n\n    for (const klass of target.classes) {\n      const ctor = namespace[klass.className];\n      if (typeof ctor !== \"function\") {\n        this._diag.debug(`${moduleName}: class ${klass.className} not exported, skipping`);\n        continue;\n      }\n      const prototype = (ctor as { prototype?: unknown }).prototype;\n      if (typeof prototype === \"object\" && prototype !== null) {\n        for (const member of klass.methods) {\n          visitOne(prototype as Record<string, unknown>, member, klass.className);\n        }\n      }\n      for (const member of klass.staticMethods ?? []) {\n        visitOne(ctor as unknown as Record<string, unknown>, member, klass.className);\n      }\n    }\n  }\n\n  private traced(\n    original: AnyMethod,\n    moduleName: string,\n    className: string | undefined,\n    target: MethodTarget,\n  ): AnyMethod {\n    // The patch must stay a `function` so the wrapped method keeps its call-site\n    // receiver, which leaves `this` taken — same as instrumentation-pg does.\n    // oxlint-disable-next-line typescript/no-this-alias -- see above\n    const instrumentation = this;\n    const defaultSpanName = `${className ? `${className}.` : \"\"}${target.name}`;\n\n    return function patched(this: unknown, ...args: unknown[]): unknown {\n      const config = instrumentation.getConfig();\n      if (config.requireParentSpan && trace.getActiveSpan() === undefined) {\n        return original.apply(this, args);\n      }\n\n      const attributes: Attributes = {\n        [ATTR_IDOS_SDK_PACKAGE]: moduleName,\n        [ATTR_IDOS_SDK_METHOD]: target.name,\n        ...(className ? { [ATTR_IDOS_SDK_CLASS]: className } : {}),\n        ...target.attributes?.(args),\n      };\n\n      const spanName = target.spanName?.(args) ?? defaultSpanName;\n      const spanOptions = { kind: target.kind ?? SpanKind.INTERNAL, attributes };\n\n      return instrumentation.tracer.startActiveSpan(spanName, spanOptions, (span) => {\n        instrumentation._runSpanCustomizationHook(config.requestHook, \"requestHook\", span, {\n          moduleName,\n          className,\n          methodName: target.name,\n          args,\n        });\n\n        let result: unknown;\n        try {\n          result = original.apply(this, args);\n        } catch (error) {\n          instrumentation.failSpan(span, error);\n          throw error;\n        }\n\n        if (!isThenable(result)) {\n          instrumentation.endSpan(span, moduleName, className, target, result);\n          return result;\n        }\n\n        return result.then(\n          (value: unknown) => {\n            instrumentation.endSpan(span, moduleName, className, target, value);\n            return value;\n          },\n          (error: unknown) => {\n            instrumentation.failSpan(span, error);\n            throw error;\n          },\n        );\n      });\n    };\n  }\n\n  private endSpan(\n    span: Span,\n    moduleName: string,\n    className: string | undefined,\n    target: MethodTarget,\n    result: unknown,\n  ): void {\n    const attributes = target.responseAttributes?.(result);\n    if (attributes) span.setAttributes(attributes);\n\n    this._runSpanCustomizationHook(this.getConfig().responseHook, \"responseHook\", span, {\n      moduleName,\n      className,\n      methodName: target.name,\n      result,\n    });\n    span.end();\n  }\n\n  private failSpan(span: Span, error: unknown): void {\n    if (error instanceof Error) {\n      span.recordException(error);\n      span.setAttribute(ATTR_ERROR_TYPE, error.name);\n      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n    } else {\n      span.setAttribute(ATTR_ERROR_TYPE, typeof error);\n      span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });\n    }\n    span.end();\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@idos-network/instrumentation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.2.0",
+  "description": "OpenTelemetry instrumentation for the idOS JavaScript SDK",
+  "keywords": [
+    "idos",
+    "instrumentation",
+    "observability",
+    "opentelemetry",
+    "tracing"
+  ],
+  "homepage": "https://idos.network",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "github:idos-network/idos-sdk-js"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opentelemetry/instrumentation": "^0.222.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0"
+  },
+  "devDependencies": {
+    "@idos-network/client": "2.2.0",
+    "@idos-network/consumer": "2.2.0",
+    "@idos-network/issuer": "2.2.0",
+    "@idos-network/kwil-infra": "2.2.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.11.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@types/node": "25.9.5",
+    "@vitest/coverage-v8": "4.1.11",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "publint": "pnpx publint --strict",
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/index.ts

@@ -0,0 +1,19 @@
+export { IdosInstrumentation } from "./instrumentation";
+export {
+  ATTR_IDOS_KWIL_SYNCHRONOUS,
+  ATTR_IDOS_KWIL_TX_HASH,
+  ATTR_IDOS_SDK_CLASS,
+  ATTR_IDOS_SDK_METHOD,
+  ATTR_IDOS_SDK_PACKAGE,
+  IDOS_KWIL_NAMESPACE,
+  IDOS_KWIL_SYSTEM,
+} from "./semconv";
+export { TARGETS } from "./targets";
+export type { ClassTarget, MethodTarget, ModuleTarget } from "./targets";
+export type {
+  IdosInstrumentationConfig,
+  IdosInstrumentationRequestHook,
+  IdosInstrumentationResponseHook,
+  IdosRequestHookInformation,
+  IdosResponseHookInformation,
+} from "./types";

package/src/instrumentation.test.ts

@@ -0,0 +1,191 @@
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+
+import { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import {
+  BasicTracerProvider,
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_OPERATION_NAME,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_ERROR_TYPE,
+} from "@opentelemetry/semantic-conventions";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { IdosInstrumentation } from "./instrumentation";
+import { ATTR_IDOS_KWIL_TX_HASH, ATTR_IDOS_SDK_CLASS, ATTR_IDOS_SDK_METHOD } from "./semconv";
+
+type KwilCallParams = { name: string; inputs?: Record<string, unknown> };
+
+/**
+ * Stand-ins with the shape `TARGETS` expects. Built fresh per test so that a
+ * patched prototype never leaks into the next one.
+ */
+const buildNamespaces = () => {
+  class KwilActionClient {
+    async call(params: KwilCallParams): Promise<string> {
+      return `called:${params.name}`;
+    }
+
+    async execute(params: KwilCallParams): Promise<string> {
+      if (params.name === "boom") throw new Error("kwil exploded");
+      const txHash = "0xdeadbeef";
+      await this.waitForTx(txHash);
+      return txHash;
+    }
+
+    async waitForTx(txHash: string): Promise<void> {
+      if (txHash === "tx-that-times-out") {
+        const error = new Error("timed out waiting for tx");
+        error.name = "KwilTxPollTimeoutError";
+        throw error;
+      }
+    }
+  }
+
+  const kwil = new KwilActionClient();
+
+  class idOSIssuer {
+    async getUser(id: string): Promise<{ id: string }> {
+      await kwil.call({ name: "get_user", inputs: { id } });
+      return { id };
+    }
+  }
+
+  return {
+    kwil,
+    kwilInfra: { KwilActionClient },
+    issuer: { idOSIssuer },
+  };
+};
+
+describe("IdosInstrumentation", () => {
+  let exporter: InMemorySpanExporter;
+  let instrumentation: IdosInstrumentation;
+  let namespaces: ReturnType<typeof buildNamespaces>;
+
+  beforeEach(() => {
+    // Without a context manager `context.with` cannot propagate, so nothing nests.
+    context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
+    exporter = new InMemorySpanExporter();
+    instrumentation = new IdosInstrumentation();
+    instrumentation.setTracerProvider(
+      new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] }),
+    );
+    namespaces = buildNamespaces();
+  });
+
+  afterEach(() => {
+    context.disable();
+  });
+
+  const finished = (): ReadableSpan[] => exporter.getFinishedSpans();
+
+  it("traces kwil calls with db semantic conventions and keeps inputs off the span", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await namespaces.kwil.call({ name: "get_user", inputs: { id: "secret-user-id" } });
+
+    expect(finished()).toHaveLength(1);
+    const [span] = finished();
+    expect(span.name).toBe("idos.kwil.call get_user");
+    expect(span.kind).toBe(SpanKind.CLIENT);
+    expect(span.attributes[ATTR_DB_SYSTEM_NAME]).toBe("kwil");
+    expect(span.attributes[ATTR_DB_NAMESPACE]).toBe("main");
+    expect(span.attributes[ATTR_DB_OPERATION_NAME]).toBe("get_user");
+    expect(JSON.stringify(span.attributes)).not.toContain("secret-user-id");
+  });
+
+  it("records the tx hash of an execute", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await namespaces.kwil.execute({ name: "add_wallet" });
+
+    expect(finished()[0].attributes[ATTR_IDOS_KWIL_TX_HASH]).toBe("0xdeadbeef");
+  });
+
+  it("traces the tx wait as a child of the execute that broadcast it", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await namespaces.kwil.execute({ name: "add_wallet" });
+
+    const [wait, execute] = finished();
+    expect(wait.name).toBe("idos.kwil.waitForTx");
+    expect(wait.kind).toBe(SpanKind.CLIENT);
+    expect(wait.attributes[ATTR_IDOS_KWIL_TX_HASH]).toBe("0xdeadbeef");
+    expect(execute.name).toBe("idos.kwil.execute add_wallet");
+    expect(wait.parentSpanContext?.spanId).toBe(execute.spanContext().spanId);
+  });
+
+  it("distinguishes a tx poll timeout from other failures via error.type", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await expect(namespaces.kwil.waitForTx("tx-that-times-out")).rejects.toThrow(
+      "timed out waiting for tx",
+    );
+
+    const [span] = finished();
+    expect(span.status.code).toBe(SpanStatusCode.ERROR);
+    expect(span.attributes[ATTR_ERROR_TYPE]).toBe("KwilTxPollTimeoutError");
+  });
+
+  it("marks the span failed and rethrows when the method rejects", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await expect(namespaces.kwil.execute({ name: "boom" })).rejects.toThrow("kwil exploded");
+
+    const [span] = finished();
+    expect(span.status.code).toBe(SpanStatusCode.ERROR);
+    expect(span.status.message).toBe("kwil exploded");
+    expect(span.events.map((event) => event.name)).toContain("exception");
+  });
+
+  it("nests kwil spans under the SDK method that issued them", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+    instrumentation.patchModuleExports("@idos-network/issuer", namespaces.issuer);
+
+    await new namespaces.issuer.idOSIssuer().getUser("u1");
+
+    const [child, parent] = finished();
+    expect(parent.name).toBe("idOSIssuer.getUser");
+    expect(parent.attributes[ATTR_IDOS_SDK_CLASS]).toBe("idOSIssuer");
+    expect(parent.attributes[ATTR_IDOS_SDK_METHOD]).toBe("getUser");
+    expect(child.name).toBe("idos.kwil.call get_user");
+    expect(child.parentSpanContext?.spanId).toBe(parent.spanContext().spanId);
+  });
+
+  it("skips instrumentation when requireParentSpan is set and there is no parent", async () => {
+    instrumentation.setConfig({ requireParentSpan: true });
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await namespaces.kwil.call({ name: "get_user" });
+
+    expect(finished()).toHaveLength(0);
+  });
+
+  it("runs the request and response hooks so callers can opt into their own attributes", async () => {
+    instrumentation.setConfig({
+      requestHook: (span, info) => span.setAttribute("test.args", JSON.stringify(info.args)),
+      responseHook: (span, info) => span.setAttribute("test.result", String(info.result)),
+    });
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await namespaces.kwil.call({ name: "get_user", inputs: { id: "u1" } });
+
+    const [span] = finished();
+    expect(span.attributes["test.args"]).toContain("u1");
+    expect(span.attributes["test.result"]).toBe("called:get_user");
+  });
+
+  it("restores the original methods on unpatch", async () => {
+    instrumentation.patchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+    instrumentation.unpatchModuleExports("@idos-network/kwil-infra", namespaces.kwilInfra);
+
+    await namespaces.kwil.call({ name: "get_user" });
+
+    expect(finished()).toHaveLength(0);
+  });
+});

package/src/instrumentation.ts

@@ -0,0 +1,234 @@
+import type { Attributes, Span } from "@opentelemetry/api";
+
+import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import {
+  InstrumentationBase,
+  InstrumentationNodeModuleDefinition,
+  isWrapped,
+} from "@opentelemetry/instrumentation";
+import { ATTR_ERROR_TYPE } from "@opentelemetry/semantic-conventions";
+
+import type { MethodTarget, ModuleTarget } from "./targets";
+import type { IdosInstrumentationConfig } from "./types";
+
+import { ATTR_IDOS_SDK_CLASS, ATTR_IDOS_SDK_METHOD, ATTR_IDOS_SDK_PACKAGE } from "./semconv";
+import { TARGETS } from "./targets";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "./version";
+
+type AnyMethod = (...args: unknown[]) => unknown;
+
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  typeof (value as PromiseLike<unknown> | null)?.then === "function";
+
+/**
+ * Traces the idOS SDK: every public method of `@idos-network/client`,
+ * `/consumer`, `/issuer`, the enclave providers, `verifyCredential`, and the
+ * kwil `call`/`execute` round-trips they all bottom out in.
+ */
+export class IdosInstrumentation extends InstrumentationBase<IdosInstrumentationConfig> {
+  constructor(config: IdosInstrumentationConfig = {}) {
+    super(PACKAGE_NAME, PACKAGE_VERSION, config);
+  }
+
+  protected init(): InstrumentationNodeModuleDefinition[] {
+    return TARGETS.map(
+      (target) =>
+        new InstrumentationNodeModuleDefinition(
+          target.name,
+          target.supportedVersions,
+          (moduleExports: unknown) => this.applyPatch(target.name, target, moduleExports),
+          (moduleExports: unknown) => this.removePatch(target.name, target, moduleExports),
+        ),
+    );
+  }
+
+  /**
+   * Patch a module namespace you already imported.
+   *
+   * The automatic hooking in {@link InstrumentationBase} needs Node's module
+   * loader hook (`import-in-the-middle`), which has to be installed with
+   * `module.register()` before the import — and does not exist at all in a
+   * browser or a bundled app. This is the alternative everywhere: import the
+   * idOS module and hand its namespace over. Exports the module does not have
+   * are skipped.
+   */
+  patchModuleExports(moduleName: string, moduleExports: unknown): void {
+    const target = this.findTarget(moduleName);
+    if (target) this.applyPatch(moduleName, target, moduleExports);
+  }
+
+  /** Reverse of {@link patchModuleExports}. */
+  unpatchModuleExports(moduleName: string, moduleExports: unknown): void {
+    const target = this.findTarget(moduleName);
+    if (target) this.removePatch(moduleName, target, moduleExports);
+  }
+
+  private findTarget(moduleName: string): ModuleTarget | undefined {
+    const target = TARGETS.find((t) => t.name === moduleName);
+    if (!target) this._diag.warn(`No instrumentation targets known for "${moduleName}"`);
+    return target;
+  }
+
+  private applyPatch(moduleName: string, target: ModuleTarget, moduleExports: unknown): unknown {
+    this.eachMember(moduleName, target, moduleExports, (owner, name, method, className) => {
+      if (isWrapped(owner[name])) this._unwrap(owner, name);
+      this._wrap(owner, name, (original) =>
+        this.traced(original as AnyMethod, moduleName, className, method),
+      );
+    });
+    return moduleExports;
+  }
+
+  private removePatch(moduleName: string, target: ModuleTarget, moduleExports: unknown): unknown {
+    this.eachMember(moduleName, target, moduleExports, (owner, name) => {
+      if (isWrapped(owner[name])) this._unwrap(owner, name);
+    });
+    return moduleExports;
+  }
+
+  /** Resolves every target method to the object that owns it, skipping what is absent. */
+  private eachMember(
+    moduleName: string,
+    target: ModuleTarget,
+    moduleExports: unknown,
+    visit: (
+      owner: Record<string, unknown>,
+      name: string,
+      method: MethodTarget,
+      className: string | undefined,
+    ) => void,
+  ): void {
+    if (typeof moduleExports !== "object" || moduleExports === null) return;
+    const namespace = moduleExports as Record<string, unknown>;
+
+    const visitOne = (
+      owner: Record<string, unknown>,
+      member: string | MethodTarget,
+      className: string | undefined,
+    ): void => {
+      const method: MethodTarget = typeof member === "string" ? { name: member } : member;
+      const label = `${className ? `${className}.` : ""}${method.name}`;
+      if (typeof owner[method.name] !== "function") {
+        this._diag.debug(`${moduleName}: ${label} is not a function, skipping`);
+        return;
+      }
+      try {
+        visit(owner, method.name, method, className);
+      } catch (error) {
+        // An ESM namespace object is read-only unless an import hook made it writable.
+        this._diag.warn(`${moduleName}: could not patch ${label}: ${String(error)}`);
+      }
+    };
+
+    for (const klass of target.classes) {
+      const ctor = namespace[klass.className];
+      if (typeof ctor !== "function") {
+        this._diag.debug(`${moduleName}: class ${klass.className} not exported, skipping`);
+        continue;
+      }
+      const prototype = (ctor as { prototype?: unknown }).prototype;
+      if (typeof prototype === "object" && prototype !== null) {
+        for (const member of klass.methods) {
+          visitOne(prototype as Record<string, unknown>, member, klass.className);
+        }
+      }
+      for (const member of klass.staticMethods ?? []) {
+        visitOne(ctor as unknown as Record<string, unknown>, member, klass.className);
+      }
+    }
+  }
+
+  private traced(
+    original: AnyMethod,
+    moduleName: string,
+    className: string | undefined,
+    target: MethodTarget,
+  ): AnyMethod {
+    // The patch must stay a `function` so the wrapped method keeps its call-site
+    // receiver, which leaves `this` taken — same as instrumentation-pg does.
+    // oxlint-disable-next-line typescript/no-this-alias -- see above
+    const instrumentation = this;
+    const defaultSpanName = `${className ? `${className}.` : ""}${target.name}`;
+
+    return function patched(this: unknown, ...args: unknown[]): unknown {
+      const config = instrumentation.getConfig();
+      if (config.requireParentSpan && trace.getActiveSpan() === undefined) {
+        return original.apply(this, args);
+      }
+
+      const attributes: Attributes = {
+        [ATTR_IDOS_SDK_PACKAGE]: moduleName,
+        [ATTR_IDOS_SDK_METHOD]: target.name,
+        ...(className ? { [ATTR_IDOS_SDK_CLASS]: className } : {}),
+        ...target.attributes?.(args),
+      };
+
+      const spanName = target.spanName?.(args) ?? defaultSpanName;
+      const spanOptions = { kind: target.kind ?? SpanKind.INTERNAL, attributes };
+
+      return instrumentation.tracer.startActiveSpan(spanName, spanOptions, (span) => {
+        instrumentation._runSpanCustomizationHook(config.requestHook, "requestHook", span, {
+          moduleName,
+          className,
+          methodName: target.name,
+          args,
+        });
+
+        let result: unknown;
+        try {
+          result = original.apply(this, args);
+        } catch (error) {
+          instrumentation.failSpan(span, error);
+          throw error;
+        }
+
+        if (!isThenable(result)) {
+          instrumentation.endSpan(span, moduleName, className, target, result);
+          return result;
+        }
+
+        return result.then(
+          (value: unknown) => {
+            instrumentation.endSpan(span, moduleName, className, target, value);
+            return value;
+          },
+          (error: unknown) => {
+            instrumentation.failSpan(span, error);
+            throw error;
+          },
+        );
+      });
+    };
+  }
+
+  private endSpan(
+    span: Span,
+    moduleName: string,
+    className: string | undefined,
+    target: MethodTarget,
+    result: unknown,
+  ): void {
+    const attributes = target.responseAttributes?.(result);
+    if (attributes) span.setAttributes(attributes);
+
+    this._runSpanCustomizationHook(this.getConfig().responseHook, "responseHook", span, {
+      moduleName,
+      className,
+      methodName: target.name,
+      result,
+    });
+    span.end();
+  }
+
+  private failSpan(span: Span, error: unknown): void {
+    if (error instanceof Error) {
+      span.recordException(error);
+      span.setAttribute(ATTR_ERROR_TYPE, error.name);
+      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+    } else {
+      span.setAttribute(ATTR_ERROR_TYPE, typeof error);
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+    }
+    span.end();
+  }
+}

package/src/semconv.ts

@@ -0,0 +1,26 @@
+/**
+ * Attributes emitted by this instrumentation that have no stable OpenTelemetry
+ * semantic convention. Stable ones (`db.*`, `error.type`) are imported from
+ * `@opentelemetry/semantic-conventions` at the call site.
+ */
+
+/** Package the traced method lives in, e.g. `@idos-network/issuer`. */
+export const ATTR_IDOS_SDK_PACKAGE = "idos.sdk.package";
+
+/** Class the traced method lives on, e.g. `idOSIssuer`. */
+export const ATTR_IDOS_SDK_CLASS = "idos.sdk.class";
+
+/** Traced method name, e.g. `createUserProfile`. */
+export const ATTR_IDOS_SDK_METHOD = "idos.sdk.method";
+
+/** `db.system.name` value for the idOS kwil network. */
+export const IDOS_KWIL_SYSTEM = "kwil";
+
+/** Kwil namespace every idOS action runs against. */
+export const IDOS_KWIL_NAMESPACE = "main";
+
+/** Transaction hash returned by a kwil `execute`. */
+export const ATTR_IDOS_KWIL_TX_HASH = "idos.kwil.tx_hash";
+
+/** Whether a kwil `execute` waited for the transaction to be mined. */
+export const ATTR_IDOS_KWIL_SYNCHRONOUS = "idos.kwil.synchronous";

package/src/targets.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+
+import type { ClassTarget, MethodTarget } from "./targets";
+
+import { TARGETS } from "./targets";
+
+/**
+ * The target table names classes and methods as strings, so a rename in an SDK
+ * package would silently stop producing spans. This resolves every entry
+ * against the real modules so drift fails the build instead.
+ */
+
+const unresolved = (namespace: Record<string, unknown>, classes: ClassTarget[]): string[] => {
+  const problems: string[] = [];
+
+  const probe = (owner: unknown, members: (string | MethodTarget)[], label: string): void => {
+    for (const member of members) {
+      const name = typeof member === "string" ? member : member.name;
+      if (typeof (owner as Record<string, unknown> | null)?.[name] !== "function") {
+        problems.push(`${label}${name}`);
+      }
+    }
+  };
+
+  for (const klass of classes) {
+    const ctor = namespace[klass.className] as { prototype?: unknown } | undefined;
+    if (typeof ctor !== "function") {
+      problems.push(klass.className);
+      continue;
+    }
+    probe(ctor.prototype, klass.methods, `${klass.className}.`);
+    probe(ctor, klass.staticMethods ?? [], `${klass.className}.`);
+  }
+
+  return problems;
+};
+
+describe("TARGETS", () => {
+  for (const target of TARGETS) {
+    it(`resolves every target in ${target.name}`, async () => {
+      const namespace = (await import(target.name)) as Record<string, unknown>;
+      expect(unresolved(namespace, target.classes)).toEqual([]);
+    });
+  }
+
+  // Every method has to sit on a prototype or constructor for the no-loader-hook
+  // path to reach it; a bare function export would need `import-in-the-middle`.
+  it("has no bare function exports as targets", () => {
+    expect(TARGETS.every((t) => t.classes.length > 0)).toBe(true);
+  });
+});

package/src/targets.ts

@@ -0,0 +1,209 @@
+import type { Attributes } from "@opentelemetry/api";
+
+import { SpanKind } from "@opentelemetry/api";
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_OPERATION_NAME,
+  ATTR_DB_SYSTEM_NAME,
+} from "@opentelemetry/semantic-conventions";
+
+import {
+  ATTR_IDOS_KWIL_SYNCHRONOUS,
+  ATTR_IDOS_KWIL_TX_HASH,
+  IDOS_KWIL_NAMESPACE,
+  IDOS_KWIL_SYSTEM,
+} from "./semconv";
+
+/** A method to wrap. A bare string uses every default. */
+export type MethodTarget = {
+  name: string;
+  /** Span name. Defaults to `<Class>.<method>`, or `<method>` for a function export. */
+  spanName?: (args: readonly unknown[]) => string;
+  /** Attributes derived from the arguments. Must not emit personal data. */
+  attributes?: (args: readonly unknown[]) => Attributes;
+  /** Attributes derived from the resolved value. Must not emit personal data. */
+  responseAttributes?: (result: unknown) => Attributes;
+  /** @default SpanKind.INTERNAL */
+  kind?: SpanKind;
+};
+
+export type ClassTarget = {
+  /** Name of the class as exported by the module. */
+  className: string;
+  /** Instance methods, wrapped on the prototype. */
+  methods: (string | MethodTarget)[];
+  /** Static methods, wrapped on the constructor (`init`-style factories). */
+  staticMethods?: (string | MethodTarget)[];
+};
+
+export type ModuleTarget = {
+  /** Module specifier. */
+  name: string;
+  supportedVersions: string[];
+  /**
+   * Only classes. Every method lives on a prototype or a constructor, both of
+   * which are ordinary mutable objects — that is what lets
+   * {@link IdosInstrumentation.patchModuleExports} work without a loader hook.
+   * A bare function export would sit on the sealed module namespace instead,
+   * and could only be reached via `import-in-the-middle`.
+   */
+  classes: ClassTarget[];
+};
+
+const SUPPORTED = [">=2.0.0 <3"];
+
+/**
+ * Kwil `call`/`execute` are the idOS equivalent of `pg.Client.query`: every SDK
+ * operation bottoms out here. The action name is a fixed identifier from the
+ * action schema, so it is safe to record; the inputs are not.
+ */
+const kwilAttributes = (args: readonly unknown[]): Attributes => {
+  const params = args[0] as { name?: unknown } | undefined;
+  return {
+    [ATTR_DB_SYSTEM_NAME]: IDOS_KWIL_SYSTEM,
+    [ATTR_DB_NAMESPACE]: IDOS_KWIL_NAMESPACE,
+    ...(typeof params?.name === "string" ? { [ATTR_DB_OPERATION_NAME]: params.name } : {}),
+  };
+};
+
+const kwilSpanName =
+  (operation: string) =>
+  (args: readonly unknown[]): string => {
+    const params = args[0] as { name?: unknown } | undefined;
+    return typeof params?.name === "string"
+      ? `idos.kwil.${operation} ${params.name}`
+      : `idos.kwil.${operation}`;
+  };
+
+/** Methods shared by every logged-out-capable client state. */
+const CLIENT_LOGGED_IN_METHODS = [
+  "requestDWGMessage",
+  "createCredential",
+  "removeCredential",
+  "getCredentialById",
+  "shareCredential",
+  "getAllCredentials",
+  "getAccessGrantsOwned",
+  "getAttributes",
+  "createAttribute",
+  "getCredentialContentSha256Hash",
+  "getCredentialContent",
+  "getCredentialWithEncryptedContent",
+  "getCredentialSharedContent",
+  "getGrants",
+  "getGrantsCount",
+  "getCredentialShared",
+  "revokeAccessGrant",
+  "addWallet",
+  "addWallets",
+  "getWallets",
+  "removeWallet",
+  "removeWallets",
+  "filterCredentials",
+  "requestAccessGrant",
+  "logOut",
+];
+
+export const TARGETS: ModuleTarget[] = [
+  {
+    name: "@idos-network/kwil-infra",
+    supportedVersions: SUPPORTED,
+    classes: [
+      {
+        className: "KwilActionClient",
+        methods: [
+          {
+            name: "call",
+            kind: SpanKind.CLIENT,
+            spanName: kwilSpanName("call"),
+            attributes: kwilAttributes,
+          },
+          {
+            name: "execute",
+            kind: SpanKind.CLIENT,
+            spanName: kwilSpanName("execute"),
+            attributes: (args) => ({
+              ...kwilAttributes(args),
+              // `synchronous` defaults to true and also decides whether the span
+              // covers the tx-confirmation polling loop.
+              [ATTR_IDOS_KWIL_SYNCHRONOUS]: args[2] === undefined ? true : Boolean(args[2]),
+            }),
+            responseAttributes: (result) =>
+              typeof result === "string" ? { [ATTR_IDOS_KWIL_TX_HASH]: result } : {},
+          },
+          {
+            // Usually the bulk of an `execute`: polling the node until the tx is
+            // mined. A tx hash is a public chain identifier, so it is safe to record.
+            name: "waitForTx",
+            kind: SpanKind.CLIENT,
+            spanName: () => "idos.kwil.waitForTx",
+            attributes: (args) => ({
+              [ATTR_DB_SYSTEM_NAME]: IDOS_KWIL_SYSTEM,
+              [ATTR_DB_NAMESPACE]: IDOS_KWIL_NAMESPACE,
+              ...(typeof args[0] === "string" ? { [ATTR_IDOS_KWIL_TX_HASH]: args[0] } : {}),
+            }),
+          },
+        ],
+      },
+    ],
+  },
+  {
+    name: "@idos-network/client",
+    supportedVersions: SUPPORTED,
+    classes: [
+      { className: "idOSClientConfiguration", methods: ["createClient"] },
+      {
+        className: "idOSClientIdle",
+        methods: ["addressHasProfile", "withUserSigner", "logOut"],
+        staticMethods: ["fromConfig"],
+      },
+      {
+        className: "idOSClientWithUserSigner",
+        methods: ["hasProfile", "createUserEncryptionProfile", "logIn", "logOut"],
+      },
+      { className: "idOSClientLoggedIn", methods: CLIENT_LOGGED_IN_METHODS },
+    ],
+  },
+  {
+    name: "@idos-network/issuer",
+    supportedVersions: SUPPORTED,
+    classes: [
+      {
+        className: "idOSIssuer",
+        staticMethods: ["init"],
+        methods: [
+          "hasProfile",
+          "createUserProfile",
+          "upsertWalletAsInserter",
+          "createUser",
+          "getUser",
+          "requestDelegatedWriteGrantMessage",
+          "createCredentialByDelegatedWriteGrant",
+          "editCredentialAsIssuer",
+          "getCredentialIdByContentHash",
+          "getCredentialShared",
+        ],
+      },
+    ],
+  },
+  {
+    name: "@idos-network/consumer",
+    supportedVersions: SUPPORTED,
+    classes: [
+      {
+        className: "idOSConsumer",
+        staticMethods: ["init"],
+        methods: [
+          "getCredentialSharedFromIDOS",
+          "getCredentialSharedContentDecrypted",
+          "rescindSharedCredential",
+          "getGrantsCount",
+          "getAccessGrantsForCredential",
+          "getCredentialsSharedByUser",
+          "getAccessGrants",
+          "verifyCredential",
+        ],
+      },
+    ],
+  },
+];

package/src/types.ts

@@ -0,0 +1,61 @@
+import type { Span } from "@opentelemetry/api";
+import type { InstrumentationConfig } from "@opentelemetry/instrumentation";
+
+/** Data about the call that is about to be made, passed to {@link IdosInstrumentationConfig.requestHook}. */
+export type IdosRequestHookInformation = {
+  /** Module the traced method was exported from, e.g. `@idos-network/issuer`. */
+  moduleName: string;
+  /** Class the method lives on, or `undefined` for a bare function export. */
+  className: string | undefined;
+  /** Method name, e.g. `createUserProfile`. */
+  methodName: string;
+  /** The arguments the method was called with. May contain personal data — see README. */
+  args: readonly unknown[];
+};
+
+/** Data about the completed call, passed to {@link IdosInstrumentationConfig.responseHook}. */
+export type IdosResponseHookInformation = {
+  moduleName: string;
+  className: string | undefined;
+  methodName: string;
+  /** The resolved return value. May contain personal data — see README. */
+  result: unknown;
+};
+
+export type IdosInstrumentationRequestHook = (span: Span, info: IdosRequestHookInformation) => void;
+
+export type IdosInstrumentationResponseHook = (
+  span: Span,
+  info: IdosResponseHookInformation,
+) => void;
+
+export interface IdosInstrumentationConfig extends InstrumentationConfig {
+  /**
+   * Hook for adding custom attributes from the call arguments, or renaming the span.
+   *
+   * Nothing derived from arguments is recorded by default: idOS SDK arguments carry
+   * credentials, wallet identifiers and encryption keys. Opt in here, per deployment.
+   *
+   * @default undefined
+   */
+  requestHook?: IdosInstrumentationRequestHook;
+
+  /**
+   * Hook for adding custom attributes from the resolved return value.
+   *
+   * Same caveat as {@link requestHook}: return values carry credential contents.
+   *
+   * @default undefined
+   */
+  responseHook?: IdosInstrumentationResponseHook;
+
+  /**
+   * If true, spans are only created when there is already an active span.
+   *
+   * Useful in the browser, where an idOS call outside a user-interaction span
+   * would otherwise produce a single-span orphan trace.
+   *
+   * @default false
+   */
+  requireParentSpan?: boolean;
+}

package/src/version.ts

@@ -0,0 +1,3 @@
+// Keep in sync with package.json — it is the `otel.scope.version` of every emitted span.
+export const PACKAGE_NAME = "@idos-network/instrumentation";
+export const PACKAGE_VERSION = "2.0.1";