@composed-di/instrumentation-core 0.6.0-alpha → 0.7.0-alpha

package/dist/index.d.ts

@@ -1,4 +1,3 @@
 export * from './serviceInstrumentation';
-export * from './instrument';
 export * from './redaction';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,aAAa,CAAA"}

package/dist/index.js

@@ -15,6 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./serviceInstrumentation"), exports);
-__exportStar(require("./instrument"), exports);
 __exportStar(require("./redaction"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAwC;AACxC,+CAA4B;AAC5B,8CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAwC;AACxC,8CAA2B"}

package/dist/redaction.d.ts

@@ -19,7 +19,7 @@ export type Mask<T, K extends Extract<keyof T, string>> = T[K] extends (...args:
 /**
  * Marks a service — or specific properties of it — as sensitive, so the
  * values flowing through its events are redacted. Passed to
- * {@link instrument} via InstrumentOptions.redactionRules and applied
+ * {@link ServiceInstrumentation.instrument} via the capture options' `redact` list and applied
  * centrally, after the capture flags: values a rule matches are scrubbed
  * before the instrumentation ever sees them, and when capture is off
  * there is nothing to redact. Returned by
@@ -31,16 +31,16 @@ export type Mask<T, K extends Extract<keyof T, string>> = T[K] extends (...args:
 export interface RedactionRule<T> {
     readonly key: ServiceKey<T>;
     /**
-     * The args to report for a call to `functionName`: unchanged if not
+     * The args to report for a call to `methodName`: unchanged if not
      * redacted, otherwise blanked or run through a custom `maskArgs`.
      */
-    maskArgs(functionName: string, args: readonly unknown[]): readonly unknown[];
+    maskArgs(methodName: string, args: readonly unknown[]): readonly unknown[];
     /**
      * The value to report for a method call's success outcome: unchanged
      * if not redacted, otherwise blanked or run through a custom
      * `maskResult`.
      */
-    maskResult(functionName: string, result: unknown): unknown;
+    maskResult(methodName: string, result: unknown): unknown;
 }
 /**
  * Fluent, single-key rule builder returned by {@link redactionRule}.

package/dist/redaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CACrE,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,MAAM,CAAC,GACR;IACE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAA;CACnC,GACD,KAAK,CAAA;AAeT;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IAE3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAAA;IAE5E;;;;OAIG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IAKrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;gBAEpC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;IAE/C,yCAAyC;IACzC,SAAS,IAAI,IAAI;IAMjB;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAM5E;;;OAGG;IACH,OAAO,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,GAAG,IAAI;IAOnD,KAAK,IAAI,aAAa,CAAC,GAAG,CAAC;CAyC5B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAE5E"}
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CACrE,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,MAAM,CAAC,GACR;IACE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAA;CACnC,GACD,KAAK,CAAA;AAeT;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IAE3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAAA;IAE1E;;;;OAIG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IAKrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;gBAEpC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;IAE/C,yCAAyC;IACzC,SAAS,IAAI,IAAI;IAMjB;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAM5E;;;OAGG;IACH,OAAO,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,GAAG,IAAI;IAOnD,KAAK,IAAI,aAAa,CAAC,GAAG,CAAC;CAyC5B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAE5E"}

package/dist/redaction.js

@@ -75,8 +75,8 @@ class RedactionRuleBuilder {
         const overrides = this.overrides;
         return {
             key: this.key,
-            maskArgs(functionName, args) {
-                const override = overrides[functionName];
+            maskArgs(methodName, args) {
+                const override = overrides[methodName];
                 const redacted = override ? override.redacted : redactAllFlag;
                 if (!redacted) {
                     return args;
@@ -89,8 +89,8 @@ class RedactionRuleBuilder {
                         // delegate still sees the call's arity.
                         args.map(() => exports.REDACTED_VALUE);
             },
-            maskResult(functionName, result) {
-                const override = overrides[functionName];
+            maskResult(methodName, result) {
+                const override = overrides[methodName];
                 const redacted = override ? override.redacted : redactAllFlag;
                 if (!redacted) {
                     return result;

package/dist/redaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}

package/dist/serviceInstrumentation.d.ts

@@ -1,4 +1,6 @@
-import type { ServiceKey } from '@composed-di/core';
+import { ServiceFactory, ServiceKey, ServiceModule } from '@composed-di/core';
+import type { RedactionRule } from './redaction';
+type GenericFactory = ServiceFactory<unknown, readonly ServiceKey<any>[]>;
 /**
  * A handle representing a single in-flight operation (initialization,
  * disposal, or method call), returned by a ServiceInstrumentation when the
@@ -9,7 +11,7 @@ import type { ServiceKey } from '@composed-di/core';
  * handle, a correlation id) without any bookkeeping to pair concurrent
  * start/finish events.
  */
-export interface EventSpan {
+export interface OperationSpan {
     /**
      * Wrapper around the operation itself. The instrumented factory invokes
      * the operation as `run(() => operation())`, so the instrumentation can
@@ -37,23 +39,23 @@ export interface EventSpan {
      * @param outcome - How the operation finished, and its value or error.
      * @return void
      */
-    end(outcome: EventOutcome): void;
+    end(outcome: OperationOutcome): void;
 }
 /**
- * How an operation finished, delivered to EventSpan.end: `success` may
+ * How an operation finished, delivered to OperationSpan.end: `success` may
  * carry the return or resolved value of a method call (initialize and
  * dispose outcomes never carry one); `failure` carries the error that was
  * thrown or rejected.
  *
- * Whether `value` is present is decided by {@link instrument}, not by the
- * implementation: it is absent unless result capture is enabled in the
- * InstrumentOptions, and holds the redacted value when a redaction rule
- * matches. Implementations must record the value exactly when it is
+ * Whether `value` is present is decided by {@link ServiceInstrumentation.instrument},
+ * not by the implementation: it is absent unless result capture is enabled
+ * in the InstrumentOptions, and holds the redacted value when a redaction
+ * rule matches. Implementations must record the value exactly when it is
  * present (`'value' in outcome` — a captured `undefined` return is
  * delivered as a present `value: undefined`) and must not record any
  * result when it is absent.
  */
-export type EventOutcome = {
+export type OperationOutcome = {
     type: 'success';
     value?: unknown;
 } | {
@@ -99,53 +101,128 @@ export interface MethodCallContext {
     /**
      * The name of the method that is being called.
      */
-    functionName: string;
+    methodName: string;
     /**
      * The arguments to report for this call, passed by reference;
      * implementations must not mutate them.
      *
-     * Whether they are present is decided by {@link instrument}, not by the
-     * implementation: absent unless argument capture is enabled in the
-     * InstrumentOptions, and already redacted when a redaction rule matches.
-     * Implementations must record the arguments exactly when present and
-     * must not record any arguments when absent.
+     * Whether they are present is decided by {@link ServiceInstrumentation.instrument},
+     * not by the implementation: absent unless argument capture is enabled in
+     * the InstrumentOptions, and already redacted when a redaction rule
+     * matches. Implementations must record the arguments exactly when present
+     * and must not record any arguments when absent.
      */
     args?: readonly unknown[];
 }
 /**
- * Interface for instrumenting services wrapped by {@link instrument}.
- * Implement this interface to observe lifecycle events and method calls
- * of the instrumented services.
+ * What runtime values are delivered to the instrumentation, and how they
+ * are scrubbed first. Nothing is captured by default: values may be large
+ * or contain secrets, and they end up wherever the instrumentation
+ * exports them.
+ */
+export interface CaptureOptions {
+    /**
+     * Deliver method arguments to the instrumentation (as
+     * MethodCallContext.args). When off, the instrumentation never sees the
+     * arguments at all.
+     */
+    arguments?: boolean;
+    /**
+     * Deliver method call return / resolved values to the instrumentation
+     * (as the success outcome's `value`). When off, the instrumentation
+     * never sees the values at all. Initialize and dispose outcomes never
+     * carry a value: the service instance is not useful information to
+     * report.
+     */
+    results?: boolean;
+    /**
+     * Per-service redaction applied to whatever the capture flags let
+     * through: matched arguments and success values are blanked (or run
+     * through the rule's custom mask) before the instrumentation sees them.
+     * The capture flags are the primary gate — when capture is off there is
+     * nothing to redact, and rules cannot re-enable delivery.
+     */
+    redact?: readonly RedactionRule<any>[];
+}
+/**
+ * Configuration for {@link ServiceInstrumentation.instrument}. Capture
+ * policy lives here, not in the ServiceInstrumentation subclasses: what a
+ * subclass receives is exactly what it is allowed to record, so no
+ * subclass carries its own capture flags or redaction logic.
+ */
+export interface InstrumentOptions {
+    /**
+     * What runtime values (arguments, results) reach the instrumentation,
+     * and the redaction applied to them first. Nothing is captured when
+     * omitted.
+     */
+    capture?: CaptureOptions;
+}
+/**
+ * Base class for instrumenting services. Extend it and override the hooks
+ * to observe lifecycle events and method calls of the services wrapped by
+ * {@link ServiceInstrumentation.instrument}.
  *
- * Instrumentation is strictly observational: implementations see every
- * operation but must never alter it — see the EventSpan contract.
+ * Instrumentation is strictly observational: subclasses see every
+ * operation but must never alter it — see the OperationSpan contract.
  *
- * Each method is invoked when the corresponding operation starts and may
- * return an EventSpan that is notified when that operation finishes.
+ * Each hook is invoked when the corresponding operation starts and may
+ * return an OperationSpan that is notified when that operation finishes.
  * Returning nothing opts out of completion tracking for that call.
  */
-export interface ServiceInstrumentation {
+export declare class ServiceInstrumentation {
     /**
      * Invoked at the start of the initialization process for a specific service.
      *
      * @param context - Context of the initialization, including the service key.
-     * @return An EventSpan notified when initialization finishes, or void.
+     * @return An OperationSpan notified when initialization finishes, or void.
      */
-    onInitialize?(context: InitializeContext): EventSpan | void;
+    onInitialize?(context: InitializeContext): OperationSpan | void;
     /**
      * Invoked when the disposal process for a service starts.
      *
      * @param context - Context of the disposal, including the service key.
-     * @return An EventSpan notified when disposal finishes, or void.
+     * @return An OperationSpan notified when disposal finishes, or void.
      */
-    onDispose?(context: DisposeContext): EventSpan | void;
+    onDispose?(context: DisposeContext): OperationSpan | void;
     /**
      * Invoked when a method call starts on a service instance.
      *
      * @param context - Context of the invocation, including the service key,
      * the method name, and its arguments.
-     * @return An EventSpan notified when the call finishes, or void.
+     * @return An OperationSpan notified when the call finishes, or void.
+     */
+    onMethodCall?(context: MethodCallContext): OperationSpan | void;
+    /**
+     * Wraps service factories so this instrumentation is notified when a
+     * service is initialized or disposed and when a method is called on a
+     * service instance. Service instances are wrapped in a Proxy to observe
+     * method calls, and errors are rethrown after being reported, so
+     * behavior is otherwise unchanged.
+     *
+     * ServiceModule entries are flattened into their factories, so an
+     * already-built module can be instrumented as a whole. Compose the
+     * result with `ServiceModule.from`:
+     *
+     * @example
+     * ```ts
+     * const module = ServiceModule.from(
+     *   otel.instrument([db, cache, api], {
+     *     capture: {
+     *       arguments: true,
+     *       results: true,
+     *       redact: [redactionRule(VaultKey).redact('getSecret').build()],
+     *     },
+     *   }),
+     * );
+     * ```
+     *
+     * @param entries - An array of ServiceModule or factory instances to wrap.
+     * @param options - The capture and redaction policy applied before
+     * anything reaches this instrumentation.
+     * @return The wrapped factories, ready to be passed to ServiceModule.from.
      */
-    onMethodCall?(context: MethodCallContext): EventSpan | void;
+    instrument(entries: (ServiceModule | GenericFactory)[], options?: InstrumentOptions): GenericFactory[];
 }
+export {};
 //# sourceMappingURL=serviceInstrumentation.d.ts.map

package/dist/serviceInstrumentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serviceInstrumentation.d.ts","sourceRoot":"","sources":["../src/serviceInstrumentation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IAEtB;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEvC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAA;IAE3D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAA;IAErD;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAA;CAC5D"}
+{"version":3,"file":"serviceInstrumentation.d.ts","sourceRoot":"","sources":["../src/serviceInstrumentation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,KAAK,cAAc,GAAG,cAAc,CAAC,OAAO,EAAE,SAAS,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AAEzE;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IAEtB;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEvC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,CAAA;IAExB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE,CAAA;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAsB;IACjC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,GAAG,IAAI;IAE/D;;;;;OAKG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI;IAEzD;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,GAAG,IAAI;IAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,UAAU,CACR,OAAO,EAAE,CAAC,aAAa,GAAG,cAAc,CAAC,EAAE,EAC3C,OAAO,GAAE,iBAAsB,GAC9B,cAAc,EAAE;CAKpB"}

package/dist/serviceInstrumentation.js

@@ -1,3 +1,219 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceInstrumentation = void 0;
+const core_1 = require("@composed-di/core");
+/**
+ * Base class for instrumenting services. Extend it and override the hooks
+ * to observe lifecycle events and method calls of the services wrapped by
+ * {@link ServiceInstrumentation.instrument}.
+ *
+ * Instrumentation is strictly observational: subclasses see every
+ * operation but must never alter it — see the OperationSpan contract.
+ *
+ * Each hook is invoked when the corresponding operation starts and may
+ * return an OperationSpan that is notified when that operation finishes.
+ * Returning nothing opts out of completion tracking for that call.
+ */
+class ServiceInstrumentation {
+    /**
+     * Wraps service factories so this instrumentation is notified when a
+     * service is initialized or disposed and when a method is called on a
+     * service instance. Service instances are wrapped in a Proxy to observe
+     * method calls, and errors are rethrown after being reported, so
+     * behavior is otherwise unchanged.
+     *
+     * ServiceModule entries are flattened into their factories, so an
+     * already-built module can be instrumented as a whole. Compose the
+     * result with `ServiceModule.from`:
+     *
+     * @example
+     * ```ts
+     * const module = ServiceModule.from(
+     *   otel.instrument([db, cache, api], {
+     *     capture: {
+     *       arguments: true,
+     *       results: true,
+     *       redact: [redactionRule(VaultKey).redact('getSecret').build()],
+     *     },
+     *   }),
+     * );
+     * ```
+     *
+     * @param entries - An array of ServiceModule or factory instances to wrap.
+     * @param options - The capture and redaction policy applied before
+     * anything reaches this instrumentation.
+     * @return The wrapped factories, ready to be passed to ServiceModule.from.
+     */
+    instrument(entries, options = {}) {
+        return entries
+            .flatMap((e) => (e instanceof core_1.ServiceModule ? e.factories : [e]))
+            .map((factory) => instrumentedServiceFactory(this, options, factory));
+    }
+}
+exports.ServiceInstrumentation = ServiceInstrumentation;
+function buildCapturePolicy(options, key) {
+    var _a, _b, _c;
+    const capture = options.capture;
+    const rule = (_a = capture === null || capture === void 0 ? void 0 : capture.redact) === null || _a === void 0 ? void 0 : _a.find((r) => r.key === key);
+    const captureArguments = (_b = capture === null || capture === void 0 ? void 0 : capture.arguments) !== null && _b !== void 0 ? _b : false;
+    const captureResults = (_c = capture === null || capture === void 0 ? void 0 : capture.results) !== null && _c !== void 0 ? _c : false;
+    return {
+        args: (methodName, args) => captureArguments
+            ? rule
+                ? rule.maskArgs(methodName, args)
+                : args
+            : undefined,
+        result: (methodName, value) => captureResults
+            ? { value: rule ? rule.maskResult(methodName, value) : value }
+            : undefined,
+    };
+}
+/**
+ * Wraps a given service factory with instrumentation to notify a
+ * ServiceInstrumentation of lifecycle events and method calls.
+ *
+ * For each of initialize, dispose, and method calls, the instrumentation
+ * is invoked at the start of the operation and may return an OperationSpan
+ * whose `end` is called with the outcome when the operation finishes.
+ * Errors are rethrown after being reported.
+ *
+ * @param instrumentation The instrumentation to notify.
+ * @param options The capture policy.
+ * @param delegate The original service factory to be instrumented.
+ * @return A new service factory that provides the same dependencies but includes event notification logic.
+ */
+function instrumentedServiceFactory(instrumentation, options, delegate) {
+    const key = delegate.provides;
+    const capturePolicy = buildCapturePolicy(options, key);
+    return core_1.ServiceFactory.singleton({
+        scope: delegate.scope,
+        provides: delegate.provides,
+        dependsOn: delegate.dependsOn,
+        initialize: (...args) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const span = (_a = instrumentation.onInitialize) === null || _a === void 0 ? void 0 : _a.call(instrumentation, { key });
+            if (!span) {
+                return delegate.initialize(...args);
+            }
+            try {
+                const instance = yield span.run(() => delegate.initialize(...args));
+                span.end({ type: 'success' });
+                return observeMethodCalls(instance, instrumentation, key, capturePolicy);
+            }
+            catch (error) {
+                span.end({ type: 'failure', error });
+                throw error;
+            }
+        }),
+        dispose: () => {
+            var _a;
+            const dispose = delegate.dispose;
+            if (dispose) {
+                const span = (_a = instrumentation.onDispose) === null || _a === void 0 ? void 0 : _a.call(instrumentation, { key });
+                if (span) {
+                    try {
+                        span.run(dispose);
+                        span.end({ type: 'success' });
+                    }
+                    catch (error) {
+                        span.end({ type: 'failure', error });
+                        throw error;
+                    }
+                }
+                else {
+                    dispose();
+                }
+            }
+        },
+    });
+}
+/**
+ * Wraps an object with a Proxy to notify the instrumentation of method calls.
+ *
+ * Methods returning a promise report their outcome when the promise
+ * settles, not when the method returns.
+ *
+ * @param thing The object whose method calls need to be observed.
+ * @param instrumentation The instrumentation notified of method call events.
+ * @param key The service key used to identify the service in events.
+ * @param capturePolicy The capture policy deciding what argument and result
+ * values (if any) are delivered with each event.
+ * @return A Proxy wrapping the input object, with all method calls being reported.
+ */
+function observeMethodCalls(thing, instrumentation, key, capturePolicy) {
+    if (typeof thing !== 'object' || thing === null) {
+        return thing;
+    }
+    const className = classNameOf(thing);
+    return new Proxy(thing, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop);
+            if (typeof value === 'function' && typeof prop === 'string') {
+                return (...args) => {
+                    var _a;
+                    const span = (_a = instrumentation.onMethodCall) === null || _a === void 0 ? void 0 : _a.call(instrumentation, {
+                        key,
+                        className,
+                        methodName: prop,
+                        args: capturePolicy.args(prop, args),
+                    });
+                    try {
+                        const result = invokeWithin(span, () => value.apply(target, args));
+                        if (result instanceof Promise) {
+                            return result.then((resolved) => {
+                                span === null || span === void 0 ? void 0 : span.end(Object.assign({ type: 'success' }, capturePolicy.result(prop, resolved)));
+                                return resolved;
+                            }, (error) => {
+                                span === null || span === void 0 ? void 0 : span.end({ type: 'failure', error });
+                                throw error;
+                            });
+                        }
+                        span === null || span === void 0 ? void 0 : span.end(Object.assign({ type: 'success' }, capturePolicy.result(prop, result)));
+                        return result;
+                    }
+                    catch (error) {
+                        span === null || span === void 0 ? void 0 : span.end({ type: 'failure', error });
+                        throw error;
+                    }
+                };
+            }
+            return value;
+        },
+    });
+}
+/**
+ * Invokes an operation through the OperationSpan's `run` wrapper when the
+ * instrumentation returned a span, so it can establish ambient state
+ * (tracing context) around the operation; invokes the operation directly
+ * otherwise.
+ *
+ * @param span The OperationSpan returned by the instrumentation, if any.
+ * @param fn The thunk performing the operation.
+ * @returns The value returned by `fn`.
+ */
+function invokeWithin(span, fn) {
+    return span ? span.run(fn) : fn();
+}
+/**
+ * Resolves the class name of a service instance, or undefined for values
+ * that are not instances of a named class (plain object literals,
+ * null-prototype objects).
+ *
+ * @param thing The service instance to inspect.
+ * @returns The constructor name, or undefined when there is none to report.
+ */
+function classNameOf(thing) {
+    var _a;
+    const name = (_a = thing.constructor) === null || _a === void 0 ? void 0 : _a.name;
+    return name && name !== 'Object' ? name : undefined;
+}
 //# sourceMappingURL=serviceInstrumentation.js.map

package/dist/serviceInstrumentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"serviceInstrumentation.js","sourceRoot":"","sources":["../src/serviceInstrumentation.ts"],"names":[],"mappings":""}
+{"version":3,"file":"serviceInstrumentation.js","sourceRoot":"","sources":["../src/serviceInstrumentation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composed-di/instrumentation-core",
-  "version": "0.6.0-alpha",
+  "version": "0.7.0-alpha",
   "private": false,
   "keywords": [
     "dependency injection",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@composed-di/core": "^0.6.0-alpha"
+    "@composed-di/core": "^0.7.0-alpha"
   },
   "scripts": {
     "build": "tsc --build",

package/src/index.ts

@@ -1,3 +1,2 @@
 export * from './serviceInstrumentation'
-export * from './instrument'
 export * from './redaction'

package/src/redaction.ts

@@ -39,7 +39,7 @@ interface PropertyOverride {
 /**
  * Marks a service — or specific properties of it — as sensitive, so the
  * values flowing through its events are redacted. Passed to
- * {@link instrument} via InstrumentOptions.redactionRules and applied
+ * {@link ServiceInstrumentation.instrument} via the capture options' `redact` list and applied
  * centrally, after the capture flags: values a rule matches are scrubbed
  * before the instrumentation ever sees them, and when capture is off
  * there is nothing to redact. Returned by
@@ -52,17 +52,17 @@ export interface RedactionRule<T> {
   readonly key: ServiceKey<T>
 
   /**
-   * The args to report for a call to `functionName`: unchanged if not
+   * The args to report for a call to `methodName`: unchanged if not
    * redacted, otherwise blanked or run through a custom `maskArgs`.
    */
-  maskArgs(functionName: string, args: readonly unknown[]): readonly unknown[]
+  maskArgs(methodName: string, args: readonly unknown[]): readonly unknown[]
 
   /**
    * The value to report for a method call's success outcome: unchanged
    * if not redacted, otherwise blanked or run through a custom
    * `maskResult`.
    */
-  maskResult(functionName: string, result: unknown): unknown
+  maskResult(methodName: string, result: unknown): unknown
 }
 
 /**
@@ -140,8 +140,8 @@ export class RedactionRuleBuilder<T> {
 
     return {
       key: this.key,
-      maskArgs(functionName, args) {
-        const override = overrides[functionName]
+      maskArgs(methodName, args) {
+        const override = overrides[methodName]
         const redacted = override ? override.redacted : redactAllFlag
         if (!redacted) {
           return args
@@ -154,8 +154,8 @@ export class RedactionRuleBuilder<T> {
             // delegate still sees the call's arity.
             args.map(() => REDACTED_VALUE)
       },
-      maskResult(functionName, result) {
-        const override = overrides[functionName]
+      maskResult(methodName, result) {
+        const override = overrides[methodName]
         const redacted = override ? override.redacted : redactAllFlag
         if (!redacted) {
           return result

package/src/serviceInstrumentation.ts

@@ -1,4 +1,7 @@
-import type { ServiceKey } from '@composed-di/core'
+import { ServiceFactory, ServiceKey, ServiceModule } from '@composed-di/core'
+import type { RedactionRule } from './redaction'
+
+type GenericFactory = ServiceFactory<unknown, readonly ServiceKey<any>[]>
 
 /**
  * A handle representing a single in-flight operation (initialization,
@@ -10,7 +13,7 @@ import type { ServiceKey } from '@composed-di/core'
  * handle, a correlation id) without any bookkeeping to pair concurrent
  * start/finish events.
  */
-export interface EventSpan {
+export interface OperationSpan {
   /**
    * Wrapper around the operation itself. The instrumented factory invokes
    * the operation as `run(() => operation())`, so the instrumentation can
@@ -39,24 +42,24 @@ export interface EventSpan {
    * @param outcome - How the operation finished, and its value or error.
    * @return void
    */
-  end(outcome: EventOutcome): void
+  end(outcome: OperationOutcome): void
 }
 
 /**
- * How an operation finished, delivered to EventSpan.end: `success` may
+ * How an operation finished, delivered to OperationSpan.end: `success` may
  * carry the return or resolved value of a method call (initialize and
  * dispose outcomes never carry one); `failure` carries the error that was
  * thrown or rejected.
  *
- * Whether `value` is present is decided by {@link instrument}, not by the
- * implementation: it is absent unless result capture is enabled in the
- * InstrumentOptions, and holds the redacted value when a redaction rule
- * matches. Implementations must record the value exactly when it is
+ * Whether `value` is present is decided by {@link ServiceInstrumentation.instrument},
+ * not by the implementation: it is absent unless result capture is enabled
+ * in the InstrumentOptions, and holds the redacted value when a redaction
+ * rule matches. Implementations must record the value exactly when it is
  * present (`'value' in outcome` — a captured `undefined` return is
  * delivered as a present `value: undefined`) and must not record any
  * result when it is absent.
  */
-export type EventOutcome =
+export type OperationOutcome =
   | { type: 'success'; value?: unknown }
   | { type: 'failure'; error: unknown }
 
@@ -103,56 +106,349 @@ export interface MethodCallContext {
   /**
    * The name of the method that is being called.
    */
-  functionName: string
+  methodName: string
 
   /**
    * The arguments to report for this call, passed by reference;
    * implementations must not mutate them.
    *
-   * Whether they are present is decided by {@link instrument}, not by the
-   * implementation: absent unless argument capture is enabled in the
-   * InstrumentOptions, and already redacted when a redaction rule matches.
-   * Implementations must record the arguments exactly when present and
-   * must not record any arguments when absent.
+   * Whether they are present is decided by {@link ServiceInstrumentation.instrument},
+   * not by the implementation: absent unless argument capture is enabled in
+   * the InstrumentOptions, and already redacted when a redaction rule
+   * matches. Implementations must record the arguments exactly when present
+   * and must not record any arguments when absent.
    */
   args?: readonly unknown[]
 }
 
 /**
- * Interface for instrumenting services wrapped by {@link instrument}.
- * Implement this interface to observe lifecycle events and method calls
- * of the instrumented services.
+ * What runtime values are delivered to the instrumentation, and how they
+ * are scrubbed first. Nothing is captured by default: values may be large
+ * or contain secrets, and they end up wherever the instrumentation
+ * exports them.
+ */
+export interface CaptureOptions {
+  /**
+   * Deliver method arguments to the instrumentation (as
+   * MethodCallContext.args). When off, the instrumentation never sees the
+   * arguments at all.
+   */
+  arguments?: boolean
+
+  /**
+   * Deliver method call return / resolved values to the instrumentation
+   * (as the success outcome's `value`). When off, the instrumentation
+   * never sees the values at all. Initialize and dispose outcomes never
+   * carry a value: the service instance is not useful information to
+   * report.
+   */
+  results?: boolean
+
+  /**
+   * Per-service redaction applied to whatever the capture flags let
+   * through: matched arguments and success values are blanked (or run
+   * through the rule's custom mask) before the instrumentation sees them.
+   * The capture flags are the primary gate — when capture is off there is
+   * nothing to redact, and rules cannot re-enable delivery.
+   */
+  redact?: readonly RedactionRule<any>[]
+}
+
+/**
+ * Configuration for {@link ServiceInstrumentation.instrument}. Capture
+ * policy lives here, not in the ServiceInstrumentation subclasses: what a
+ * subclass receives is exactly what it is allowed to record, so no
+ * subclass carries its own capture flags or redaction logic.
+ */
+export interface InstrumentOptions {
+  /**
+   * What runtime values (arguments, results) reach the instrumentation,
+   * and the redaction applied to them first. Nothing is captured when
+   * omitted.
+   */
+  capture?: CaptureOptions
+}
+
+/**
+ * Base class for instrumenting services. Extend it and override the hooks
+ * to observe lifecycle events and method calls of the services wrapped by
+ * {@link ServiceInstrumentation.instrument}.
  *
- * Instrumentation is strictly observational: implementations see every
- * operation but must never alter it — see the EventSpan contract.
+ * Instrumentation is strictly observational: subclasses see every
+ * operation but must never alter it — see the OperationSpan contract.
  *
- * Each method is invoked when the corresponding operation starts and may
- * return an EventSpan that is notified when that operation finishes.
+ * Each hook is invoked when the corresponding operation starts and may
+ * return an OperationSpan that is notified when that operation finishes.
  * Returning nothing opts out of completion tracking for that call.
  */
-export interface ServiceInstrumentation {
+export class ServiceInstrumentation {
   /**
    * Invoked at the start of the initialization process for a specific service.
    *
    * @param context - Context of the initialization, including the service key.
-   * @return An EventSpan notified when initialization finishes, or void.
+   * @return An OperationSpan notified when initialization finishes, or void.
    */
-  onInitialize?(context: InitializeContext): EventSpan | void
+  onInitialize?(context: InitializeContext): OperationSpan | void
 
   /**
    * Invoked when the disposal process for a service starts.
    *
    * @param context - Context of the disposal, including the service key.
-   * @return An EventSpan notified when disposal finishes, or void.
+   * @return An OperationSpan notified when disposal finishes, or void.
    */
-  onDispose?(context: DisposeContext): EventSpan | void
+  onDispose?(context: DisposeContext): OperationSpan | void
 
   /**
    * Invoked when a method call starts on a service instance.
    *
    * @param context - Context of the invocation, including the service key,
    * the method name, and its arguments.
-   * @return An EventSpan notified when the call finishes, or void.
+   * @return An OperationSpan notified when the call finishes, or void.
+   */
+  onMethodCall?(context: MethodCallContext): OperationSpan | void
+
+  /**
+   * Wraps service factories so this instrumentation is notified when a
+   * service is initialized or disposed and when a method is called on a
+   * service instance. Service instances are wrapped in a Proxy to observe
+   * method calls, and errors are rethrown after being reported, so
+   * behavior is otherwise unchanged.
+   *
+   * ServiceModule entries are flattened into their factories, so an
+   * already-built module can be instrumented as a whole. Compose the
+   * result with `ServiceModule.from`:
+   *
+   * @example
+   * ```ts
+   * const module = ServiceModule.from(
+   *   otel.instrument([db, cache, api], {
+   *     capture: {
+   *       arguments: true,
+   *       results: true,
+   *       redact: [redactionRule(VaultKey).redact('getSecret').build()],
+   *     },
+   *   }),
+   * );
+   * ```
+   *
+   * @param entries - An array of ServiceModule or factory instances to wrap.
+   * @param options - The capture and redaction policy applied before
+   * anything reaches this instrumentation.
+   * @return The wrapped factories, ready to be passed to ServiceModule.from.
+   */
+  instrument(
+    entries: (ServiceModule | GenericFactory)[],
+    options: InstrumentOptions = {},
+  ): GenericFactory[] {
+    return entries
+      .flatMap((e) => (e instanceof ServiceModule ? e.factories : [e]))
+      .map((factory) => instrumentedServiceFactory(this, options, factory))
+  }
+}
+
+/**
+ * The capture policy of one instrumented factory: resolves what to report
+ * for a call's arguments and result, combining the capture flags with the
+ * factory's redaction rule (if any). This is the single place that
+ * decides visibility — instrumentations record what they receive and
+ * nothing else.
+ */
+interface CapturePolicy {
+  /**
+   * The arguments to deliver in MethodCallContext, or undefined when
+   * argument capture is off.
    */
-  onMethodCall?(context: MethodCallContext): EventSpan | void
+  args(
+    methodName: string,
+    args: readonly unknown[],
+  ): readonly unknown[] | undefined
+
+  /**
+   * The result to deliver with a method call's success outcome: the
+   * (possibly redacted) value, wrapped so spreading it into the outcome
+   * preserves the value-presence contract — a captured `undefined` return
+   * yields `{ value: undefined }` (key present), while capture off yields
+   * undefined (no key at all).
+   */
+  result(methodName: string, value: unknown): { value: unknown } | undefined
+}
+
+function buildCapturePolicy(
+  options: InstrumentOptions,
+  key: ServiceKey<unknown>,
+): CapturePolicy {
+  const capture = options.capture
+  const rule = capture?.redact?.find((r) => r.key === key)
+  const captureArguments = capture?.arguments ?? false
+  const captureResults = capture?.results ?? false
+
+  return {
+    args: (methodName, args) =>
+      captureArguments
+        ? rule
+          ? rule.maskArgs(methodName, args)
+          : args
+        : undefined,
+    result: (methodName, value) =>
+      captureResults
+        ? { value: rule ? rule.maskResult(methodName, value) : value }
+        : undefined,
+  }
+}
+
+/**
+ * Wraps a given service factory with instrumentation to notify a
+ * ServiceInstrumentation of lifecycle events and method calls.
+ *
+ * For each of initialize, dispose, and method calls, the instrumentation
+ * is invoked at the start of the operation and may return an OperationSpan
+ * whose `end` is called with the outcome when the operation finishes.
+ * Errors are rethrown after being reported.
+ *
+ * @param instrumentation The instrumentation to notify.
+ * @param options The capture policy.
+ * @param delegate The original service factory to be instrumented.
+ * @return A new service factory that provides the same dependencies but includes event notification logic.
+ */
+function instrumentedServiceFactory<T, D extends readonly ServiceKey<any>[]>(
+  instrumentation: ServiceInstrumentation,
+  options: InstrumentOptions,
+  delegate: ServiceFactory<any, D>,
+): ServiceFactory<T, D> {
+  const key = delegate.provides
+  const capturePolicy = buildCapturePolicy(options, key)
+
+  return ServiceFactory.singleton({
+    scope: delegate.scope,
+    provides: delegate.provides,
+    dependsOn: delegate.dependsOn,
+    initialize: async (...args) => {
+      const span = instrumentation.onInitialize?.({ key })
+      if (!span) {
+        return delegate.initialize(...args)
+      }
+
+      try {
+        const instance = await span.run(() => delegate.initialize(...args))
+        span.end({ type: 'success' })
+        return observeMethodCalls(instance, instrumentation, key, capturePolicy)
+      } catch (error) {
+        span.end({ type: 'failure', error })
+        throw error
+      }
+    },
+    dispose: () => {
+      const dispose = delegate.dispose
+      if (dispose) {
+        const span = instrumentation.onDispose?.({ key })
+        if (span) {
+          try {
+            span.run(dispose)
+            span.end({ type: 'success' })
+          } catch (error) {
+            span.end({ type: 'failure', error })
+            throw error
+          }
+        } else {
+          dispose()
+        }
+      }
+    },
+  })
+}
+
+/**
+ * Wraps an object with a Proxy to notify the instrumentation of method calls.
+ *
+ * Methods returning a promise report their outcome when the promise
+ * settles, not when the method returns.
+ *
+ * @param thing The object whose method calls need to be observed.
+ * @param instrumentation The instrumentation notified of method call events.
+ * @param key The service key used to identify the service in events.
+ * @param capturePolicy The capture policy deciding what argument and result
+ * values (if any) are delivered with each event.
+ * @return A Proxy wrapping the input object, with all method calls being reported.
+ */
+function observeMethodCalls(
+  thing: any,
+  instrumentation: ServiceInstrumentation,
+  key: ServiceKey<unknown>,
+  capturePolicy: CapturePolicy,
+): any {
+  if (typeof thing !== 'object' || thing === null) {
+    return thing
+  }
+
+  const className = classNameOf(thing)
+
+  return new Proxy(thing, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop)
+      if (typeof value === 'function' && typeof prop === 'string') {
+        return (...args: unknown[]) => {
+          const span = instrumentation.onMethodCall?.({
+            key,
+            className,
+            methodName: prop,
+            args: capturePolicy.args(prop, args),
+          })
+          try {
+            const result = invokeWithin(span, () => value.apply(target, args))
+            if (result instanceof Promise) {
+              return result.then(
+                (resolved) => {
+                  span?.end({
+                    type: 'success',
+                    ...capturePolicy.result(prop, resolved),
+                  })
+                  return resolved
+                },
+                (error) => {
+                  span?.end({ type: 'failure', error })
+                  throw error
+                },
+              )
+            }
+            span?.end({
+              type: 'success',
+              ...capturePolicy.result(prop, result),
+            })
+            return result
+          } catch (error) {
+            span?.end({ type: 'failure', error })
+            throw error
+          }
+        }
+      }
+      return value
+    },
+  })
+}
+
+/**
+ * Invokes an operation through the OperationSpan's `run` wrapper when the
+ * instrumentation returned a span, so it can establish ambient state
+ * (tracing context) around the operation; invokes the operation directly
+ * otherwise.
+ *
+ * @param span The OperationSpan returned by the instrumentation, if any.
+ * @param fn The thunk performing the operation.
+ * @returns The value returned by `fn`.
+ */
+function invokeWithin<T>(span: OperationSpan | void, fn: () => T): T {
+  return span ? span.run(fn) : fn()
+}
+
+/**
+ * Resolves the class name of a service instance, or undefined for values
+ * that are not instances of a named class (plain object literals,
+ * null-prototype objects).
+ *
+ * @param thing The service instance to inspect.
+ * @returns The constructor name, or undefined when there is none to report.
+ */
+function classNameOf(thing: object): string | undefined {
+  const name = thing.constructor?.name
+  return name && name !== 'Object' ? name : undefined
 }

package/src/instrument.ts

@@ -1,285 +0,0 @@
-import { ServiceFactory, ServiceKey, ServiceModule } from '@composed-di/core'
-import type {
-  EventOutcome,
-  EventSpan,
-  ServiceInstrumentation,
-} from './serviceInstrumentation'
-import type { RedactionRule } from './redaction'
-
-type GenericFactory = ServiceFactory<unknown, readonly ServiceKey<any>[]>
-
-/**
- * Configuration for {@link instrument}. Capture policy lives here, not in
- * the ServiceInstrumentation implementations: what an implementation
- * receives is exactly what it is allowed to record, so no implementation
- * carries its own capture flags or redaction logic.
- */
-export interface InstrumentOptions {
-  /**
-   * The instrumentation notified of service lifecycle events and method
-   * calls.
-   */
-  instrumentation: ServiceInstrumentation
-
-  /**
-   * Deliver method arguments to the instrumentation (as
-   * MethodCallContext.args). Off by default: arguments may be large or
-   * contain secrets, and they end up wherever the instrumentation exports
-   * them. When off, the instrumentation never sees the arguments at all.
-   */
-  captureArguments?: boolean
-
-  /**
-   * Deliver method call return / resolved values to the instrumentation
-   * (as the success outcome's `value`). Off by default, for the same
-   * reasons as `captureArguments`. When off, the instrumentation never
-   * sees the values at all. Initialize and dispose outcomes never carry a
-   * value: the service instance is not useful information to report.
-   */
-  captureResults?: boolean
-
-  /**
-   * Per-service redaction applied to whatever the capture flags let
-   * through: matched arguments and success values are blanked (or run
-   * through the rule's custom mask) before the instrumentation sees them.
-   * The capture flags are the primary gate — when capture is off there is
-   * nothing to redact, and rules cannot re-enable delivery.
-   */
-  redactionRules?: readonly RedactionRule<any>[]
-}
-
-/**
- * Wraps service factories with instrumentation, so the given
- * ServiceInstrumentation is notified when a service is initialized or
- * disposed and when a method is called on a service instance, and may
- * return an EventSpan per operation to observe its completion. Service
- * instances are wrapped in a Proxy to observe method calls, and errors
- * are rethrown after being reported, so behavior is otherwise unchanged.
- *
- * ServiceModule entries are flattened into their factories, so an
- * already-built module can be instrumented as a whole. Compose the result
- * with `ServiceModule.from`:
- *
- * @example
- * ```ts
- * const module = ServiceModule.from(
- *   instrument([db, cache, api], {
- *     instrumentation: otel,
- *     captureArguments: true,
- *     captureResults: true,
- *     redactionRules: [redactionRule(VaultKey).redact('getSecret').build()],
- *   }),
- * );
- * ```
- *
- * @param entries - An array of ServiceModule or factory instances to wrap.
- * @param options - The instrumentation to notify, plus the capture and
- * redaction policy applied before anything reaches it.
- * @return The wrapped factories, ready to be passed to ServiceModule.from.
- */
-export function instrument(
-  entries: (ServiceModule | GenericFactory)[],
-  options: InstrumentOptions,
-): GenericFactory[] {
-  return entries
-    .flatMap((e) => (e instanceof ServiceModule ? e.factories : [e]))
-    .map((factory) => makeObservable(options, factory))
-}
-
-/**
- * The capture policy of one instrumented factory: resolves what to report
- * for a call's arguments and a success outcome, combining the capture
- * flags with the factory's redaction rule (if any). This is the single
- * place that decides visibility — instrumentations record what they
- * receive and nothing else.
- */
-interface Capture {
-  /**
-   * The arguments to deliver in MethodCallContext, or undefined when
-   * argument capture is off.
-   */
-  args(
-    functionName: string,
-    args: readonly unknown[],
-  ): readonly unknown[] | undefined
-
-  /**
-   * The success outcome to deliver to EventSpan.end for a method call:
-   * carries the (possibly redacted) value when result capture is on, no
-   * value otherwise.
-   */
-  success(functionName: string, value: unknown): EventOutcome
-}
-
-function makeCapture(
-  options: InstrumentOptions,
-  key: ServiceKey<unknown>,
-): Capture {
-  const rule = options.redactionRules?.find((r) => r.key === key)
-  const captureArguments = options.captureArguments ?? false
-  const captureResults = options.captureResults ?? false
-
-  return {
-    args: (functionName, args) =>
-      captureArguments
-        ? rule
-          ? rule.maskArgs(functionName, args)
-          : args
-        : undefined,
-    success: (functionName, value) =>
-      captureResults
-        ? {
-            type: 'success',
-            value: rule ? rule.maskResult(functionName, value) : value,
-          }
-        : { type: 'success' },
-  }
-}
-
-/**
- * Wraps a given service factory with instrumentation to notify a
- * ServiceInstrumentation of lifecycle events and method calls.
- *
- * For each of initialize, dispose, and method calls, the instrumentation
- * is invoked at the start of the operation and may return an EventSpan
- * whose `end` is called with the outcome when the operation finishes.
- * Errors are rethrown after being reported.
- *
- * @param options The instrumentation to notify and the capture policy.
- * @param delegate The original service factory to be instrumented.
- * @return A new service factory that provides the same dependencies but includes event notification logic.
- */
-function makeObservable<T, D extends readonly ServiceKey<any>[]>(
-  options: InstrumentOptions,
-  delegate: ServiceFactory<any, D>,
-): ServiceFactory<T, D> {
-  const instrumentation = options.instrumentation
-  const key = delegate.provides
-  const capture = makeCapture(options, key)
-
-  return ServiceFactory.singleton({
-    scope: delegate.scope,
-    provides: delegate.provides,
-    dependsOn: delegate.dependsOn,
-    initialize: async (...args) => {
-      const span = instrumentation.onInitialize?.({ key })
-      if (!span) {
-        return delegate.initialize(...args)
-      }
-
-      try {
-        const instance = await span.run(() => delegate.initialize(...args))
-        span.end({ type: 'success' })
-        return observeMethodCalls(instance, instrumentation, key, capture)
-      } catch (error) {
-        span.end({ type: 'failure', error })
-        throw error
-      }
-    },
-    dispose: () => {
-      const dispose = delegate.dispose
-      if (dispose) {
-        const span = instrumentation.onDispose?.({ key })
-        if (span) {
-          try {
-            span.run(dispose)
-            span.end({ type: 'success' })
-          } catch (error) {
-            span.end({ type: 'failure', error })
-            throw error
-          }
-        }
-      }
-    },
-  })
-}
-
-/**
- * Wraps an object with a Proxy to notify the instrumentation of method calls.
- *
- * Methods returning a promise report their outcome when the promise
- * settles, not when the method returns.
- *
- * @param thing The object whose method calls need to be observed.
- * @param instrumentation The instrumentation notified of method call events.
- * @param key The service key used to identify the service in events.
- * @param capture The capture policy deciding what argument and result
- * values (if any) are delivered with each event.
- * @return A Proxy wrapping the input object, with all method calls being reported.
- */
-function observeMethodCalls(
-  thing: any,
-  instrumentation: ServiceInstrumentation,
-  key: ServiceKey<unknown>,
-  capture: Capture,
-): any {
-  if (typeof thing !== 'object' || thing === null) {
-    return thing
-  }
-
-  const className = classNameOf(thing)
-
-  return new Proxy(thing, {
-    get(target, prop) {
-      const value = Reflect.get(target, prop)
-      if (typeof value === 'function' && typeof prop === 'string') {
-        return (...args: unknown[]) => {
-          const span = instrumentation.onMethodCall?.({
-            key,
-            className,
-            functionName: prop,
-            args: capture.args(prop, args),
-          })
-          try {
-            const result = invokeWithin(span, () => value.apply(target, args))
-            if (result instanceof Promise) {
-              return result.then(
-                (resolved) => {
-                  span?.end(capture.success(prop, resolved))
-                  return resolved
-                },
-                (error) => {
-                  span?.end({ type: 'failure', error })
-                  throw error
-                },
-              )
-            }
-            span?.end(capture.success(prop, result))
-            return result
-          } catch (error) {
-            span?.end({ type: 'failure', error })
-            throw error
-          }
-        }
-      }
-      return value
-    },
-  })
-}
-
-/**
- * Invokes an operation through the EventSpan's `run` wrapper when the
- * instrumentation returned a span, so it can establish ambient state
- * (tracing context) around the operation; invokes the operation directly
- * otherwise.
- *
- * @param span The EventSpan returned by the instrumentation, if any.
- * @param fn The thunk performing the operation.
- * @returns The value returned by `fn`.
- */
-function invokeWithin<T>(span: EventSpan | void, fn: () => T): T {
-  return span ? span.run(fn) : fn()
-}
-
-/**
- * Resolves the class name of a service instance, or undefined for values
- * that are not instances of a named class (plain object literals,
- * null-prototype objects).
- *
- * @param thing The service instance to inspect.
- * @returns The constructor name, or undefined when there is none to report.
- */
-function classNameOf(thing: object): string | undefined {
-  const name = thing.constructor?.name
-  return name && name !== 'Object' ? name : undefined
-}