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

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;