@mastra/observability 1.17.5-alpha.0 → 1.17.5-alpha.2

package/README.md

@@ -1,6 +1,6 @@
-# Mastra Observability
+# @mastra/observability
 
-Tracing, metrics, and structured logging for AI operations in Mastra.
+Monitor Mastra agents, workflows, tools, and model calls with hierarchical traces, automatically extracted metrics, and structured logs correlated to the active trace.
 
 ## Installation
 
@@ -8,7 +8,7 @@ Tracing, metrics, and structured logging for AI operations in Mastra.
 npm install @mastra/observability
 ```
 
-## Quick Start
+## Usage
 
 ```typescript
 import { Mastra } from '@mastra/core';
@@ -19,100 +19,29 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [
-          new MastraStorageExporter(), // Persists observability events to Mastra Storage
-          new MastraPlatformExporter(), // Sends observability events to Mastra Platform
-        ],
+        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
       },
     },
   }),
 });
 ```
 
-A `SensitiveDataFilter` span output processor is auto-applied to every configured instance by default, redacting secrets (API keys, tokens, passwords, etc.) before they reach exporters. Set `sensitiveDataFilter: false` on the `Observability` config to opt out, or pass a `SensitiveDataFilterOptions` object to customize it.
-
-## Features
-
-- **Auto-instrumentation** - Traces agent runs, LLM calls, tool executions, and workflows
-- **Pluggable Exporters** - Exporters for Studio, 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
-
-## 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_duration_ms`
-- `mastra_tool_duration_ms`
-- `mastra_workflow_duration_ms`
-- `mastra_model_duration_ms`
-- `mastra_model_total_input_tokens` / `mastra_model_total_output_tokens`
-- `mastra_model_input_text_tokens` / `mastra_model_input_cache_read_tokens` / `mastra_model_input_cache_write_tokens` / `mastra_model_input_cache_write_5m_tokens` / `mastra_model_input_cache_write_1h_tokens` / `mastra_model_input_audio_tokens` / `mastra_model_input_image_tokens`
-- `mastra_model_output_text_tokens` / `mastra_model_output_reasoning_tokens` / `mastra_model_output_audio_tokens` / `mastra_model_output_image_tokens`
-
-For Anthropic models, the aggregate cache-write metric remains available while the 5-minute and 1-hour metrics preserve the provider's TTL-specific token counts and pricing.
-
-Auto-extracted metrics carry labels: `entity_type`, `entity_name`, `status`, 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
-- `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
-
-## Metrics Labels
+## Documentation
 
-### Auto-extracted metric labels
+`Observability` instruments agent runs, model generations, tool and MCP calls, processor execution, workflow runs, and workflow steps. Each configured observability instance has its own service name, exporters, sampling strategy, and span processors.
 
-| 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                    |
+Exporters receive tracing events through the central observability bus. `MastraStorageExporter` persists them to the configured Mastra storage so Studio can query them, while `MastraPlatformExporter` sends them to Mastra Platform. Additional packages provide exporters for services such as Arize, Braintrust, Langfuse, LangSmith, Sentry, and OpenTelemetry-compatible backends.
 
-### User-emitted metric labels (via MetricsContext)
+A `SensitiveDataFilter` output processor is enabled by default and redacts common secrets before spans reach exporters. Set `sensitiveDataFilter: false` to disable it, or provide filter options to customize its behavior. Sampling can retain every trace, use a ratio, or apply application-specific logic.
 
-User-emitted metrics inherit additional context labels from the active span:
+The package automatically derives duration, status, model token, and cache token metrics from span lifecycle events. Structured logs inherit trace and span IDs, tags, and entity metadata, while metric labels pass through cardinality filtering to prevent user IDs, trace IDs, and other unbounded values from overwhelming metrics backends.
 
-| 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 |
+- [Observability documentation](https://mastra.ai/docs/studio/observability)
 
-### Common query patterns
+## Changelog
 
-- **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`
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/observability/mastra/CHANGELOG.md) for version history and release notes.
 
-## Documentation
+## Support
 
-For configuration options, exporters, sampling strategies, and more, see the [full documentation](https://mastra.ai/docs/v1/observability/overview).
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

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

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/context/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAyB,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE/C,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC,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;IACH,YAAY,MAAM,EAAE,mBAAmB,EAUtC;IAED,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED,yBAAyB;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;IAED,yBAAyB;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;IAED,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED;;OAEG;IACH,OAAO,CAAC,GAAG;CAqBZ"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/context/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAyB,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAG/C,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC,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;IACH,YAAY,MAAM,EAAE,mBAAmB,EAUtC;IAED,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED,yBAAyB;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;IAED,yBAAyB;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;IAED,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED;;OAEG;IACH,OAAO,CAAC,GAAG;CAqBZ"}

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

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/context/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EACP,KAAK,EACL,SAAS,EACT,kBAAkB,EAIlB,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,0DAA0D;IAC1D,iBAAiB,EAAE,iBAAiB,CAAC;IAErC,6BAA6B;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,kBAAkB,CAAC,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,CAA0B;IAC3C,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,gBAAgB,CAAmB;IAE3C;;;OAGG;IACH,YAAY,MAAM,EAAE,oBAAoB,EAOvC;IAED,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAuBpG;IAED,wCAAwC;IACxC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM7B;IAED,wCAAwC;IACxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAMzB;IAED,wCAAwC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAMjC;CACF"}
+{"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,EACT,kBAAkB,EAIlB,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IAExC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,0DAA0D;IAC1D,iBAAiB,EAAE,iBAAiB,CAAC;IAErC,6BAA6B;IAC7B,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,kBAAkB,CAAC,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,CAA0B;IAC3C,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,gBAAgB,CAAmB;IAE3C;;;OAGG;IACH,YAAY,MAAM,EAAE,oBAAoB,EAOvC;IAED,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAuBpG;IAED,wCAAwC;IACxC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM7B;IAED,wCAAwC;IACxC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAMzB;IAED,wCAAwC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAMjC;CACF"}

package/dist/ids.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Signal and span id helpers.
+ *
+ * These two utilities also exist in `@mastra/core/observability`. This package
+ * deliberately keeps local copies rather than importing them.
+ *
+ * Importing a helper from core ties this package's real minimum core version to
+ * whichever release happened to add that helper. A named ESM import of an export
+ * that does not exist fails at link time, before any application code runs, so
+ * the mismatch surfaces as a startup crash rather than a resolvable install
+ * error. That is how `resolveExportedSpanId` (added in `@mastra/core@1.63.0`)
+ * broke deployments pinned to an older core while the declared peer floor still
+ * said `>=1.16.0`; `generateSignalId` (added in `@mastra/core@1.26.0`) had
+ * already raised the true floor the same way, unnoticed.
+ *
+ * Both helpers are self-contained: `generateSignalId` wraps `crypto.randomUUID`,
+ * and `resolveExportedSpanId` is structurally typed against an optional method
+ * rather than any core class. A local copy costs a few lines and lets the
+ * declared peer range stay honest.
+ *
+ * Keep them local. Re-importing either from core silently raises this package's
+ * minimum core version again.
+ *
+ * TODO(mastra-v2): delete this file and import both helpers from
+ * `@mastra/core/observability` again.
+ *
+ * The duplication exists only because a peer floor cannot be raised inside a
+ * major version without breaking consumers pinned to an older core. A v2
+ * release resets that floor anyway, so importing from core stops being a
+ * compatibility hazard at that point. On v2:
+ *
+ *   1. Set the `@mastra/core` peer range to the v2 line.
+ *   2. Re-point the four import sites -- `generateSignalId` in
+ *      `context/logger.ts`, `context/metrics.ts` and `recorded.ts`, and
+ *      `resolveExportedSpanId` in `instances/base.ts`.
+ *   3. Delete this file.
+ *
+ * Do not undo it before then: both helpers are still missing from cores inside
+ * this package's currently declared range (`generateSignalId` landed in core
+ * 1.26.0, `resolveExportedSpanId` in 1.63.0, floor is 1.16.0).
+ *
+ * Context: https://github.com/mastra-ai/mastra/issues/22885
+ */
+/** Generate a unique id for an observability signal (log, metric, score, feedback). */
+export declare function generateSignalId(): string;
+/**
+ * Resolve the spanId an observability signal should reference for a span.
+ *
+ * Signals (logs, metrics, and a suspending run's resume link) must name a span
+ * that actually reached exporters. An internal or excluded span is never stored,
+ * so referencing its raw id leaves the signal pointing at nothing: log/metric
+ * span lookups 404, and a resumed run's exported children inherit a dangling
+ * parentSpanId and land as orphans. `undefined` is a valid answer, omitting the
+ * reference rather than pointing it at a span that does not exist.
+ *
+ * `getExportedSpanId` is optional on the `Span` interface, so the typeof guard
+ * separates "this implementation predates the method" (keep the old behavior of
+ * referencing the span's own id) from "the method ran and found nothing
+ * exportable" (undefined). Without it the two collapse and custom span
+ * implementations silently lose correlation.
+ */
+export declare function resolveExportedSpanId(span: {
+    id?: string;
+    getExportedSpanId?: () => string | undefined;
+} | undefined | null): string | undefined;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,uFAAuF;AACvF,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,GACrF,MAAM,GAAG,SAAS,CAGpB"}

package/dist/index.cjs

@@ -35,7 +35,7 @@ path = __toESM(path, 1);
 let stream_web = require("stream/web");
 let _mastra_core_features = require("@mastra/core/features");
 let _mastra_core_storage = require("@mastra/core/storage");
-let crypto = require("crypto");
+let crypto$1 = require("crypto");
 //#region src/bus/route-event.ts
 /**
 * Route a single event to the appropriate method on a handler.
@@ -887,13 +887,76 @@ const observabilityRegistryConfigSchema = zod_v4.z.object({
 	return true;
 }, { message: "A \"configSelector\" requires at least one config or default observability to be configured." });
 //#endregion
-//#region src/context/logger.ts
+//#region src/ids.ts
+/**
+* Signal and span id helpers.
+*
+* These two utilities also exist in `@mastra/core/observability`. This package
+* deliberately keeps local copies rather than importing them.
+*
+* Importing a helper from core ties this package's real minimum core version to
+* whichever release happened to add that helper. A named ESM import of an export
+* that does not exist fails at link time, before any application code runs, so
+* the mismatch surfaces as a startup crash rather than a resolvable install
+* error. That is how `resolveExportedSpanId` (added in `@mastra/core@1.63.0`)
+* broke deployments pinned to an older core while the declared peer floor still
+* said `>=1.16.0`; `generateSignalId` (added in `@mastra/core@1.26.0`) had
+* already raised the true floor the same way, unnoticed.
+*
+* Both helpers are self-contained: `generateSignalId` wraps `crypto.randomUUID`,
+* and `resolveExportedSpanId` is structurally typed against an optional method
+* rather than any core class. A local copy costs a few lines and lets the
+* declared peer range stay honest.
+*
+* Keep them local. Re-importing either from core silently raises this package's
+* minimum core version again.
+*
+* TODO(mastra-v2): delete this file and import both helpers from
+* `@mastra/core/observability` again.
+*
+* The duplication exists only because a peer floor cannot be raised inside a
+* major version without breaking consumers pinned to an older core. A v2
+* release resets that floor anyway, so importing from core stops being a
+* compatibility hazard at that point. On v2:
+*
+*   1. Set the `@mastra/core` peer range to the v2 line.
+*   2. Re-point the four import sites -- `generateSignalId` in
+*      `context/logger.ts`, `context/metrics.ts` and `recorded.ts`, and
+*      `resolveExportedSpanId` in `instances/base.ts`.
+*   3. Delete this file.
+*
+* Do not undo it before then: both helpers are still missing from cores inside
+* this package's currently declared range (`generateSignalId` landed in core
+* 1.26.0, `resolveExportedSpanId` in 1.63.0, floor is 1.16.0).
+*
+* Context: https://github.com/mastra-ai/mastra/issues/22885
+*/
+/** Generate a unique id for an observability signal (log, metric, score, feedback). */
+function generateSignalId() {
+	return crypto.randomUUID();
+}
 /**
-* LoggerContextImpl - Structured logging with automatic trace correlation.
+* Resolve the spanId an observability signal should reference for a span.
 *
-* Emits LogEvent to the ObservabilityBus. All context (correlationContext,
-* metadata) is snapshotted at construction time.
+* Signals (logs, metrics, and a suspending run's resume link) must name a span
+* that actually reached exporters. An internal or excluded span is never stored,
+* so referencing its raw id leaves the signal pointing at nothing: log/metric
+* span lookups 404, and a resumed run's exported children inherit a dangling
+* parentSpanId and land as orphans. `undefined` is a valid answer, omitting the
+* reference rather than pointing it at a span that does not exist.
+*
+* `getExportedSpanId` is optional on the `Span` interface, so the typeof guard
+* separates "this implementation predates the method" (keep the old behavior of
+* referencing the span's own id) from "the method ran and found nothing
+* exportable" (undefined). Without it the two collapse and custom span
+* implementations silently lose correlation.
 */
+function resolveExportedSpanId(span) {
+	if (!span) return void 0;
+	return typeof span.getExportedSpanId === "function" ? span.getExportedSpanId() : span.id;
+}
+//#endregion
+//#region src/context/logger.ts
 /** Numeric priority used to compare log levels against the configured minimum. */
 const LOG_LEVEL_PRIORITY = {
 	debug: 0,
@@ -947,7 +1010,7 @@ var LoggerContextImpl = class {
 		const event = {
 			type: "log",
 			log: {
-				logId: (0, _mastra_core_observability.generateSignalId)(),
+				logId: generateSignalId(),
 				timestamp: /* @__PURE__ */ new Date(),
 				level,
 				message,
@@ -964,13 +1027,6 @@ var LoggerContextImpl = class {
 //#endregion
 //#region src/context/metrics.ts
 /**
-* MetricsContextImpl - User-facing metric emission API.
-*
-* All metrics are validated, cardinality-filtered, and constructed here
-* before being routed through ObservabilityBus.emit().
-* CorrelationContext and metadata are snapshotted at construction time.
-*/
-/**
 * User-facing metric emission API. All metrics are routed through
 * ObservabilityBus.emit() after validation and cardinality filtering.
 */
@@ -1001,7 +1057,7 @@ var MetricsContextImpl = class {
 		const event = {
 			type: "metric",
 			metric: {
-				metricId: (0, _mastra_core_observability.generateSignalId)(),
+				metricId: generateSignalId(),
 				timestamp: /* @__PURE__ */ new Date(),
 				traceId: this.traceId,
 				spanId: this.spanId,
@@ -3482,7 +3538,7 @@ var BaseObservabilityInstance = class extends _mastra_core_base.MastraBase {
 		const metadata = span?.metadata ? structuredClone(span.metadata) : void 0;
 		return new LoggerContextImpl({
 			traceId: span?.traceId,
-			spanId: (0, _mastra_core_observability.resolveExportedSpanId)(span),
+			spanId: resolveExportedSpanId(span),
 			correlationContext,
 			metadata,
 			observabilityBus: this.observabilityBus,
@@ -3499,7 +3555,7 @@ var BaseObservabilityInstance = class extends _mastra_core_base.MastraBase {
 		const metadata = span?.metadata ? structuredClone(span.metadata) : void 0;
 		return new MetricsContextImpl({
 			traceId: span?.traceId,
-			spanId: (0, _mastra_core_observability.resolveExportedSpanId)(span),
+			spanId: resolveExportedSpanId(span),
 			correlationContext,
 			metadata,
 			cardinalityFilter: this.cardinalityFilter,
@@ -8695,7 +8751,7 @@ function buildScoreEvent(args) {
 	return {
 		type: "score",
 		score: {
-			scoreId: (0, _mastra_core_observability.generateSignalId)(),
+			scoreId: generateSignalId(),
 			timestamp: /* @__PURE__ */ new Date(),
 			traceId,
 			spanId,
@@ -8719,7 +8775,7 @@ function buildFeedbackEvent(args) {
 	return {
 		type: "feedback",
 		feedback: {
-			feedbackId: (0, _mastra_core_observability.generateSignalId)(),
+			feedbackId: generateSignalId(),
 			timestamp: /* @__PURE__ */ new Date(),
 			traceId,
 			spanId,
@@ -9214,7 +9270,7 @@ var SensitiveDataFilter = class {
 			return str.slice(0, 3) + "…" + str.slice(len - 3);
 		}
 		if (this.redactionStyle === "indexed" && indexedState) {
-			const valueKey = (0, crypto.createHash)("sha256").update(String(value)).digest("hex");
+			const valueKey = (0, crypto$1.createHash)("sha256").update(String(value)).digest("hex");
 			const existing = indexedState.tokensByValue.get(valueKey);
 			if (existing) return existing;
 			if (indexedState.tokensByValue.size >= MAX_TRACKED_VALUES_PER_TRACE) return this.redactionToken;