@mastra/mcp-docs-server 0.13.24 → 0.13.25-alpha.0

package/.docs/raw/reference/observability/ai-tracing/interfaces.mdx

@@ -0,0 +1,651 @@
+---
+title: "Interfaces | AI Tracing | Reference"
+description: AI Tracing type definitions and interfaces
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# Interfaces
+
+## Core Interfaces
+
+### AITracing
+
+Primary interface for AI Tracing.
+
+```typescript
+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.
+
+```typescript
+interface AISpanTypeMap {
+  AGENT_RUN: AgentRunAttributes;
+  WORKFLOW_RUN: WorkflowRunAttributes;
+  LLM_GENERATION: LLMGenerationAttributes;
+  LLM_CHUNK: LLMChunkAttributes;
+  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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+enum AISpanType {
+  /** Agent run - root span for agent processes */
+  AGENT_RUN = 'agent_run',
+  
+  /** Generic span for custom operations */
+  GENERIC = 'generic',
+  
+  /** LLM generation with model calls, token usage, prompts, completions */
+  LLM_GENERATION = 'llm_generation',
+  
+  /** Individual LLM streaming chunk/event */
+  LLM_CHUNK = 'llm_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.
+
+```typescript
+type AnyAISpan = AISpan<keyof AISpanTypeMap>;
+```
+
+## 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;
+}
+```
+
+### LLMGenerationAttributes
+
+LLM Generation attributes.
+
+```typescript
+interface LLMGenerationAttributes {
+  /** Model name (e.g., 'gpt-4', 'claude-3') */
+  model?: string;
+  
+  /** Model provider (e.g., 'openai', 'anthropic') */
+  provider?: string;
+  
+  /** Type of result/output this LLM 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;
+}
+```
+
+### LLMChunkAttributes
+
+LLM Chunk attributes - for individual streaming chunks/events.
+
+```typescript
+interface LLMChunkAttributes {
+  /** 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;
+}
+```
+
+### WorkflowRunAttributes
+
+Workflow Run attributes.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```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>;
+}
+```
+
+### 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
+
+### TracingConfig
+
+Configuration for a single tracing instance.
+
+```typescript
+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.
+
+```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<TracingConfig, 'name'> | AITracing>;
+  
+  /** 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 {
+  runtimeContext?: RuntimeContext;
+  metadata?: Record<string, any>;
+}
+```
+
+## Config Selector Types
+
+### ConfigSelector
+
+Function to select which AI tracing instance to use for a given span.
+
+```typescript
+type ConfigSelector = (
+  options: ConfigSelectorOptions,
+  availableConfigs: ReadonlyMap<string, AITracing>
+) => string | undefined;
+```
+
+### ConfigSelectorOptions
+
+Options passed when using a custom tracing config selector.
+
+```typescript
+interface ConfigSelectorOptions {
+  /** Runtime context */
+  runtimeContext?: RuntimeContext;
+}
+```
+
+## 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,
+  
+  /** LLM spans are marked internal */
+  LLM = 1 << 3,
+  
+  /** All spans are marked internal */
+  ALL = (1 << 4) - 1,
+}
+```
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Complete guide to AI tracing
+- [Creating Child Spans](/docs/observability/ai-tracing/overview#creating-child-spans) - Working with span hierarchies
+- [Adding Custom Metadata](/docs/observability/ai-tracing/overview#adding-custom-metadata) - Enriching traces
+
+### Reference
+- [Configuration](/reference/observability/ai-tracing/configuration) - Registry and configuration
+- [AITracing Classes](/reference/observability/ai-tracing/ai-tracing) - Core implementations
+- [Span Reference](/reference/observability/ai-tracing/span) - Span lifecycle methods
+
+### Examples
+- [Basic AI Tracing](/examples/observability/basic-ai-tracing) - Implementation example