@mastra/observability 1.2.1 → 1.3.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @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

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"}