> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# 介面

## 核心介面

### `ObservabilityInstance`

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`

Span 類型與其對應屬性介面的映射。

```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
  PROVIDER_TOOL_CALL: ProviderToolCallAttributes
  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
}
```

此映射定義建立或處理 span 時，每種 span 類型所使用的屬性介面。

### Span

供 tracing 內部使用的 Span 介面。

```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`

Observability exporter 的介面。

```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>
}
```

事件回呼的 payload 使用 observability 事件匯流排 envelope： `TracingEvent` 透過 `exportedSpan` 傳遞 span 生命週期事件；`LogEvent` 在 `log` 中封裝 `ExportedLog`；`MetricEvent` 在 `metric` 中封裝 `ExportedMetric`；`ScoreEvent` 在 `score` 中封裝 `ExportedScore`；而 `FeedbackEvent` 則在 `feedback` 中封裝 `ExportedFeedback`。如要了解 Mastra 平台 exporter 對這些 回呼的處理方式，請參閱 [MastraPlatformExporter](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/exporters/mastra-platform-exporter)。

與 `LogEvent`、`MetricEvent` 及 `FeedbackEvent` 一樣，`ScoreEvent` 是一個 observability 匯流排 envelope，用來封裝範圍明確的 payload。對 score 而言，該 payload 是 `ExportedScore`。

### `ScoreEvent`

Score 事件會透過 `onScoreEvent` 傳送至 exporter。此事件是一個小型 envelope，包含訊號類型及 score payload：

```typescript
interface ScoreEvent {
  type: 'score'
  score: ExportedScore
}
```

### `ExportedScore`

`ExportedScore` 是 exporter 在 `ScoreEvent.score` 內收到、範圍明確的 payload。當中包含 score 身分、目標 trace 或 span 錨點、 scorer 詳情、數值、可選說明及關聯 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` 及 `spanId` 識別被評分的 trace 或 span。`scoreTraceId` 則在該 scorer 有進行 tracing 時，識別評分執行本身的 trace。對 新 exporter，應優先使用 `scoreSource`，而非已棄用的 `source` 欄位，並 優先使用 `correlationContext.experimentId`，而非已棄用的頂層 `experimentId` 欄位。

`EntityType` 是 Mastra 的 observability 實體 enum。目前的值包括 `agent`, `scorer`, `rag_ingestion`, `trajectory`, `input_processor`, `input_step_processor`, `output_processor`, `output_step_processor`, `workflow_step`、`tool`、`workflow_run` 及 `memory`。

`CorrelationContext` 是附加至 observability 訊號的共用 context 快照。它可包含實體階層欄位、使用者或機構識別碼、 run、session、thread、request、environment、source、service name、experiment 及 tag。對被評分目標，應優先使用 `ExportedScore` 的頂層 `traceId` 及 `spanId` 欄位。

### `ObservabilityDropEvent`

當 exporter pipeline 捨棄 observability 事件時發出的結構化事件。

```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
  }
}
```

在自訂 exporter 或 bridge 上使用 `onDroppedEvent`，將這些事件轉送至外部 metrics 或警報系統。

### `SpanOutputProcessor`

Span 輸出 processor 的介面。

```typescript
interface SpanOutputProcessor {
  /** Processor name */
  name: string

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

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

## Span 類型

### `SpanType`

AI 專用 span 類型及其相關 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',

  /**
   * Provider-executed (server-side) tool span. Reconstructed from
   * tool-call and tool-result stream chunks for tools the model
   * provider executes (e.g. Anthropic code execution, server-side
   * web search). Created on the tool-result chunk under the model
   * step that delivered it, with the start time backdated to the
   * tool-call chunk.
   */
  PROVIDER_TOOL_CALL = 'provider_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`

用於需要處理任何 span 情況的 union 類型。

```typescript
type AnySpan = Span<keyof SpanTypeMap>
```

## Span 屬性

### `AgentRunAttributes`

Agent Run 屬性。

```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 屬性。

```typescript
interface ModelGenerationAttributes {
  /** Model name (e.g., 'gpt-5.4', 'claude-opus-4-6') */
  model?: string

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

  /**
   * Definitions of the tools made available to the model for this generation
   * (name, description, and JSON-schema parameters), captured once per
   * generation. Per-step tool names live on MODEL_INFERENCE spans as
   * `availableTools`.
   */
  tools?: ModelToolDefinition[]

  /** 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
}
```

### `ModelToolDefinition`

提供予模型使用的單一 tool 之序列化定義，會附加至 `MODEL_GENERATION` span，讓 observability exporter 可以呈現 tool schema。

```typescript
interface ModelToolDefinition {
  /** Tool type: 'function' for standard tools, or the provider tool type (e.g. 'provider-defined') */
  type: string

  name: string

  description?: string

  /** JSON schema of the tool's input parameters (function tools) */
  parameters?: Record<string, unknown>

  /** Provider tool id (e.g. 'anthropic.web_search_20250305') for provider-defined tools */
  id?: string
}
```

### `ModelStepAttributes`

Model Step 屬性——用於 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 屬性——用於個別串流 chunk／事件。

```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 屬性。

```typescript
interface ToolCallAttributes {
  toolId?: string
  toolType?: string
  toolDescription?: string
  toolCallId?: string
  success?: boolean
}
```

### MCPToolCallAttributes

MCP Tool Call 屬性。

```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

  toolCallId?: string

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

### `ProcessorRunAttributes`

Processor 屬性。

```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 屬性。

```typescript
interface WorkflowRunAttributes {
  /** Workflow identifier */
  workflowId: string

  /** Workflow status */
  status?: WorkflowRunStatus
}
```

### `WorkflowStepAttributes`

Workflow Step 屬性。

```typescript
interface WorkflowStepAttributes {
  /** Step identifier */
  stepId: string

  /** Step status */
  status?: WorkflowStepStatus
}
```

## Options 類型

### `StartSpanOptions`

啟動新 span 的 options。

```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`

更新 span 的 options。

```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`

結束 span 的 options。

```typescript
interface EndSpanOptions<TType extends SpanType> {
  /** Output data */
  output?: any

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

  /** Span attributes */
  attributes?: Partial<SpanTypeMap[TType]>
}
```

### `ErrorSpanOptions`

記錄 span 錯誤的 options。

```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 類型

### `TracingContext`

在 Workflow 及 Agent 執行期間流轉的 Tracing context。

```typescript
interface TracingContext {
  /** Current span for creating child spans and adding metadata */
  currentSpan?: AnySpan
}
```

### `TracingProperties`

傳回給使用者、供其從外部操作 trace 的屬性。

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

### `TracingOptions`

啟動新的 Agent 或 Workflow 執行時傳入的 options。

```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`

建立 Workflow 或 Agent 時套用的政策層級 tracing 設定。

```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
}
```

## 設定類型

### `ObservabilityInstanceConfig`

單一 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`

完整的 observability registry 設定。

```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 類型

### `SamplingStrategy`

Sampling 策略設定。

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

### `CustomSamplerOptions`

使用自訂 sampler 策略時傳入的 options。

```typescript
interface CustomSamplerOptions {
  requestContext?: RequestContext
  metadata?: Record<string, any>
}
```

## Config selector 類型

### `ConfigSelector`

選擇 span 所使用 observability instance 的函式。

```typescript
type ConfigSelector = (
  options: ConfigSelectorOptions,
  availableConfigs: ReadonlyMap<string, ObservabilityInstance>,
) => string | undefined
```

### `ConfigSelectorOptions`

使用自訂 tracing config selector 時傳入的 options。

```typescript
interface ConfigSelectorOptions {
  /** Request Context */
  requestContext?: RequestContext
}
```

## 內部 span

### `InternalSpans`

用於在 Workflow 或 Agent 執行中，將不同 span 類型設為內部 span 的 bitwise options。

```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,
}
```

## 另請參閱

### 文件

- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：Tracing 完整指南
- [建立子 span](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：使用 span 階層
- [新增自訂 metadata](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：為 trace 加入更多資訊

### 參考

- [設定](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/configuration)：Registry 及設定
- [Tracing class](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/instances)：核心實作
- [Span 參考](https://mastra.zisheng.pro/zh-HK/reference/observability/tracing/spans)：Span 生命週期方法