Configuration

ObservabilityRegistryConfig

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

default:

{ enabled?: boolean }

Enable default configuration with DefaultExporter and CloudExporter

configs:

Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>

Named observability instance configurations or pre-instantiated instances

configSelector:

ConfigSelector

Runtime configuration selector function

ObservabilityInstanceConfig

interface ObservabilityInstanceConfig {
  name: string
  serviceName: string
  sampling?: SamplingStrategy
  exporters?: ObservabilityExporter[]
  spanOutputProcessors?: SpanOutputProcessor[]
  includeInternalSpans?: boolean
  requestContextKeys?: string[]
  serializationOptions?: SerializationOptions
}

name:

string

Configuration identifier

serviceName:

string

Service name in traces

sampling:

SamplingStrategy

Sampling configuration (defaults to ALWAYS)

exporters:

ObservabilityExporter[]

Trace data exporters

spanOutputProcessors:

SpanOutputProcessor[]

Span output processors

includeInternalSpans:

boolean

Include spans internal to Mastra operations

requestContextKeys:

string[]

RequestContext keys to extract as metadata (supports dot notation)

serializationOptions:

SerializationOptions

Options for controlling serialization of span data (input/output/attributes)

SerializationOptions

maxStringLength?:

number

Maximum length for string values (default: 1024)

maxDepth?:

number

Maximum depth for nested objects (default: 6)

maxArrayLength?:

number

Maximum number of items in arrays (default: 50)

maxObjectKeys?:

number

Maximum number of keys in objects (default: 50)

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
}

Registry methods

The Observability class provides methods for managing observability instances:

registerInstance

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

Registers an observability instance in the registry.

getInstance

getInstance(name: string): ObservabilityInstance | undefined;

Retrieves an observability instance by name.

getDefaultInstance

getDefaultInstance(): ObservabilityInstance | undefined;

Returns the default observability instance.

getSelectedInstance

getSelectedInstance(
  options: ConfigSelectorOptions
): ObservabilityInstance | undefined;

Returns the observability instance selected by the config selector or default.

listInstances

listInstances(): ReadonlyMap<string, ObservabilityInstance>;

Returns all registered observability instances.

hasInstance

hasInstance(name: string): boolean;

Checks if an observability instance exists.

setConfigSelector

setConfigSelector(selector: ConfigSelector): void;

Sets the config selector function.

unregisterInstance

unregisterInstance(name: string): boolean;

Removes an observability instance from the registry.

clear

clear(): void;

Clears all instances without shutdown.

shutdown

async shutdown(): Promise<void>;

Shuts down all observability instances and clears the registry.

See also

Documentation

• Tracing Overview - Concepts and usage guide
• Sampling Strategies - Sampling configuration details
• Multi-Config Setup - Using multiple configurations

Reference

• Tracing Classes - Core tracing classes
• Interfaces - Type definitions
• Spans Reference - Span lifecycle

Exporters

• DefaultExporter - Storage configuration
• CloudExporter - Cloud setup
• Braintrust - Braintrust integration
• Langfuse - Langfuse integration
• LangSmith - LangSmith integration