@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-observability-tracing-interfaces.md

@@ -0,0 +1,743 @@
+# 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
+  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
+
+  /** Export tracing events */
+  exportTracingEvent(event: TracingEvent): Promise<void>
+
+  /** Add score to a trace (optional) */
+  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>
+}
+```
+
+### 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',
+
+  /** 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-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.
+
+```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
+
+  /** 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