feat(instrumentation): add util to execute span customization hook in base class

CHANGELOG.md

@@ -11,6 +11,7 @@ For experimental package changes, see the [experimental CHANGELOG](experimental/
 
 ### :rocket: (Enhancement)
 
+* feat(instrumentation): add util to execute instrumentation event hook in base class [#4663](https://github.com/open-telemetry/opentelemetry-js/pull/4663) @blumamir
 * feat: support node 22 [#4666](https://github.com/open-telemetry/opentelemetry-js/pull/4666) @dyladan
 
 ### :bug: (Bug Fix)

experimental/packages/opentelemetry-instrumentation/src/instrumentation.ts

@@ -23,13 +23,15 @@ import {
   trace,
   Tracer,
   TracerProvider,
+  Span,
 } from '@opentelemetry/api';
 import { Logger, LoggerProvider, logs } from '@opentelemetry/api-logs';
 import * as shimmer from 'shimmer';
 import {
   InstrumentationModuleDefinition,
   Instrumentation,
   InstrumentationConfig,
+  InstrumentationEventHook,
 } from './types';
 
 /**
@@ -173,4 +175,33 @@ export abstract class InstrumentationAbstract implements Instrumentation {
     | InstrumentationModuleDefinition
     | InstrumentationModuleDefinition[]
     | void;
+
+  /**
+   * Execute instrumentation event hook, if configured, and log any errors.
+   * Any semantics of the event type and eventInfo are defined by the specific instrumentation.
+   * @param hookHandler The optional hook handler which the user has configured via instrumentation config\
+   * @param eventName The name of the event being triggered, for logging purposes
+   * @param span The span to which the hook should be applied
+   * @param eventInfo The event info to be passed to the hook
+   */
+  protected _runInstrumentationEventHook<EventInfoType>(
+    hookHandler: InstrumentationEventHook<EventInfoType> | undefined,
+    eventName: string,
+    span: Span,
+    eventInfo: EventInfoType
+  ) {
+    if (!hookHandler) {
+      return;
+    }
+
+    try {
+      hookHandler(span, eventInfo);
+    } catch (e) {
+      this._diag.error(
+        `Error running instrumentation event hook for event due to exception in handler`,
+        { eventName },
+        e
+      );
+    }
+  }
 }

experimental/packages/opentelemetry-instrumentation/src/types.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { TracerProvider, MeterProvider } from '@opentelemetry/api';
+import { TracerProvider, MeterProvider, Span } from '@opentelemetry/api';
 import { LoggerProvider } from '@opentelemetry/api-logs';
 
 /** Interface Instrumentation to apply patch. */
@@ -127,3 +127,24 @@ export interface InstrumentationModuleDefinition {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   unpatch?: (moduleExports: any, moduleVersion?: string) => void;
 }
+
+/**
+ * InstrumentationEventHook is a common way for instrumentations to expose extension points
+ * where users can add custom behavior to a span.
+ * This is an advanced feature, commonly used to add additional or non spec compliant attributes to the span,
+ * capture payloads, modify the span in some way, or carry some other side effect.
+ *
+ * The hook is registered with the instrumentation specific config by implementing an handler function with this signature,
+ * and if the hook is present it will be called with the span and the event information
+ * when the event is emitted.
+ *
+ * The event semantics - when and under what conditions the hook is called and what information is passed
+ * in the eventInfo object, is specific to each instrumentation and event and should be documented
+ * where it is used.
+ *
+ * Instrumentation may define multiple hooks, for different spans, or different events on a span.
+ */
+export type InstrumentationEventHook<EventInfoType> = (
+  span: Span,
+  eventInfo: EventInfoType
+) => void;

experimental/packages/opentelemetry-instrumentation/test/common/Instrumentation.test.ts

@@ -19,6 +19,7 @@ import {
   Instrumentation,
   InstrumentationBase,
   InstrumentationConfig,
+  InstrumentationEventHook,
   InstrumentationModuleDefinition,
 } from '../../src';
 
@@ -36,6 +37,12 @@ class TestInstrumentation extends InstrumentationBase {
   override enable() {}
   override disable() {}
   init() {}
+
+  // the runInstrumentationEventHook, so we have to invoke it from the class for testing
+  testRunHook(hookHandler?: InstrumentationEventHook<any>) {
+    const span = this.tracer.startSpan('test');
+    this._runInstrumentationEventHook(hookHandler, 'test', span, {});
+  }
 }
 
 describe('BaseInstrumentation', () => {
@@ -182,5 +189,30 @@ describe('BaseInstrumentation', () => {
 
       assert.deepStrictEqual(instrumentation.getModuleDefinitions(), []);
     });
+
+    describe('runInstrumentationEventHook', () => {
+      it('should call the hook', () => {
+        const instrumentation = new TestInstrumentation({});
+        let called = false;
+        const hook = () => {
+          called = true;
+        };
+        instrumentation.testRunHook(hook);
+        assert.strictEqual(called, true);
+      });
+
+      it('empty hook should work', () => {
+        const instrumentation = new TestInstrumentation({});
+        instrumentation.testRunHook(undefined);
+      });
+
+      it('exception in hook should not crash', () => {
+        const instrumentation = new TestInstrumentation({});
+        const hook = () => {
+          throw new Error('test');
+        };
+        instrumentation.testRunHook(hook);
+      });
+    });
   });
 });