feat(node): Add Mistral AI integration

Instrument `@mistralai/mistralai` v2 with gen_ai spans, turning the
previously-failing integration tests green.

- Automatic `mistralAIIntegration()` via the orchestrion diagnostics
  channels (default-on in Node)
- Manual `instrumentMistralClient()` proxy for edge runtimes
- Covers chat, embeddings, agents (invoke_agent) and fim
  (text_completion), including streaming, with `recordInputs` /
  `recordOutputs` controls

Mistral's typed responses/usage are camelCase, so the response/stream
mapping reads `promptTokens`/`completionTokens`/`totalTokens` and
`choices[].finishReason` directly. `@mistralai/mistralai` v2 is ESM-only,
so the CJS test variants are marked `failsOnCjs`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nicohrubec

dev-packages/node-integration-tests/suites/tracing/mistral/test.ts

@@ -25,6 +25,7 @@ export {
   mongoIntegration,
   mongooseIntegration,
   mysqlIntegration,
+  mistralAIIntegration,
   mysql2Integration,
   openAIIntegration,
   postgresIntegration,
@@ -40,6 +41,7 @@ export {
   instrumentOpenAiClient,
   instrumentAnthropicAiClient,
   instrumentGoogleGenAIClient,
+  instrumentMistralClient,
   createLangChainCallbackHandler,
   instrumentLangChainEmbeddings,
   instrumentStateGraph,

packages/node/src/index.ts

@@ -7,6 +7,7 @@
 export { instrumentOpenAiClient } from './openai';
 export { instrumentAnthropicAiClient } from './anthropic-ai';
 export { instrumentGoogleGenAIClient } from './google-genai';
+export { instrumentMistralClient } from './mistral';
 export { instrumentWorkersAiClient } from './workers-ai';
 export { createLangChainCallbackHandler, instrumentLangChainEmbeddings } from './langchain';
 export { instrumentStateGraph, instrumentStateGraphCompile, instrumentCreateReactAgent } from './langgraph';

packages/server-utils/src/ai/index.ts

@@ -0,0 +1,15 @@
+import type { InstrumentedMethodRegistry } from '../core/utils';
+
+export const MISTRAL_INTEGRATION_NAME = 'Mistral' as const;
+
+// https://docs.mistral.ai/api/
+// `*.stream` methods are intrinsically streaming (no `stream: true` param), so they are flagged here.
+export const MISTRAL_METHOD_REGISTRY = {
+  'chat.complete': { operation: 'chat' },
+  'chat.stream': { operation: 'chat', streaming: true },
+  'embeddings.create': { operation: 'embeddings' },
+  'agents.complete': { operation: 'invoke_agent' },
+  'agents.stream': { operation: 'invoke_agent', streaming: true },
+  'fim.complete': { operation: 'text_completion' },
+  'fim.stream': { operation: 'text_completion', streaming: true },
+} as const satisfies InstrumentedMethodRegistry;

packages/server-utils/src/ai/mistral/constants.ts

@@ -0,0 +1,200 @@
+import {
+  getClient,
+  hasSpanStreamingEnabled,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SPAN_STATUS_ERROR,
+  startSpan,
+  startSpanManual,
+  stringify,
+} from '@sentry/core';
+import type { Span, SpanAttributeValue } from '@sentry/core';
+import {
+  GEN_AI_AGENT_NAME,
+  GEN_AI_EMBEDDINGS_INPUT,
+  GEN_AI_INPUT_MESSAGES,
+  GEN_AI_OPERATION_NAME,
+  GEN_AI_PROVIDER_NAME,
+  GEN_AI_SYSTEM_INSTRUCTIONS,
+} from '@sentry/conventions/attributes';
+import type { InstrumentedMethodEntry } from '../core/utils';
+import {
+  buildMethodPath,
+  extractSystemInstructions,
+  getGenAiSpanOp,
+  resolveAIRecordingOptions,
+  wrapPromiseWithMethods,
+} from '../core/utils';
+import { MISTRAL_METHOD_REGISTRY } from './constants';
+import { instrumentStream } from './streaming';
+import type { MistralOptions } from './types';
+import { addResponseAttributes, extractRequestParameters, getModelForSpanName } from './utils';
+
+/**
+ * Extract request attributes from method arguments.
+ */
+export function extractRequestAttributes(args: unknown[], operationName: string): Record<string, unknown> {
+  const attributes: Record<string, unknown> = {
+    [GEN_AI_PROVIDER_NAME]: 'mistral',
+    [GEN_AI_OPERATION_NAME]: operationName,
+    [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.ai.mistral',
+  };
+
+  if (args.length > 0 && typeof args[0] === 'object' && args[0] !== null) {
+    const params = args[0] as Record<string, unknown>;
+
+    if (operationName === 'invoke_agent' && typeof params.agentId === 'string') {
+      attributes[GEN_AI_AGENT_NAME] = params.agentId;
+    }
+
+    Object.assign(attributes, extractRequestParameters(params));
+  }
+
+  return attributes;
+}
+
+/**
+ * Record AI request inputs on the span, if recording is enabled.
+ */
+export function addRequestAttributes(span: Span, params: Record<string, unknown>, operationName: string): void {
+  if (operationName === 'embeddings') {
+    const input = params.inputs;
+    if (input == null || (typeof input === 'string' && input.length === 0) || (Array.isArray(input) && !input.length)) {
+      return;
+    }
+    span.setAttribute(GEN_AI_EMBEDDINGS_INPUT, stringify(input, String));
+    return;
+  }
+
+  // FIM completions carry a raw `prompt` string rather than a messages array.
+  if (operationName === 'text_completion') {
+    if (typeof params.prompt === 'string' && params.prompt.length > 0) {
+      span.setAttribute(GEN_AI_INPUT_MESSAGES, stringify(params.prompt));
+    }
+    return;
+  }
+
+  const src = 'messages' in params ? params.messages : undefined;
+  if (!src || (Array.isArray(src) && src.length === 0)) {
+    return;
+  }
+
+  const { systemInstructions, filteredMessages } = extractSystemInstructions(src);
+  if (systemInstructions) {
+    span.setAttribute(GEN_AI_SYSTEM_INSTRUCTIONS, systemInstructions);
+  }
+  span.setAttribute(GEN_AI_INPUT_MESSAGES, stringify(filteredMessages));
+}
+
+/**
+ * Instrument a single Mistral SDK method with a gen_ai span.
+ * @see https://docs.sentry.io/platforms/javascript/guides/node/tracing/instrumentation/ai-agents-module/#manual-instrumentation
+ */
+function instrumentMethod<T extends unknown[], R>(
+  originalMethod: (...args: T) => Promise<R>,
+  instrumentedMethod: InstrumentedMethodEntry,
+  context: unknown,
+  options: MistralOptions,
+): (...args: T) => Promise<R> {
+  return function instrumentedCall(...args: T): Promise<R> {
+    const operationName = instrumentedMethod.operation || 'unknown';
+    const requestAttributes = extractRequestAttributes(args, operationName);
+
+    const params = args[0] as Record<string, unknown> | undefined;
+    const model = getModelForSpanName(params, operationName);
+    // `*.stream` methods are always streaming; `complete` methods stream only with `stream: true`.
+    const isStreamRequested = !!instrumentedMethod.streaming || params?.stream === true;
+    const client = getClient();
+
+    const spanConfig = {
+      // With span streaming, omit the `'unknown'` model sentinel so the name stays low-cardinality.
+      name:
+        model !== 'unknown' || !(client && hasSpanStreamingEnabled(client))
+          ? `${operationName} ${model}`
+          : operationName,
+      op: getGenAiSpanOp(operationName),
+      attributes: requestAttributes as Record<string, SpanAttributeValue>,
+    };
+
+    if (isStreamRequested) {
+      let originalResult!: Promise<R>;
+
+      const instrumentedPromise = startSpanManual(spanConfig, (span: Span) => {
+        originalResult = originalMethod.apply(context, args);
+
+        if (options.recordInputs && params) {
+          addRequestAttributes(span, params, operationName);
+        }
+
+        return (async () => {
+          try {
+            const result = await originalResult;
+            return instrumentStream(
+              result as AsyncIterable<unknown>,
+              span,
+              options.recordOutputs ?? false,
+            ) as unknown as R;
+          } catch (error) {
+            span.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
+            span.end();
+            throw error;
+          }
+        })();
+      });
+
+      return wrapPromiseWithMethods(originalResult, instrumentedPromise);
+    }
+
+    let originalResult!: Promise<R>;
+
+    const instrumentedPromise = startSpan(spanConfig, (span: Span) => {
+      originalResult = originalMethod.apply(context, args);
+
+      if (options.recordInputs && params) {
+        addRequestAttributes(span, params, operationName);
+      }
+
+      return originalResult.then(result => {
+        addResponseAttributes(span, result, options.recordOutputs);
+        return result;
+      });
+    });
+
+    return wrapPromiseWithMethods(originalResult, instrumentedPromise);
+  };
+}
+
+/**
+ * Create a deep proxy for Mistral client instrumentation.
+ */
+function createDeepProxy<T extends object>(target: T, currentPath = '', options: MistralOptions): T {
+  return new Proxy(target, {
+    get(obj: object, prop: string): unknown {
+      const value = (obj as Record<string, unknown>)[prop];
+      const methodPath = buildMethodPath(currentPath, String(prop));
+
+      const instrumentedMethod = MISTRAL_METHOD_REGISTRY[methodPath as keyof typeof MISTRAL_METHOD_REGISTRY];
+      if (typeof value === 'function' && instrumentedMethod) {
+        return instrumentMethod(value as (...args: unknown[]) => Promise<unknown>, instrumentedMethod, obj, options);
+      }
+
+      if (typeof value === 'function') {
+        // Preserve the original `this` for uninstrumented methods (private class fields).
+        return value.bind(obj);
+      }
+
+      if (value && typeof value === 'object') {
+        return createDeepProxy(value, methodPath, options);
+      }
+
+      return value;
+    },
+  }) as T;
+}
+
+/**
+ * Instrument a Mistral client with Sentry tracing.
+ * Can be used across Node.js, Cloudflare Workers, and Vercel Edge.
+ */
+export function instrumentMistralClient<T extends object>(client: T, options?: MistralOptions): T {
+  return createDeepProxy(client, '', resolveAIRecordingOptions(options));
+}

packages/server-utils/src/ai/mistral/index.ts

@@ -0,0 +1,73 @@
+import type { Span } from '@sentry/core';
+import { endStreamSpan } from '../core/utils';
+import type { MistralCompletionChunk } from './types';
+
+/**
+ * State accumulated while consuming a Mistral event stream.
+ */
+interface StreamingState {
+  responseTexts: string[];
+  finishReasons: string[];
+  responseId: string;
+  responseModel: string;
+  promptTokens: number | undefined;
+  completionTokens: number | undefined;
+  totalTokens: number | undefined;
+}
+
+function processChunk(chunk: MistralCompletionChunk, state: StreamingState, recordOutputs: boolean): void {
+  state.responseId = chunk.id ?? state.responseId;
+  state.responseModel = chunk.model ?? state.responseModel;
+
+  if (chunk.usage) {
+    // Input tokens stay constant across the stream; output tokens are only finalized in the last
+    // event, so we overwrite on every event that carries usage to guarantee the totals are set.
+    state.promptTokens = chunk.usage.promptTokens;
+    state.completionTokens = chunk.usage.completionTokens;
+    state.totalTokens = chunk.usage.totalTokens;
+  }
+
+  for (const choice of chunk.choices ?? []) {
+    if (recordOutputs && typeof choice.delta?.content === 'string' && choice.delta.content) {
+      state.responseTexts.push(choice.delta.content);
+    }
+    if (choice.finishReason) {
+      state.finishReasons.push(choice.finishReason);
+    }
+  }
+}
+
+/**
+ * Instrument a Mistral event stream, accumulating response attributes and ending the span when
+ * iteration finishes. Mistral yields `CompletionEvent` objects that wrap the chunk under `data`.
+ */
+export async function* instrumentStream<T>(
+  stream: AsyncIterable<T>,
+  span: Span,
+  recordOutputs: boolean,
+): AsyncGenerator<T, void, unknown> {
+  const state: StreamingState = {
+    responseTexts: [],
+    finishReasons: [],
+    responseId: '',
+    responseModel: '',
+    promptTokens: undefined,
+    completionTokens: undefined,
+    totalTokens: undefined,
+  };
+
+  try {
+    for await (const event of stream) {
+      const chunk =
+        event && typeof event === 'object' && 'data' in event
+          ? (event as { data: MistralCompletionChunk }).data
+          : (event as unknown as MistralCompletionChunk);
+      if (chunk && typeof chunk === 'object') {
+        processChunk(chunk, state, recordOutputs);
+      }
+      yield event;
+    }
+  } finally {
+    endStreamSpan(span, { ...state, toolCalls: [] }, recordOutputs);
+  }
+}

packages/server-utils/src/ai/mistral/streaming.ts

@@ -0,0 +1,24 @@
+import type { GenAiOptions } from '../core/utils';
+
+/** Options for the Mistral integration. */
+export type MistralOptions = GenAiOptions;
+
+/**
+ * A single streaming chunk. Field names are camelCase because the SDK deserializes the snake_case
+ * wire payload into typed objects before instrumentation sees them. Streaming APIs actually yield
+ * `CompletionEvent` objects that wrap this under `data`.
+ * @see https://docs.mistral.ai/api/#tag/chat/operation/stream_chat
+ */
+export interface MistralCompletionChunk {
+  id: string;
+  model: string;
+  choices?: Array<{
+    delta?: { content?: string | Array<unknown> | null };
+    finishReason?: string | null;
+  }>;
+  usage?: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+  };
+}