@mastra/observability 1.0.0-beta.10 → 1.0.0-beta.11

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @mastra/observability
 
+## 1.0.0-beta.11
+
+### Major Changes
+
+- **Breaking Change**: Convert OUTPUT generic from `OutputSchema` constraint to plain generic ([#11741](https://github.com/mastra-ai/mastra/pull/11741))
+
+  This change removes the direct dependency on Zod typings in the public API by converting all `OUTPUT extends OutputSchema` generic constraints to plain `OUTPUT` generics throughout the codebase. This is preparation for moving to a standard schema approach.
+  - All generic type parameters previously constrained to `OutputSchema` (e.g., `<OUTPUT extends OutputSchema = undefined>`) are now plain generics with defaults (e.g., `<OUTPUT = undefined>`)
+  - Affects all public APIs including `Agent`, `MastraModelOutput`, `AgentExecutionOptions`, and stream/generate methods
+  - `InferSchemaOutput<OUTPUT>` replaced with `OUTPUT` throughout
+  - `PartialSchemaOutput<OUTPUT>` replaced with `Partial<OUTPUT>`
+  - Schema fields now use `NonNullable<OutputSchema<OUTPUT>>` instead of `OUTPUT` directly
+  - Added `FullOutput<OUTPUT>` type representing complete output with all fields
+  - Added `AgentExecutionOptionsBase<OUTPUT>` type
+  - `getFullOutput()` method now returns `Promise<FullOutput<OUTPUT>>`
+  - `Agent` class now generic: `Agent<TAgentId, TTools, TOutput>`
+  - `agent.generate()` and `agent.stream()` methods have updated signatures
+  - `MastraModelOutput<OUTPUT>` no longer requires `OutputSchema` constraint
+  - Network route and streaming APIs updated to use plain OUTPUT generic
+
+  **Before:**
+
+  ```typescript
+  const output = await agent.generate<z.ZodType>({
+    messages: [...],
+    structuredOutput: { schema: mySchema }
+  });
+
+  **After:**
+  const output = await agent.generate<z.infer<typeof mySchema>>({
+    messages: [...],
+    structuredOutput: { schema: mySchema }
+  });
+  // Or rely on type inference:
+  const output = await agent.generate({
+    messages: [...],
+    structuredOutput: { schema: mySchema }
+  });
+
+  ```
+
+### Minor Changes
+
+- Add `hideInput` and `hideOutput` options to `TracingOptions` for protecting sensitive data in traces. ([#11969](https://github.com/mastra-ai/mastra/pull/11969))
+
+  When set to `true`, these options hide input/output data from all spans in a trace, including child spans. This is useful for protecting sensitive information from being logged to observability platforms.
+
+  ```typescript
+  const agent = mastra.getAgent('myAgent');
+  await agent.generate('Process this sensitive data', {
+    tracingOptions: {
+      hideInput: true, // Input will be hidden from all spans
+      hideOutput: true, // Output will be hidden from all spans
+    },
+  });
+  ```
+
+  The options can be used independently (hide only input or only output) or together. The settings are propagated to all child spans via `TraceState`, ensuring consistent behavior across the entire trace.
+
+  Fixes #10888
+
+- Added `TrackingExporter` base class with improved handling for: ([#11870](https://github.com/mastra-ai/mastra/pull/11870))
+  - **Out-of-order span processing**: Spans that arrive before their parents are now queued and processed once dependencies are available
+  - **Delayed cleanup**: Trace data is retained briefly after spans end to handle late-arriving updates
+  - **Memory management**: Configurable limits on pending and total traces to prevent memory leaks
+
+  New configuration options on `TrackingExporterConfig`:
+  - `earlyQueueMaxAttempts` - Max retry attempts for queued events (default: 5)
+  - `earlyQueueTTLMs` - TTL for queued events in ms (default: 30000)
+  - `traceCleanupDelayMs` - Delay before cleaning up completed traces (default: 30000)
+  - `maxPendingCleanupTraces` - Soft cap on traces awaiting cleanup (default: 100)
+  - `maxTotalTraces` - Hard cap on total traces (default: 500)
+
+  Updated @mastra/braintrust, @mastra/langfuse, @mastra/langsmith, @mastra/posthog to use the new TrackingExporter
+
+### Patch Changes
+
+- feat(spans): implement entity inheritance for child spans ([#11914](https://github.com/mastra-ai/mastra/pull/11914))
+
+  Added tests to verify that child spans inherit entityId and entityName from their parent spans when not explicitly provided. Also included functionality to allow child spans to override these inherited values. This ensures proper entity identification across multiple levels of span hierarchy.
+
+- Improved tracing by filtering infrastructure chunks from model streams and adding success attribute to tool spans. ([#11943](https://github.com/mastra-ai/mastra/pull/11943))
+
+  Added generic input/output attribute mapping for additional span types in Arize exporter.
+
+- Real-time span export for Inngest workflow engine ([#11973](https://github.com/mastra-ai/mastra/pull/11973))
+  - Spans are now exported immediately when created and ended, instead of being batched at workflow completion
+  - Added durable span lifecycle hooks (`createStepSpan`, `endStepSpan`, `errorStepSpan`, `createChildSpan`, `endChildSpan`, `errorChildSpan`) that wrap span operations in Inngest's `step.run()` for memoization
+  - Added `rebuildSpan()` method to reconstruct span objects from exported data after Inngest replay
+  - Fixed nested workflow step spans missing output data
+  - Spans correctly maintain parent-child relationships across Inngest's durable execution boundaries using `tracingIds`
+
+- Updated dependencies [[`ebae12a`](https://github.com/mastra-ai/mastra/commit/ebae12a2dd0212e75478981053b148a2c246962d), [`c61a0a5`](https://github.com/mastra-ai/mastra/commit/c61a0a5de4904c88fd8b3718bc26d1be1c2ec6e7), [`69136e7`](https://github.com/mastra-ai/mastra/commit/69136e748e32f57297728a4e0f9a75988462f1a7), [`449aed2`](https://github.com/mastra-ai/mastra/commit/449aed2ba9d507b75bf93d427646ea94f734dfd1), [`eb648a2`](https://github.com/mastra-ai/mastra/commit/eb648a2cc1728f7678768dd70cd77619b448dab9), [`0131105`](https://github.com/mastra-ai/mastra/commit/0131105532e83bdcbb73352fc7d0879eebf140dc), [`9d5059e`](https://github.com/mastra-ai/mastra/commit/9d5059eae810829935fb08e81a9bb7ecd5b144a7), [`ef756c6`](https://github.com/mastra-ai/mastra/commit/ef756c65f82d16531c43f49a27290a416611e526), [`b00ccd3`](https://github.com/mastra-ai/mastra/commit/b00ccd325ebd5d9e37e34dd0a105caae67eb568f), [`3bdfa75`](https://github.com/mastra-ai/mastra/commit/3bdfa7507a91db66f176ba8221aa28dd546e464a), [`e770de9`](https://github.com/mastra-ai/mastra/commit/e770de941a287a49b1964d44db5a5763d19890a6), [`52e2716`](https://github.com/mastra-ai/mastra/commit/52e2716b42df6eff443de72360ae83e86ec23993), [`27b4040`](https://github.com/mastra-ai/mastra/commit/27b4040bfa1a95d92546f420a02a626b1419a1d6), [`610a70b`](https://github.com/mastra-ai/mastra/commit/610a70bdad282079f0c630e0d7bb284578f20151), [`8dc7f55`](https://github.com/mastra-ai/mastra/commit/8dc7f55900395771da851dc7d78d53ae84fe34ec), [`8379099`](https://github.com/mastra-ai/mastra/commit/8379099fc467af6bef54dd7f80c9bd75bf8bbddf), [`8c0ec25`](https://github.com/mastra-ai/mastra/commit/8c0ec25646c8a7df253ed1e5ff4863a0d3f1316c), [`ff4d9a6`](https://github.com/mastra-ai/mastra/commit/ff4d9a6704fc87b31a380a76ed22736fdedbba5a), [`69821ef`](https://github.com/mastra-ai/mastra/commit/69821ef806482e2c44e2197ac0b050c3fe3a5285), [`1ed5716`](https://github.com/mastra-ai/mastra/commit/1ed5716830867b3774c4a1b43cc0d82935f32b96), [`4186bdd`](https://github.com/mastra-ai/mastra/commit/4186bdd00731305726fa06adba0b076a1d50b49f), [`7aaf973`](https://github.com/mastra-ai/mastra/commit/7aaf973f83fbbe9521f1f9e7a4fd99b8de464617)]:
+  - @mastra/core@1.0.0-beta.22
+
 ## 1.0.0-beta.10
 
 ### Minor Changes

package/README.md

@@ -1,99 +1,54 @@
 # Mastra Observability
 
-A comprehensive observability system for AI operations in Mastra, providing type-safe span tracking, event-driven exports, and flexible tracing configuration.
+Tracing and monitoring for AI operations in Mastra.
 
-## Overview
+## Installation
 
-The Mastra Observability system enables detailed observability for AI-driven applications by tracking operations through spans that capture metadata, timing, and context. It's designed to work seamlessly with Mastra's architecture while providing flexible configuration and export options.
-
-## Key Features
-
-- **Type-Safe Spans**: Strongly typed metadata based on span type prevents runtime errors
-- **Event-Driven Architecture**: Real-time tracing events for immediate observability
-- **OpenTelemetry Compatible**: Uses standard trace and span ID formats for integration
-- **Flexible Sampling**: Multiple sampling strategies with custom sampler support
-- **Pluggable Processors**: Modify or filter span fields before export
-- **Pluggable Exporters**: Multiple export formats and destinations
-- **Automatic Lifecycle Management**: Spans automatically emit events without manual intervention
-
-## Quick Start
-
-### Manual Tracing
-
-```typescript
-import { DefaultObservabilityInstance, SpanType } from '@mastra/observability';
-
-// Create observability instance
-const observability = new DefaultObservabilityInstance({
-  name: 'my-app',
-  serviceName: 'my-app',
-});
-
-// Start an agent span
-const agentSpan = observability.startSpan({
-  type: SpanType.AGENT_RUN,
-  name: 'customer-support-agent',
-  attributes: {
-    agentId: 'agent-123',
-    instructions: 'Help with customer support',
-    maxSteps: 10,
-  },
-});
-
-// Create child spans for nested operations
-const llmSpan = agentSpan.createChildSpan({
-  type: SpanType.MODEL_GENERATION,
-  name: 'gpt-4-response',
-  attributes: {
-    model: 'gpt-4',
-    provider: 'openai',
-    streaming: false,
-  },
-});
-
-// End spans with results
-llmSpan.end({
-  output: 'Generated response',
-  attributes: { usage: { totalTokens: 180 } },
-});
-agentSpan.end();
+```bash
+npm install @mastra/observability
 ```
 
-### Span Types
-
-- **`WORKFLOW_RUN`**: Root span for entire workflow execution
-- **`WORKFLOW_STEP`**: Individual step execution within a workflow
-- **`AGENT_RUN`**: Agent processing (supports tools, memory, multi-step)
-- **`MODEL_GENERATION`**: Individual model API calls with token usage
-- **`TOOL_CALL`**: Function/tool execution
-- **`MCP_TOOL_CALL`**: Model Context Protocol tool execution
-- **`PROCESSOR_RUN`**: Input/output processor execution
-- **`GENERIC`**: Custom spans for other operations
-
-### Basic Configuration
-
-Enable observability in your Mastra instance:
+## Quick Start
 
 ```typescript
 import { Mastra } from '@mastra/core';
-import { Observability } from '@mastra/observability';
+import { Observability, DefaultExporter, CloudExporter, SensitiveDataFilter } from '@mastra/observability';
 
 export const mastra = new Mastra({
-  // ... other config
   observability: new Observability({
-    default: { enabled: true },
+    configs: {
+      default: {
+        serviceName: 'my-app',
+        exporters: [
+          new DefaultExporter(), // Persists traces for Mastra Studio
+          new CloudExporter(), // Sends to Mastra Cloud
+        ],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
   }),
 });
 ```
 
-This enables the `DefaultExporter` and `CloudExporter`, with the `SensitiveDataFilter` span output processor, and `always` sampling.
+## Features
+
+- **Auto-instrumentation** - Traces agent runs, LLM calls, tool executions, and workflows
+- **Pluggable Exporters** - Exporters for Studio and Cloud, plus integrations for Arize, Braintrust, Langfuse, LangSmith, and OpenTelemetry
+- **Sampling Strategies** - Always, ratio-based, or custom sampling
+- **Span Processors** - Transform or filter span data before export
+- **OpenTelemetry Compatible** - Standard trace/span ID formats for integration
 
-## Performance Considerations
+## Span Types
 
-### Current Implementation
+- `WORKFLOW_RUN` - Workflow execution
+- `WORKFLOW_STEP` - Individual workflow step
+- `AGENT_RUN` - Agent processing
+- `MODEL_GENERATION` - LLM API calls
+- `TOOL_CALL` - Tool execution
+- `MCP_TOOL_CALL` - MCP tool execution
+- `PROCESSOR_RUN` - Processor execution
+- `GENERIC` - Custom operations
 
-The current implementation prioritizes correctness and ease of use:
+## Documentation
 
-- **Automatic Lifecycle Management**: All spans automatically emit events through method wrapping
-- **Real-time Export**: Events are exported immediately when they occur
-- **Memory Overhead**: Each span maintains references to tracing instance
+For configuration options, exporters, sampling strategies, and more, see the [full documentation](https://mastra.ai/docs/v1/observability/overview).

package/dist/exporters/base.d.ts

@@ -49,12 +49,13 @@ export interface BaseExporterConfig {
  * ```
  */
 export declare abstract class BaseExporter implements ObservabilityExporter {
+    #private;
     /** Exporter name - must be implemented by subclasses */
     abstract name: string;
     /** Mastra logger instance */
     protected logger: IMastraLogger;
-    /** Whether this exporter is disabled */
-    protected isDisabled: boolean;
+    /** Public getter for disabled state */
+    get isDisabled(): boolean;
     /**
      * Initialize the base exporter with logger
      */

package/dist/exporters/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/exporters/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAiB,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAE3G;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,YAAa,YAAW,qBAAqB;IACjE,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6BAA6B;IAC7B,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAEhC,wCAAwC;IACxC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAS;IAEtC;;OAEG;gBACS,MAAM,GAAE,kBAAuB;IAO3C;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAMxC;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK3C;;;;;OAKG;IACG,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;OAEG;IACH,IAAI,CAAC,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAE1C;;OAEG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjB;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/exporters/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAiB,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAE3G;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,YAAa,YAAW,qBAAqB;;IACjE,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6BAA6B;IAC7B,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAKhC,uCAAuC;IACvC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;gBACS,MAAM,GAAE,kBAAuB;IAO3C;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAMxC;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK3C;;;;;OAKG;IACG,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;OAEG;IACH,IAAI,CAAC,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAE1C;;OAEG;IACH,eAAe,CAAC,CAAC,KAAK,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjB;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/exporters/index.d.ts

@@ -2,8 +2,8 @@
  * Mastra Tracing Exporters
  */
 export * from './base.js';
-export { CloudExporter } from './cloud.js';
-export type { CloudExporterConfig } from './cloud.js';
+export * from './tracking.js';
+export * from './cloud.js';
 export * from './console.js';
 export * from './default.js';
 export * from './test.js';

package/dist/exporters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/exporters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,QAAQ,CAAC;AAGvB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/exporters/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAG3B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC"}