@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

package/.docs/reference/observability/tracing/interfaces.md

@@ -1,749 +0,0 @@
-# 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