@mastra/core
Version:
857 lines (627 loc) • 21.7 kB
Markdown
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
# Interfaces
## Core interfaces
### `ObservabilityInstance`
Primary interface for observability.
```typescript
interface ObservabilityInstance {
/** Get current configuration */
getConfig(): Readonly<Required<ObservabilityInstanceConfig>>
/** Get all exporters */
getExporters(): readonly ObservabilityExporter[]
/** Get all span output processors */
getSpanOutputProcessors(): readonly SpanOutputProcessor[]
/** Get the logger instance (for exporters and other components) */
getLogger(): IMastraLogger
/** Start a new span of a specific SpanType */
startSpan<TType extends SpanType>(options: StartSpanOptions<TType>): Span<TType>
/** Force flush any buffered spans without shutting down */
flush(): Promise<void>
/** Shutdown observability and clean up resources */
shutdown(): Promise<void>
}
```
### `SpanTypeMap`
Mapping of span types to their corresponding attribute interfaces.
```typescript
interface SpanTypeMap {
AGENT_RUN: AgentRunAttributes
WORKFLOW_RUN: WorkflowRunAttributes
MODEL_GENERATION: ModelGenerationAttributes
MODEL_STEP: ModelStepAttributes
MODEL_CHUNK: ModelChunkAttributes
TOOL_CALL: ToolCallAttributes
CLIENT_TOOL_CALL: ClientToolCallAttributes
MCP_TOOL_CALL: MCPToolCallAttributes
PROCESSOR_RUN: ProcessorRunAttributes
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.
### Span
Span interface, used internally for tracing.
```typescript
interface Span<TType extends SpanType> {
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?: AnySpan
/** Pointer to the ObservabilityInstance instance */
observabilityInstance: ObservabilityInstance
attributes?: SpanTypeMap[TType]
metadata?: Record<string, any>
input?: any
output?: any
errorInfo?: any
/** Tags for categorizing traces (only present on root spans) */
tags?: string[]
/** 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 SpanType>(
options: ChildSpanOptions<TChildType>,
): Span<TChildType>
/** Create event span - can be any span type independent of parent */
createEventSpan<TChildType extends SpanType>(
options: ChildEventOptions<TChildType>,
): Span<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
}
```
### `ObservabilityExporter`
Interface for observability exporters.
```typescript
interface ObservabilityExporter {
/** Exporter name */
name: string
/** Initialize exporter with tracing configuration and/or access to Mastra */
init?(options: InitExporterOptions): void
/** Handle tracing events */
onTracingEvent?(event: TracingEvent): void | Promise<void>
/** Handle log events */
onLogEvent?(event: LogEvent): void | Promise<void>
/** Handle metric events */
onMetricEvent?(event: MetricEvent): void | Promise<void>
/** Handle score events */
onScoreEvent?(event: ScoreEvent): void | Promise<void>
/** Handle feedback events */
onFeedbackEvent?(event: FeedbackEvent): void | Promise<void>
/** Handle exporter pipeline droppedEvent */
onDroppedEvent?(event: ObservabilityDropEvent): void | Promise<void>
/** Export tracing events */
exportTracingEvent(event: TracingEvent): Promise<void>
/**
* @deprecated Implement `onScoreEvent` instead. Eval scores now flow through the
* unified observability bus as `ScoreEvent`s. This method is preserved on the
* interface for backwards compatibility with existing exporters; new exporters
* should not implement it.
*/
addScoreToTrace?({
traceId,
spanId,
score,
reason,
scorerName,
metadata,
}: {
traceId: string
spanId?: string
score: number
reason?: string
scorerName: string
metadata?: Record<string, any>
}): Promise<void>
/** Force flush any buffered spans without shutting down */
flush(): Promise<void>
/** Shutdown exporter */
shutdown(): Promise<void>
}
```
Event callback payloads use observability event bus envelopes: `TracingEvent` carries span lifecycle events with `exportedSpan`, `LogEvent` wraps `ExportedLog` in `log`, `MetricEvent` wraps `ExportedMetric` in `metric`, `ScoreEvent` wraps `ExportedScore` in `score`, and `FeedbackEvent` wraps `ExportedFeedback` in `feedback`. For Mastra platform exporter behavior for these callbacks, see [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
Like `LogEvent`, `MetricEvent`, and `FeedbackEvent`, `ScoreEvent` is an observability bus envelope that wraps a bounded payload. For scores, that payload is `ExportedScore`.
### `ScoreEvent`
Score events are sent to exporters through `onScoreEvent`. The event is a small envelope with the signal type and the score payload:
```typescript
interface ScoreEvent {
type: 'score'
score: ExportedScore
}
```
### `ExportedScore`
`ExportedScore` is the bounded payload that exporters receive inside `ScoreEvent.score`. It contains the score identity, target trace or span anchor, scorer details, value, optional explanation, and correlation metadata.
```typescript
interface ExportedScore {
scoreId: string
timestamp: Date
traceId?: string
spanId?: string
scorerId: string
scorerName?: string
scorerVersion?: string
source?: string
scoreSource?: string
score: number
reason?: string
experimentId?: string
scoreTraceId?: string
targetEntityType?: EntityType
correlationContext?: CorrelationContext
metadata?: Record<string, unknown>
}
```
`traceId` and `spanId` identify the trace or span being scored. `scoreTraceId` identifies the trace of the scoring run itself when that scorer was traced. For new exporters, prefer `scoreSource` over the deprecated `source` field, and prefer `correlationContext.experimentId` over the deprecated top-level `experimentId` field.
`EntityType` is Mastra's observability entity enum. Current values include `agent`, `scorer`, `rag_ingestion`, `trajectory`, `input_processor`, `input_step_processor`, `output_processor`, `output_step_processor`, `workflow_step`, `tool`, `workflow_run`, and `memory`.
`CorrelationContext` is the shared context snapshot attached to observability signals. It can carry entity hierarchy fields, user or organization identifiers, run, session, thread, request, environment, source, service name, experiment, and tags. Prefer the top-level `traceId` and `spanId` fields on `ExportedScore` for the scored target.
### `ObservabilityDropEvent`
Structured event emitted when the exporter pipeline drops observability events.
```typescript
type ObservabilityDropSignal = 'tracing' | 'log' | 'metric' | 'score' | 'feedback'
type ObservabilityDropReason = 'unsupported-storage' | 'retry-exhausted'
interface ObservabilityDropEvent {
type: 'drop'
signal: ObservabilityDropSignal
reason: ObservabilityDropReason
count: number
timestamp: Date
exporterName: string
storageName?: string
error?: {
id?: string
domain?: string
message: string
}
}
```
Use `onDroppedEvent` on a custom exporter or bridge to forward these events to external metrics or alerting systems.
### `SpanOutputProcessor`
Interface for span output processors.
```typescript
interface SpanOutputProcessor {
/** Processor name */
name: string
/** Process span before export */
process(span?: AnySpan): AnySpan | undefined
/** Shutdown processor */
shutdown(): Promise<void>
}
```
## Span types
### `SpanType`
AI-specific span types with their associated metadata.
```typescript
enum SpanType {
/** 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',
/** Input or Output Processor execution */
PROCESSOR_RUN = 'processor_run',
/** Function/tool execution with inputs, outputs, errors */
TOOL_CALL = 'tool_call',
/**
* Client-side tool execution marker. The server creates this span
* when the model emits a client tool call, injects its W3C carrier
* into the outgoing tool-call chunk, then ends the span once tool
* args are available. Child spans/logs from the client SDK flow back
* as OTLP/JSON via the ClientObservabilityProxy interface in
* @mastra/observability and parent themselves under this span.
* See the "Client tools" section in the @mastra/client-js reference
* for the full flow.
*/
CLIENT_TOOL_CALL = 'client_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',
}
```
### `AnySpan`
Union type for cases that need to handle any span.
```typescript
type AnySpan = Span<keyof SpanTypeMap>
```
## Span attributes
### `AgentRunAttributes`
Agent Run attributes.
```typescript
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.
```typescript
interface ModelGenerationAttributes {
/** Model name (e.g., 'gpt-5.4', 'claude-opus-4-6') */
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.
```typescript
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.
```typescript
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.
```typescript
interface ToolCallAttributes {
toolId?: string
toolType?: string
toolDescription?: string
success?: boolean
}
```
### MCPToolCallAttributes
MCP Tool Call attributes.
```typescript
interface MCPToolCallAttributes {
/** Id of the MCP tool/function */
toolId: string
/** MCP server identifier */
mcpServer: string
/** MCP server version */
serverVersion?: string
/** Tool description */
toolDescription?: string
/** Whether tool execution was successful */
success?: boolean
}
```
### `ProcessorRunAttributes`
Processor attributes.
```typescript
interface ProcessorRunAttributes {
/** Name of the Processor */
processorName: string
/** Processor type (input or output) */
processorType: 'input' | 'output'
/** Processor index in the agent */
processorIndex?: number
}
```
### `WorkflowRunAttributes`
Workflow Run attributes.
```typescript
interface WorkflowRunAttributes {
/** Workflow identifier */
workflowId: string
/** Workflow status */
status?: WorkflowRunStatus
}
```
### `WorkflowStepAttributes`
Workflow Step attributes.
```typescript
interface WorkflowStepAttributes {
/** Step identifier */
stepId: string
/** Step status */
status?: WorkflowStepStatus
}
```
## Options types
### `StartSpanOptions`
Options for starting new spans.
```typescript
interface StartSpanOptions<TType extends SpanType> {
/** Span type */
type: TType
/** Span name */
name: string
/** Span attributes */
attributes?: SpanTypeMap[TType]
/** Span metadata */
metadata?: Record<string, any>
/** Input data */
input?: any
/** Parent span */
parent?: AnySpan
/** Policy-level tracing configuration */
tracingPolicy?: TracingPolicy
/** Options passed when using a custom sampler strategy */
customSamplerOptions?: CustomSamplerOptions
}
```
### `UpdateSpanOptions`
Options for updating spans.
```typescript
interface UpdateSpanOptions<TType extends SpanType> {
/** Span attributes */
attributes?: Partial<SpanTypeMap[TType]>
/** Span metadata */
metadata?: Record<string, any>
/** Input data */
input?: any
/** Output data */
output?: any
}
```
### `EndSpanOptions`
Options for ending spans.
```typescript
interface EndSpanOptions<TType extends SpanType> {
/** Output data */
output?: any
/** Span metadata */
metadata?: Record<string, any>
/** Span attributes */
attributes?: Partial<SpanTypeMap[TType]>
}
```
### `ErrorSpanOptions`
Options for recording span errors.
```typescript
interface ErrorSpanOptions<TType extends SpanType> {
/** 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<SpanTypeMap[TType]>
}
```
## Context types
### `TracingContext`
Context for Tracing that flows through workflow and agent execution.
```typescript
interface TracingContext {
/** Current span for creating child spans and adding metadata */
currentSpan?: AnySpan
}
```
### `TracingProperties`
Properties returned to the user for working with traces externally.
```typescript
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.
```typescript
interface TracingOptions {
/** Metadata to add to the root trace span */
metadata?: Record<string, any>
/**
* Additional RequestContext keys to extract as metadata for this trace.
* These keys are added to the requestContextKeys config.
* Supports dot notation for nested values (e.g., 'user.id', 'session.data.experimentId').
*/
requestContextKeys?: string[]
/**
* Trace ID to use for this execution (1-32 hexadecimal characters).
* If provided, this trace will be part of the specified trace rather than starting a new one.
*/
traceId?: string
/**
* Parent span ID to use for this execution (1-16 hexadecimal characters).
* If provided, the root span will be created as a child of this span.
*/
parentSpanId?: string
/**
* Tags to apply to this trace.
* Tags are string labels that can be used to categorize and filter traces
* Note: Tags are only applied to the root span of a trace.
*/
tags?: string[]
/**
* When true, input data will be hidden from all spans in this trace.
* Useful for protecting sensitive data from being logged.
*/
hideInput?: boolean
/**
* When true, output data will be hidden from all spans in this trace.
* Useful for protecting sensitive data from being logged.
*/
hideOutput?: boolean
}
```
### `TracingPolicy`
Policy-level tracing configuration applied when creating a workflow or agent.
```typescript
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
### `ObservabilityInstanceConfig`
Configuration for a single observability instance.
```typescript
interface ObservabilityInstanceConfig {
/** Unique identifier for this config in the observability registry */
name: string
/** Service name for observability */
serviceName: string
/** Sampling strategy - controls whether tracing is collected (defaults to ALWAYS) */
sampling?: SamplingStrategy
/** Custom exporters */
exporters?: ObservabilityExporter[]
/** Custom span output processors */
spanOutputProcessors?: SpanOutputProcessor[]
/** Set to true if you want to see spans internal to the operation of mastra */
includeInternalSpans?: boolean
/** RequestContext keys to automatically extract as metadata for all spans */
requestContextKeys?: string[]
}
```
### `ObservabilityRegistryConfig`
Complete observability registry configuration.
```typescript
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<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
/** Optional selector function to choose which tracing instance to use */
configSelector?: ConfigSelector
}
```
## Sampling types
### `SamplingStrategy`
Sampling strategy configuration.
```typescript
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.
```typescript
interface CustomSamplerOptions {
requestContext?: RequestContext
metadata?: Record<string, any>
}
```
## Config selector types
### `ConfigSelector`
Function to select which observability instance to use for a given span.
```typescript
type ConfigSelector = (
options: ConfigSelectorOptions,
availableConfigs: ReadonlyMap<string, ObservabilityInstance>,
) => string | undefined
```
### `ConfigSelectorOptions`
Options passed when using a custom tracing config selector.
```typescript
interface ConfigSelectorOptions {
/** Request Context */
requestContext?: RequestContext
}
```
## Internal spans
### `InternalSpans`
Bitwise options to set different types of spans as internal in a workflow or agent execution.
```typescript
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
- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide to Tracing
- [Creating Child Spans](https://mastra.ai/docs/observability/tracing/overview): Working with span hierarchies
- [Adding Custom Metadata](https://mastra.ai/docs/observability/tracing/overview): Enriching traces
### Reference
- [Configuration](https://mastra.ai/reference/observability/tracing/configuration): Registry and configuration
- [Tracing Classes](https://mastra.ai/reference/observability/tracing/instances): Core implementations
- [Spans Reference](https://mastra.ai/reference/observability/tracing/spans): Span lifecycle methods