@mastra/observability 1.10.3-alpha.0 → 1.11.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # @mastra/observability
 
+## 1.11.0-alpha.0
+
+### Minor Changes
+
+- Auto-attach the Mastra-level `environment` to all observability signals. ([#15956](https://github.com/mastra-ai/mastra/pull/15956))
+
+### Patch Changes
+
+- Updated dependencies [[`1723e09`](https://github.com/mastra-ai/mastra/commit/1723e099829892419ddbfe49287acfeac2522724), [`629f9e9`](https://github.com/mastra-ai/mastra/commit/629f9e9a7e56aa8f129515a3923c5813298790c7), [`25168fb`](https://github.com/mastra-ai/mastra/commit/25168fb9c1de9db7f8171df4f58ceb842c53aa29), [`ab34b5a`](https://github.com/mastra-ai/mastra/commit/ab34b5a2191b8e4353df1dbf7b9155e7d6628d79), [`5fb6c2a`](https://github.com/mastra-ai/mastra/commit/5fb6c2a95c1843cc231704b91354311fc1f34a71), [`394f0cf`](https://github.com/mastra-ai/mastra/commit/394f0cfc31e6b4d801219fdef2e9cc69e5bc8682), [`3d7f709`](https://github.com/mastra-ai/mastra/commit/3d7f709b615e588050bb6283c4ee5cfe2978cbde), [`48a42f1`](https://github.com/mastra-ai/mastra/commit/48a42f114a4006a95e0b7a1b5ad1a24815a175c2), [`2c83efc`](https://github.com/mastra-ai/mastra/commit/2c83efc4482b3efe50830e3b8b4ba9a8d219edff), [`282a10c`](https://github.com/mastra-ai/mastra/commit/282a10c9446e9922afe80e10e3770481c8ac8a28)]:
+  - @mastra/core@1.31.0-alpha.0
+
+## 1.10.3
+
+### Patch Changes
+
+- Add durable agents with resumable streams ([#12557](https://github.com/mastra-ai/mastra/pull/12557))
+
+  Durable agents make agent execution resilient to disconnections, crashes, and long-running operations.
+
+  ### The Problem
+
+  Standard agent streaming has two fragility points:
+  1. **Connection drops** - If a client disconnects mid-stream (network blip, browser refresh, mobile app backgrounded), all subsequent events are lost. The client has no way to "catch up" on what they missed.
+  2. **Long-running operations** - Agent loops with tool calls can take minutes. Holding an HTTP connection open that long is unreliable. If the server restarts or the connection times out, the work is lost.
+
+  ### The Solution
+
+  **Resumable streams** solve connection drops. Every event is cached with a sequential index. If a client disconnects at event 5, they can reconnect and request events starting from index 6. They receive cached events immediately, then continue with live events as they arrive.
+
+  **Durable execution** solves long-running operations. Instead of executing the agent loop directly in the HTTP request, execution happens in a workflow engine (built-in evented engine or Inngest). The HTTP request just subscribes to events. If the connection drops, execution continues. The client can reconnect anytime to observe progress.
+
+  ### Usage
+
+  Wrap any existing `Agent` with durability using factory functions:
+
+  ```typescript
+  import { Agent } from '@mastra/core/agent';
+  import { createDurableAgent } from '@mastra/core/agent/durable';
+
+  const agent = new Agent({
+    id: 'my-agent',
+    model: openai('gpt-4'),
+    instructions: 'You are helpful',
+  });
+
+  const durableAgent = createDurableAgent({ agent });
+  ```
+
+  **Factory functions for different execution strategies:**
+
+  | Factory                                  | Execution                           | Use Case                        |
+  | ---------------------------------------- | ----------------------------------- | ------------------------------- |
+  | `createDurableAgent({ agent })`          | Local, synchronous                  | Development, simple deployments |
+  | `createEventedAgent({ agent })`          | Fire-and-forget via workflow engine | Long-running operations         |
+  | `createInngestAgent({ agent, inngest })` | Inngest-powered                     | Production, distributed systems |
+
+  ### Resumable Streams
+
+  ```typescript
+  // Start streaming
+  const { runId, output } = await durableAgent.stream('Analyze this data...');
+
+  // Client disconnects at event 5...
+
+  // Reconnect and resume from where we left off
+  const { output: resumed } = await durableAgent.observe(runId, { offset: 6 });
+  // Receives events 6, 7, 8... from cache, then continues with live events
+  ```
+
+  ### PubSub and Cache
+
+  Durable agents use two infrastructure components:
+
+  | Component  | Purpose                                   | Default               |
+  | ---------- | ----------------------------------------- | --------------------- |
+  | **PubSub** | Real-time event delivery during streaming | `EventEmitterPubSub`  |
+  | **Cache**  | Stores events for replay on reconnection  | `InMemoryServerCache` |
+
+  When `stream()` is called, events flow through pubsub in real-time. The cache stores each event with a sequential index. When `observe()` is called, missed events replay from cache before continuing with live events.
+
+  **Configure via Mastra instance (recommended):**
+
+  ```typescript
+  const mastra = new Mastra({
+    cache: new RedisServerCache({ url: 'redis://...' }),
+    pubsub: new RedisPubSub({ url: 'redis://...' }),
+    agents: {
+      // Inherits cache and pubsub from Mastra
+      myAgent: createDurableAgent({ agent }),
+    },
+  });
+  ```
+
+  **Configure per-agent (overrides Mastra):**
+
+  ```typescript
+  const durableAgent = createDurableAgent({
+    agent,
+    cache: new RedisServerCache({ url: 'redis://...' }),
+    pubsub: new RedisPubSub({ url: 'redis://...' }),
+  });
+  ```
+
+  **Disable caching (streams won't be resumable):**
+
+  ```typescript
+  const durableAgent = createDurableAgent({ agent, cache: false });
+  ```
+
+  For single-instance deployments, the defaults work fine. For multi-instance deployments (load balancer, horizontal scaling), use Redis-backed implementations so any instance can serve reconnection requests.
+
+  ### Class Hierarchy
+  - `DurableAgent` extends `Agent` - base class with resumable streams
+  - `EventedAgent` extends `DurableAgent` - fire-and-forget execution
+  - `InngestAgent` extends `DurableAgent` - Inngest-powered execution
+
+- Reduced default cloud observability volume by filtering model chunk spans from CloudExporter uploads by default and raising the default observability log level to `warn`. ([#15815](https://github.com/mastra-ai/mastra/pull/15815))
+
+- Updated dependencies [[`920c757`](https://github.com/mastra-ai/mastra/commit/920c75799c6bd71787d86deaf654a35af4c839ca), [`d587199`](https://github.com/mastra-ai/mastra/commit/d5871993c0371bde2b0717d6b47194755baa1443), [`1fe2533`](https://github.com/mastra-ai/mastra/commit/1fe2533c4382ca6858aac7c4b63e888c2eac6541), [`f8694b6`](https://github.com/mastra-ai/mastra/commit/f8694b6fa0b7a5cde71d794c3bbef4957c55bcb8)]:
+  - @mastra/core@1.30.0
+
 ## 1.10.3-alpha.0
 
 ### Patch Changes

package/dist/default.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../src/default.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,aAAa,EAEb,uBAAuB,EACvB,qBAAqB,EACrB,aAAa,EACb,UAAU,EAEX,MAAM,4BAA4B,CAAC;AAIpC,OAAO,KAAK,EAA+B,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAsBzF;;;GAGG;AACH,qBAAa,aAAc,SAAQ,UAAW,YAAW,uBAAuB;;gBAIlE,MAAM,EAAE,2BAA2B;IAkG/C,yFAAyF;IACzF,gBAAgB,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAwBnD,sFAAsF;IACtF,SAAS,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAOnD,0FAA0F;IAC1F,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,SAAS;IAIhF,gBAAgB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA6B1E,QAAQ,CAAC,IAAI,EAAE;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;QACxC,KAAK,EAAE,UAAU,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCX,WAAW,CAAC,IAAI,EAAE;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;QACxC,QAAQ,EAAE,aAAa,CAAC;KACzB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjB,iFAAiF;IACjF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,SAAS,UAAQ,GAAG,IAAI;IAIxF,yCAAyC;IACzC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAI5D,8CAA8C;IAC9C,kBAAkB,IAAI,qBAAqB,GAAG,SAAS;IAIvD,mDAAmD;IACnD,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAI3D,gFAAgF;IAChF,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIzC,mEAAmE;IACnE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC,qEAAqE;IACrE,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAIjD,8DAA8D;IAC9D,KAAK,IAAI,IAAI;IAIb,qEAAqE;IAC/D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAqDhC"}
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../src/default.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,aAAa,EAEb,uBAAuB,EACvB,qBAAqB,EACrB,aAAa,EACb,UAAU,EAEX,MAAM,4BAA4B,CAAC;AAIpC,OAAO,KAAK,EAA+B,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAsBzF;;;GAGG;AACH,qBAAa,aAAc,SAAQ,UAAW,YAAW,uBAAuB;;gBAIlE,MAAM,EAAE,2BAA2B;IAkG/C,yFAAyF;IACzF,gBAAgB,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA8BnD,sFAAsF;IACtF,SAAS,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAOnD,0FAA0F;IAC1F,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,SAAS;IAIhF,gBAAgB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA6B1E,QAAQ,CAAC,IAAI,EAAE;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;QACxC,KAAK,EAAE,UAAU,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCX,WAAW,CAAC,IAAI,EAAE;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;QACxC,QAAQ,EAAE,aAAa,CAAC;KACzB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjB,iFAAiF;IACjF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,SAAS,UAAQ,GAAG,IAAI;IAWxF,yCAAyC;IACzC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAI5D,8CAA8C;IAC9C,kBAAkB,IAAI,qBAAqB,GAAG,SAAS;IAIvD,mDAAmD;IACnD,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAAC;IAI3D,gFAAgF;IAChF,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIzC,mEAAmE;IACnE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC,qEAAqE;IACrE,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAIjD,8DAA8D;IAC9D,KAAK,IAAI,IAAI;IAIb,qEAAqE;IAC/D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAqDhC"}

package/dist/index.cjs

@@ -19443,7 +19443,7 @@ var BaseSpan = class {
       sessionId: getMetadataString("sessionId"),
       threadId: getMetadataString("threadId"),
       requestId: getMetadataString("requestId"),
-      environment: getMetadataString("environment"),
+      environment: getMetadataString("environment") ?? this.observabilityInstance.getMastraEnvironment?.(),
       source: getMetadataString("source"),
       serviceName: getMetadataString("serviceName") ?? this.observabilityInstance.getConfig().serviceName,
       experimentId: getMetadataString("experimentId")
@@ -19715,6 +19715,12 @@ var BaseObservabilityInstance = class extends base.MastraBase {
    * Cardinality filter for metrics label protection.
    */
   cardinalityFilter;
+  /**
+   * Deployment environment propagated from the parent Mastra instance.
+   * Set by `Observability.setMastraContext`, read by spans as a fallback when
+   * a span's `metadata.environment` isn't set.
+   */
+  #mastraEnvironment;
   constructor(config2) {
     super({ component: logger.RegisteredLogger.OBSERVABILITY, name: config2.serviceName });
     this.config = {
@@ -19807,6 +19813,7 @@ var BaseObservabilityInstance = class extends base.MastraBase {
     const tracingMetadata = !options.parent ? tracingOptions?.metadata : void 0;
     const mergedMetadata = metadata || tracingMetadata ? { ...metadata, ...tracingMetadata } : void 0;
     const enrichedMetadata = this.extractMetadataFromRequestContext(requestContext, mergedMetadata, traceState);
+    const finalMetadata = !options.parent && this.#mastraEnvironment !== void 0 && (enrichedMetadata === void 0 || enrichedMetadata.environment === void 0) ? { ...enrichedMetadata ?? {}, environment: this.#mastraEnvironment } : enrichedMetadata;
     const tags = !options.parent ? tracingOptions?.tags : void 0;
     const traceId = !options.parent ? options.traceId ?? tracingOptions?.traceId : options.traceId;
     const parentSpanId = !options.parent ? options.parentSpanId ?? tracingOptions?.parentSpanId : options.parentSpanId;
@@ -19814,7 +19821,7 @@ var BaseObservabilityInstance = class extends base.MastraBase {
       ...rest,
       traceId,
       parentSpanId,
-      metadata: enrichedMetadata,
+      metadata: finalMetadata,
       traceState,
       tags,
       requestContext
@@ -19867,6 +19874,20 @@ var BaseObservabilityInstance = class extends base.MastraBase {
   getConfig() {
     return { ...this.config };
   }
+  /**
+   * Returns the deployment environment propagated from the parent Mastra instance.
+   * Spans use this as a fallback when `metadata.environment` isn't set.
+   */
+  getMastraEnvironment() {
+    return this.#mastraEnvironment;
+  }
+  /**
+   * Internal hook used by `Observability.setMastraContext` to push the
+   * resolved Mastra-level environment into this instance.
+   */
+  __setMastraEnvironment(environment) {
+    this.#mastraEnvironment = environment;
+  }
   // ============================================================================
   // Plugin Access
   // ============================================================================
@@ -20881,7 +20902,9 @@ var Observability = class extends base.MastraBase {
     const instances = this.listInstances();
     const { mastra } = options;
     this.#mastra = mastra;
+    const mastraEnvironment = mastra.getEnvironment?.();
     instances.forEach((instance) => {
+      instance.__setMastraEnvironment?.(mastraEnvironment);
       const config2 = instance.getConfig();
       const exporters = instance.getExporters();
       exporters.forEach((exporter) => {
@@ -20998,6 +21021,9 @@ var Observability = class extends base.MastraBase {
   /** Register a named observability instance, optionally marking it as default. */
   registerInstance(name, instance, isDefault = false) {
     this.#registry.register(name, instance, isDefault);
+    if (this.#mastra) {
+      instance.__setMastraEnvironment?.(this.#mastra.getEnvironment?.());
+    }
   }
   /** Get a registered instance by name. */
   getInstance(name) {