> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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`): 运行时配置选择器函数

**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): 控制是否向每个已配置的实例自动应用 SensitiveDataFilter。默认为 true。传入 false 可停用，或传入 SensitiveDataFilterOptions 对象来自定义字段、脱敏标记或脱敏样式。如果配置的 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 输出处理器

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

## 注册表方法

Observability 类提供以下方法来管理可观测性实例：

### `registerInstance`

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

在注册表中注册可观测性实例。

### `getInstance`

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

按名称检索可观测性实例。

### `getDefaultInstance`

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

返回默认的可观测性实例。

### `getSelectedInstance`

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

返回由配置选择器选中的可观测性实例；如果未选中，则返回默认实例。

### `listInstances`

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

返回所有已注册的可观测性实例。

### `hasInstance`

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

检查可观测性实例是否存在。

### `setConfigSelector`

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

设置配置选择器函数。

### `unregisterInstance`

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

从注册表中移除可观测性实例。

### clear

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

清除所有实例，但不将其关闭。

### shutdown

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

关闭所有可观测性实例并清空注册表。

## 另请参阅

### 文档

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)：概念和使用指南
- [采样策略](https://mastra.zisheng.pro/docs/observability/tracing/overview)：采样配置详情
- [多配置设置](https://mastra.zisheng.pro/docs/observability/overview)：使用多项配置

### 参考

- [Tracing 类](https://mastra.zisheng.pro/reference/observability/tracing/instances)：核心 Tracing 类
- [接口](https://mastra.zisheng.pro/reference/observability/tracing/interfaces)：类型定义
- [Span 参考](https://mastra.zisheng.pro/reference/observability/tracing/spans)：Span 生命周期

### Exporter

- [MastraStorageExporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/mastra-storage-exporter)：将可观测性事件持久化到 Mastra Storage
- [MastraPlatformExporter](https://mastra.zisheng.pro/reference/observability/tracing/exporters/mastra-platform-exporter)：将可观测性事件发送到 Mastra 平台
- [Braintrust](https://mastra.zisheng.pro/reference/observability/tracing/exporters/braintrust)：Braintrust 集成
- [Langfuse](https://mastra.zisheng.pro/reference/observability/tracing/exporters/langfuse)：Langfuse 集成
- [LangSmith](https://mastra.zisheng.pro/reference/observability/tracing/exporters/langsmith)：LangSmith 集成
- [Span 过滤](https://mastra.zisheng.pro/reference/observability/tracing/span-filtering)：选择性排除 Span