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

# 設定

## `ObservabilityRegistryConfig`

```typescript
interface ObservabilityRegistryConfig {
  default?: { enabled?: boolean }
  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
  configSelector?: ConfigSelector
  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
}
```

**default** (`{ enabled?: boolean }`): 啟用包含 MastraStorageExporter 與 MastraPlatformExporter 的預設設定

**configs** (`Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>`): 具名可觀測性執行個體設定或預先執行個體化的執行個體

**configSelector** (`ConfigSelector`): Runtime 設定 selector 函式

**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): 控制是否將 SensitiveDataFilter 自動套用至每個已設定的執行個體。預設為 true。傳入 false 可選擇停用，或傳入 SensitiveDataFilterOptions 物件以自訂欄位、遮蔽 token 或遮蔽樣式。如果某設定的 spanOutputProcessors 已包含 SensitiveDataFilter，則不會重複新增。預先執行個體化的執行個體不會修改。

## `ObservabilityInstanceConfig`

```typescript
interface ObservabilityInstanceConfig {
  name: string
  serviceName: string
  sampling?: SamplingStrategy
  exporters?: ObservabilityExporter[]
  spanOutputProcessors?: SpanOutputProcessor[]
  includeInternalSpans?: boolean
  excludeSpanTypes?: SpanType[]
  spanFilter?: (span: AnyExportedSpan) => boolean
  requestContextKeys?: string[]
  serializationOptions?: SerializationOptions
  logging?: { enabled?: boolean; level?: LogLevel }
}
```

**name** (`string`): 設定識別碼

**serviceName** (`string`): Trace 中的服務名稱

**sampling** (`SamplingStrategy`): 取樣設定（預設為 ALWAYS）

**exporters** (`ObservabilityExporter[]`): Trace 資料 exporter

**spanOutputProcessors** (`SpanOutputProcessor[]`): Span 輸出 processor

**includeInternalSpans** (`boolean`): 包含 Mastra 操作的內部 span

**excludeSpanTypes** (`SpanType[]`): 要從匯出中排除的 span 類型。適合用於降低以 span 計費平台的雜訊與費用。如需詳細資訊，請參閱 span 篩選參考。

**spanFilter** (`(span: AnyExportedSpan) => boolean`): 控制匯出哪些 span 的 filter 函式。傳回 true 以保留，傳回 false 以捨棄。在 excludeSpanTypes 與 spanOutputProcessors 之後執行。如需詳細資訊，請參閱 span 篩選參考。

**requestContextKeys** (`string[]`): 要擷取為 metadata 的 RequestContext key（支援點記法）

**serializationOptions** (`SerializationOptions`): 控制 span 資料（input／output／attributes）序列化的選項

**serializationOptions.maxStringLength** (`number`): 字串值的長度上限（預設：1024）

**serializationOptions.maxDepth** (`number`): 巢狀物件的深度上限（預設：6）

**serializationOptions.maxArrayLength** (`number`): Array 的項目數上限（預設：50）

**serializationOptions.maxObjectKeys** (`number`): 物件的 key 數量上限（預設：50）

**logging** (`{ enabled?: boolean; level?: LogLevel }`): 控制將 log 轉送至可觀測性儲存空間。詳情請參閱記錄至可觀測性儲存空間。

**logging.enabled** (`boolean`): 設為 false 以停用將 log 轉送至可觀測性儲存空間（預設：true）

**logging.level** (`LogLevel`): 要轉送的最低 log 層級。可為 'debug'、'info'、'warn'、'error'、'fatal' 之一（預設：'debug'）

## `SamplingStrategy`

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

## `ConfigSelector`

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

## `ConfigSelectorOptions`

```typescript
interface ConfigSelectorOptions {
  requestContext?: RequestContext
}
```

## Registry 方法

Observability 類別提供用於管理可觀測性執行個體的方法：

### `registerInstance`

```typescript
registerInstance(
  name: string,
  instance: ObservabilityInstance,
  isDefault?: boolean
): void;
```

在 registry 中註冊可觀測性執行個體。

### `getInstance`

```typescript
getInstance(name: string): ObservabilityInstance | undefined;
```

依名稱擷取可觀測性執行個體。

### `getDefaultInstance`

```typescript
getDefaultInstance(): ObservabilityInstance | undefined;
```

傳回預設可觀測性執行個體。

### `getSelectedInstance`

```typescript
getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;
```

傳回由 config selector 選取的可觀測性執行個體，若未選取則傳回預設執行個體。

### `listInstances`

```typescript
listInstances(): ReadonlyMap<string, ObservabilityInstance>;
```

傳回所有已註冊的可觀測性執行個體。

### `hasInstance`

```typescript
hasInstance(name: string): boolean;
```

檢查可觀測性執行個體是否存在。

### `setConfigSelector`

```typescript
setConfigSelector(selector: ConfigSelector): void;
```

設定 config selector 函式。

### `unregisterInstance`

```typescript
unregisterInstance(name: string): boolean;
```

從 registry 移除可觀測性執行個體。

### clear

```typescript
clear(): void;
```

清除所有執行個體，但不將其關閉。

### shutdown

```typescript
async shutdown(): Promise<void>;
```

關閉所有可觀測性執行個體，並清除 registry。

## 另請參閱

### 文件

- [Tracing 概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)：概念與使用指南
- [取樣策略](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)：取樣設定詳細資料
- [多設定建置](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)：使用多個設定

### 參考

- [Tracing 類別](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/instances)：核心 tracing 類別
- [介面](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/interfaces)：型別定義
- [Span 參考](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/spans)：span 生命週期

### Exporter

- [MastraStorageExporter](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/mastra-storage-exporter)：將可觀測性事件持久化至 Mastra Storage
- [MastraPlatformExporter](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/mastra-platform-exporter)：將可觀測性事件傳送至 Mastra platform
- [Braintrust](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/braintrust)：Braintrust 整合
- [Langfuse](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/langfuse)：Langfuse 整合
- [LangSmith](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/exporters/langsmith)：LangSmith 整合
- [Span 篩選](https://mastra.zisheng.pro/zh-TW/reference/observability/tracing/span-filtering)：選擇性排除 span