From ed2098b7007d0f51b6b0e6abf481fbbc4d33e691 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 22 Jul 2026 11:41:03 +0200 Subject: [PATCH] feat(core): Add `instrumentStateGraph` API `instrumentLangGraph` only instruments the `StateGraph` class, which is confusing now that there is a separate `instrumentCreateReactAgent` API. Add `instrumentStateGraph` as the new name and keep `instrumentLangGraph` as a deprecated alias so this change is non-breaking on v10. Ref #20584 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../suites/tracing/langgraph/index.ts | 2 +- packages/astro/src/index.server.ts | 2 ++ packages/aws-serverless/src/index.ts | 2 ++ packages/bun/src/index.ts | 2 ++ packages/cloudflare/src/index.ts | 2 ++ packages/core/src/server-exports.ts | 2 ++ packages/core/src/tracing/langgraph/index.ts | 14 ++++++++--- .../core/test/lib/tracing/langgraph.test.ts | 23 ++++++++++++++++++- packages/elysia/src/index.ts | 2 ++ packages/google-cloud-serverless/src/index.ts | 2 ++ packages/node/src/index.ts | 2 ++ .../tracing/langgraph/instrumentation.ts | 4 ++-- packages/remix/src/server/index.ts | 2 ++ packages/sveltekit/src/server/index.ts | 2 ++ packages/vercel-edge/src/index.ts | 2 ++ 15 files changed, 58 insertions(+), 7 deletions(-) diff --git a/dev-packages/cloudflare-integration-tests/suites/tracing/langgraph/index.ts b/dev-packages/cloudflare-integration-tests/suites/tracing/langgraph/index.ts index 0153302d598c..2c021727fcc6 100644 --- a/dev-packages/cloudflare-integration-tests/suites/tracing/langgraph/index.ts +++ b/dev-packages/cloudflare-integration-tests/suites/tracing/langgraph/index.ts @@ -53,7 +53,7 @@ export default Sentry.withSentry( .addEdge(START, 'agent') .addEdge('agent', END); - Sentry.instrumentLangGraph(graph, { recordInputs: true, recordOutputs: true }); + Sentry.instrumentStateGraph(graph, { recordInputs: true, recordOutputs: true }); const compiled = graph.compile({ name: 'weather_assistant' }); diff --git a/packages/astro/src/index.server.ts b/packages/astro/src/index.server.ts index 7be3132e0fd4..c4e312d60274 100644 --- a/packages/astro/src/index.server.ts +++ b/packages/astro/src/index.server.ts @@ -158,6 +158,8 @@ export { instrumentAnthropicAiClient, instrumentGoogleGenAIClient, instrumentLangChainEmbeddings, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/aws-serverless/src/index.ts b/packages/aws-serverless/src/index.ts index 5b7b9ebafeb8..0457275e2f34 100644 --- a/packages/aws-serverless/src/index.ts +++ b/packages/aws-serverless/src/index.ts @@ -140,6 +140,8 @@ export { instrumentOpenAiClient, instrumentAnthropicAiClient, instrumentGoogleGenAIClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/bun/src/index.ts b/packages/bun/src/index.ts index 3e174941751c..f5d4788de639 100644 --- a/packages/bun/src/index.ts +++ b/packages/bun/src/index.ts @@ -158,6 +158,8 @@ export { instrumentOpenAiClient, instrumentAnthropicAiClient, instrumentGoogleGenAIClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/cloudflare/src/index.ts b/packages/cloudflare/src/index.ts index 20a537c5b307..d163dd351bec 100644 --- a/packages/cloudflare/src/index.ts +++ b/packages/cloudflare/src/index.ts @@ -112,6 +112,8 @@ export { metrics, withStreamedSpan, spanStreamingIntegration, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentCreateReactAgent, } from '@sentry/core'; diff --git a/packages/core/src/server-exports.ts b/packages/core/src/server-exports.ts index 63a7b1b0398f..3ecde66cc323 100644 --- a/packages/core/src/server-exports.ts +++ b/packages/core/src/server-exports.ts @@ -101,6 +101,8 @@ export type { LangChainOptions, LangChainIntegration } from './tracing/langchain export { instrumentStateGraphCompile, instrumentCreateReactAgent, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentCompiledGraphInvoke, _INTERNAL_getLangGraphCreateAgentSpanOptions, diff --git a/packages/core/src/tracing/langgraph/index.ts b/packages/core/src/tracing/langgraph/index.ts index daf2f55552ea..7a78e952758a 100644 --- a/packages/core/src/tracing/langgraph/index.ts +++ b/packages/core/src/tracing/langgraph/index.ts @@ -328,7 +328,7 @@ export function instrumentCreateReactAgent( * * @example * ```typescript - * import { instrumentLangGraph } from '@sentry/cloudflare'; + * import { instrumentStateGraph } from '@sentry/cloudflare'; * import { StateGraph } from '@langchain/langgraph'; * * const graph = new StateGraph(MessagesAnnotation) @@ -336,12 +336,12 @@ export function instrumentCreateReactAgent( * .addEdge(START, 'agent') * .addEdge('agent', END); * - * instrumentLangGraph(graph, { recordInputs: true, recordOutputs: true }); + * instrumentStateGraph(graph, { recordInputs: true, recordOutputs: true }); * const compiled = graph.compile({ name: 'my_agent' }); * ``` */ // eslint-disable-next-line @typescript-eslint/no-explicit-any -export function instrumentLangGraph any }>( +export function instrumentStateGraph any }>( stateGraph: T, options?: LangGraphOptions, ): T { @@ -349,3 +349,11 @@ export function instrumentLangGraph any return stateGraph; } + +/** + * Directly instruments a StateGraph instance to add tracing spans. + * + * @deprecated This function was renamed and will be removed in a future major version. + * Use `instrumentStateGraph` instead. + */ +export const instrumentLangGraph = instrumentStateGraph; diff --git a/packages/core/test/lib/tracing/langgraph.test.ts b/packages/core/test/lib/tracing/langgraph.test.ts index 6cbd6ff2fdcb..34c859882387 100644 --- a/packages/core/test/lib/tracing/langgraph.test.ts +++ b/packages/core/test/lib/tracing/langgraph.test.ts @@ -1,5 +1,10 @@ import { describe, expect, it } from 'vitest'; -import { instrumentCreateReactAgent, instrumentStateGraphCompile } from '../../../src/tracing/langgraph'; +import { + instrumentCreateReactAgent, + instrumentLangGraph, + instrumentStateGraph, + instrumentStateGraphCompile, +} from '../../../src/tracing/langgraph'; describe('langgraph double-patch guard', () => { it('instrumentStateGraphCompile returns the same wrapper when applied twice', () => { @@ -16,3 +21,19 @@ describe('langgraph double-patch guard', () => { expect(second).toBe(first); }); }); + +describe('instrumentStateGraph', () => { + it('wraps the compile method of a StateGraph instance and returns the same instance', () => { + const originalCompile = () => ({}); + const stateGraph = { compile: originalCompile }; + + const result = instrumentStateGraph(stateGraph); + + expect(result).toBe(stateGraph); + expect(stateGraph.compile).not.toBe(originalCompile); + }); + + it('exposes instrumentLangGraph as a deprecated alias for instrumentStateGraph', () => { + expect(instrumentLangGraph).toBe(instrumentStateGraph); + }); +}); diff --git a/packages/elysia/src/index.ts b/packages/elysia/src/index.ts index 63a80ae7e81a..01c65856747c 100644 --- a/packages/elysia/src/index.ts +++ b/packages/elysia/src/index.ts @@ -136,6 +136,8 @@ export { instrumentOpenAiClient, instrumentAnthropicAiClient, instrumentGoogleGenAIClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/google-cloud-serverless/src/index.ts b/packages/google-cloud-serverless/src/index.ts index e37ed3c5b559..40753c794073 100644 --- a/packages/google-cloud-serverless/src/index.ts +++ b/packages/google-cloud-serverless/src/index.ts @@ -138,6 +138,8 @@ export { instrumentOpenAiClient, instrumentAnthropicAiClient, instrumentGoogleGenAIClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/node/src/index.ts b/packages/node/src/index.ts index 70a52d1c5b27..4fcbad7f7d1c 100644 --- a/packages/node/src/index.ts +++ b/packages/node/src/index.ts @@ -151,6 +151,8 @@ export { spanStreamingIntegration, createLangChainCallbackHandler, instrumentLangChainEmbeddings, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, } from '@sentry/core'; diff --git a/packages/node/src/integrations/tracing/langgraph/instrumentation.ts b/packages/node/src/integrations/tracing/langgraph/instrumentation.ts index 6f091a32711e..b41bc4f16b65 100644 --- a/packages/node/src/integrations/tracing/langgraph/instrumentation.ts +++ b/packages/node/src/integrations/tracing/langgraph/instrumentation.ts @@ -6,7 +6,7 @@ import { } from '@opentelemetry/instrumentation'; import { InstrumentationNodeModuleFile } from '../InstrumentationNodeModuleFile'; import type { CompiledGraph, LangGraphOptions } from '@sentry/core'; -import { getClient, instrumentCreateReactAgent, instrumentLangGraph, SDK_VERSION } from '@sentry/core'; +import { getClient, instrumentCreateReactAgent, instrumentStateGraph, SDK_VERSION } from '@sentry/core'; const supportedVersions = ['>=0.0.0 <2.0.0']; @@ -100,7 +100,7 @@ export class SentryLangGraphInstrumentation extends InstrumentationBase unknown }, options); + instrumentStateGraph(exports.StateGraph.prototype as { compile: (...args: unknown[]) => unknown }, options); } // Patch createReactAgent to instrument agent creation and invocation diff --git a/packages/remix/src/server/index.ts b/packages/remix/src/server/index.ts index eaca7585db42..1a3d4b0be24f 100644 --- a/packages/remix/src/server/index.ts +++ b/packages/remix/src/server/index.ts @@ -125,6 +125,8 @@ export { instrumentOpenAiClient, instrumentAnthropicAiClient, instrumentGoogleGenAIClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/sveltekit/src/server/index.ts b/packages/sveltekit/src/server/index.ts index 2c712e9f7a4a..861c0bf70a37 100644 --- a/packages/sveltekit/src/server/index.ts +++ b/packages/sveltekit/src/server/index.ts @@ -127,6 +127,8 @@ export { instrumentOpenAiClient, instrumentAnthropicAiClient, instrumentGoogleGenAIClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentStateGraphCompile, zodErrorsIntegration, diff --git a/packages/vercel-edge/src/index.ts b/packages/vercel-edge/src/index.ts index b7eb963d4f6c..81da79c2877a 100644 --- a/packages/vercel-edge/src/index.ts +++ b/packages/vercel-edge/src/index.ts @@ -74,6 +74,8 @@ export { // eslint-disable-next-line typescript/no-deprecated inboundFiltersIntegration, instrumentOpenAiClient, + instrumentStateGraph, + // eslint-disable-next-line typescript/no-deprecated instrumentLangGraph, instrumentGoogleGenAIClient, instrumentAnthropicAiClient,