netra-sdk 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -59,10 +59,11 @@ declare const DEFAULT_INSTRUMENTS: Set<NetraInstruments>;
 declare class Config {
     static readonly SDK_NAME = "netra";
     static readonly LIBRARY_NAME = "netra";
-    static readonly LIBRARY_VERSION = "1.0.0";
+    static readonly LIBRARY_VERSION = "1.4.0";
     static readonly TRIAL_BLOCK_DURATION_SECONDS = 900;
     static readonly ATTRIBUTE_MAX_LEN: number;
     static readonly CONVERSATION_MAX_LEN: number;
+    static readonly SPAN_ATTRIBUTE_MAX_SIZE: number;
     appName: string;
     otlpEndpoint?: string;
     apiKey?: string;
@@ -94,6 +95,7 @@ declare class Config {
      * This ensures the Traceloop SDK picks up our configuration.
      */
     setTraceloopEnv(): void;
+    private _setResourceAttributesEnv;
 }
 
 /**
@@ -847,6 +849,23 @@ declare class Prompts {
     getPrompt(params: GetPromptParams): Promise<PromptResponse | null>;
 }
 
+/**
+ * Attribute Size Limit Span Processor
+ *
+ * Enforces a hard max length on every span attribute value via setAttribute
+ * wrapping in onStart. Prevents "entity too large" errors during export.
+ */
+
+declare class AttributeSizeLimitProcessor implements SpanProcessor {
+    private maxAttributeSize;
+    constructor(maxAttributeSize?: number);
+    onStart(span: Span, _parentContext: Context): void;
+    onEnd(_span: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private _wrapSetAttribute;
+}
+
 /**
  * Instrumentation Span Processor
  *
@@ -947,6 +966,8 @@ declare class ScrubbingSpanProcessor implements SpanProcessor {
  */
 
 declare class SessionSpanProcessor implements SpanProcessor {
+    private readonly environment;
+    constructor(environment?: string);
     /**
      * Called when a span starts. Adds session and entity context attributes.
      */
@@ -1214,6 +1235,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 +1371,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 {
@@ -1560,4 +1606,4 @@ declare class Netra {
     static withBlockedSpansLocal: typeof withBlockedSpansLocal;
 }
 
-export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type ProcessedFile, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };
+export { type ActionModel, Aggregation, AttributeSizeLimitProcessor, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type ProcessedFile, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };

package/dist/index.d.ts

@@ -59,10 +59,11 @@ declare const DEFAULT_INSTRUMENTS: Set<NetraInstruments>;
 declare class Config {
     static readonly SDK_NAME = "netra";
     static readonly LIBRARY_NAME = "netra";
-    static readonly LIBRARY_VERSION = "1.0.0";
+    static readonly LIBRARY_VERSION = "1.4.0";
     static readonly TRIAL_BLOCK_DURATION_SECONDS = 900;
     static readonly ATTRIBUTE_MAX_LEN: number;
     static readonly CONVERSATION_MAX_LEN: number;
+    static readonly SPAN_ATTRIBUTE_MAX_SIZE: number;
     appName: string;
     otlpEndpoint?: string;
     apiKey?: string;
@@ -94,6 +95,7 @@ declare class Config {
      * This ensures the Traceloop SDK picks up our configuration.
      */
     setTraceloopEnv(): void;
+    private _setResourceAttributesEnv;
 }
 
 /**
@@ -847,6 +849,23 @@ declare class Prompts {
     getPrompt(params: GetPromptParams): Promise<PromptResponse | null>;
 }
 
+/**
+ * Attribute Size Limit Span Processor
+ *
+ * Enforces a hard max length on every span attribute value via setAttribute
+ * wrapping in onStart. Prevents "entity too large" errors during export.
+ */
+
+declare class AttributeSizeLimitProcessor implements SpanProcessor {
+    private maxAttributeSize;
+    constructor(maxAttributeSize?: number);
+    onStart(span: Span, _parentContext: Context): void;
+    onEnd(_span: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private _wrapSetAttribute;
+}
+
 /**
  * Instrumentation Span Processor
  *
@@ -947,6 +966,8 @@ declare class ScrubbingSpanProcessor implements SpanProcessor {
  */
 
 declare class SessionSpanProcessor implements SpanProcessor {
+    private readonly environment;
+    constructor(environment?: string);
     /**
      * Called when a span starts. Adds session and entity context attributes.
      */
@@ -1214,6 +1235,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 +1371,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 {
@@ -1560,4 +1606,4 @@ declare class Netra {
     static withBlockedSpansLocal: typeof withBlockedSpansLocal;
 }
 
-export { type ActionModel, Aggregation, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type ProcessedFile, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };
+export { type ActionModel, Aggregation, AttributeSizeLimitProcessor, BaseTask, type CategoricalDataPoint, ChartType, Config, type ConversationResponse, type ConversationResult, ConversationType, type CreateDatasetParams, type CreateRunResult, DEFAULT_INSTRUMENTS, DEFAULT_INSTRUMENTS_FOR_ROOT, Dashboard, type DashboardData, type Dataset, type DatasetEntry, type DatasetItem, type Dimension, DimensionField, type DimensionValue, EntryStatus, Evaluation, type EvaluationScore, type EvaluatorFunction, type Filter, type FilterConfig, FilterField, FilterType, FilteringSpanExporter, type GetPromptParams, GroupBy, InstrumentationSpanProcessor, type ListSpansParams, type ListTracesParams, Measure, type Metrics, Netra, NetraAgentsTracingProcessor, NetraInstruments, NetraOpenAIAgentsInstrumentor, type NumberResponse, Operator, type ProcessedFile, type PromptResponse, Prompts, type QueryDataParams, type QueryResponse, type Run, RunEntryContext, RunStatus, Scope, ScrubbingSpanProcessor, SessionSpanProcessor, type SessionUsageData, Simulation, type SimulationItem, type SimulationOptions, type SimulationResult, SpanIOProcessor, type SpanOptions, SpanType, type SpansPage, type TaskFunction, type TaskResult, type TenantUsageData, type TestSuiteResult, type TimeRange, type TimeSeriesDataPoint, type TimeSeriesResponse, type TimeSeriesWithDimension, type TraceSpan, type TraceSummary, type TracesPage, TrialAwareOTLPExporter, Usage, type UsageModel, agent, Netra as default, metadataField, mistralAIInstrumentor, netraExpressMiddleware, openaiAgentsInstrumentor, runWithExtractedContext, span, task, workflow };