Interfaces

Core Interfaces

AITracing

Primary interface for AI Tracing.

interface AITracing {
  /** Get current configuration */
  getConfig(): Readonly<Required<TracingConfig>>;

  /** Get all exporters */
  getExporters(): readonly AITracingExporter[];

  /** Get all processors */
  getProcessors(): readonly AISpanProcessor[];

  /** Get the logger instance (for exporters and other components) */
  getLogger(): IMastraLogger;

  /** Start a new span of a specific AISpanType */
  startSpan<TType extends AISpanType>(
    options: StartSpanOptions<TType>,
  ): AISpan<TType>;

  /** Shutdown AI tracing and clean up resources */
  shutdown(): Promise<void>;
}

AISpanTypeMap

Mapping of span types to their corresponding attribute interfaces.

interface AISpanTypeMap {
  AGENT_RUN: AgentRunAttributes;
  WORKFLOW_RUN: WorkflowRunAttributes;
  MODEL_GENERATION: ModelGenerationAttributes;
  MODEL_STEP: ModelStepAttributes;
  MODEL_CHUNK: ModelChunkAttributes;
  TOOL_CALL: ToolCallAttributes;
  MCP_TOOL_CALL: MCPToolCallAttributes;
  WORKFLOW_STEP: WorkflowStepAttributes;
  WORKFLOW_CONDITIONAL: WorkflowConditionalAttributes;
  WORKFLOW_CONDITIONAL_EVAL: WorkflowConditionalEvalAttributes;
  WORKFLOW_PARALLEL: WorkflowParallelAttributes;
  WORKFLOW_LOOP: WorkflowLoopAttributes;
  WORKFLOW_SLEEP: WorkflowSleepAttributes;
  WORKFLOW_WAIT_EVENT: WorkflowWaitEventAttributes;
  GENERIC: AIBaseAttributes;
}

This mapping defines which attribute interface is used for each span type when creating or processing spans.

AISpan

AI Span interface, used internally for tracing.

interface AISpan<TType extends AISpanType> {
  readonly id: string;
  readonly traceId: string;
  readonly type: TType;
  readonly name: string;

  /** Is an internal span? (spans internal to the operation of mastra) */
  isInternal: boolean;

  /** Parent span reference (undefined for root spans) */
  parent?: AnyAISpan;

  /** Pointer to the AITracing instance */
  aiTracing: AITracing;

  attributes?: AISpanTypeMap[TType];
  metadata?: Record<string, any>;
  input?: any;
  output?: any;
  errorInfo?: any;

  /** End the span */
  end(options?: EndSpanOptions<TType>): void;

  /** Record an error for the span, optionally end the span as well */
  error(options: ErrorSpanOptions<TType>): void;

  /** Update span attributes */
  update(options: UpdateSpanOptions<TType>): void;

  /** Create child span - can be any span type independent of parent */
  createChildSpan<TChildType extends AISpanType>(
    options: ChildSpanOptions<TChildType>,
  ): AISpan<TChildType>;

  /** Create event span - can be any span type independent of parent */
  createEventSpan<TChildType extends AISpanType>(
    options: ChildEventOptions<TChildType>,
  ): AISpan<TChildType>;

  /** Returns TRUE if the span is the root span of a trace */
  get isRootSpan(): boolean;

  /** Returns TRUE if the span is a valid span (not a NO-OP Span) */
  get isValid(): boolean;
}

AITracingExporter

Interface for tracing exporters.

interface AITracingExporter {
  /** Exporter name */
  name: string;

  /** Initialize exporter (called after all dependencies are ready) */
  init?(): void;

  /** Export tracing events */
  exportEvent(event: AITracingEvent): Promise<void>;

  /** Shutdown exporter */
  shutdown(): Promise<void>;
}

AISpanProcessor

Interface for span processors.

interface AISpanProcessor {
  /** Processor name */
  name: string;

  /** Process span before export */
  process(span?: AnyAISpan): AnyAISpan | undefined;

  /** Shutdown processor */
  shutdown(): Promise<void>;
}

Span Types

AISpanType

AI-specific span types with their associated metadata.

enum AISpanType {
  /** Agent run - root span for agent processes */
  AGENT_RUN = "agent_run",

  /** Generic span for custom operations */
  GENERIC = "generic",

  /** Model generation with model calls, token usage, prompts, completions */
  MODEL_GENERATION = "model_generation",

  /** Single model execution step within a generation (one API call) */
  MODEL_STEP = "model_step",

  /** Individual model streaming chunk/event */
  MODEL_CHUNK = "model_chunk",

  /** MCP (Model Context Protocol) tool execution */
  MCP_TOOL_CALL = "mcp_tool_call",

  /** Function/tool execution with inputs, outputs, errors */
  TOOL_CALL = "tool_call",

  /** Workflow run - root span for workflow processes */
  WORKFLOW_RUN = "workflow_run",

  /** Workflow step execution with step status, data flow */
  WORKFLOW_STEP = "workflow_step",

  /** Workflow conditional execution with condition evaluation */
  WORKFLOW_CONDITIONAL = "workflow_conditional",

  /** Individual condition evaluation within conditional */
  WORKFLOW_CONDITIONAL_EVAL = "workflow_conditional_eval",

  /** Workflow parallel execution */
  WORKFLOW_PARALLEL = "workflow_parallel",

  /** Workflow loop execution */
  WORKFLOW_LOOP = "workflow_loop",

  /** Workflow sleep operation */
  WORKFLOW_SLEEP = "workflow_sleep",

  /** Workflow wait for event operation */
  WORKFLOW_WAIT_EVENT = "workflow_wait_event",
}

AnyAISpan

Union type for cases that need to handle any span.

type AnyAISpan = AISpan<keyof AISpanTypeMap>;

Span Attributes

AgentRunAttributes

Agent Run attributes.

interface AgentRunAttributes {
  /** Agent identifier */
  agentId: string;

  /** Agent Instructions */
  instructions?: string;

  /** Agent Prompt */
  prompt?: string;

  /** Available tools for this execution */
  availableTools?: string[];

  /** Maximum steps allowed */
  maxSteps?: number;
}

ModelGenerationAttributes

Model Generation attributes.

interface ModelGenerationAttributes {
  /** Model name (e.g., 'gpt-4', 'claude-3') */
  model?: string;

  /** Model provider (e.g., 'openai', 'anthropic') */
  provider?: string;

  /** Type of result/output this model call produced */
  resultType?:
    | "tool_selection"
    | "response_generation"
    | "reasoning"
    | "planning";

  /** Token usage statistics */
  usage?: {
    promptTokens?: number;
    completionTokens?: number;
    totalTokens?: number;
    promptCacheHitTokens?: number;
    promptCacheMissTokens?: number;
  };

  /** Model parameters */
  parameters?: {
    maxOutputTokens?: number;
    temperature?: number;
    topP?: number;
    topK?: number;
    presencePenalty?: number;
    frequencyPenalty?: number;
    stopSequences?: string[];
    seed?: number;
    maxRetries?: number;
  };

  /** Whether this was a streaming response */
  streaming?: boolean;

  /** Reason the generation finished */
  finishReason?: string;
}

ModelStepAttributes

Model Step attributes - for a single model execution within a generation.

interface ModelStepAttributes {
  /** Index of this step in the generation (0, 1, 2, ...) */
  stepIndex?: number;

  /** Token usage statistics */
  usage?: UsageStats;

  /** Reason this step finished (stop, tool-calls, length, etc.) */
  finishReason?: string;

  /** Should execution continue */
  isContinued?: boolean;

  /** Result warnings */
  warnings?: Record<string, any>;
}

ModelChunkAttributes

Model Chunk attributes - for individual streaming chunks/events.

interface ModelChunkAttributes {
  /** Type of chunk (text-delta, reasoning-delta, tool-call, etc.) */
  chunkType?: string;

  /** Sequence number of this chunk in the stream */
  sequenceNumber?: number;
}

ToolCallAttributes

Tool Call attributes.

interface ToolCallAttributes {
  toolId?: string;
  toolType?: string;
  toolDescription?: string;
  success?: boolean;
}

MCPToolCallAttributes

MCP Tool Call attributes.

interface MCPToolCallAttributes {
  /** Id of the MCP tool/function */
  toolId: string;

  /** MCP server identifier */
  mcpServer: string;

  /** MCP server version */
  serverVersion?: string;

  /** Whether tool execution was successful */
  success?: boolean;
}

WorkflowRunAttributes

Workflow Run attributes.

interface WorkflowRunAttributes {
  /** Workflow identifier */
  workflowId: string;

  /** Workflow version */
  workflowVersion?: string;

  /** Workflow run ID */
  runId?: string;

  /** Final workflow execution status */
  status?: WorkflowRunStatus;
}

WorkflowStepAttributes

Workflow Step attributes.

interface WorkflowStepAttributes {
  /** Step identifier */
  stepId?: string;

  /** Step type */
  stepType?: string;

  /** Step status */
  status?: WorkflowStepStatus;

  /** Step execution order */
  stepNumber?: number;

  /** Result store key */
  resultKey?: string;
}

Options Types

StartSpanOptions

Options for starting new spans.

interface StartSpanOptions<TType extends AISpanType> {
  /** Span type */
  type: TType;

  /** Span name */
  name: string;

  /** Span attributes */
  attributes?: AISpanTypeMap[TType];

  /** Span metadata */
  metadata?: Record<string, any>;

  /** Input data */
  input?: any;

  /** Parent span */
  parent?: AnyAISpan;

  /** Policy-level tracing configuration */
  tracingPolicy?: TracingPolicy;

  /** Options passed when using a custom sampler strategy */
  customSamplerOptions?: CustomSamplerOptions;
}

UpdateSpanOptions

Options for updating spans.

interface UpdateSpanOptions<TType extends AISpanType> {
  /** Span attributes */
  attributes?: Partial<AISpanTypeMap[TType]>;

  /** Span metadata */
  metadata?: Record<string, any>;

  /** Input data */
  input?: any;

  /** Output data */
  output?: any;
}

EndSpanOptions

Options for ending spans.

interface EndSpanOptions<TType extends AISpanType> {
  /** Output data */
  output?: any;

  /** Span metadata */
  metadata?: Record<string, any>;

  /** Span attributes */
  attributes?: Partial<AISpanTypeMap[TType]>;
}

ErrorSpanOptions

Options for recording span errors.

interface ErrorSpanOptions<TType extends AISpanType> {
  /** The error associated with the issue */
  error: Error;

  /** End the span when true */
  endSpan?: boolean;

  /** Span metadata */
  metadata?: Record<string, any>;

  /** Span attributes */
  attributes?: Partial<AISpanTypeMap[TType]>;
}

Context Types

TracingContext

Context for AI tracing that flows through workflow and agent execution.

interface TracingContext {
  /** Current AI span for creating child spans and adding metadata */
  currentSpan?: AnyAISpan;
}

TracingProperties

Properties returned to the user for working with traces externally.

type TracingProperties = {
  /** Trace ID used on the execution (if the execution was traced) */
  traceId?: string;
};

TracingOptions

Options passed when starting a new agent or workflow execution.

interface TracingOptions {
  /** Metadata to add to the root trace span */
  metadata?: Record<string, any>;
}

TracingPolicy

Policy-level tracing configuration applied when creating a workflow or agent.

interface TracingPolicy {
  /**
   * Bitwise options to set different types of spans as Internal in
   * a workflow or agent execution. Internal spans are hidden by
   * default in exported traces.
   */
  internal?: InternalSpans;
}

Configuration Types

TracingConfig

Configuration for a single tracing instance.

interface TracingConfig {
  /** Unique identifier for this config in the ai tracing registry */
  name: string;

  /** Service name for tracing */
  serviceName: string;

  /** Sampling strategy - controls whether tracing is collected (defaults to ALWAYS) */
  sampling?: SamplingStrategy;

  /** Custom exporters */
  exporters?: AITracingExporter[];

  /** Custom processors */
  processors?: AISpanProcessor[];

  /** Set to true if you want to see spans internal to the operation of mastra */
  includeInternalSpans?: boolean;
}

ObservabilityRegistryConfig

Complete AI Tracing registry configuration.

interface ObservabilityRegistryConfig {
  /** Enables default exporters, with sampling: always, and sensitive data filtering */
  default?: {
    enabled?: boolean;
  };

  /** Map of tracing instance names to their configurations or pre-instantiated instances */
  configs?: Record<string, Omit<TracingConfig, "name"> | AITracing>;

  /** Optional selector function to choose which tracing instance to use */
  configSelector?: ConfigSelector;
}

Sampling Types

SamplingStrategy

Sampling strategy configuration.

type SamplingStrategy =
  | { type: "always" }
  | { type: "never" }
  | { type: "ratio"; probability: number }
  | { type: "custom"; sampler: (options?: CustomSamplerOptions) => boolean };

CustomSamplerOptions

Options passed when using a custom sampler strategy.

interface CustomSamplerOptions {
  runtimeContext?: RuntimeContext;
  metadata?: Record<string, any>;
}

Config Selector Types

ConfigSelector

Function to select which AI tracing instance to use for a given span.

type ConfigSelector = (
  options: ConfigSelectorOptions,
  availableConfigs: ReadonlyMap<string, AITracing>,
) => string | undefined;

ConfigSelectorOptions

Options passed when using a custom tracing config selector.

interface ConfigSelectorOptions {
  /** Request Context */
  runtimeContext?: RuntimeContext;
}

Internal Spans

InternalSpans

Bitwise options to set different types of spans as internal in a workflow or agent execution.

enum InternalSpans {
  /** No spans are marked internal */
  NONE = 0,

  /** Workflow spans are marked internal */
  WORKFLOW = 1 << 0,

  /** Agent spans are marked internal */
  AGENT = 1 << 1,

  /** Tool spans are marked internal */
  TOOL = 1 << 2,

  /** Model spans are marked internal */
  MODEL = 1 << 3,

  /** All spans are marked internal */
  ALL = (1 << 4) - 1,
}

See Also

Documentation

• AI Tracing Overview - Complete guide to AI tracing
• Creating Child Spans - Working with span hierarchies
• Adding Custom Metadata - Enriching traces

Reference

• Configuration - Registry and configuration
• AITracing Classes - Core implementations
• Span Reference - Span lifecycle methods

Examples

• Basic AI Tracing - Implementation example