netra-sdk 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -1214,6 +1214,28 @@ declare function span(target: AnyClass): void;
 declare function span<T extends AnyFunction>(target: T): T;
 declare function span(options?: DecoratorOptions): UnifiedDecorator;
 
+/**
+ * Shared utility functions for instrumentation.
+ * Handles setting OTel span attributes for LLM request/response tracing.
+ */
+
+/**
+ * Controls where native traces are sent.
+ *
+ * - `"netra"` -- Replace the SDK's default processors so traces go
+ *   only to Netra. If the SDK does not expose the required APIs, falls back
+ *   to additive mode (both Netra and native) and logs a warning.
+ * - `"netra-strict"` (default) -- Same replacement as `"netra"`, but if the SDK APIs
+ *   are unavailable the processor is **not** registered at all, ensuring
+ *   traces never reach native even at the cost of no tracing.
+ * - `"both"` -- The Netra processor is added alongside the native defaults;
+ *   traces go to both Netra and native.
+ *
+ * Can also be set via the `NATIVE_TRACING_MODE` environment
+ * variable using the same string values.
+ */
+type NativeTracingMode = "both" | "netra" | "netra-strict";
+
 /**
  * Custom MistralAI instrumentor for Netra SDK
  *
@@ -1328,12 +1350,15 @@ interface TracingProcessor {
     forceFlush(): Promise<void> | void;
     shutdown(timeout?: number): Promise<void> | void;
 }
+
 interface InstrumentorOptions {
     tracerProvider?: {
         getTracer(name: string, version?: string): any;
     };
     /** Override the `llm.system` attribute value (default: `"openai"`). */
     systemName?: string;
+    /** Controls where traces are sent. See {@link NativeTracingMode}. */
+    nativeTracing?: NativeTracingMode;
 }
 
 declare class NetraAgentsTracingProcessor implements TracingProcessor {

package/dist/index.d.ts

@@ -1214,6 +1214,28 @@ declare function span(target: AnyClass): void;
 declare function span<T extends AnyFunction>(target: T): T;
 declare function span(options?: DecoratorOptions): UnifiedDecorator;
 
+/**
+ * Shared utility functions for instrumentation.
+ * Handles setting OTel span attributes for LLM request/response tracing.
+ */
+
+/**
+ * Controls where native traces are sent.
+ *
+ * - `"netra"` -- Replace the SDK's default processors so traces go
+ *   only to Netra. If the SDK does not expose the required APIs, falls back
+ *   to additive mode (both Netra and native) and logs a warning.
+ * - `"netra-strict"` (default) -- Same replacement as `"netra"`, but if the SDK APIs
+ *   are unavailable the processor is **not** registered at all, ensuring
+ *   traces never reach native even at the cost of no tracing.
+ * - `"both"` -- The Netra processor is added alongside the native defaults;
+ *   traces go to both Netra and native.
+ *
+ * Can also be set via the `NATIVE_TRACING_MODE` environment
+ * variable using the same string values.
+ */
+type NativeTracingMode = "both" | "netra" | "netra-strict";
+
 /**
  * Custom MistralAI instrumentor for Netra SDK
  *
@@ -1328,12 +1350,15 @@ interface TracingProcessor {
     forceFlush(): Promise<void> | void;
     shutdown(timeout?: number): Promise<void> | void;
 }
+
 interface InstrumentorOptions {
     tracerProvider?: {
         getTracer(name: string, version?: string): any;
     };
     /** Override the `llm.system` attribute value (default: `"openai"`). */
     systemName?: string;
+    /** Controls where traces are sent. See {@link NativeTracingMode}. */
+    nativeTracing?: NativeTracingMode;
 }
 
 declare class NetraAgentsTracingProcessor implements TracingProcessor {

package/dist/index.js

@@ -610,7 +610,8 @@ var DEFAULT_INSTRUMENTS_FOR_ROOT = /* @__PURE__ */ new Set([
   // AI frameworks
   "langchain" /* LANGCHAIN */,
   "langgraph" /* LANGGRAPH */,
-  "llama_index" /* LLAMA_INDEX */
+  "llama_index" /* LLAMA_INDEX */,
+  "openai_agents" /* OPENAI_AGENTS */
 ]);
 var DEFAULT_INSTRUMENTS = /* @__PURE__ */ new Set([
   ...DEFAULT_INSTRUMENTS_FOR_ROOT,
@@ -3626,6 +3627,13 @@ var SpanAttributes2 = {
 };
 
 // src/instrumentation/utils.ts
+var VALID_NATIVE_TRACING_MODES = /* @__PURE__ */ new Set(["both", "netra", "netra-strict"]);
+function parseNativeTracingEnv(name) {
+  const val = process.env[name];
+  if (val === void 0 || val === "") return void 0;
+  if (VALID_NATIVE_TRACING_MODES.has(val)) return val;
+  return void 0;
+}
 var SUPPRESS_INSTRUMENTATION_KEY = /* @__PURE__ */ Symbol("netra.suppress_instrumentation");
 function shouldSuppressInstrumentation() {
   const ctx = context.active();
@@ -9132,6 +9140,8 @@ var cachedAgentsModule = null;
 var isInstrumented6 = false;
 var activeTracer = null;
 var activeProcessor = null;
+var originalProcessors = null;
+var didReplaceProcessors = false;
 async function resolveAgentsModule() {
   if (cachedAgentsModule) return cachedAgentsModule;
   try {
@@ -9184,20 +9194,51 @@ var NetraOpenAIAgentsInstrumentor = class {
     }
     const systemName = options.systemName ?? DEFAULT_LLM_SYSTEM;
     activeProcessor = new NetraAgentsTracingProcessor(activeTracer, systemName);
+    const mode = options.nativeTracing ?? parseNativeTracingEnv("NATIVE_TRACING_MODE") ?? "netra-strict";
+    const canSet = typeof agentsModule.setTraceProcessors === "function";
+    const canAdd = typeof agentsModule.addTraceProcessor === "function";
+    let strategy;
+    if (mode === "both" || mode === "netra" && !canSet) {
+      strategy = "append";
+    } else if (canSet) {
+      strategy = "replace";
+    } else {
+      strategy = "skip";
+    }
     try {
-      if (typeof agentsModule.addTraceProcessor === "function") {
-        agentsModule.addTraceProcessor(activeProcessor);
-      } else if (typeof agentsModule.setTraceProcessors === "function") {
-        const existing = typeof agentsModule.getTraceProcessors === "function" ? agentsModule.getTraceProcessors() : [];
-        agentsModule.setTraceProcessors([...existing, activeProcessor]);
-      } else {
-        Logger.warn(
-          "OpenAI Agents SDK does not expose addTraceProcessor or setTraceProcessors.",
-          "Tracing integration may not work."
-        );
-        activeProcessor = null;
-        activeTracer = null;
-        return this;
+      switch (strategy) {
+        case "replace":
+          if (typeof agentsModule.getTraceProcessors === "function") {
+            originalProcessors = agentsModule.getTraceProcessors();
+          }
+          agentsModule.setTraceProcessors([activeProcessor]);
+          didReplaceProcessors = true;
+          Logger.debug("OpenAI Agents native tracing disabled \u2014 traces will only be sent to Netra.");
+          break;
+        case "append":
+          if (canAdd) {
+            agentsModule.addTraceProcessor(activeProcessor);
+          } else {
+            Logger.warn("OpenAI Agents SDK does not expose addTraceProcessor or setTraceProcessors.");
+            activeProcessor = null;
+            activeTracer = null;
+            return this;
+          }
+          if (mode === "netra") {
+            Logger.warn(
+              "Cannot exclusively replace native trace processors in this @openai/agents version.",
+              "Traces may still be sent to OpenAI."
+            );
+          }
+          break;
+        case "skip":
+          Logger.warn(
+            'nativeTracing is "netra-strict" but the installed @openai/agents version',
+            "does not support processor replacement. Skipping instrumentation."
+          );
+          activeProcessor = null;
+          activeTracer = null;
+          return this;
       }
     } catch (error) {
       Logger.warn("Failed to register trace processor with @openai/agents:", error);
@@ -9217,6 +9258,21 @@ var NetraOpenAIAgentsInstrumentor = class {
       activeProcessor.shutdown();
       activeProcessor = null;
     }
+    if (didReplaceProcessors && cachedAgentsModule) {
+      try {
+        if (originalProcessors && typeof cachedAgentsModule.setTraceProcessors === "function") {
+          cachedAgentsModule.setTraceProcessors(originalProcessors);
+          Logger.debug("Restored original OpenAI Agents trace processors");
+        } else if (typeof cachedAgentsModule.setDefaultOpenAITracingExporter === "function") {
+          cachedAgentsModule.setDefaultOpenAITracingExporter();
+          Logger.debug("Restored default OpenAI Agents tracing exporter");
+        }
+      } catch (error) {
+        Logger.debug("Failed to restore original trace processors:", error);
+      }
+    }
+    originalProcessors = null;
+    didReplaceProcessors = false;
     activeTracer = null;
     cachedAgentsModule = null;
     isInstrumented6 = false;
@@ -10099,7 +10155,9 @@ function initInstrumentations(config2, instruments, blockInstruments, rootInstru
     mistral: false,
     langgraph: false,
     googleGenAI: false,
-    anthropic: false};
+    anthropic: false,
+    openAiAgents: false
+  };
   const resolved = enableAll ? new Set(Object.values(NetraInstruments).filter((v) => v !== "__all__" /* ALL */)) : instruments && instruments.size > 0 ? instruments : DEFAULT_INSTRUMENTS;
   instrumentModules.google_vertexai = false;
   instrumentModules.langchain = false;
@@ -10147,6 +10205,9 @@ function initInstrumentations(config2, instruments, blockInstruments, rootInstru
   if (resolved.has("anthropic" /* ANTHROPIC */)) {
     customInstrumentModules.anthropic = true;
   }
+  if (resolved.has("openai_agents" /* OPENAI_AGENTS */)) {
+    customInstrumentModules.openAiAgents = true;
+  }
   if (blockInstruments && blockInstruments.size > 0) {
     const blockAll = blockInstruments.has("__all__" /* ALL */);
     if (blockAll || blockInstruments.has("openai" /* OPENAI */)) customInstrumentModules.openai = false;
@@ -10155,6 +10216,7 @@ function initInstrumentations(config2, instruments, blockInstruments, rootInstru
     if (blockAll || blockInstruments.has("langgraph" /* LANGGRAPH */)) customInstrumentModules.langgraph = false;
     if (blockAll || blockInstruments.has("google_genai" /* GOOGLE_GENERATIVE_AI */)) customInstrumentModules.googleGenAI = false;
     if (blockAll || blockInstruments.has("anthropic" /* ANTHROPIC */)) customInstrumentModules.anthropic = false;
+    if (blockAll || blockInstruments.has("openai_agents" /* OPENAI_AGENTS */)) customInstrumentModules.openAiAgents = false;
     if (blockAll || blockInstruments.has("vertexai" /* VERTEX_AI */)) instrumentModules.google_vertexai = false;
     if (blockAll || blockInstruments.has("langchain" /* LANGCHAIN */)) instrumentModules.langchain = false;
     if (blockAll || blockInstruments.has("llama_index" /* LLAMA_INDEX */)) instrumentModules.llamaIndex = false;
@@ -10277,7 +10339,7 @@ async function initCustomInstrumentationsAsync(config2, tracerProvider, customIn
       Logger.debug("Failed to initialize custom Anthropic instrumentation:", e);
     }
   }
-  if (customInstrumentModules.openaiAgents && !blockInstruments?.has("openai_agents" /* OPENAI_AGENTS */)) {
+  if (customInstrumentModules.openAiAgents && !blockInstruments?.has("openai_agents" /* OPENAI_AGENTS */)) {
     try {
       await openaiAgentsInstrumentor.instrument({ tracerProvider });
       Logger.debug("Custom OpenAI Agents SDK instrumentation enabled");