wip(ai): Support scope-level conversation ID for AI tracing

Author: RulaKhaled

packages/core/src/exports.ts

@@ -111,6 +111,24 @@ export function setUser(user: User | null): void {
   getIsolationScope().setUser(user);
 }
 
+/**
+ * Sets the conversation ID for the current isolation scope.
+ *
+ * @param conversationId The conversation ID to set. Pass `null` or `undefined` to unset the conversation ID.
+ */
+export function setConversationId(conversationId: string | null | undefined): void {
+  getIsolationScope().setConversationId(conversationId);
+}
+
+/**
+ * Gets the conversation ID from the current isolation scope.
+ *
+ * @returns The conversation ID, or `undefined` if not set.
+ */
+export function getConversationId(): string | undefined {
+  return getIsolationScope().getConversationId();
+}
+
 /**
  * The last error event id of the isolation scope.
  *

packages/core/src/index.ts

@@ -25,6 +25,8 @@ export {
   setTag,
   setTags,
   setUser,
+  setConversationId,
+  getConversationId,
   isInitialized,
   isEnabled,
   startSession,

packages/core/src/scope.ts

@@ -153,6 +153,9 @@ export class Scope {
   /** Contains the last event id of a captured event.  */
   protected _lastEventId?: string;
 
+  /** Conversation ID */
+  protected _conversationId?: string;
+
   // NOTE: Any field which gets added here should get added not only to the constructor but also to the `clone` method.
 
   public constructor() {
@@ -202,6 +205,7 @@ export class Scope {
     newScope._propagationContext = { ...this._propagationContext };
     newScope._client = this._client;
     newScope._lastEventId = this._lastEventId;
+    newScope._conversationId = this._conversationId;
 
     _setSpanForScope(newScope, _getSpanForScope(this));
 
@@ -284,6 +288,23 @@ export class Scope {
     return this._user;
   }
 
+  /**
+   * Set the conversation ID for this scope.
+   * Set to `null` to unset the conversation ID.
+   */
+  public setConversationId(conversationId: string | null | undefined): this {
+    this._conversationId = conversationId || undefined;
+    this._notifyScopeListeners();
+    return this;
+  }
+
+  /**
+   * Get the conversation ID from this scope.
+   */
+  public getConversationId(): string | undefined {
+    return this._conversationId;
+  }
+
   /**
    * Set an object that will be merged into existing tags on the scope,
    * and will be sent as tags data with the event.

packages/core/src/tracing/sentrySpan.ts

@@ -38,6 +38,7 @@ import {
   TRACE_FLAG_SAMPLED,
 } from '../utils/spanUtils';
 import { timestampInSeconds } from '../utils/time';
+import { GEN_AI_CONVERSATION_ID_ATTRIBUTE } from './ai/gen-ai-attributes';
 import { getDynamicSamplingContextFromSpan } from './dynamicSamplingContext';
 import { logSpanEnd } from './logSpans';
 import { timedEventsToMeasurements } from './measurement';
@@ -221,6 +222,22 @@ export class SentrySpan implements Span {
    * use `spanToJSON(span)` instead.
    */
   public getSpanJSON(): SpanJSON {
+    // Automatically inject conversation ID from scope if not already set
+    if (!this._attributes[GEN_AI_CONVERSATION_ID_ATTRIBUTE]) {
+      const capturedScopes = getCapturedScopesOnSpan(this);
+      // Try isolation scope first (where setConversationId sets it)
+      let conversationId = capturedScopes.isolationScope?.getConversationId();
+
+      // Fallback to regular scope
+      if (!conversationId) {
+        conversationId = capturedScopes.scope?.getConversationId();
+      }
+
+      if (conversationId) {
+        this._attributes[GEN_AI_CONVERSATION_ID_ATTRIBUTE] = conversationId;
+      }
+    }
+
     return {
       data: this._attributes,
       description: this._name,

packages/core/src/utils/spanUtils.ts

@@ -7,6 +7,7 @@ import {
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
 } from '../semanticAttributes';
+import { GEN_AI_CONVERSATION_ID_ATTRIBUTE } from '../tracing/ai/gen-ai-attributes';
 import type { SentrySpan } from '../tracing/sentrySpan';
 import { SPAN_STATUS_OK, SPAN_STATUS_UNSET } from '../tracing/spanstatus';
 import { getCapturedScopesOnSpan } from '../tracing/utils';
@@ -149,6 +150,28 @@ export function spanToJSON(span: Span): SpanJSON {
   // Handle a span from @opentelemetry/sdk-base-trace's `Span` class
   if (spanIsOpenTelemetrySdkTraceBaseSpan(span)) {
     const { attributes, startTime, name, endTime, status, links } = span;
+    // Automatically inject conversation ID from scope if not already set
+    if (!attributes[GEN_AI_CONVERSATION_ID_ATTRIBUTE]) {
+      // First try captured scopes (scopes at span creation time)
+      const capturedScopes = getCapturedScopesOnSpan(span);
+      // Try captured isolation scope first (where setConversationId sets it)
+      let conversationId = capturedScopes.isolationScope?.getConversationId();
+
+      // Fallback to regular scope
+      if (!conversationId) {
+        conversationId = capturedScopes.scope?.getConversationId();
+      }
+
+      // If not found in captured scopes, try current scopes (from AsyncLocalStorage)
+      if (!conversationId) {
+        const currentScope = getCurrentScope();
+        conversationId = currentScope?.getConversationId();
+      }
+
+      if (conversationId) {
+        attributes[GEN_AI_CONVERSATION_ID_ATTRIBUTE] = conversationId;
+      }
+    }
 
     // In preparation for the next major of OpenTelemetry, we want to support
     // looking up the parent span id according to the new API

packages/node/src/index.ts

@@ -83,6 +83,8 @@ export {
   setTag,
   setTags,
   setUser,
+  setConversationId,
+  getConversationId,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,