@composed-di/instrumentation-core 0.6.0-alpha

package/dist/serviceInstrumentation.d.ts.map

@@ -0,0 +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"}

package/dist/serviceInstrumentation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=serviceInstrumentation.js.map

package/dist/serviceInstrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceInstrumentation.js","sourceRoot":"","sources":["../src/serviceInstrumentation.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@composed-di/instrumentation-core",
+  "version": "0.6.0-alpha",
+  "private": false,
+  "keywords": [
+    "dependency injection",
+    "di",
+    "instrumentation",
+    "observability",
+    "tracing"
+  ],
+  "license": "MIT",
+  "author": "Juan Herrera juanhr454@gmail.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imherrera/composed-di.git",
+    "directory": "packages/instrumentation-core"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@composed-di/core": "^0.6.0-alpha"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean"
+  }
+}

package/src/index.ts

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

package/src/instrument.ts

@@ -0,0 +1,285 @@
+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
+}

package/src/redaction.ts

@@ -0,0 +1,173 @@
+import type { ServiceKey } from '@composed-di/core'
+
+/**
+ * The placeholder that replaces a redacted value when no custom
+ * transform is given for it.
+ */
+export const REDACTED_VALUE = '[REDACTED]'
+
+/**
+ * Custom masking for one included property, narrowed to the exact
+ * method named when {@link RedactionRuleBuilder.redact} is called.
+ * Omitting a side fully blanks it with {@link REDACTED_VALUE}; providing
+ * one lets you report a partial mask instead (e.g. the last 4 digits of
+ * a card number) — both always return a `string`, the masked
+ * representation to report in place of the real value.
+ */
+export type Mask<T, K extends Extract<keyof T, string>> = T[K] extends (
+  ...args: infer A
+) => infer R
+  ? {
+      maskArgs?: (...args: A) => string
+      maskResult?: (result: R) => string
+    }
+  : never
+
+/**
+ * Per-property override, layered on top of a rule's `redactAll` default.
+ * `redacted: true` (from {@link RedactionRuleBuilder.redact}) redacts
+ * that property, optionally with a custom mask; `redacted: false` (from
+ * {@link RedactionRuleBuilder.exclude}) forces it to be left untouched
+ * regardless of `redactAll`.
+ */
+interface PropertyOverride {
+  redacted: boolean
+  maskArgs?: (...args: any[]) => string
+  maskResult?: (result: any) => string
+}
+
+/**
+ * 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
+ * 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
+ * {@link RedactionRuleBuilder.build}, which is the only way to construct
+ * one — the `redactAll`/per-property merge logic lives entirely inside
+ * `maskArgs`/`maskResult`, so callers never need to know how a rule
+ * reached its decision, only what to do with it.
+ */
+export interface RedactionRule<T> {
+  readonly key: ServiceKey<T>
+
+  /**
+   * The args to report for a call to `functionName`: unchanged if not
+   * redacted, otherwise blanked or run through a custom `maskArgs`.
+   */
+  maskArgs(functionName: 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
+}
+
+/**
+ * Fluent, single-key rule builder returned by {@link redactionRule}.
+ * `redactAll`, `redact`, and `exclude` all merge into the same rule —
+ * call them in any combination, in any order; the more specific
+ * per-property calls (`redact`/`exclude`) always win over the blanket
+ * `redactAll` default for the properties they name.
+ *
+ * @example
+ * ```ts
+ * const rules = [
+ *   redactionRule(SecretClientKey)
+ *     .redactAll()
+ *     .build(), // whole service is sensitive
+ *   redactionRule(BillingKey)
+ *     .redactAll()
+ *     .redact('chargeCard', { maskResult: (card) => `card ending in ${card.number.slice(-4)}` })
+ *     .exclude('ping') // redact everything except this, with one custom mask
+ *     .build(),
+ *   redactionRule(VaultKey)
+ *     .redact('getSecret')
+ *     .build(), // only this call, nothing else
+ * ];
+ * ```
+ */
+export class RedactionRuleBuilder<T> {
+  private redactAllFlag = false
+  private hasRedact = false
+  private readonly overrides: Record<string, PropertyOverride> = {}
+
+  constructor(private readonly key: ServiceKey<T>) {}
+
+  /** Redacts every property by default. */
+  redactAll(): this {
+    this.redactAllFlag = true
+    this.hasRedact = true
+    return this
+  }
+
+  /**
+   * Marks one property (method) as redacted, with optional custom
+   * masking. Call repeatedly for several properties. Overrides
+   * `redactAll`/`exclude` for this specific property.
+   */
+  redact<K extends Extract<keyof T, string>>(name: K, mask?: Mask<T, K>): this {
+    this.overrides[name] = { redacted: true, ...mask }
+    this.hasRedact = true
+    return this
+  }
+
+  /**
+   * Marks one or more properties as explicitly NOT redacted, overriding
+   * `redactAll` for just these.
+   */
+  exclude(...names: Extract<keyof T, string>[]): this {
+    for (const name of names) {
+      this.overrides[name] = { redacted: false }
+    }
+    return this
+  }
+
+  build(): RedactionRule<any> {
+    // `exclude` alone never redacts anything — at least one call to
+    // `redactAll`/`redact` is required for this rule to have any effect.
+    if (!this.hasRedact) {
+      throw new Error(
+        `redactionRule(${this.key.name}) has no effect: call .redactAll() and/or .redact(...) ` +
+          'before .build() — .exclude() alone never redacts anything.',
+      )
+    }
+
+    const redactAllFlag = this.redactAllFlag
+    const overrides = this.overrides
+
+    return {
+      key: this.key,
+      maskArgs(functionName, args) {
+        const override = overrides[functionName]
+        const redacted = override ? override.redacted : redactAllFlag
+        if (!redacted) {
+          return args
+        }
+        return override?.maskArgs
+          ? // A custom mask reports one string for the whole call,
+            // rather than a value per argument.
+            [override.maskArgs(...args)]
+          : // Replace each argument rather than the whole array, so the
+            // delegate still sees the call's arity.
+            args.map(() => REDACTED_VALUE)
+      },
+      maskResult(functionName, result) {
+        const override = overrides[functionName]
+        const redacted = override ? override.redacted : redactAllFlag
+        if (!redacted) {
+          return result
+        }
+        return override?.maskResult
+          ? override.maskResult(result)
+          : REDACTED_VALUE
+      },
+    } as RedactionRule<any>
+  }
+}
+
+export function redactionRule<T>(key: ServiceKey<T>): RedactionRuleBuilder<T> {
+  return new RedactionRuleBuilder(key)
+}

package/src/serviceInstrumentation.ts

@@ -0,0 +1,158 @@
+import type { ServiceKey } from '@composed-di/core'
+
+/**
+ * A handle representing a single in-flight operation (initialization,
+ * disposal, or method call), returned by a ServiceInstrumentation when the
+ * operation starts.
+ *
+ * `end` is invoked exactly once when the operation finishes, so
+ * implementations can close over per-call state (a start time, a span
+ * handle, a correlation id) without any bookkeeping to pair concurrent
+ * start/finish events.
+ */
+export interface EventSpan {
+  /**
+   * Wrapper around the operation itself. The instrumented factory invokes
+   * the operation as `run(() => operation())`, so the instrumentation can
+   * establish ambient state that the operation body and its async
+   * continuations inherit — this is what lets spans of nested service
+   * calls form a parent-child hierarchy.
+   *
+   * Implementations must invoke `fn` exactly once, synchronously, and
+   * return its result unchanged (for async operations, the promise itself).
+   * `end` is still delivered separately when the operation finishes.
+   *
+   * @param fn - A thunk that performs the operation.
+   * @return The value returned by `fn`.
+   */
+  run<T>(fn: () => T): T
+
+  /**
+   * Invoked exactly once when the operation finishes, whether it succeeded
+   * or failed. For methods that return a promise, this fires when the
+   * promise settles, not when the method returns. On failure, the error is
+   * rethrown to the caller after this is invoked.
+   *
+   * Whether to retain or log the outcome is the implementation's choice;
+   * values are passed by reference, so implementations must not mutate them.
+   *
+   * @param outcome - How the operation finished, and its value or error.
+   * @return void
+   */
+  end(outcome: EventOutcome): void
+}
+
+/**
+ * How an operation finished, delivered to EventSpan.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
+ * 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 =
+  | { type: 'success'; value?: unknown }
+  | { type: 'failure'; error: unknown }
+
+/**
+ * Context of a service initialization, delivered to onInitialize.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface InitializeContext {
+  /**
+   * The unique identifier of the service that is being initialized.
+   */
+  key: ServiceKey<unknown>
+}
+
+/**
+ * Context of a service disposal, delivered to onDispose.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface DisposeContext {
+  /**
+   * The unique identifier of the service that is being disposed.
+   */
+  key: ServiceKey<unknown>
+}
+
+/**
+ * Context of a method invocation, delivered to onMethodCall.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface MethodCallContext {
+  /**
+   * The unique identifier of the service the method belongs to.
+   */
+  key: ServiceKey<unknown>
+
+  /**
+   * The name of the class implementing the service (the instance's
+   * constructor name), which may differ from `key.name`. Undefined for
+   * services that are not instances of a named class, such as plain
+   * object literals.
+   */
+  className?: string
+
+  /**
+   * The name of the method that is being called.
+   */
+  functionName: 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.
+   */
+  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.
+ *
+ * Instrumentation is strictly observational: implementations see every
+ * operation but must never alter it — see the EventSpan contract.
+ *
+ * Each method is invoked when the corresponding operation starts and may
+ * return an EventSpan that is notified when that operation finishes.
+ * Returning nothing opts out of completion tracking for that call.
+ */
+export interface 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.
+   */
+  onInitialize?(context: InitializeContext): EventSpan | 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.
+   */
+  onDispose?(context: DisposeContext): EventSpan | 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.
+   */
+  onMethodCall?(context: MethodCallContext): EventSpan | void
+}