> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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>`): 具名的可觀測性 instance 設定或預先建立的 instance

**configSelector** (`ConfigSelector`): 執行階段設定選擇器函數

**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): 控制是否為每個已設定的 instance 自動套用 SensitiveDataFilter。預設為 true。傳入 false 可停用此功能，或傳入 SensitiveDataFilterOptions 物件以自訂欄位、遮蓋 token 或遮蓋樣式。如設定的 spanOutputProcessors 已包含 SensitiveDataFilter，則不會重複加入。預先建立的 instance 不會被修改。

## `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 輸出處理器

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

**excludeSpanTypes** (`SpanType[]`): 不匯出的 span 類型。適合用於減少雜訊，以及降低按 span 收費平台的成本。詳情請參閱 Span 篩選參考。

**spanFilter** (`(span: AnyExportedSpan) => boolean`): 控制要匯出哪些 span 的篩選函數。傳回 true 以保留，傳回 false 以捨棄。此函數在 excludeSpanTypes 及 spanOutputProcessors 之後執行。詳情請參閱 Span 篩選參考。

**requestContextKeys** (`string[]`): 要擷取為元數據的 RequestContext 鍵（支援點號標記法）

**serializationOptions** (`SerializationOptions`): 控制 span 資料（輸入／輸出／屬性）序列化的選項

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

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

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

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

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

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

**logging.level** (`LogLevel`): 要轉送的最低日誌層級。可以是 '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 類別提供以下方法來管理可觀測性 instance：

### `registerInstance`

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

在 registry 中註冊可觀測性 instance。

### `getInstance`

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

按名稱取得可觀測性 instance。

### `getDefaultInstance`

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

傳回預設的可觀測性 instance。

### `getSelectedInstance`

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

傳回由設定選擇器選取的可觀測性 instance，或預設 instance。

### `listInstances`

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

傳回所有已註冊的可觀測性 instance。

### `hasInstance`

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

檢查可觀測性 instance 是否存在。

### `setConfigSelector`

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

設定設定選擇器函數。

### `unregisterInstance`

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

從 registry 移除可觀測性 instance。

### clear

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

清除所有 instance，但不將其關閉。

### shutdown

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

關閉所有可觀測性 instance 並清除 registry。

## 另請參閱

### 文件

- [Tracing 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：概念及使用指南
- [取樣策略](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)：取樣設定詳情
- [多重設定](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)：使用多個設定

### 參考

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

### Exporter

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