@mastra/observability 1.2.1-alpha.0 → 1.3.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @mastra/observability
 
+## 1.3.0-alpha.0
+
+### Minor Changes
+
+- Adds the ObservabilityBus with built-in promise tracking and flush support, laying the groundwork for fixing #13388 where spans were lost in durable execution contexts. ([#13612](https://github.com/mastra-ai/mastra/pull/13612))
+
+  Introduces new metrics and structured logging contexts as standalone features:
+
+  **Automatic metrics** — New auto-extracted metrics emit duration and count metrics for agent runs, tool calls, and workflows with structured labels, removing the need for manual instrumentation.
+
+  **Structured logging** — New LoggerContext provides trace-correlated logging, automatically linking logs to their parent traces and spans for easier debugging across agents and workflows.
+
+  **Cardinality protection** — New CardinalityFilter prevents high-cardinality labels from overwhelming metric backends.
+
+### Patch Changes
+
+- Updated dependencies [[`504fc8b`](https://github.com/mastra-ai/mastra/commit/504fc8b9d0ddab717577ad3bf9c95ea4bd5377bd), [`f9c150b`](https://github.com/mastra-ai/mastra/commit/f9c150b7595ad05ad9cc9a11098e2944361e8c22), [`88de7e8`](https://github.com/mastra-ai/mastra/commit/88de7e8dfe4b7e1951a9e441bb33136e705ce24e), [`edee4b3`](https://github.com/mastra-ai/mastra/commit/edee4b37dff0af515fc7cc0e8d71ee39e6a762f0), [`3790c75`](https://github.com/mastra-ai/mastra/commit/3790c7578cc6a47d854eb12d89e6b1912867fe29), [`e7a235b`](https://github.com/mastra-ai/mastra/commit/e7a235be6472e0c870ed6c791ddb17c492dc188b), [`d51d298`](https://github.com/mastra-ai/mastra/commit/d51d298953967aab1f58ec965b644d109214f085), [`6dbeeb9`](https://github.com/mastra-ai/mastra/commit/6dbeeb94a8b1eebb727300d1a98961f882180794), [`d5f0d8d`](https://github.com/mastra-ai/mastra/commit/d5f0d8d6a03e515ddaa9b5da19b7e44b8357b07b), [`09c3b18`](https://github.com/mastra-ai/mastra/commit/09c3b1802ff14e243a8a8baea327440bc8cc2e32), [`b896379`](https://github.com/mastra-ai/mastra/commit/b8963791c6afa79484645fcec596a201f936b9a2), [`85c84eb`](https://github.com/mastra-ai/mastra/commit/85c84ebb78aebfcba9d209c8e152b16d7a00cb71), [`a89272a`](https://github.com/mastra-ai/mastra/commit/a89272a5d71939b9fcd284e6a6dc1dd091a6bdcf), [`ee9c8df`](https://github.com/mastra-ai/mastra/commit/ee9c8df644f19d055af5f496bf4942705f5a47b7), [`77b4a25`](https://github.com/mastra-ai/mastra/commit/77b4a254e51907f8ff3a3ba95596a18e93ae4b35), [`276246e`](https://github.com/mastra-ai/mastra/commit/276246e0b9066a1ea48bbc70df84dbe528daaf99), [`08ecfdb`](https://github.com/mastra-ai/mastra/commit/08ecfdbdad6fb8285deef86a034bdf4a6047cfca), [`d5f628c`](https://github.com/mastra-ai/mastra/commit/d5f628ca86c6f6f3ff1035d52f635df32dd81cab), [`524c0f3`](https://github.com/mastra-ai/mastra/commit/524c0f3c434c3d9d18f66338dcef383d6161b59c), [`c18a0e9`](https://github.com/mastra-ai/mastra/commit/c18a0e9cef1e4ca004b2963d35e4cfc031971eac), [`4bd21ea`](https://github.com/mastra-ai/mastra/commit/4bd21ea43d44d0a0427414fc047577f9f0aa3bec), [`115a7a4`](https://github.com/mastra-ai/mastra/commit/115a7a47db5e9896fec12ae6507501adb9ec89bf), [`22a48ae`](https://github.com/mastra-ai/mastra/commit/22a48ae2513eb54d8d79dad361fddbca97a155e8), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9311c17`](https://github.com/mastra-ai/mastra/commit/9311c17d7a0640d9c4da2e71b814dc67c57c6369), [`7edf78f`](https://github.com/mastra-ai/mastra/commit/7edf78f80422c43e84585f08ba11df0d4d0b73c5), [`1c4221c`](https://github.com/mastra-ai/mastra/commit/1c4221cf6032ec98d0e094d4ee11da3e48490d96), [`d25b9ea`](https://github.com/mastra-ai/mastra/commit/d25b9eabd400167255a97b690ffbc4ee4097ded5), [`fe1ce5c`](https://github.com/mastra-ai/mastra/commit/fe1ce5c9211c03d561606fda95cbfe7df1d9a9b5), [`b03c0e0`](https://github.com/mastra-ai/mastra/commit/b03c0e0389a799523929a458b0509c9e4244d562), [`0a8366b`](https://github.com/mastra-ai/mastra/commit/0a8366b0a692fcdde56c4d526e4cf03c502ae4ac), [`85664e9`](https://github.com/mastra-ai/mastra/commit/85664e9fd857320fbc245e301f764f45f66f32a3), [`bc79650`](https://github.com/mastra-ai/mastra/commit/bc796500c6e0334faa158a96077e3fb332274869), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`3a3a59e`](https://github.com/mastra-ai/mastra/commit/3a3a59e8ffaa6a985fe3d9a126a3f5ade11a6724), [`3108d4e`](https://github.com/mastra-ai/mastra/commit/3108d4e649c9fddbf03253a6feeb388a5fa9fa5a), [`0c33b2c`](https://github.com/mastra-ai/mastra/commit/0c33b2c9db537f815e1c59e2c898ffce2e395a79), [`191e5bd`](https://github.com/mastra-ai/mastra/commit/191e5bd29b82f5bda35243945790da7bc7b695c2), [`f77cd94`](https://github.com/mastra-ai/mastra/commit/f77cd94c44eabed490384e7d19232a865e13214c), [`e8135c7`](https://github.com/mastra-ai/mastra/commit/e8135c7e300dac5040670eec7eab896ac6092e30), [`daca48f`](https://github.com/mastra-ai/mastra/commit/daca48f0fb17b7ae0b62a2ac40cf0e491b2fd0b7), [`257d14f`](https://github.com/mastra-ai/mastra/commit/257d14faca5931f2e4186fc165b6f0b1f915deee), [`352f25d`](https://github.com/mastra-ai/mastra/commit/352f25da316b24cdd5b410fd8dddf6a8b763da2a), [`93477d0`](https://github.com/mastra-ai/mastra/commit/93477d0769b8a13ea5ed73d508d967fb23eaeed9), [`31c78b3`](https://github.com/mastra-ai/mastra/commit/31c78b3eb28f58a8017f1dcc795c33214d87feac), [`0bc0720`](https://github.com/mastra-ai/mastra/commit/0bc07201095791858087cc56f353fcd65e87ab54), [`36516ac`](https://github.com/mastra-ai/mastra/commit/36516aca1021cbeb42e74751b46a2614101f37c8), [`e947652`](https://github.com/mastra-ai/mastra/commit/e9476527fdecb4449e54570e80dfaf8466901254), [`3c6ef79`](https://github.com/mastra-ai/mastra/commit/3c6ef798481e00d6d22563be2de98818fd4dd5e0), [`9257d01`](https://github.com/mastra-ai/mastra/commit/9257d01d1366d81f84c582fe02b5e200cf9621f4), [`ec248f6`](https://github.com/mastra-ai/mastra/commit/ec248f6b56e8a037c066c49b2178e2507471d988)]:
+  - @mastra/core@1.9.0-alpha.0
+
+## 1.2.1
+
+### Patch Changes
+
+- Fixed telemetry spans being silently dropped when the default exporter was used. The exporter now holds spans in memory until initialization completes, ensuring all spans are propagated to your tracing backend. ([#12936](https://github.com/mastra-ai/mastra/pull/12936))
+
+- Fixed `keysToStrip.has is not a function` crash in `deepClean()` when bundlers transform `new Set([...])` into a plain object or array. This affected agents with memory deployed to Mastra Cloud. ([#13322](https://github.com/mastra-ai/mastra/pull/13322))
+
+- Updated dependencies [[`0d9efb4`](https://github.com/mastra-ai/mastra/commit/0d9efb47992c34aa90581c18b9f51f774f6252a5), [`5caa13d`](https://github.com/mastra-ai/mastra/commit/5caa13d1b2a496e2565ab124a11de9a51ad3e3b9), [`940163f`](https://github.com/mastra-ai/mastra/commit/940163fc492401d7562301e6f106ccef4fefe06f), [`47892c8`](https://github.com/mastra-ai/mastra/commit/47892c85708eac348209f99f10f9a5f5267e11c0), [`45bb78b`](https://github.com/mastra-ai/mastra/commit/45bb78b70bd9db29678fe49476cd9f4ed01bfd0b), [`70eef84`](https://github.com/mastra-ai/mastra/commit/70eef84b8f44493598fdafa2980a0e7283415eda), [`d84e52d`](https://github.com/mastra-ai/mastra/commit/d84e52d0f6511283ddd21ed5fe7f945449d0f799), [`24b80af`](https://github.com/mastra-ai/mastra/commit/24b80af87da93bb84d389340181e17b7477fa9ca), [`608e156`](https://github.com/mastra-ai/mastra/commit/608e156def954c9604c5e3f6d9dfce3bcc7aeab0), [`2b2e157`](https://github.com/mastra-ai/mastra/commit/2b2e157a092cd597d9d3f0000d62b8bb4a7348ed), [`59d30b5`](https://github.com/mastra-ai/mastra/commit/59d30b5d0cb44ea7a1c440e7460dfb57eac9a9b5), [`453693b`](https://github.com/mastra-ai/mastra/commit/453693bf9e265ddccecef901d50da6caaea0fbc6), [`78d1c80`](https://github.com/mastra-ai/mastra/commit/78d1c808ad90201897a300af551bcc1d34458a20), [`c204b63`](https://github.com/mastra-ai/mastra/commit/c204b632d19e66acb6d6e19b11c4540dd6ad5380), [`742a417`](https://github.com/mastra-ai/mastra/commit/742a417896088220a3b5560c354c45c5ca6d88b9)]:
+  - @mastra/core@1.6.0
+
 ## 1.2.1-alpha.0
 
 ### Patch Changes

package/LICENSE.md

@@ -1,3 +1,18 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
 # Apache License 2.0
 
 Copyright (c) 2025 Kepler Software, Inc.

package/README.md

@@ -1,6 +1,6 @@
 # Mastra Observability
 
-Tracing and monitoring for AI operations in Mastra.
+Tracing, metrics, and structured logging for AI operations in Mastra.
 
 ## Installation
 
@@ -38,6 +38,36 @@ export const mastra = new Mastra({
 - **Span Processors** - Transform or filter span data before export
 - **OpenTelemetry Compatible** - Standard trace/span ID formats for integration
 
+## Architecture
+
+### ObservabilityBus
+
+Central event router that dispatches tracing, metric, and log events to registered exporters. All handler promises are tracked for reliable flush and shutdown — no events are silently dropped.
+
+Exporters register via `registerExporter()` and can optionally implement `onLogEvent` and `onMetricEvent` handlers alongside the existing `exportTracingEvent`.
+
+### Auto-extracted metrics
+
+Metrics are automatically extracted from span lifecycle events by `AutoExtractedMetrics`:
+
+- `mastra_agent_runs_started` / `mastra_agent_runs_ended` / `mastra_agent_duration_ms`
+- `mastra_tool_calls_started` / `mastra_tool_calls_ended` / `mastra_tool_duration_ms`
+- `mastra_model_requests_started` / `mastra_model_requests_ended` / `mastra_model_duration_ms`
+- `mastra_model_input_tokens` / `mastra_model_output_tokens` / `mastra_model_cache_read_tokens` / `mastra_model_cache_write_tokens`
+- `mastra_workflow_runs_started` / `mastra_workflow_runs_ended` / `mastra_workflow_duration_ms`
+- `mastra_scores_total` (from score events)
+- `mastra_feedback_total` (from feedback events)
+
+Auto-extracted metrics carry labels: `entity_type`, `entity_name`, `status` (on `_ended` metrics), plus `model` and `provider` on model generation spans.
+
+### Structured logging
+
+`LoggerContextImpl` emits log events with automatic trace correlation (traceId, spanId), inherited tags, and entity metadata. Supports minimum log level filtering (debug/info/warn/error/fatal).
+
+### Metrics context
+
+`MetricsContextImpl` provides counter, gauge, and histogram instruments. All labels pass through a `CardinalityFilter` that blocks high-cardinality keys (trace_id, user_id, etc.) to protect metric backends.
+
 ## Span Types
 
 - `WORKFLOW_RUN` - Workflow execution
@@ -49,6 +79,37 @@ export const mastra = new Mastra({
 - `PROCESSOR_RUN` - Processor execution
 - `GENERIC` - Custom operations
 
+## Metrics Labels
+
+### Auto-extracted metric labels
+
+| Label         | Description                                                          | Cardinality                 |
+| ------------- | -------------------------------------------------------------------- | --------------------------- |
+| `entity_type` | What is being measured (e.g., `agent`, `tool`, `workflow_run`)       | Small enum (~9 values)      |
+| `entity_name` | Name of the entity (e.g., `researcher`, `search`)                    | Bounded by defined entities |
+| `model`       | LLM model ID (only on model generation spans)                        | Bounded by LLM providers    |
+| `provider`    | LLM provider (only on model generation spans)                        | Bounded by LLM providers    |
+| `status`      | Outcome of the operation (`ok` or `error`), on `_ended` metrics only | 2 values                    |
+
+### User-emitted metric labels (via MetricsContext)
+
+User-emitted metrics inherit additional context labels from the active span:
+
+| Label          | Description                                                                 | Cardinality                 |
+| -------------- | --------------------------------------------------------------------------- | --------------------------- |
+| `parent_type`  | Entity type of the nearest parent                                           | Same small enum             |
+| `parent_name`  | Name of the nearest parent entity                                           | Bounded by defined entities |
+| `root_type`    | Entity type of the outermost ancestor (only set when different from parent) | Same small enum             |
+| `root_name`    | Name of the outermost ancestor entity                                       | Bounded by defined entities |
+| `service_name` | Service name from observability config                                      | Single value per deployment |
+
+### Common query patterns
+
+- **Which agent is expensive?** → group by `entity_name` where `entity_type=agent`
+- **Why is this tool slow only sometimes?** → group by `parent_name`
+- **What's the total cost of this user-facing flow?** → group by `root_name`
+- **Which model is cheapest for this agent?** → group by `model` where `entity_name=X`
+
 ## Documentation
 
 For configuration options, exporters, sampling strategies, and more, see the [full documentation](https://mastra.ai/docs/v1/observability/overview).

package/dist/bus/base.d.ts

@@ -0,0 +1,43 @@
+/**
+ * BaseObservabilityEventBus - Generic event bus for observability events.
+ *
+ * Provides a synchronous pub/sub mechanism:
+ * - Events are dispatched to subscribers immediately on emit()
+ * - Graceful error handling (handler errors don't break other handlers)
+ * - flush() awaits any in-flight async subscriber promises
+ * - Clean shutdown flushes then clears subscribers
+ *
+ * Buffering/batching is intentionally NOT done here — individual exporters
+ * own their own batching strategy (e.g. CloudExporter batches uploads).
+ */
+import { MastraBase } from '@mastra/core/base';
+import type { ObservabilityEventBus } from '@mastra/core/observability';
+export declare class BaseObservabilityEventBus<TEvent> extends MastraBase implements ObservabilityEventBus<TEvent> {
+    private subscribers;
+    /** In-flight async subscriber promises. Self-cleaning via .finally(). */
+    private pendingSubscribers;
+    constructor({ name }?: {
+        name?: string;
+    });
+    /**
+     * Dispatch an event to all subscribers synchronously.
+     * Async handler promises are tracked internally and drained by {@link flush}.
+     *
+     * @param event - The event to broadcast to subscribers.
+     */
+    emit(event: TEvent): void;
+    /**
+     * Register a handler to receive future events.
+     *
+     * @param handler - Callback invoked synchronously on each {@link emit}.
+     * @returns An unsubscribe function that removes the handler.
+     */
+    subscribe(handler: (event: TEvent) => void): () => void;
+    /** Max flush drain iterations before bailing — prevents infinite loops when handlers re-emit. */
+    private static readonly MAX_FLUSH_ITERATIONS;
+    /** Await all in-flight async subscriber promises, draining until empty. */
+    flush(): Promise<void>;
+    /** Flush pending promises, then clear all subscribers. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/bus/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE,qBAAa,yBAAyB,CAAC,MAAM,CAAE,SAAQ,UAAW,YAAW,qBAAqB,CAAC,MAAM,CAAC;IACxG,OAAO,CAAC,WAAW,CAA2C;IAE9D,yEAAyE;IACzE,OAAO,CAAC,kBAAkB,CAAiC;gBAE/C,EAAE,IAAI,EAAE,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO;IAI5C;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAmBzB;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,iGAAiG;IACjG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAK;IAEjD,2EAA2E;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B,0DAA0D;IACpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAIhC"}

package/dist/bus/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Observability Event Bus
+ */
+export { BaseObservabilityEventBus } from './base.js';
+export { ObservabilityBus } from './observability-bus.js';
+export { routeToHandler, type ObservabilityHandler } from './route-event.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bus/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/bus/observability-bus.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ObservabilityBus - Unified event bus for all observability signals.
+ *
+ * Routes events to registered exporters and an optional bridge based on event
+ * type. Each handler declares which signals it supports by implementing the
+ * corresponding method (onTracingEvent, onLogEvent, onMetricEvent,
+ * onScoreEvent, onFeedbackEvent).
+ *
+ * Handler presence = signal support. If a handler does not implement a method,
+ * events of that type are silently skipped for that handler.
+ */
+import type { ObservabilityExporter, ObservabilityBridge, ObservabilityEvent } from '@mastra/core/observability';
+import type { CardinalityFilter } from '../metrics/cardinality.js';
+import { BaseObservabilityEventBus } from './base.js';
+export declare class ObservabilityBus extends BaseObservabilityEventBus<ObservabilityEvent> {
+    private exporters;
+    private bridge?;
+    private autoExtractor?;
+    /** In-flight handler promises from routeToHandler. Self-cleaning via .finally(). */
+    private pendingHandlers;
+    constructor();
+    /**
+     * Enable auto-extraction of metrics from tracing, score, and feedback events.
+     * When enabled, span lifecycle events automatically generate counter/histogram
+     * metrics (e.g., mastra_agent_runs_started, mastra_model_duration_ms).
+     *
+     * No-ops if auto-extraction is already enabled.
+     *
+     * @param cardinalityFilter - Optional filter applied to auto-extracted metric labels.
+     */
+    enableAutoExtractedMetrics(cardinalityFilter?: CardinalityFilter): void;
+    /**
+     * Register an exporter to receive routed events.
+     * Duplicate registrations (same instance) are silently ignored.
+     *
+     * @param exporter - The exporter to register.
+     */
+    registerExporter(exporter: ObservabilityExporter): void;
+    /**
+     * Unregister an exporter.
+     *
+     * @param exporter - The exporter instance to remove.
+     * @returns `true` if the exporter was found and removed, `false` otherwise.
+     */
+    unregisterExporter(exporter: ObservabilityExporter): boolean;
+    /**
+     * Get registered exporters (read-only snapshot).
+     */
+    getExporters(): readonly ObservabilityExporter[];
+    /**
+     * Register a bridge to receive all routed events alongside exporters.
+     * Only one bridge can be registered at a time; replacing an existing bridge
+     * logs a warning.
+     *
+     * @param bridge - The bridge to register.
+     */
+    registerBridge(bridge: ObservabilityBridge): void;
+    /**
+     * Unregister the bridge.
+     *
+     * @returns `true` if a bridge was registered and removed, `false` otherwise.
+     */
+    unregisterBridge(): boolean;
+    /**
+     * Get the registered bridge, if any.
+     */
+    getBridge(): ObservabilityBridge | undefined;
+    /**
+     * Emit an event: route to exporter/bridge handlers, run auto-extraction,
+     * then forward to base class for subscriber delivery.
+     *
+     * emit() is synchronous — async handler promises are tracked internally
+     * and can be drained via flush().
+     */
+    emit(event: ObservabilityEvent): void;
+    /**
+     * Track an async handler promise so flush() can await it.
+     * No-ops for sync (void) results.
+     */
+    private trackPromise;
+    /**
+     * Two-phase flush to ensure all observability data is fully exported.
+     *
+     * **Phase 1 — Delivery:** Await all in-flight handler promises (exporters,
+     * bridge, and base-class subscribers). After this resolves, all event data
+     * has been delivered to handler methods.
+     *
+     * **Phase 2 — Buffer drain:** Call flush() on each exporter and bridge to
+     * drain their SDK-internal buffers (e.g., OTEL BatchSpanProcessor, Langfuse
+     * client queue). Phases are sequential — Phase 2 must not start until
+     * Phase 1 completes, otherwise exporters would flush empty buffers.
+     */
+    flush(): Promise<void>;
+    /** Flush all pending events and exporter buffers, then clear subscribers. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=observability-bus.d.ts.map

package/dist/bus/observability-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-bus.d.ts","sourceRoot":"","sources":["../../src/bus/observability-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EAInB,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AAenD,qBAAa,gBAAiB,SAAQ,yBAAyB,CAAC,kBAAkB,CAAC;IACjF,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAE7C,oFAAoF;IACpF,OAAO,CAAC,eAAe,CAAiC;;IAMxD;;;;;;;;OAQG;IACH,0BAA0B,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAOvE;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAOvD;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO;IAS5D;;OAEG;IACH,YAAY,IAAI,SAAS,qBAAqB,EAAE;IAIhD;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAOjD;;;;OAIG;IACH,gBAAgB,IAAI,OAAO;IAQ3B;;OAEG;IACH,SAAS,IAAI,mBAAmB,GAAG,SAAS;IAI5C;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IA+BrC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;;;;;;;OAWG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B5B,6EAA6E;IACvE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAIhC"}

package/dist/bus/route-event.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared event routing logic for observability handlers (exporters and bridges).
+ *
+ * Both ObservabilityExporter and ObservabilityBridge implement the same optional
+ * signal handlers (onTracingEvent, onLogEvent, onMetricEvent, onScoreEvent,
+ * onFeedbackEvent). This module provides a single routing function used by both
+ * the ObservabilityBus (for exporters) and BaseObservabilityInstance (for bridges).
+ */
+import type { IMastraLogger } from '@mastra/core/logger';
+import type { ObservabilityEvents, ObservabilityEvent } from '@mastra/core/observability';
+/**
+ * Any handler that can receive routed observability events.
+ * Both ObservabilityExporter and ObservabilityBridge extend
+ * ObservabilityEvents, so this matches either.
+ */
+export type ObservabilityHandler = ObservabilityEvents & {
+    name: string;
+};
+/**
+ * Route a single event to the appropriate method on a handler.
+ *
+ * For tracing events, prefers onTracingEvent when present and falls back
+ * to exportTracingEvent. For all other signals, calls the corresponding
+ * optional handler method if the handler implements it.
+ *
+ * Returns the handler promise (if async) so callers can track it for flush().
+ * Async rejections are caught to prevent unhandled rejections.
+ * Sync throws are caught so one failing handler doesn't break others.
+ */
+export declare function routeToHandler(handler: ObservabilityHandler, event: ObservabilityEvent, logger: IMastraLogger): void | Promise<void>;
+//# sourceMappingURL=route-event.d.ts.map

package/dist/bus/route-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-event.d.ts","sourceRoot":"","sources":["../../src/bus/route-event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EACV,mBAAmB,EAMnB,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAGpC;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,aAAa,GACpB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCtB"}

package/dist/context/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Context implementations for observability signals.
+ */
+export { LoggerContextImpl, type LoggerContextConfig } from './logger.js';
+export { MetricsContextImpl, type MetricsContextConfig } from './metrics.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/dist/context/logger.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LoggerContextImpl - Structured logging with automatic trace correlation.
+ *
+ * Emits LogEvent to the ObservabilityBus. All context (traceId, spanId,
+ * tags, metadata) is snapshotted at construction time.
+ */
+import type { LogLevel, LoggerContext } from '@mastra/core/observability';
+import type { ObservabilityBus } from '../bus/index.js';
+export interface LoggerContextConfig {
+    /** Trace ID for log correlation */
+    traceId?: string;
+    /** Span ID for log correlation */
+    spanId?: string;
+    /** Tags for filtering/categorization */
+    tags?: string[];
+    /** Metadata (entity context, runId, environment, serviceName, etc.) */
+    metadata?: Record<string, unknown>;
+    /** Bus for event emission */
+    observabilityBus: ObservabilityBus;
+    /** Minimum log level (logs below this are discarded) */
+    minLevel?: LogLevel;
+}
+export declare class LoggerContextImpl implements LoggerContext {
+    private config;
+    /**
+     * Create a logger context. Tags and metadata are defensively copied so
+     * mutations after construction do not affect emitted logs.
+     */
+    constructor(config: LoggerContextConfig);
+    /** Log at DEBUG level. */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Log at INFO level. */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Log at WARN level. */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Log at ERROR level. */
+    error(message: string, data?: Record<string, unknown>): void;
+    /** Log at FATAL level. */
+    fatal(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Build an ExportedLog, check against the minimum level, and emit it through the bus.
+     */
+    private log;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/context/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/context/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAyB,MAAM,4BAA4B,CAAC;AAEjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE/C,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,6BAA6B;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;IAEnC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAWD,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,MAAM,CAAsB;IAEpC;;;OAGG;gBACS,MAAM,EAAE,mBAAmB;IAQvC,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,yBAAyB;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,yBAAyB;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;OAEG;IACH,OAAO,CAAC,GAAG;CAoBZ"}

package/dist/context/metrics.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MetricsContextImpl - Metric emission with cardinality protection.
+ *
+ * Provides counter, gauge, and histogram instrument creation.
+ * All metrics pass through cardinality filtering before emission.
+ * Context labels are snapshotted at construction time.
+ */
+import type { MetricsContext, Counter, Gauge, Histogram } from '@mastra/core/observability';
+import type { ObservabilityBus } from '../bus/index.js';
+import type { CardinalityFilter } from '../metrics/cardinality.js';
+export interface MetricsContextConfig {
+    /** Base labels merged into every emitted metric (entity context, model, provider, serviceName, etc.) */
+    labels?: Record<string, string>;
+    /** Bus for event emission */
+    observabilityBus: ObservabilityBus;
+    /** Cardinality filter applied to all labels */
+    cardinalityFilter: CardinalityFilter;
+}
+export declare class MetricsContextImpl implements MetricsContext {
+    private config;
+    /**
+     * Create a metrics context. Base labels are defensively copied so
+     * mutations after construction do not affect emitted metrics.
+     */
+    constructor(config: MetricsContextConfig);
+    /**
+     * Create a counter instrument. Call `.add(value)` to increment.
+     *
+     * @param name - Metric name (e.g. `mastra_custom_requests_total`).
+     */
+    counter(name: string): Counter;
+    /**
+     * Create a gauge instrument. Call `.set(value)` to record a point-in-time value.
+     *
+     * @param name - Metric name (e.g. `mastra_queue_depth`).
+     */
+    gauge(name: string): Gauge;
+    /**
+     * Create a histogram instrument. Call `.record(value)` to observe a measurement.
+     *
+     * @param name - Metric name (e.g. `mastra_request_duration_ms`).
+     */
+    histogram(name: string): Histogram;
+    /** Merge base + additional labels, apply cardinality filtering, and emit a MetricEvent. Non-finite values are silently dropped. */
+    private emit;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/context/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/context/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EACP,KAAK,EACL,SAAS,EAIV,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACnC,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,6BAA6B;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;IAEnC,+CAA+C;IAC/C,iBAAiB,EAAE,iBAAiB,CAAC;CACtC;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,MAAM,CAAuB;IAErC;;;OAGG;gBACS,MAAM,EAAE,oBAAoB;IAOxC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQ9B;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAQ1B;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IAQlC,mIAAmI;IACnI,OAAO,CAAC,IAAI;CAoBb"}

package/dist/exporters/base.d.ts

@@ -112,6 +112,17 @@ export declare abstract class BaseExporter implements ObservabilityExporter {
      * @returns The (possibly modified) event to process
      */
     protected applySpanFormatter(event: TracingEvent): Promise<TracingEvent>;
+    /**
+     * Default onTracingEvent handler that delegates to exportTracingEvent.
+     *
+     * This provides backward compatibility: existing exporters that only implement
+     * _exportTracingEvent will automatically receive tracing events routed through
+     * the ObservabilityBus. Subclasses can override this if they need different
+     * routing behavior for bus-delivered events.
+     *
+     * Handler presence on ObservabilityExporter = signal support.
+     */
+    onTracingEvent(event: TracingEvent): void | Promise<void>;
     /**
      * Export a tracing event
      *

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,EACV,YAAY,EACZ,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAEpC;;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;IAC1D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;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,oDAAoD;IACpD,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAKlD,uCAAuC;IACvC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;gBACS,MAAM,GAAE,kBAAuB;IAQ3C;;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;;;;;;;;;OASG;cACa,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAoB9E;;;;;;OAMG;IACG,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D;;;;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;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;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,EACV,YAAY,EACZ,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAEpC;;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;IAC1D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;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,oDAAoD;IACpD,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAKlD,uCAAuC;IACvC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;gBACS,MAAM,GAAE,kBAAuB;IAQ3C;;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;;;;;;;;;OASG;cACa,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAoB9E;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;;;;;OAMG;IACG,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D;;;;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;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/exporters/index.d.ts

@@ -8,5 +8,4 @@ export * from './cloud.js';
 export * from './console.js';
 export * from './default.js';
 export * from './test.js';
-export * from './json.js';
 //# sourceMappingURL=index.d.ts.map

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;AACvB,cAAc,YAAY,CAAC;AAG3B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,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,mBAAmB,CAAC;AAGlC,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC"}