@mastra/core/dist/observability/utils.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

/**
 * Browser-safe observability utilities.
 *
 * Functions that depend on AsyncLocalStorage (getCurrentSpan, executeWithContext,
 * executeWithContextSync) are in context-storage.ts and should only be imported
 * by server-side code.
 */
import { EntityType, SpanType } from './types/index.js';
import type { Span, GetOrCreateSpanOptions, AnySpan } from './types/index.js';
export declare function setCurrentSpanResolver(resolver: (() => AnySpan | undefined) | undefined): void;
export declare function resolveCurrentSpan(): AnySpan | undefined;
/** Generate a unique id for an observability signal (log, metric, score, feedback). */
export declare function generateSignalId(): string;
/**
 * Compute the names of tools the model can call on a single inference step,
 * applying `activeTools` filtering when present. Used to populate the
 * `availableTools` attribute on MODEL_INFERENCE spans so observers see the
 * post-processor tool set, which can differ per-step from the AGENT_RUN view.
 *
 * `activeTools` is treated by presence, not truthiness: an explicit empty
 * array means "no tools enabled for this step" and is honored as such.
 * Returns `[]` (not `undefined`) when `tools` is provided but empty, so a
 * tool-less agent still reports a definitive empty list to observers.
 */
export declare function getStepAvailableToolNames(tools?: Record<string, unknown> | undefined, activeTools?: readonly string[] | undefined): string[] | undefined;
type ExecuteWithContextFn = <T>(params: {
    span?: AnySpan;
    fn: () => Promise<T>;
}) => Promise<T>;
type ExecuteWithContextSyncFn = <T>(params: {
    span?: AnySpan;
    fn: () => T;
}) => T;
export declare function setExecuteWithContext(impl: ExecuteWithContextFn): void;
export declare function setExecuteWithContextSync(impl: ExecuteWithContextSyncFn): void;
/**
 * Execute an async function within a span's tracing context.
 * Falls back to direct execution if no context-storage implementation is registered or no span exists.
 */
export declare function executeWithContext<T>(params: {
    span?: AnySpan;
    fn: () => Promise<T>;
}): Promise<T>;
/**
 * Execute a sync function within a span's tracing context.
 * Falls back to direct execution if no context-storage implementation is registered or no span exists.
 */
export declare function executeWithContextSync<T>(params: {
    span?: AnySpan;
    fn: () => T;
}): T;
/**
 * Creates or gets a child span from existing tracing context or starts a new trace.
 * This helper consolidates the common pattern of creating spans that can either be:
 * 1. Children of an existing span (when tracingContext.currentSpan exists)
 * 2. New root spans (when no current span exists)
 *
 * @param options - Configuration object for span creation
 * @returns The created Span or undefined if tracing is disabled
 */
export declare function getOrCreateSpan<T extends SpanType>(options: GetOrCreateSpanOptions<T>): Span<T> | undefined;
/**
 * Returns the top-most non-internal span that would appear in exported tracing output.
 *
 * Public API results should use this span for trace/span correlation because internal Mastra
 * workflow spans are omitted from external exporters.
 */
export declare function getRootExportSpan(span?: AnySpan): AnySpan | undefined;
/**
 * Resolves the best available entity type for a span-like record.
 *
 * Prefers an explicit `entityType` when present and valid, then falls back to the
 * span type for common observability entities.
 */
export declare function getEntityTypeForSpan(span: {
    entityType?: string | null;
    spanType?: SpanType | string | null;
}): EntityType | undefined;
export {};
//# sourceMappingURL=utils.d.ts.map