@mastra/observability 1.2.1 → 1.3.0

package/dist/instances/base.d.ts

@@ -4,13 +4,24 @@
 import { MastraBase } from '@mastra/core/base';
 import type { RequestContext } from '@mastra/core/di';
 import type { IMastraLogger } from '@mastra/core/logger';
-import type { Span, SpanType, ObservabilityExporter, ObservabilityBridge, SpanOutputProcessor, TracingEvent, AnySpan, StartSpanOptions, CreateSpanOptions, ObservabilityInstance, CustomSamplerOptions, ExportedSpan, AnyExportedSpan, TraceState, TracingOptions } from '@mastra/core/observability';
+import type { Span, ObservabilityExporter, ObservabilityBridge, SpanOutputProcessor, TracingEvent, AnySpan, StartSpanOptions, CreateSpanOptions, ObservabilityInstance, CustomSamplerOptions, ExportedSpan, AnyExportedSpan, TraceState, TracingOptions, LoggerContext, MetricsContext, ObservabilityEvent, SpanType } from '@mastra/core/observability';
+import { ObservabilityBus } from '../bus/index.js';
 import type { ObservabilityInstanceConfig } from '../config.js';
+import { CardinalityFilter } from '../metrics/cardinality.js';
 /**
  * Abstract base class for all Observability implementations in Mastra.
  */
 export declare abstract class BaseObservabilityInstance extends MastraBase implements ObservabilityInstance {
     protected config: ObservabilityInstanceConfig;
+    /**
+     * Unified event bus for all observability signals.
+     * Routes events to registered exporters based on event type.
+     */
+    protected observabilityBus: ObservabilityBus;
+    /**
+     * Cardinality filter for metrics label protection.
+     */
+    protected cardinalityFilter: CardinalityFilter;
     constructor(config: ObservabilityInstanceConfig);
     /**
      * Override setLogger to add Observability specific initialization log
@@ -79,6 +90,43 @@ export declare abstract class BaseObservabilityInstance extends MastraBase imple
      * Get the logger instance (for exporters and other components)
      */
     getLogger(): IMastraLogger;
+    /**
+     * Get the ObservabilityBus for this instance.
+     * The bus routes all observability events (tracing, logs, metrics, scores, feedback)
+     * to registered exporters based on event type.
+     */
+    getObservabilityBus(): ObservabilityBus;
+    /**
+     * Extract entity context labels from a span's entity hierarchy by
+     * walking the parent chain.
+     *
+     * Returns labels for: entity_type/name, parent_type/name, root_type/name.
+     * Internal spans are skipped when resolving parent and root entities.
+     */
+    private extractEntityLabels;
+    /**
+     * Resolve tags for a span. Uses the span's own tags if present,
+     * otherwise walks to the root span to inherit its tags.
+     */
+    private resolveSpanTags;
+    /**
+     * Get a LoggerContext correlated to a span.
+     * Called by the context-factory in core (deriveLoggerContext) so that
+     * `observabilityContext.loggerVNext` is a real logger instead of no-op.
+     */
+    getLoggerContext(span?: AnySpan): LoggerContext;
+    /**
+     * Get a MetricsContext, optionally tagged from a span's entity info.
+     * Called by the context-factory in core (deriveMetricsContext) so that
+     * `observabilityContext.metrics` is a real metrics context instead of no-op.
+     */
+    getMetricsContext(span?: AnySpan): MetricsContext;
+    /**
+     * Emit any observability event through the bus.
+     * The bus routes the event to the appropriate handler on each registered exporter,
+     * and for tracing events triggers auto-extracted metrics.
+     */
+    protected emitObservabilityEvent(event: ObservabilityEvent): void;
     /**
      * Automatically wires up Observability lifecycle events for any span
      * This ensures all spans emit events regardless of implementation
@@ -106,19 +154,36 @@ export declare abstract class BaseObservabilityInstance extends MastraBase imple
     private processSpan;
     getSpanForExport(span: AnySpan): AnyExportedSpan | undefined;
     /**
-     * Emit a span started event
+     * Emit a span started event.
+     * Routes through the ObservabilityBus so exporters receive it via onTracingEvent
+     * and auto-extracted metrics are generated.
      */
     protected emitSpanStarted(span: AnySpan): void;
     /**
-     * Emit a span ended event (called automatically when spans end)
+     * Emit a span ended event (called automatically when spans end).
+     * Routes through the ObservabilityBus so exporters receive it via onTracingEvent
+     * and auto-extracted metrics are generated.
      */
     protected emitSpanEnded(span: AnySpan): void;
     /**
-     * Emit a span updated event
+     * Emit a span updated event.
+     * Routes through the ObservabilityBus so exporters receive it via onTracingEvent
+     * and auto-extracted metrics are generated.
      */
     protected emitSpanUpdated(span: AnySpan): void;
     /**
-     * Export tracing event through all exporters and bridge (realtime mode)
+     * Emit a tracing event through the bus.
+     *
+     * The bus routes the event to each registered exporter's and bridge's
+     * onTracingEvent handler and triggers auto-extracted metrics (e.g.,
+     * mastra_agent_runs_started, mastra_model_duration_ms).
+     */
+    private emitTracingEvent;
+    /**
+     * Export tracing event through all exporters and bridge.
+     *
+     * @deprecated Prefer emitTracingEvent() which routes through the bus.
+     * Kept for backward compatibility with subclasses that may override it.
      */
     protected exportTracingEvent(event: TracingEvent): Promise<void>;
     /**
@@ -126,12 +191,14 @@ export declare abstract class BaseObservabilityInstance extends MastraBase imple
      */
     init(): void;
     /**
-     * Force flush any buffered/queued spans from all exporters and the bridge
-     * without shutting down the observability instance.
+     * Flush all observability data: awaits in-flight handler promises, then
+     * drains exporter and bridge SDK-internal buffers.
+     *
+     * Delegates to ObservabilityBus.flush() which owns the two-phase logic.
      *
-     * This is useful in serverless environments (like Vercel's fluid compute) where
-     * you need to ensure all spans are exported before the runtime instance is
-     * terminated, while keeping the observability system active for future requests.
+     * This is critical for durable execution engines (e.g., Inngest) where
+     * the process may be interrupted after a step completes. Calling flush()
+     * outside the durable step ensures all span data reaches external systems.
      */
     flush(): Promise<void>;
     /**

package/dist/instances/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/instances/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/instances/base.ts"],"names":[],"mappings":"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"}

package/dist/metrics/auto-extract.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AutoExtractedMetrics - Converts TracingEvent, ScoreEvent, and FeedbackEvent
+ * into MetricEvents automatically.
+ *
+ * Cross-emission pattern: When a tracing span ends, this class emits
+ * metric events for agent runs, tool calls, workflow runs, and model
+ * generation stats (including token usage).
+ */
+import type { TracingEvent, ScoreEvent, FeedbackEvent } from '@mastra/core/observability';
+import type { ObservabilityBus } from '../bus/index.js';
+import type { CardinalityFilter } from './cardinality.js';
+export declare class AutoExtractedMetrics {
+    private observabilityBus;
+    private cardinalityFilter?;
+    /**
+     * @param observabilityBus - Bus used to emit derived MetricEvents.
+     * @param cardinalityFilter - Optional filter applied to metric labels before emission.
+     */
+    constructor(observabilityBus: ObservabilityBus, cardinalityFilter?: CardinalityFilter | undefined);
+    /**
+     * Route a tracing event to the appropriate span lifecycle handler.
+     * SPAN_STARTED increments a started counter; SPAN_ENDED emits ended counter,
+     * duration histogram, and (for model spans) token counters.
+     */
+    processTracingEvent(event: TracingEvent): void;
+    /** Emit a `mastra_scores_total` counter for a score event. */
+    processScoreEvent(event: ScoreEvent): void;
+    /** Emit a `mastra_feedback_total` counter for a feedback event. */
+    processFeedbackEvent(event: FeedbackEvent): void;
+    /** Emit a started counter (e.g. `mastra_agent_runs_started`) for the span type. */
+    private onSpanStarted;
+    /** Emit ended counter, duration histogram, and token counters (for model spans). */
+    private onSpanEnded;
+    /** Build base metric labels from a span's entity and model attributes. */
+    private extractLabels;
+    /** Emit token usage counters from a MODEL_GENERATION span's `usage` attributes. Negative and non-finite values are skipped. */
+    private extractTokenMetrics;
+    /** Map a span type to its `*_started` counter metric name, or `null` for unsupported types. */
+    private getStartedMetricName;
+    /** Map a span type to its `*_ended` counter metric name, or `null` for unsupported types. */
+    private getEndedMetricName;
+    /** Map a span type to its `*_duration_ms` histogram metric name, or `null` for unsupported types. */
+    private getDurationMetricName;
+    /** Build an ExportedMetric, apply cardinality filtering, and emit it through the bus. */
+    private emit;
+}
+//# sourceMappingURL=auto-extract.d.ts.map

package/dist/metrics/auto-extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-extract.d.ts","sourceRoot":"","sources":["../../src/metrics/auto-extract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EAKd,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,qBAAa,oBAAoB;IAM7B,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,iBAAiB,CAAC;IAN5B;;;OAGG;gBAEO,gBAAgB,EAAE,gBAAgB,EAClC,iBAAiB,CAAC,EAAE,iBAAiB,YAAA;IAG/C;;;;OAIG;IACH,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAW9C,8DAA8D;IAC9D,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAa1C,mEAAmE;IACnE,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAchD,mFAAmF;IACnF,OAAO,CAAC,aAAa;IAQrB,oFAAoF;IACpF,OAAO,CAAC,WAAW;IAkCnB,0EAA0E;IAC1E,OAAO,CAAC,aAAa;IAkBrB,+HAA+H;IAC/H,OAAO,CAAC,mBAAmB;IAyB3B,+FAA+F;IAC/F,OAAO,CAAC,oBAAoB;IAe5B,6FAA6F;IAC7F,OAAO,CAAC,kBAAkB;IAe1B,qGAAqG;IACrG,OAAO,CAAC,qBAAqB;IAe7B,yFAAyF;IACzF,OAAO,CAAC,IAAI;CAab"}

package/dist/metrics/cardinality.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CardinalityFilter - Prevents metric cardinality explosion.
+ *
+ * Filters out high-cardinality labels (like trace_id, user_id) and
+ * optionally blocks UUID-like values in labels.
+ */
+import type { CardinalityConfig } from '@mastra/core/observability';
+export declare class CardinalityFilter {
+    private blockedLabels;
+    private blockUUIDs;
+    /**
+     * @param config - Optional configuration. When omitted, uses
+     *   {@link DEFAULT_BLOCKED_LABELS} and blocks UUID-valued labels.
+     */
+    constructor(config?: CardinalityConfig);
+    /**
+     * Return a copy of `labels` with blocked keys and UUID values removed.
+     *
+     * @param labels - Raw metric labels to filter.
+     * @returns A new object containing only the allowed labels.
+     */
+    filterLabels(labels: Record<string, string>): Record<string, string>;
+}
+//# sourceMappingURL=cardinality.d.ts.map

package/dist/metrics/cardinality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardinality.d.ts","sourceRoot":"","sources":["../../src/metrics/cardinality.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAMpE,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,UAAU,CAAU;IAE5B;;;OAGG;gBACS,MAAM,CAAC,EAAE,iBAAiB;IAMtC;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAiBrE"}

package/dist/metrics/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Metrics implementations for observability.
+ */
+export { CardinalityFilter } from './cardinality.js';
+export { AutoExtractedMetrics } from './auto-extract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/observability",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Core observability package for Mastra - includes tracing and scoring features",
   "type": "module",
   "main": "dist/index.js",
@@ -32,11 +32,11 @@
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
     "zod": "^3.25.76",
-    "@internal/lint": "0.0.61",
-    "@internal/types-builder": "0.0.36",
-    "@internal/ai-sdk-v4": "0.0.8",
-    "@mastra/core": "1.6.0",
-    "@internal/ai-sdk-v5": "0.0.8"
+    "@internal/types-builder": "0.0.39",
+    "@internal/ai-sdk-v4": "0.0.11",
+    "@internal/lint": "0.0.64",
+    "@internal/ai-sdk-v5": "0.0.11",
+    "@mastra/core": "1.9.0"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.1.0-0 <2.0.0-0"

package/dist/exporters/json.d.ts

@@ -1,386 +0,0 @@
-/**
- * JSON Exporter for Observability Testing
- *
- * A full-featured exporter primarily designed for testing purposes that provides:
- * - In-memory event collection with JSON serialization
- * - File output support
- * - Span lifecycle tracking and validation
- * - Query methods for filtering spans by type, trace ID, span ID, etc.
- * - Statistics and analytics on collected spans
- */
-import type { TracingEvent, TracingEventType, AnyExportedSpan, ExportedSpan, SpanType } from '@mastra/core/observability';
-import { BaseExporter } from './base.js';
-import type { BaseExporterConfig } from './base.js';
-/**
- * Span state tracking for lifecycle validation
- */
-interface SpanState {
-    /** Whether SPAN_STARTED was received */
-    hasStart: boolean;
-    /** Whether SPAN_ENDED was received */
-    hasEnd: boolean;
-    /** Whether SPAN_UPDATED was received */
-    hasUpdate: boolean;
-    /** All events for this span in order */
-    events: TracingEvent[];
-    /** Whether this is an event span (zero duration) */
-    isEventSpan?: boolean;
-}
-/**
- * Statistics about collected spans
- */
-export interface JsonExporterStats {
-    /** Total number of events collected */
-    totalEvents: number;
-    /** Number of unique spans */
-    totalSpans: number;
-    /** Number of unique traces */
-    totalTraces: number;
-    /** Number of completed spans */
-    completedSpans: number;
-    /** Number of incomplete spans (started but not ended) */
-    incompleteSpans: number;
-    /** Breakdown by event type */
-    byEventType: {
-        started: number;
-        updated: number;
-        ended: number;
-    };
-    /** Breakdown by span type */
-    bySpanType: Record<string, number>;
-}
-/**
- * Span node in a tree structure with nested children
- */
-export interface SpanTreeNode {
-    /** The span data */
-    span: AnyExportedSpan;
-    /** Child spans nested under this span */
-    children: SpanTreeNode[];
-}
-/**
- * Normalized span data for snapshot testing.
- * Dynamic fields (IDs, timestamps) are replaced with stable values.
- */
-export interface NormalizedSpan {
-    /** Stable ID like <span-1>, <span-2> */
-    id: string;
-    /** Normalized trace ID like <trace-1>, <trace-2> */
-    traceId: string;
-    /** Normalized parent ID, or undefined for root */
-    parentId?: string;
-    /** Span name */
-    name: string;
-    /** Span type */
-    type: string;
-    /** Entity type */
-    entityType?: string;
-    /** Entity ID */
-    entityId?: string;
-    /** Whether the span completed (had an endTime) */
-    completed: boolean;
-    /** Span attributes */
-    attributes?: Record<string, unknown>;
-    /** Span metadata */
-    metadata?: Record<string, unknown>;
-    /** Input data */
-    input?: unknown;
-    /** Output data */
-    output?: unknown;
-    /** Error info if span failed */
-    errorInfo?: unknown;
-    /** Is an event span */
-    isEvent: boolean;
-    /** Is root span */
-    isRootSpan: boolean;
-    /** Tags */
-    tags?: string[];
-}
-/**
- * Normalized tree node for snapshot testing
- */
-export interface NormalizedTreeNode {
-    /** Normalized span data */
-    span: NormalizedSpan;
-    /** Child nodes (omitted if empty) */
-    children?: NormalizedTreeNode[];
-}
-/**
- * Incomplete span information for debugging
- */
-export interface IncompleteSpanInfo {
-    spanId: string;
-    span: AnyExportedSpan | undefined;
-    state: {
-        hasStart: boolean;
-        hasUpdate: boolean;
-        hasEnd: boolean;
-    };
-}
-/**
- * Configuration for JsonExporter
- */
-export interface JsonExporterConfig extends BaseExporterConfig {
-    /**
-     * Whether to validate span lifecycles in real-time.
-     * When true, will log warnings for lifecycle violations.
-     * @default true
-     */
-    validateLifecycle?: boolean;
-    /**
-     * Whether to store verbose logs for debugging.
-     * @default true
-     */
-    storeLogs?: boolean;
-    /**
-     * Indentation for JSON output (number of spaces, or undefined for compact).
-     * @default 2
-     */
-    jsonIndent?: number;
-}
-/**
- * JSON Exporter for testing and debugging observability.
- *
- * Provides comprehensive span collection, querying, and JSON output capabilities
- * designed primarily for testing purposes but useful for debugging as well.
- *
- * @example
- * ```typescript
- * const exporter = new JsonExporter();
- *
- * // Use with Mastra
- * const mastra = new Mastra({
- *   observability: {
- *     configs: {
- *       test: {
- *         serviceName: 'test',
- *         exporters: [exporter],
- *       },
- *     },
- *   },
- * });
- *
- * // Run some operations...
- *
- * // Query spans
- * const agentSpans = exporter.getSpansByType('agent_run');
- * const traceSpans = exporter.getByTraceId('abc123');
- *
- * // Get statistics
- * const stats = exporter.getStatistics();
- *
- * // Export to JSON
- * await exporter.writeToFile('./traces.json');
- * const jsonString = exporter.toJSON();
- * ```
- */
-export declare class JsonExporter extends BaseExporter {
-    #private;
-    name: string;
-    constructor(config?: JsonExporterConfig);
-    /**
-     * Process incoming tracing events with lifecycle tracking
-     */
-    protected _exportTracingEvent(event: TracingEvent): Promise<void>;
-    /**
-     * Get all collected events
-     */
-    get events(): TracingEvent[];
-    /**
-     * Get completed spans by SpanType (e.g., 'agent_run', 'tool_call')
-     *
-     * @param type - The SpanType to filter by
-     * @returns Array of completed exported spans of the specified type
-     */
-    getSpansByType<T extends SpanType>(type: T): ExportedSpan<T>[];
-    /**
-     * Get events by TracingEventType (SPAN_STARTED, SPAN_UPDATED, SPAN_ENDED)
-     *
-     * @param type - The TracingEventType to filter by
-     * @returns Array of events of the specified type
-     */
-    getByEventType(type: TracingEventType): TracingEvent[];
-    /**
-     * Get all events and spans for a specific trace
-     *
-     * @param traceId - The trace ID to filter by
-     * @returns Object containing events and final spans for the trace
-     */
-    getByTraceId(traceId: string): {
-        events: TracingEvent[];
-        spans: AnyExportedSpan[];
-    };
-    /**
-     * Get all events for a specific span
-     *
-     * @param spanId - The span ID to filter by
-     * @returns Object containing events and final span state
-     */
-    getBySpanId(spanId: string): {
-        events: TracingEvent[];
-        span: AnyExportedSpan | undefined;
-        state: SpanState | undefined;
-    };
-    /**
-     * Get all unique spans (returns the final state of each span)
-     */
-    getAllSpans(): AnyExportedSpan[];
-    /**
-     * Get only completed spans (those that have received SPAN_ENDED)
-     */
-    getCompletedSpans(): AnyExportedSpan[];
-    /**
-     * Get root spans only (spans with no parent)
-     */
-    getRootSpans(): AnyExportedSpan[];
-    /**
-     * Get incomplete spans (started but not yet ended)
-     */
-    getIncompleteSpans(): IncompleteSpanInfo[];
-    /**
-     * Get unique trace IDs from all collected spans
-     */
-    getTraceIds(): string[];
-    /**
-     * Get comprehensive statistics about collected spans
-     */
-    getStatistics(): JsonExporterStats;
-    /**
-     * Serialize all collected data to JSON string
-     *
-     * @param options - Serialization options
-     * @returns JSON string of all collected data
-     */
-    toJSON(options?: {
-        indent?: number;
-        includeEvents?: boolean;
-        includeStats?: boolean;
-    }): string;
-    /**
-     * Build a tree structure from spans, nesting children under their parents
-     *
-     * @returns Array of root span tree nodes (spans with no parent)
-     */
-    buildSpanTree(): SpanTreeNode[];
-    /**
-     * Serialize spans as a tree structure to JSON string
-     *
-     * @param options - Serialization options
-     * @returns JSON string with spans nested in tree format
-     */
-    toTreeJSON(options?: {
-        indent?: number;
-        includeStats?: boolean;
-    }): string;
-    /**
-     * Build a normalized tree structure suitable for snapshot testing.
-     *
-     * Normalizations applied:
-     * - Span IDs replaced with stable placeholders (<span-1>, <span-2>, etc.)
-     * - Trace IDs replaced with stable placeholders (<trace-1>, <trace-2>, etc.)
-     * - parentSpanId replaced with normalized parent ID
-     * - Timestamps replaced with durationMs (or null if not ended)
-     * - Empty children arrays are omitted
-     *
-     * @returns Array of normalized root tree nodes
-     */
-    buildNormalizedTree(): NormalizedTreeNode[];
-    /**
-     * Generate an ASCII tree structure graph for debugging.
-     * Shows span type and name in a hierarchical format.
-     *
-     * @param nodes - Normalized tree nodes (defaults to current normalized tree)
-     * @returns Array of strings representing the tree structure
-     *
-     * @example
-     * ```
-     * agent_run: "agent run: 'test-agent'"
-     * ├── processor_run: "input processor: validator"
-     * │   └── agent_run: "agent run: 'validator-agent'"
-     * └── model_generation: "llm: 'mock-model-id'"
-     * ```
-     */
-    generateStructureGraph(nodes?: NormalizedTreeNode[]): string[];
-    /**
-     * Serialize spans as a normalized tree structure for snapshot testing.
-     * Includes a __structure__ field with an ASCII tree graph for readability.
-     *
-     * @param options - Serialization options
-     * @returns JSON string with normalized spans in tree format
-     */
-    toNormalizedTreeJSON(options?: {
-        indent?: number;
-        includeStructure?: boolean;
-    }): string;
-    /**
-     * Write collected data to a JSON file
-     *
-     * @param filePath - Path to write the JSON file
-     * @param options - Serialization options
-     */
-    writeToFile(filePath: string, options?: {
-        indent?: number;
-        includeEvents?: boolean;
-        includeStats?: boolean;
-        format?: 'flat' | 'tree' | 'normalized';
-    }): Promise<void>;
-    /**
-     * Assert that the current normalized tree matches a snapshot file.
-     * Throws an error with a diff if they don't match.
-     *
-     * The snapshot format includes:
-     * - `__structure__`: ASCII tree graph (compared first for quick validation)
-     * - `spans`: The normalized span tree (detailed comparison)
-     *
-     * Supports special markers in the snapshot:
-     * - `{"__or__": ["value1", "value2"]}` - matches if actual equals any listed value
-     * - `{"__any__": "string"}` - matches any string value
-     * - `{"__any__": "number"}` - matches any number value
-     * - `{"__any__": "boolean"}` - matches any boolean value
-     * - `{"__any__": "object"}` - matches any object value
-     * - `{"__any__": "array"}` - matches any array value
-     * - `{"__any__": true}` - matches any non-null/undefined value
-     *
-     * Environment variables:
-     * Use `{ updateSnapshot: true }` option to update the snapshot instead of comparing
-     *
-     * @param snapshotName - Name of the snapshot file (resolved relative to __snapshots__ directory)
-     * @param options - Options for snapshot comparison
-     * @param options.updateSnapshot - If true, update the snapshot file instead of comparing
-     * @throws Error if the snapshot doesn't match (and updateSnapshot is false)
-     */
-    assertMatchesSnapshot(snapshotName: string, options?: {
-        updateSnapshot?: boolean;
-    }): Promise<void>;
-    /**
-     * Get all stored logs
-     */
-    getLogs(): string[];
-    /**
-     * Dump logs to console for debugging (uses console.error for visibility in test output)
-     */
-    dumpLogs(): void;
-    /**
-     * Validate final state - useful for test assertions
-     *
-     * @returns Object with validation results
-     */
-    validateFinalState(): {
-        valid: boolean;
-        singleTraceId: boolean;
-        allSpansComplete: boolean;
-        traceIds: string[];
-        incompleteSpans: IncompleteSpanInfo[];
-    };
-    /**
-     * Clear all collected events and state
-     */
-    clearEvents(): void;
-    /**
-     * Alias for clearEvents (compatibility with TestExporter)
-     */
-    reset(): void;
-    shutdown(): Promise<void>;
-}
-export {};
-//# sourceMappingURL=json.d.ts.map

package/dist/exporters/json.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/exporters/json.ts"],"names":[],"mappings":"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"}