/**
 * BaseObservability - Abstract base class for Observability implementations
 */
import { MastraBase } from '@mastra/core/base';
import type { RequestContext } from '@mastra/core/di';
import type { IMastraLogger } from '@mastra/core/logger';
import { SpanType } from '@mastra/core/observability';
import type { Span, ObservabilityExporter, ObservabilityBridge, SpanOutputProcessor, TracingEvent, AnySpan, StartSpanOptions, CreateSpanOptions, ObservabilityInstance, CustomSamplerOptions, ExportedSpan, AnyExportedSpan, TraceState, TracingOptions, LoggerContext, MetricsContext, ObservabilityEvent } 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 {
    #private;
    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
     * and propagate logger to exporters and bridge
     */
    __setLogger(logger: IMastraLogger): void;
    protected get exporters(): ObservabilityExporter[];
    protected get spanOutputProcessors(): SpanOutputProcessor[];
    /**
     * Start a new span of a specific SpanType
     *
     * Sampling Decision:
     * - For root spans (no parent): Perform sampling check using the configured strategy
     * - For child spans: Inherit the sampling decision from the parent
     *   - If parent is a NoOpSpan (not sampled), child is also a NoOpSpan
     *   - If parent is a valid span (sampled), child is also sampled
     *
     * This ensures trace-level sampling: either all spans in a trace are sampled or none are.
     * See: https://github.com/mastra-ai/mastra/issues/11504
     */
    startSpan<TType extends SpanType>(options: StartSpanOptions<TType>): Span<TType>;
    /**
     * Rebuild a span from exported data for lifecycle operations.
     * Used by durable execution engines (e.g., Inngest) to end/update spans
     * that were created in a previous durable operation.
     *
     * The rebuilt span:
     * - Does NOT emit SPAN_STARTED (assumes original span already did)
     * - Can have end(), update(), error() called on it
     * - Will emit SPAN_ENDED or SPAN_UPDATED when those methods are called
     *
     * @param cached - The exported span data to rebuild from
     * @returns A span that can have lifecycle methods called on it
     */
    rebuildSpan<TType extends SpanType>(cached: ExportedSpan<TType>): Span<TType>;
    /**
     * Create a new span (called after sampling)
     *
     * Implementations should:
     * 1. Create a plain span with the provided attributes
     * 2. Return the span - base class handles all tracing lifecycle automatically
     *
     * The base class will automatically:
     * - Set trace relationships
     * - Wire span lifecycle callbacks
     * - Emit span_started event
     */
    protected abstract createSpan<TType extends SpanType>(options: CreateSpanOptions<TType>): Span<TType>;
    /**
     * Get current configuration
     */
    getConfig(): Readonly<ObservabilityInstanceConfig>;
    /**
     * Returns the deployment environment propagated from the parent Mastra instance.
     * Spans use this as a fallback when `metadata.environment` isn't set.
     */
    getMastraEnvironment(): string | undefined;
    /**
     * Internal hook used by `Observability.setMastraContext` to push the
     * resolved Mastra-level environment into this instance.
     */
    __setMastraEnvironment(environment: string | undefined): void;
    /**
     * Get all exporters
     */
    getExporters(): readonly ObservabilityExporter[];
    /**
     * Register an additional exporter at runtime.
     * Adds to both the bus (for event routing) and the config (for getExporters).
     */
    registerExporter(exporter: ObservabilityExporter): void;
    /**
     * Get all span output processors
     */
    getSpanOutputProcessors(): readonly SpanOutputProcessor[];
    /**
     * Get the bridge instance if configured
     */
    getBridge(): ObservabilityBridge | undefined;
    /**
     * 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;
    /**
     * 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 correlated to a span.
     * 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;
    /**
     * Internal hook used by RecordedTrace/RecordedSpan hydration to route
     * non-tracing annotation events back through the normal exporter pipeline.
     */
    __emitRecordedEvent(event: ObservabilityEvent): void;
    /**
     * Internal hook used by the client observability proxy (`client/`)
     * to route already-validated events through the normal bus without
     * going through the live span lifecycle. The caller is responsible
     * for constructing well-formed `ExportedSpan`s/`ExportedLog`s and
     * for any validation needed.
     */
    __receiveExternalEvent(event: ObservabilityEvent): void;
    /**
     * Automatically wires up Observability lifecycle events for any span
     * This ensures all spans emit events regardless of implementation
     */
    private wireSpanLifecycle;
    /**
     * Check if a trace should be sampled
     */
    protected shouldSample(options?: CustomSamplerOptions): boolean;
    /**
     * Compute TraceState for a new trace based on configured and per-request keys
     */
    protected computeTraceState(tracingOptions?: TracingOptions): TraceState | undefined;
    /**
     * Extract metadata from RequestContext using TraceState
     */
    protected extractMetadataFromRequestContext(requestContext: RequestContext | undefined, explicitMetadata: Record<string, any> | undefined, traceState: TraceState | undefined): Record<string, any> | undefined;
    /**
     * Extract specific keys from RequestContext
     */
    protected extractKeys(requestContext: RequestContext, keys: string[]): Record<string, any>;
    /**
     * Process a span through all output processors
     */
    private processSpan;
    /** Process a span through output processors and export it, returning undefined if filtered out. */
    getSpanForExport(span: AnySpan): AnyExportedSpan | undefined;
    /**
     * Emit a span started event.
     * Routes through the ObservabilityBus so exporters receive it via onTracingEvent.
     */
    protected emitSpanStarted(span: AnySpan): void;
    /**
     * Emit a span ended event (called automatically when spans end).
     * Emits any auto-extracted metrics while the live span tree is still available,
     * then routes the exported tracing event through the ObservabilityBus.
     */
    protected emitSpanEnded(span: AnySpan): void;
    /**
     * Emit a span updated event.
     * Routes through the ObservabilityBus so exporters receive it via onTracingEvent.
     */
    protected emitSpanUpdated(span: AnySpan): void;
    /**
     * When an internal MODEL_GENERATION span ends, capture the rollup payload
     * (usage, provider, model, target ancestor) needed to attribute its cost
     * to the closest exported ancestor span. Returns undefined when no rollup
     * applies — non-MODEL_GENERATION spans, spans that will be exported, or
     * spans whose usage isn't available at end time.
     */
    private captureModelUsageRollup;
    /**
     * Accumulate usage onto the ancestor's `internalUsage` attribute (for trace
     * UI visibility) and emit auto-extracted token metrics now, using the
     * ancestor's metrics context so cost / token labels point at the visible
     * span instead of the hidden agent that incurred them.
     */
    private applyUsageRollup;
    /**
     * Walk up the parent chain to find the closest ancestor that will actually
     * reach exporters. Skips both internal-filtered ancestors and ancestors
     * whose type matches `excludeSpanTypes`, so the rollup target is one whose
     * mutated `internalUsage` attribute is visible in exported traces.
     *
     * Note: this does not preemptively run `spanFilter` — that filter can be
     * async and have side effects, so the rare case of a `spanFilter`-dropped
     * ancestor falls through.
     */
    private findExportedAncestor;
    /**
     * Returns true when a span would be dropped by `getSpanForExport` for a
     * reason cheap to check up-front (internal-span filtering or
     * `excludeSpanTypes`). Used by `findExportedAncestor` to skip rollup
     * targets that would silently lose their `internalUsage` attribute.
     */
    private isFilteredFromExport;
    /**
     * Emit a tracing event through the bus.
     *
     * The bus routes the event to each registered exporter's and bridge's
     * onTracingEvent handler.
     */
    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>;
    /**
     * Initialize Observability (called by Mastra during component registration)
     */
    init(): void;
    /**
     * 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 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>;
    /**
     * Shutdown Observability and clean up resources
     */
    shutdown(): Promise<void>;
}
//# sourceMappingURL=base.d.ts.map