配置

ObservabilityRegistryConfig

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

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）

maxDepth?:

number

嵌套对象的最大深度（默认值：6）

maxArrayLength?:

number

数组中的最大项目数（默认值：50）

maxObjectKeys?:

number

对象中的最大键数（默认值：50）

logging:

{ enabled?: boolean; level?: LogLevel }

控制是否将日志转发到可观测性存储。详情请参阅记录到可观测性存储。

{ enabled?: boolean; level?: LogLevel }

enabled?:

boolean

设为 false 可禁止将日志转发到可观测性存储（默认值：true）

level?:

LogLevel

要转发的最低日志级别。可选值为 'debug'、'info'、'warn'、'error'、'fatal'（默认值：'debug'）

SamplingStrategy

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

ConfigSelector

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

ConfigSelectorOptions

interface ConfigSelectorOptions {
  requestContext?: RequestContext
}

注册表方法

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

registerInstance

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

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

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

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

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

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

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

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

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

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

hasInstance

hasInstance(name: string): boolean;

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

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

设置配置选择器函数。

unregisterInstance

unregisterInstance(name: string): boolean;

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

clear

clear(): void;

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

shutdown

async shutdown(): Promise<void>;

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

另请参阅

文档

• Tracing 概览：概念和使用指南
• 采样策略：采样配置详情
• 多配置设置：使用多项配置

参考

• Tracing 类：核心 Tracing 类
• 接口：类型定义
• Span 参考：Span 生命周期

Exporter

• MastraStorageExporter：将可观测性事件持久化到 Mastra Storage
• MastraPlatformExporter：将可观测性事件发送到 Mastra 平台
• Braintrust：Braintrust 集成
• Langfuse：Langfuse 集成
• LangSmith：LangSmith 集成
• Span 过滤：选择性排除 Span