Add user-configurable serialization options for span data in Mastra Observability. (#11484)

## Description

Add user-configurable serialization options for span data in Mastra
Observability.

This PR introduces the ability to configure how span data (input,
output, attributes) is serialized before export. Users can now
customize:
- `maxStringLength` - Maximum length for string values (default: 1024)
- `maxDepth` - Maximum depth for nested objects (default: 6)
- `maxArrayLength` - Maximum number of items in arrays (default: 50)
- `maxObjectKeys` - Maximum number of keys in objects (default: 50)

These options can be configured via
`ObservabilityInstanceConfig.serializationOptions`, allowing users to
control truncation limits for large payloads based on their
observability backend requirements.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added configurable serialization options to control span data
handling, including customizable limits for string length, object depth,
array size, and object key counts.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: jacob-lcs

observability/mastra/src/config.ts

@@ -12,6 +12,7 @@ import type {
   ObservabilityBridge,
   SpanOutputProcessor,
   ConfigSelector,
+  SerializationOptions,
 } from '@mastra/core/observability';
 import { z } from 'zod';
 
@@ -74,6 +75,11 @@ export interface ObservabilityInstanceConfig {
    * Supports dot notation for nested values.
    */
   requestContextKeys?: string[];
+  /**
+   * Options for controlling serialization of span data (input/output/attributes).
+   * Use these to customize truncation limits for large payloads.
+   */
+  serializationOptions?: SerializationOptions;
 }
 
 /**
@@ -114,6 +120,18 @@ export const samplingStrategySchema = z.discriminatedUnion('type', [
   }),
 ]);
 
+/**
+ * Zod schema for SerializationOptions
+ */
+export const serializationOptionsSchema = z
+  .object({
+    maxStringLength: z.number().int().positive().optional(),
+    maxDepth: z.number().int().positive().optional(),
+    maxArrayLength: z.number().int().positive().optional(),
+    maxObjectKeys: z.number().int().positive().optional(),
+  })
+  .optional();
+
 /**
  * Zod schema for ObservabilityInstanceConfig
  * Note: exporters, spanOutputProcessors, bridge, and configSelector are validated as any
@@ -129,6 +147,7 @@ export const observabilityInstanceConfigSchema = z
     spanOutputProcessors: z.array(z.any()).optional(),
     includeInternalSpans: z.boolean().optional(),
     requestContextKeys: z.array(z.string()).optional(),
+    serializationOptions: serializationOptionsSchema,
   })
   .refine(
     data => {
@@ -155,6 +174,7 @@ export const observabilityConfigValueSchema = z
     spanOutputProcessors: z.array(z.any()).optional(),
     includeInternalSpans: z.boolean().optional(),
     requestContextKeys: z.array(z.string()).optional(),
+    serializationOptions: serializationOptionsSchema,
   })
   .refine(
     data => {

observability/mastra/src/instances/base.ts

@@ -53,6 +53,7 @@ export abstract class BaseObservabilityInstance extends MastraBase implements Ob
       bridge: config.bridge ?? undefined,
       includeInternalSpans: config.includeInternalSpans ?? false,
       requestContextKeys: config.requestContextKeys ?? [],
+      serializationOptions: config.serializationOptions,
     };
 
     // Initialize bridge if present

observability/mastra/src/spans/base.test.ts

@@ -535,4 +535,73 @@ describe('Span', () => {
       });
     });
   });
+
+  describe('serializationOptions', () => {
+    it('should use custom maxStringLength from config', () => {
+      const tracing = new DefaultObservabilityInstance({
+        serviceName: 'test',
+        name: 'test',
+        exporters: [testExporter],
+        serializationOptions: {
+          maxStringLength: 10,
+        },
+      });
+
+      const longString = 'a'.repeat(100);
+      const span = tracing.startSpan({
+        type: SpanType.GENERIC,
+        name: 'test',
+        input: { data: longString },
+      });
+
+      // String should be truncated to 10 chars + truncation marker
+      expect(span.input.data.length).toBeLessThanOrEqual(25);
+      expect(span.input.data).toContain('[truncated]');
+      span.end();
+    });
+
+    it('should use default options when serializationOptions is not provided', () => {
+      const tracing = new DefaultObservabilityInstance({
+        serviceName: 'test',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const longString = 'a'.repeat(2000);
+      const span = tracing.startSpan({
+        type: SpanType.GENERIC,
+        name: 'test',
+        input: { data: longString },
+      });
+
+      // Default maxStringLength is 1024
+      expect(span.input.data.length).toBeLessThanOrEqual(1024 + 15);
+      expect(span.input.data).toContain('[truncated]');
+      span.end();
+    });
+
+    it('should respect custom maxDepth from config', () => {
+      const tracing = new DefaultObservabilityInstance({
+        serviceName: 'test',
+        name: 'test',
+        exporters: [testExporter],
+        serializationOptions: {
+          maxDepth: 2,
+        },
+      });
+
+      const deepObj: any = { level: 0, nested: { level: 1, nested: { level: 2, nested: { level: 3 } } } };
+      const span = tracing.startSpan({
+        type: SpanType.GENERIC,
+        name: 'test',
+        input: deepObj,
+      });
+
+      // At maxDepth 2, level 2 values should be [MaxDepth]
+      expect(span.input.level).toBe(0);
+      expect(span.input.nested.level).toBe(1);
+      expect(span.input.nested.nested.level).toBe('[MaxDepth]');
+      span.end();
+    });
+  });
 });

observability/mastra/src/spans/base.ts

@@ -18,7 +18,8 @@ import type {
 
 import { SpanType, InternalSpans } from '@mastra/core/observability';
 import { ModelSpanTracker } from '../model-tracing';
-import { deepClean } from './serialization';
+import { deepClean, mergeSerializationOptions } from './serialization';
+import type { DeepCleanOptions } from './serialization';
 
 /**
  * Determines if a span type should be considered internal based on flags.
@@ -136,12 +137,18 @@ export abstract class BaseSpan<TType extends SpanType = any> implements Span<TTy
   public entityName?: string;
   /** Parent span ID (for root spans that are children of external spans) */
   protected parentSpanId?: string;
+  /** Deep clean options for serialization */
+  protected deepCleanOptions: DeepCleanOptions;
 
   constructor(options: CreateSpanOptions<TType>, observabilityInstance: ObservabilityInstance) {
+    // Get serialization options from observability instance config
+    const serializationOptions = observabilityInstance.getConfig().serializationOptions;
+    this.deepCleanOptions = mergeSerializationOptions(serializationOptions);
+
     this.name = options.name;
     this.type = options.type;
-    this.attributes = deepClean(options.attributes) || ({} as SpanTypeMap[TType]);
-    this.metadata = deepClean(options.metadata);
+    this.attributes = deepClean(options.attributes, this.deepCleanOptions) || ({} as SpanTypeMap[TType]);
+    this.metadata = deepClean(options.metadata, this.deepCleanOptions);
     this.parent = options.parent;
     this.startTime = new Date();
     this.observabilityInstance = observabilityInstance;
@@ -158,9 +165,9 @@ export abstract class BaseSpan<TType extends SpanType = any> implements Span<TTy
     if (this.isEvent) {
       // Event spans don't have endTime or input.
       // Event spans are immediately emitted by the BaseObservability class via the end() event.
-      this.output = deepClean(options.output);
+      this.output = deepClean(options.output, this.deepCleanOptions);
     } else {
-      this.input = deepClean(options.input);
+      this.input = deepClean(options.input, this.deepCleanOptions);
     }
   }
 

observability/mastra/src/spans/default.ts

@@ -57,13 +57,13 @@ export class DefaultSpan<TType extends SpanType> extends BaseSpan<TType> {
     }
     this.endTime = new Date();
     if (options?.output !== undefined) {
-      this.output = deepClean(options.output);
+      this.output = deepClean(options.output, this.deepCleanOptions);
     }
     if (options?.attributes) {
-      this.attributes = { ...this.attributes, ...deepClean(options.attributes) };
+      this.attributes = { ...this.attributes, ...deepClean(options.attributes, this.deepCleanOptions) };
     }
     if (options?.metadata) {
-      this.metadata = { ...this.metadata, ...deepClean(options.metadata) };
+      this.metadata = { ...this.metadata, ...deepClean(options.metadata, this.deepCleanOptions) };
     }
     // Tracing events automatically handled by base class
   }
@@ -90,10 +90,10 @@ export class DefaultSpan<TType extends SpanType> extends BaseSpan<TType> {
 
     // Update attributes if provided
     if (attributes) {
-      this.attributes = { ...this.attributes, ...deepClean(attributes) };
+      this.attributes = { ...this.attributes, ...deepClean(attributes, this.deepCleanOptions) };
     }
     if (metadata) {
-      this.metadata = { ...this.metadata, ...deepClean(metadata) };
+      this.metadata = { ...this.metadata, ...deepClean(metadata, this.deepCleanOptions) };
     }
 
     if (endSpan) {
@@ -110,16 +110,16 @@ export class DefaultSpan<TType extends SpanType> extends BaseSpan<TType> {
     }
 
     if (options.input !== undefined) {
-      this.input = deepClean(options.input);
+      this.input = deepClean(options.input, this.deepCleanOptions);
     }
     if (options.output !== undefined) {
-      this.output = deepClean(options.output);
+      this.output = deepClean(options.output, this.deepCleanOptions);
     }
     if (options.attributes) {
-      this.attributes = { ...this.attributes, ...deepClean(options.attributes) };
+      this.attributes = { ...this.attributes, ...deepClean(options.attributes, this.deepCleanOptions) };
     }
     if (options.metadata) {
-      this.metadata = { ...this.metadata, ...deepClean(options.metadata) };
+      this.metadata = { ...this.metadata, ...deepClean(options.metadata, this.deepCleanOptions) };
     }
     // Tracing events automatically handled by base class
   }

observability/mastra/src/spans/serialization.ts

@@ -34,6 +34,28 @@ export const DEFAULT_DEEP_CLEAN_OPTIONS: DeepCleanOptions = Object.freeze({
   maxObjectKeys: 50,
 });
 
+/**
+ * Merge user-provided serialization options with defaults.
+ * Returns a complete DeepCleanOptions object.
+ */
+export function mergeSerializationOptions(userOptions?: {
+  maxStringLength?: number;
+  maxDepth?: number;
+  maxArrayLength?: number;
+  maxObjectKeys?: number;
+}): DeepCleanOptions {
+  if (!userOptions) {
+    return DEFAULT_DEEP_CLEAN_OPTIONS;
+  }
+  return {
+    keysToStrip: DEFAULT_KEYS_TO_STRIP,
+    maxDepth: userOptions.maxDepth ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxDepth,
+    maxStringLength: userOptions.maxStringLength ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxStringLength,
+    maxArrayLength: userOptions.maxArrayLength ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxArrayLength,
+    maxObjectKeys: userOptions.maxObjectKeys ?? DEFAULT_DEEP_CLEAN_OPTIONS.maxObjectKeys,
+  };
+}
+
 /**
  * Hard-cap any string to prevent unbounded growth.
  */

packages/core/src/observability/types/tracing.ts

@@ -893,6 +893,33 @@ export type TracingProperties = {
 // Registry Config Interfaces
 // ============================================================================
 
+/**
+ * Options for controlling serialization of span data.
+ * These options control how input, output, and attributes are cleaned before export.
+ */
+export interface SerializationOptions {
+  /**
+   * Maximum length for string values
+   * @default 1024
+   */
+  maxStringLength?: number;
+  /**
+   * Maximum depth for nested objects
+   * @default 6
+   */
+  maxDepth?: number;
+  /**
+   * Maximum number of items in arrays
+   * @default 50
+   */
+  maxArrayLength?: number;
+  /**
+   * Maximum number of keys in objects
+   * @default 50
+   */
+  maxObjectKeys?: number;
+}
+
 /**
  * Configuration for a single observability instance
  */
@@ -917,6 +944,11 @@ export interface ObservabilityInstanceConfig {
    * Supports dot notation for nested values.
    */
   requestContextKeys?: string[];
+  /**
+   * Options for controlling serialization of span data (input/output/attributes).
+   * Use these to customize truncation limits for large payloads.
+   */
+  serializationOptions?: SerializationOptions;
 }
 
 /**