ContextQMD
Back to Mastra

Reference: Configuration | Observability

docs/src/content/en/reference/observability/tracing/configuration.mdx

2025-12-186.6 KB
Original Source

import PropertiesTable from "@site/src/components/PropertiesTable";

Configuration

ObservabilityRegistryConfig

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

<PropertiesTable content={[ { name: 'default', type: '{ enabled?: boolean }', description: 'Enable default configuration with DefaultExporter and CloudExporter', required: false, }, { name: 'configs', type: "Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>", description: 'Named observability instance configurations or pre-instantiated instances', required: false, }, { name: 'configSelector', type: 'ConfigSelector', description: 'Runtime configuration selector function', required: false, }, ]} />

ObservabilityInstanceConfig

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

<PropertiesTable content={[ { name: 'name', type: 'string', description: 'Configuration identifier', required: true, }, { name: 'serviceName', type: 'string', description: 'Service name in traces', required: true, }, { name: 'sampling', type: 'SamplingStrategy', description: 'Sampling configuration (defaults to ALWAYS)', required: false, }, { name: 'exporters', type: 'ObservabilityExporter[]', description: 'Trace data exporters', required: false, }, { name: 'spanOutputProcessors', type: 'SpanOutputProcessor[]', description: 'Span output processors', required: false, }, { name: 'includeInternalSpans', type: 'boolean', description: 'Include spans internal to Mastra operations', required: false, }, { name: 'requestContextKeys', type: 'string[]', description: 'RequestContext keys to extract as metadata (supports dot notation)', required: false, }, { name: 'serializationOptions', type: 'SerializationOptions', description: 'Options for controlling serialization of span data (input/output/attributes)', required: false, properties: [ { type: 'SerializationOptions', parameters: [ { name: 'maxStringLength', type: 'number', description: 'Maximum length for string values (default: 1024)', isOptional: true, }, { name: 'maxDepth', type: 'number', description: 'Maximum depth for nested objects (default: 6)', isOptional: true, }, { name: 'maxArrayLength', type: 'number', description: 'Maximum number of items in arrays (default: 50)', isOptional: true, }, { name: 'maxObjectKeys', type: 'number', description: 'Maximum number of keys in objects (default: 50)', isOptional: true, }, ], }, ], }, ]} />

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 methods

The Observability class provides methods for managing observability instances:

registerInstance

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

Registers an observability instance in the registry.

getInstance

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

Retrieves an observability instance by name.

getDefaultInstance

typescript
getDefaultInstance(): ObservabilityInstance | undefined;

Returns the default observability instance.

getSelectedInstance

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

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

listInstances

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

Returns all registered observability instances.

hasInstance

typescript
hasInstance(name: string): boolean;

Checks if an observability instance exists.

setConfigSelector

typescript
setConfigSelector(selector: ConfigSelector): void;

Sets the config selector function.

unregisterInstance

typescript
unregisterInstance(name: string): boolean;

Removes an observability instance from the registry.

clear

typescript
clear(): void;

Clears all instances without shutdown.

shutdown

typescript
async shutdown(): Promise<void>;

Shuts down all observability instances and clears the registry.

See also

Documentation

Reference

Exporters