test(node): Add unit tests + changelog for LangChain callback fix

mdnanocom · mdnanocom · commit 92409bd26909 · 2026-05-12T21:00:27.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- fix(node): Preserve `CallbackManager` children when augmenting LangChain callbacks
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
 ## 10.53.1
diff --git a/packages/node/src/integrations/tracing/langchain/instrumentation.ts b/packages/node/src/integrations/tracing/langchain/instrumentation.ts
@@ -4,8 +4,8 @@ import {
   type InstrumentationModuleDefinition,
   InstrumentationNodeModuleDefinition,
   InstrumentationNodeModuleFile,
-} from '@opentelemetry/instrumentation';
-import type { LangChainOptions } from '@sentry/core';
+} from "@opentelemetry/instrumentation";
+import type { LangChainOptions } from "@sentry/core";
 import {
   _INTERNAL_skipAiProviderWrapping,
   ANTHROPIC_AI_INTEGRATION_NAME,
@@ -14,9 +14,9 @@ import {
   instrumentLangChainEmbeddings,
   OPENAI_INTEGRATION_NAME,
   SDK_VERSION,
-} from '@sentry/core';
+} from "@sentry/core";
 
-const supportedVersions = ['>=0.1.0 <2.0.0'];
+const supportedVersions = [">=0.1.0 <2.0.0"];
 
 type LangChainInstrumentationOptions = InstrumentationConfig & LangChainOptions;
 
@@ -37,13 +37,22 @@ function isCallbackManager(value: unknown): value is {
   copy: () => unknown;
   handlers?: unknown[];
 } {
-  if (!value || typeof value !== 'object') {
+  if (!value || typeof value !== "object") {
     return false;
   }
   const candidate = value as { addHandler?: unknown; copy?: unknown };
-  return typeof candidate.addHandler === 'function' && typeof candidate.copy === 'function';
+  return (
+    typeof candidate.addHandler === "function" &&
+    typeof candidate.copy === "function"
+  );
 }
 
+/**
+ * Exported for testing.
+ * @internal
+ */
+export const _INTERNAL_augmentCallbackHandlers = augmentCallbackHandlers;
+
 /**
  * Augments a callback handler list with Sentry's handler if not already present.
  *
@@ -65,7 +74,10 @@ function isCallbackManager(value: unknown): value is {
  * mutate the caller's manager across invocations) and register Sentry's
  * handler as an inheritable child via `.addHandler()`.
  */
-function augmentCallbackHandlers(handlers: unknown, sentryHandler: unknown): unknown {
+function augmentCallbackHandlers(
+  handlers: unknown,
+  sentryHandler: unknown,
+): unknown {
   // Handle null/undefined - return array with just our handler
   if (!handlers) {
     return [sentryHandler];
@@ -122,14 +134,17 @@ function wrapRunnableMethod(
       let options = args[optionsIndex] as Record<string, unknown> | undefined;
 
       // If options don't exist or aren't an object, create them
-      if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      if (!options || typeof options !== "object" || Array.isArray(options)) {
         options = {};
         args[optionsIndex] = options;
       }
 
       // Inject our callback handler into options.callbacks (request time callbacks)
       const existingCallbacks = options.callbacks;
-      const augmentedCallbacks = augmentCallbackHandlers(existingCallbacks, sentryHandler);
+      const augmentedCallbacks = augmentCallbackHandlers(
+        existingCallbacks,
+        sentryHandler,
+      );
       options.callbacks = augmentedCallbacks;
 
       // Call original method with augmented options
@@ -143,7 +158,7 @@ function wrapRunnableMethod(
  */
 export class SentryLangChainInstrumentation extends InstrumentationBase<LangChainInstrumentationOptions> {
   public constructor(config: LangChainInstrumentationOptions = {}) {
-    super('@sentry/instrumentation-langchain', SDK_VERSION, config);
+    super("@sentry/instrumentation-langchain", SDK_VERSION, config);
   }
 
   /**
@@ -153,17 +168,19 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
    * We hook into provider packages (@langchain/anthropic, @langchain/openai, etc.)
    * because @langchain/core is often bundled and not loaded as a separate module
    */
-  public init(): InstrumentationModuleDefinition | InstrumentationModuleDefinition[] {
+  public init():
+    | InstrumentationModuleDefinition
+    | InstrumentationModuleDefinition[] {
     const modules: InstrumentationModuleDefinition[] = [];
 
     // Hook into common LangChain provider packages
     const providerPackages = [
-      '@langchain/anthropic',
-      '@langchain/openai',
-      '@langchain/google-genai',
-      '@langchain/mistralai',
-      '@langchain/google-vertexai',
-      '@langchain/groq',
+      "@langchain/anthropic",
+      "@langchain/openai",
+      "@langchain/google-genai",
+      "@langchain/mistralai",
+      "@langchain/google-vertexai",
+      "@langchain/groq",
     ];
 
     for (const packageName of providerPackages) {
@@ -176,13 +193,13 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
           packageName,
           supportedVersions,
           this._patch.bind(this),
-          exports => exports,
+          (exports) => exports,
           [
             new InstrumentationNodeModuleFile(
               `${packageName}/dist/index.cjs`,
               supportedVersions,
               this._patch.bind(this),
-              exports => exports,
+              (exports) => exports,
             ),
           ],
         ),
@@ -192,17 +209,17 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
     // Hook into main 'langchain' package to catch initChatModel (v1+)
     modules.push(
       new InstrumentationNodeModuleDefinition(
-        'langchain',
+        "langchain",
         supportedVersions,
         this._patch.bind(this),
-        exports => exports,
+        (exports) => exports,
         [
           // To catch the CJS build that contains ConfigurableModel / initChatModel for v1
           new InstrumentationNodeModuleFile(
-            'langchain/dist/chat_models/universal.cjs',
+            "langchain/dist/chat_models/universal.cjs",
             supportedVersions,
             this._patch.bind(this),
-            exports => exports,
+            (exports) => exports,
           ),
         ],
       ),
@@ -215,7 +232,9 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
    * Core patch logic - patches chat model and embedding methods
    * This is called when a LangChain provider package is loaded
    */
-  private _patch(exports: PatchedLangChainExports): PatchedLangChainExports | void {
+  private _patch(
+    exports: PatchedLangChainExports,
+  ): PatchedLangChainExports | void {
     // Skip AI provider wrapping now that LangChain is actually being used
     // This prevents duplicate spans from Anthropic/OpenAI/GoogleGenAI standalone integrations
     _INTERNAL_skipAiProviderWrapping([
@@ -244,22 +263,30 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
    * Patches chat model methods (invoke, stream, batch) to inject Sentry callbacks
    * Finds a chat model class from the provider package exports and patches its prototype methods
    */
-  private _patchRunnableMethods(exports: PatchedLangChainExports, sentryHandler: unknown): void {
+  private _patchRunnableMethods(
+    exports: PatchedLangChainExports,
+    sentryHandler: unknown,
+  ): void {
     // Known chat model class names for each provider
     const knownChatModelNames = [
-      'ChatAnthropic',
-      'ChatOpenAI',
-      'ChatGoogleGenerativeAI',
-      'ChatMistralAI',
-      'ChatVertexAI',
-      'ChatGroq',
-      'ConfigurableModel',
+      "ChatAnthropic",
+      "ChatOpenAI",
+      "ChatGoogleGenerativeAI",
+      "ChatMistralAI",
+      "ChatVertexAI",
+      "ChatGroq",
+      "ConfigurableModel",
     ];
 
-    const exportsToPatch = (exports.universal_exports ?? exports) as Record<string, unknown>;
+    const exportsToPatch = (exports.universal_exports ?? exports) as Record<
+      string,
+      unknown
+    >;
 
-    const chatModelClass = Object.values(exportsToPatch).find(exp => {
-      return typeof exp === 'function' && knownChatModelNames.includes(exp.name);
+    const chatModelClass = Object.values(exportsToPatch).find((exp) => {
+      return (
+        typeof exp === "function" && knownChatModelNames.includes(exp.name)
+      );
     }) as { prototype: unknown; name: string } | undefined;
 
     if (!chatModelClass) {
@@ -277,11 +304,11 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
 
     // Patch the methods (invoke, stream, batch)
     // All chat model instances will inherit these patched methods
-    const methodsToPatch = ['invoke', 'stream', 'batch'] as const;
+    const methodsToPatch = ["invoke", "stream", "batch"] as const;
 
     for (const methodName of methodsToPatch) {
       const method = targetProto[methodName];
-      if (typeof method === 'function') {
+      if (typeof method === "function") {
         targetProto[methodName] = wrapRunnableMethod(
           method as (...args: unknown[]) => unknown,
           sentryHandler,
@@ -299,15 +326,24 @@ export class SentryLangChainInstrumentation extends InstrumentationBase<LangChai
    *
    * Instruments any exported class whose prototype has both embedQuery and embedDocuments as functions.
    */
-  private _patchEmbeddingsMethods(exports: PatchedLangChainExports, options: LangChainOptions): void {
-    const exportsToPatch = (exports.universal_exports ?? exports) as Record<string, unknown>;
+  private _patchEmbeddingsMethods(
+    exports: PatchedLangChainExports,
+    options: LangChainOptions,
+  ): void {
+    const exportsToPatch = (exports.universal_exports ?? exports) as Record<
+      string,
+      unknown
+    >;
 
     for (const exp of Object.values(exportsToPatch)) {
-      if (typeof exp !== 'function' || !exp.prototype) {
+      if (typeof exp !== "function" || !exp.prototype) {
         continue;
       }
       const proto = exp.prototype as Record<string, unknown>;
-      if (typeof proto.embedQuery !== 'function' || typeof proto.embedDocuments !== 'function') {
+      if (
+        typeof proto.embedQuery !== "function" ||
+        typeof proto.embedDocuments !== "function"
+      ) {
         continue;
       }
       if (proto.__sentry_patched__) {
diff --git a/packages/node/test/integrations/tracing/langchain.test.ts b/packages/node/test/integrations/tracing/langchain.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, test, vi } from "vitest";
+import { _INTERNAL_augmentCallbackHandlers } from "../../../src/integrations/tracing/langchain/instrumentation";
+
+const sentryHandler = { name: "SentryCallbackHandler" };
+
+/**
+ * Minimal `CallbackManager` stand-in. We only need the duck-typed shape
+ * (`addHandler` + `copy`) for the production code to recognize this as a
+ * `CallbackManager` rather than fall through to the "unknown" branch.
+ */
+function makeFakeCallbackManager(existingHandlers: unknown[] = []) {
+  const manager = {
+    handlers: [...existingHandlers],
+    addHandler: vi.fn(function (
+      this: any,
+      handler: unknown,
+      _inherit?: boolean,
+    ) {
+      this.handlers.push(handler);
+    }),
+    copy: vi.fn(function (this: any) {
+      return makeFakeCallbackManager(this.handlers);
+    }),
+  };
+  return manager;
+}
+
+describe("augmentCallbackHandlers", () => {
+  test("wraps Sentry handler in an array when no callbacks are configured", () => {
+    const result = _INTERNAL_augmentCallbackHandlers(undefined, sentryHandler);
+    expect(result).toEqual([sentryHandler]);
+  });
+
+  test("appends Sentry handler when callbacks is already an array", () => {
+    const other = { name: "OtherHandler" };
+    const result = _INTERNAL_augmentCallbackHandlers([other], sentryHandler);
+    expect(result).toEqual([other, sentryHandler]);
+  });
+
+  test("is idempotent when Sentry handler is already in the array", () => {
+    const result = _INTERNAL_augmentCallbackHandlers(
+      [sentryHandler],
+      sentryHandler,
+    );
+    expect(result).toEqual([sentryHandler]);
+  });
+
+  test("preserves inheritable handlers when callbacks is a CallbackManager", () => {
+    // Reproduces the LangGraph `streamMode: ['messages']` setup: a
+    // CallbackManager carrying a StreamMessagesHandler is passed via
+    // options.callbacks. Without this fix, the manager would be wrapped as
+    // `[manager, sentryHandler]`, dropping all its inheritable children.
+    const streamMessagesHandler = {
+      name: "StreamMessagesHandler",
+      lc_prefer_streaming: true,
+    };
+    const manager = makeFakeCallbackManager([streamMessagesHandler]);
+
+    const result = _INTERNAL_augmentCallbackHandlers(
+      manager,
+      sentryHandler,
+    ) as {
+      handlers: unknown[];
+    };
+
+    // The result is a manager (object), not a wrapping array.
+    expect(Array.isArray(result)).toBe(false);
+    // The original child handler is still there alongside Sentry's.
+    expect(result.handlers).toEqual([streamMessagesHandler, sentryHandler]);
+  });
+
+  test("copies the manager rather than mutating the caller-supplied one", () => {
+    // If we mutated the original manager, repeated invocations would
+    // accumulate Sentry handlers (and tracers from prior runs would leak
+    // into subsequent unrelated runs).
+    const manager = makeFakeCallbackManager([]);
+    _INTERNAL_augmentCallbackHandlers(manager, sentryHandler);
+    expect(manager.copy).toHaveBeenCalledTimes(1);
+    expect(manager.handlers).toEqual([]);
+  });
+
+  test("does not double-register Sentry handler when copy already contains it", () => {
+    const manager = makeFakeCallbackManager([sentryHandler]);
+    const result = _INTERNAL_augmentCallbackHandlers(
+      manager,
+      sentryHandler,
+    ) as {
+      handlers: unknown[];
+      addHandler: ReturnType<typeof vi.fn>;
+    };
+    expect(result.handlers).toEqual([sentryHandler]);
+    expect(result.addHandler).not.toHaveBeenCalled();
+  });
+
+  test("returns the value unchanged when it is neither an array nor a CallbackManager", () => {
+    const opaque = { name: "NotAManager" };
+    const result = _INTERNAL_augmentCallbackHandlers(opaque, sentryHandler);
+    expect(result).toBe(opaque);
+  });
+});
