ref(core): Introduce instrumented method registry for AI integrations (#19981)

Replace the shared `getOperationName()` function with per-provider
method registries that map API paths to their operation name and
streaming behavior. This explicitly couples the instrumented methods and
necessary metadata in one place instead of having convoluted substring
matching in multiple places that can be quite hard to reason about.

Closes #19987 (added automatically)

Author: nicohrubec

packages/core/src/tracing/ai/utils.ts

@@ -17,6 +17,24 @@ export interface AIRecordingOptions {
   recordOutputs?: boolean;
 }
 
+/**
+ * A method registry entry describes a single instrumented method:
+ * which gen_ai operation it maps to and whether it is intrinsically streaming.
+ */
+export interface InstrumentedMethodEntry {
+  /** Operation name (e.g. 'chat', 'embeddings', 'generate_content') */
+  operation: string;
+  /** True if the method itself is always streaming (not param-based) */
+  streaming?: boolean;
+}
+
+/**
+ * Maps method paths to their registry entries.
+ * Used by proxy-based AI client instrumentations to determine which methods
+ * to instrument, what operation name to use, and whether they stream.
+ */
+export type InstrumentedMethodRegistry = Record<string, InstrumentedMethodEntry>;
+
 /**
  * Resolves AI recording options by falling back to the client's `sendDefaultPii` setting.
  * Precedence: explicit option > sendDefaultPii > false
@@ -30,38 +48,6 @@ export function resolveAIRecordingOptions<T extends AIRecordingOptions>(options?
   } as T & Required<AIRecordingOptions>;
 }
 
-/**
- * Maps AI method paths to OpenTelemetry semantic convention operation names
- * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#llm-request-spans
- */
-export function getOperationName(methodPath: string): string {
-  // OpenAI: chat.completions.create, responses.create, conversations.create
-  // Anthropic: messages.create, messages.stream, completions.create
-  // Google GenAI: chats.create, chat.sendMessage, chat.sendMessageStream
-  if (
-    methodPath.includes('completions') ||
-    methodPath.includes('responses') ||
-    methodPath.includes('conversations') ||
-    methodPath.includes('messages') ||
-    methodPath.includes('chat')
-  ) {
-    return 'chat';
-  }
-  // OpenAI: embeddings.create
-  if (methodPath.includes('embeddings')) {
-    return 'embeddings';
-  }
-  // Google GenAI: models.generateContent, models.generateContentStream (must be before 'models' check)
-  if (methodPath.includes('generateContent')) {
-    return 'generate_content';
-  }
-  // Anthropic: models.get, models.retrieve (metadata retrieval only)
-  if (methodPath.includes('models')) {
-    return 'models';
-  }
-  return methodPath.split('.').pop() || 'unknown';
-}
-
 /**
  * Build method path from current traversal
  */

packages/core/src/tracing/anthropic-ai/constants.ts

@@ -1,13 +1,15 @@
+import type { InstrumentedMethodRegistry } from '../ai/utils';
+
 export const ANTHROPIC_AI_INTEGRATION_NAME = 'Anthropic_AI';
 
 // https://docs.anthropic.com/en/api/messages
 // https://docs.anthropic.com/en/api/models-list
-export const ANTHROPIC_AI_INSTRUMENTED_METHODS = [
-  'messages.create',
-  'messages.stream',
-  'messages.countTokens',
-  'models.get',
-  'completions.create',
-  'models.retrieve',
-  'beta.messages.create',
-] as const;
+export const ANTHROPIC_METHOD_REGISTRY = {
+  'messages.create': { operation: 'chat' },
+  'messages.stream': { operation: 'chat', streaming: true },
+  'messages.countTokens': { operation: 'chat' },
+  'models.get': { operation: 'models' },
+  'completions.create': { operation: 'chat' },
+  'models.retrieve': { operation: 'models' },
+  'beta.messages.create': { operation: 'chat' },
+} as const satisfies InstrumentedMethodRegistry;

packages/core/src/tracing/anthropic-ai/index.ts

@@ -21,30 +21,25 @@ import {
   GEN_AI_RESPONSE_TOOL_CALLS_ATTRIBUTE,
   GEN_AI_SYSTEM_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
+import type { InstrumentedMethodEntry } from '../ai/utils';
 import {
   buildMethodPath,
-  getOperationName,
   resolveAIRecordingOptions,
   setTokenUsageAttributes,
   wrapPromiseWithMethods,
 } from '../ai/utils';
+import { ANTHROPIC_METHOD_REGISTRY } from './constants';
 import { instrumentAsyncIterableStream, instrumentMessageStream } from './streaming';
-import type {
-  AnthropicAiInstrumentedMethod,
-  AnthropicAiOptions,
-  AnthropicAiResponse,
-  AnthropicAiStreamingEvent,
-  ContentBlock,
-} from './types';
-import { handleResponseError, messagesFromParams, setMessagesAttribute, shouldInstrument } from './utils';
+import type { AnthropicAiOptions, AnthropicAiResponse, AnthropicAiStreamingEvent, ContentBlock } from './types';
+import { handleResponseError, messagesFromParams, setMessagesAttribute } from './utils';
 
 /**
  * Extract request attributes from method arguments
  */
-function extractRequestAttributes(args: unknown[], methodPath: string): Record<string, unknown> {
+function extractRequestAttributes(args: unknown[], methodPath: string, operationName: string): Record<string, unknown> {
   const attributes: Record<string, unknown> = {
     [GEN_AI_SYSTEM_ATTRIBUTE]: 'anthropic',
-    [GEN_AI_OPERATION_NAME_ATTRIBUTE]: getOperationName(methodPath),
+    [GEN_AI_OPERATION_NAME_ATTRIBUTE]: operationName,
     [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ai.anthropic',
   };
 
@@ -263,19 +258,20 @@ function handleStreamingRequest<T extends unknown[], R>(
  */
 function instrumentMethod<T extends unknown[], R>(
   originalMethod: (...args: T) => R | Promise<R>,
-  methodPath: AnthropicAiInstrumentedMethod,
+  methodPath: string,
+  instrumentedMethod: InstrumentedMethodEntry,
   context: unknown,
   options: AnthropicAiOptions,
 ): (...args: T) => R | Promise<R> {
   return new Proxy(originalMethod, {
     apply(target, thisArg, args: T): R | Promise<R> {
-      const requestAttributes = extractRequestAttributes(args, methodPath);
+      const operationName = instrumentedMethod.operation;
+      const requestAttributes = extractRequestAttributes(args, methodPath, operationName);
       const model = requestAttributes[GEN_AI_REQUEST_MODEL_ATTRIBUTE] ?? 'unknown';
-      const operationName = getOperationName(methodPath);
 
       const params = typeof args[0] === 'object' ? (args[0] as Record<string, unknown>) : undefined;
       const isStreamRequested = Boolean(params?.stream);
-      const isStreamingMethod = methodPath === 'messages.stream';
+      const isStreamingMethod = instrumentedMethod.streaming === true;
 
       if (isStreamRequested || isStreamingMethod) {
         return handleStreamingRequest(
@@ -343,8 +339,15 @@ function createDeepProxy<T extends object>(target: T, currentPath = '', options:
       const value = (obj as Record<string, unknown>)[prop];
       const methodPath = buildMethodPath(currentPath, String(prop));
 
-      if (typeof value === 'function' && shouldInstrument(methodPath)) {
-        return instrumentMethod(value as (...args: unknown[]) => unknown | Promise<unknown>, methodPath, obj, options);
+      const instrumentedMethod = ANTHROPIC_METHOD_REGISTRY[methodPath as keyof typeof ANTHROPIC_METHOD_REGISTRY];
+      if (typeof value === 'function' && instrumentedMethod) {
+        return instrumentMethod(
+          value as (...args: unknown[]) => unknown | Promise<unknown>,
+          methodPath,
+          instrumentedMethod,
+          obj,
+          options,
+        );
       }
 
       if (typeof value === 'function') {

packages/core/src/tracing/anthropic-ai/types.ts

@@ -1,4 +1,4 @@
-import type { ANTHROPIC_AI_INSTRUMENTED_METHODS } from './constants';
+import type { ANTHROPIC_METHOD_REGISTRY } from './constants';
 
 export interface AnthropicAiOptions {
   /**
@@ -84,7 +84,10 @@ export interface AnthropicAiIntegration {
   options: AnthropicAiOptions;
 }
 
-export type AnthropicAiInstrumentedMethod = (typeof ANTHROPIC_AI_INSTRUMENTED_METHODS)[number];
+/**
+ * @deprecated This type is no longer used and will be removed in the next major version.
+ */
+export type AnthropicAiInstrumentedMethod = keyof typeof ANTHROPIC_METHOD_REGISTRY;
 
 /**
  * Message type for Anthropic AI

packages/core/src/tracing/anthropic-ai/utils.ts

@@ -8,15 +8,7 @@ import {
   GEN_AI_SYSTEM_INSTRUCTIONS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
 import { extractSystemInstructions, getTruncatedJsonString } from '../ai/utils';
-import { ANTHROPIC_AI_INSTRUMENTED_METHODS } from './constants';
-import type { AnthropicAiInstrumentedMethod, AnthropicAiResponse } from './types';
-
-/**
- * Check if a method path should be instrumented
- */
-export function shouldInstrument(methodPath: string): methodPath is AnthropicAiInstrumentedMethod {
-  return ANTHROPIC_AI_INSTRUMENTED_METHODS.includes(methodPath as AnthropicAiInstrumentedMethod);
-}
+import type { AnthropicAiResponse } from './types';
 
 /**
  * Set the messages and messages original length attributes.

packages/core/src/tracing/google-genai/constants.ts

@@ -1,16 +1,19 @@
+import type { InstrumentedMethodRegistry } from '../ai/utils';
+
 export const GOOGLE_GENAI_INTEGRATION_NAME = 'Google_GenAI';
 
 // https://ai.google.dev/api/rest/v1/models/generateContent
 // https://ai.google.dev/api/rest/v1/chats/sendMessage
 // https://googleapis.github.io/js-genai/release_docs/classes/models.Models.html#generatecontentstream
 // https://googleapis.github.io/js-genai/release_docs/classes/chats.Chat.html#sendmessagestream
-export const GOOGLE_GENAI_INSTRUMENTED_METHODS = [
-  'models.generateContent',
-  'models.generateContentStream',
-  'chats.create',
-  'sendMessage',
-  'sendMessageStream',
-] as const;
+export const GOOGLE_GENAI_METHOD_REGISTRY = {
+  'models.generateContent': { operation: 'generate_content' },
+  'models.generateContentStream': { operation: 'generate_content', streaming: true },
+  'chats.create': { operation: 'chat' },
+  // chat.* paths are built by createDeepProxy when it proxies the chat instance with CHAT_PATH as base
+  'chat.sendMessage': { operation: 'chat' },
+  'chat.sendMessageStream': { operation: 'chat', streaming: true },
+} as const satisfies InstrumentedMethodRegistry;
 
 // Constants for internal use
 export const GOOGLE_GENAI_SYSTEM_NAME = 'google_genai';

packages/core/src/tracing/google-genai/index.ts

@@ -26,18 +26,13 @@ import {
   GEN_AI_USAGE_TOTAL_TOKENS_ATTRIBUTE,
 } from '../ai/gen-ai-attributes';
 import { truncateGenAiMessages } from '../ai/messageTruncation';
-import { buildMethodPath, extractSystemInstructions, getOperationName, resolveAIRecordingOptions } from '../ai/utils';
-import { CHAT_PATH, CHATS_CREATE_METHOD, GOOGLE_GENAI_SYSTEM_NAME } from './constants';
+import type { InstrumentedMethodEntry } from '../ai/utils';
+import { buildMethodPath, extractSystemInstructions, resolveAIRecordingOptions } from '../ai/utils';
+import { CHAT_PATH, CHATS_CREATE_METHOD, GOOGLE_GENAI_METHOD_REGISTRY, GOOGLE_GENAI_SYSTEM_NAME } from './constants';
 import { instrumentStream } from './streaming';
-import type {
-  Candidate,
-  ContentPart,
-  GoogleGenAIIstrumentedMethod,
-  GoogleGenAIOptions,
-  GoogleGenAIResponse,
-} from './types';
+import type { Candidate, ContentPart, GoogleGenAIOptions, GoogleGenAIResponse } from './types';
 import type { ContentListUnion, ContentUnion, Message, PartListUnion } from './utils';
-import { contentUnionToMessages, isStreamingMethod, shouldInstrument } from './utils';
+import { contentUnionToMessages } from './utils';
 
 /**
  * Extract model from parameters or chat context object
@@ -99,13 +94,13 @@ function extractConfigAttributes(config: Record<string, unknown>): Record<string
  * Builds the base attributes for span creation including system info, model, and config
  */
 function extractRequestAttributes(
-  methodPath: string,
+  operationName: string,
   params?: Record<string, unknown>,
   context?: unknown,
 ): Record<string, SpanAttributeValue> {
   const attributes: Record<string, SpanAttributeValue> = {
     [GEN_AI_SYSTEM_ATTRIBUTE]: GOOGLE_GENAI_SYSTEM_NAME,
-    [GEN_AI_OPERATION_NAME_ATTRIBUTE]: getOperationName(methodPath),
+    [GEN_AI_OPERATION_NAME_ATTRIBUTE]: operationName,
     [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ai.google_genai',
   };
 
@@ -251,21 +246,22 @@ function addResponseAttributes(span: Span, response: GoogleGenAIResponse, record
  */
 function instrumentMethod<T extends unknown[], R>(
   originalMethod: (...args: T) => R | Promise<R>,
-  methodPath: GoogleGenAIIstrumentedMethod,
+  methodPath: string,
+  instrumentedMethod: InstrumentedMethodEntry,
   context: unknown,
   options: GoogleGenAIOptions,
 ): (...args: T) => R | Promise<R> {
   const isSyncCreate = methodPath === CHATS_CREATE_METHOD;
 
   return new Proxy(originalMethod, {
     apply(target, _, args: T): R | Promise<R> {
+      const operationName = instrumentedMethod.operation;
       const params = args[0] as Record<string, unknown> | undefined;
-      const requestAttributes = extractRequestAttributes(methodPath, params, context);
+      const requestAttributes = extractRequestAttributes(operationName, params, context);
       const model = requestAttributes[GEN_AI_REQUEST_MODEL_ATTRIBUTE] ?? 'unknown';
-      const operationName = getOperationName(methodPath);
 
       // Check if this is a streaming method
-      if (isStreamingMethod(methodPath)) {
+      if (instrumentedMethod.streaming) {
         // Use startSpanManual for streaming methods to control span lifecycle
         return startSpanManual(
           {
@@ -338,12 +334,19 @@ function createDeepProxy<T extends object>(target: T, currentPath = '', options:
       const value = Reflect.get(t, prop, receiver);
       const methodPath = buildMethodPath(currentPath, String(prop));
 
-      if (typeof value === 'function' && shouldInstrument(methodPath)) {
+      const instrumentedMethod = GOOGLE_GENAI_METHOD_REGISTRY[methodPath as keyof typeof GOOGLE_GENAI_METHOD_REGISTRY];
+      if (typeof value === 'function' && instrumentedMethod) {
         // Special case: chats.create is synchronous but needs both instrumentation AND result proxying
         if (methodPath === CHATS_CREATE_METHOD) {
-          const instrumentedMethod = instrumentMethod(value as (...args: unknown[]) => unknown, methodPath, t, options);
+          const wrappedMethod = instrumentMethod(
+            value as (...args: unknown[]) => unknown,
+            methodPath,
+            instrumentedMethod,
+            t,
+            options,
+          );
           return function instrumentedAndProxiedCreate(...args: unknown[]): unknown {
-            const result = instrumentedMethod(...args);
+            const result = wrappedMethod(...args);
             // If the result is an object (like a chat instance), proxy it too
             if (result && typeof result === 'object') {
               return createDeepProxy(result, CHAT_PATH, options);
@@ -352,7 +355,13 @@ function createDeepProxy<T extends object>(target: T, currentPath = '', options:
           };
         }
 
-        return instrumentMethod(value as (...args: unknown[]) => Promise<unknown>, methodPath, t, options);
+        return instrumentMethod(
+          value as (...args: unknown[]) => Promise<unknown>,
+          methodPath,
+          instrumentedMethod,
+          t,
+          options,
+        );
       }
 
       if (typeof value === 'function') {

packages/core/src/tracing/google-genai/types.ts

@@ -1,4 +1,4 @@
-import type { GOOGLE_GENAI_INSTRUMENTED_METHODS } from './constants';
+import type { GOOGLE_GENAI_METHOD_REGISTRY } from './constants';
 
 export interface GoogleGenAIOptions {
   /**
@@ -179,7 +179,10 @@ export interface GoogleGenAIChat {
   sendMessageStream: (...args: unknown[]) => Promise<AsyncGenerator<GenerateContentResponse, any, unknown>>;
 }
 
-export type GoogleGenAIIstrumentedMethod = (typeof GOOGLE_GENAI_INSTRUMENTED_METHODS)[number];
+/**
+ * @deprecated This type is no longer used and will be removed in the next major version.
+ */
+export type GoogleGenAIIstrumentedMethod = keyof typeof GOOGLE_GENAI_METHOD_REGISTRY;
 
 // Export the response type for use in instrumentation
 export type GoogleGenAIResponse = GenerateContentResponse;

packages/core/src/tracing/google-genai/utils.ts

@@ -1,27 +1,3 @@
-import { GOOGLE_GENAI_INSTRUMENTED_METHODS } from './constants';
-import type { GoogleGenAIIstrumentedMethod } from './types';
-
-/**
- * Check if a method path should be instrumented
- */
-export function shouldInstrument(methodPath: string): methodPath is GoogleGenAIIstrumentedMethod {
-  // Check for exact matches first (like 'models.generateContent')
-  if (GOOGLE_GENAI_INSTRUMENTED_METHODS.includes(methodPath as GoogleGenAIIstrumentedMethod)) {
-    return true;
-  }
-
-  // Check for method name matches (like 'sendMessage' from chat instances)
-  const methodName = methodPath.split('.').pop();
-  return GOOGLE_GENAI_INSTRUMENTED_METHODS.includes(methodName as GoogleGenAIIstrumentedMethod);
-}
-
-/**
- * Check if a method is a streaming method
- */
-export function isStreamingMethod(methodPath: string): boolean {
-  return methodPath.includes('Stream');
-}
-
 // Copied from https://googleapis.github.io/js-genai/release_docs/index.html
 export type ContentListUnion = Content | Content[] | PartListUnion;
 export type ContentUnion = Content | PartUnion[] | PartUnion;