@mastra/observability 1.8.0-alpha.1 → 1.9.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @mastra/observability
 
+## 1.9.0-alpha.0
+
+### Minor Changes
+
+- Added support for project-scoped CloudExporter collector routes for organization API keys. ([#15189](https://github.com/mastra-ai/mastra/pull/15189))
+
+  **What changed**
+  CloudExporter now accepts a `projectId` option and reads `MASTRA_PROJECT_ID` so remote writes can target project-scoped collector URLs when you authenticate with an organization API key.
+
+  ```ts
+  new CloudExporter({
+    accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
+    projectId: process.env.MASTRA_PROJECT_ID,
+  });
+  ```
+
+  When `projectId` is set, base endpoints resolve to `/projects/:projectId/ai/{signal}/publish`. Without it, existing JWT-style `/ai/{signal}/publish` routes still work as before.
+
+### Patch Changes
+
+- Updated dependencies [[`ef94400`](https://github.com/mastra-ai/mastra/commit/ef9440049402596b31f2ab976c5e4508f6cb6c91)]:
+  - @mastra/core@1.24.1-alpha.0
+
+## 1.8.0
+
+### Minor Changes
+
+- Added CloudExporter support for Mastra Observability logs, metrics, scores, and feedback. ([#15124](https://github.com/mastra-ai/mastra/pull/15124))
+
+  CloudExporter now batches and uploads all Mastra Observability signals to Mastra Cloud, not just tracing spans.
+
+  This includes a breaking change to the CloudExporter endpoint format. We now pass a base endpoint URL and let let the exporter derive the standard publish paths automatically.
+
+  ```ts
+  import { CloudExporter, Observability } from '@mastra/observability';
+
+  const observability = new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-app',
+        exporters: [
+          new CloudExporter({
+            endpoint: 'https://collector.example.com',
+          }),
+        ],
+      },
+    },
+  });
+
+  // Traces, logs, metrics, scores, and feedback now all publish through CloudExporter.
+  ```
+
+  After updating the exporter endpoint config, the exporter will continue to work for traces, and the same exporter will now also publish structured logs, auto-extracted metrics, scores, and feedback records.
+
+- Added `excludeSpanTypes` and `spanFilter` options to `ObservabilityInstanceConfig` for selectively filtering spans before export. Use `excludeSpanTypes` to drop entire categories of spans by type (e.g., `MODEL_CHUNK`, `MODEL_STEP`) or `spanFilter` for fine-grained predicate-based filtering by attributes, metadata, entity, or any combination. Both options help reduce noise and costs in observability platforms that charge per-span. ([#15131](https://github.com/mastra-ai/mastra/pull/15131))
+
+  **`excludeSpanTypes` example:**
+
+  ```ts
+  excludeSpanTypes: [SpanType.MODEL_CHUNK, SpanType.MODEL_STEP, SpanType.WORKFLOW_SLEEP];
+  ```
+
+  **`spanFilter` example:**
+
+  ```ts
+  spanFilter: span => {
+    if (span.type === SpanType.MODEL_CHUNK) return false;
+    if (span.type === SpanType.TOOL_CALL && span.attributes?.success) return false;
+    return true;
+  };
+  ```
+
+  Resolves https://github.com/mastra-ai/mastra/issues/12710
+
+### Patch Changes
+
+- ObservabilityBus now honors per-instance `serializationOptions` (maxStringLength, maxDepth, maxArrayLength, maxObjectKeys) when deep-cleaning log/metric/score/feedback payloads, matching the behavior of tracing spans. Previously these signals always used the built-in defaults regardless of user configuration. ([#15138](https://github.com/mastra-ai/mastra/pull/15138))
+
+- Apply `deepClean()` to all observability signals (logs, metrics, scores, feedback) before fanning out to exporters and bridges. Previously only tracing spans were deep-cleaned at construction time, leaving free-form payload fields on other signals (e.g. `log.data`, `log.metadata`, `metric.metadata`, `metric.costContext.costMetadata`, `score.metadata`, `feedback.metadata`) susceptible to circular references, oversized strings, and other non-serializable values. Sanitization now happens centrally in `ObservabilityBus.emit()` so every signal leaving the bus is bounded and JSON-safe. ([#15135](https://github.com/mastra-ai/mastra/pull/15135))
+
+- `deepClean()` now preserves data for `Map`, `Set`, and richer `Error` objects. Previously Maps and Sets were serialized as empty `{}` (entries silently dropped) and Errors only kept `name`/`message`. Maps are now converted to plain objects of entries, Sets to arrays (both respecting `maxObjectKeys`/`maxArrayLength` and cycle detection), and Errors additionally preserve `stack` and recursively cleaned `cause`. ([#15136](https://github.com/mastra-ai/mastra/pull/15136))
+
+- Updated dependencies [[`8db7663`](https://github.com/mastra-ai/mastra/commit/8db7663c9a9c735828094c359d2e327fd4f8fba3), [`153e864`](https://github.com/mastra-ai/mastra/commit/153e86476b425db7cd0dc8490050096e92964a38), [`715710d`](https://github.com/mastra-ai/mastra/commit/715710d12fa47cf88e09d41f13843eddc29327b0), [`378c6c4`](https://github.com/mastra-ai/mastra/commit/378c6c4755726e8d8cf83a14809b350b90d46c62), [`9f91fd5`](https://github.com/mastra-ai/mastra/commit/9f91fd538ab2a44f8cc740bcad8e51205f74fbea), [`ba6fa9c`](https://github.com/mastra-ai/mastra/commit/ba6fa9cc0f3e1912c49fd70d4c3bb8c44903ddaa)]:
+  - @mastra/core@1.24.0
+
 ## 1.8.0-alpha.1
 
 ### Minor Changes

package/dist/exporters/cloud.d.ts

@@ -6,6 +6,7 @@ export interface CloudExporterConfig extends BaseExporterConfig {
     maxBatchWaitMs?: number;
     maxRetries?: number;
     accessToken?: string;
+    projectId?: string;
     endpoint?: string;
     tracesEndpoint?: string;
     logsEndpoint?: string;
@@ -15,7 +16,7 @@ export interface CloudExporterConfig extends BaseExporterConfig {
 }
 export declare class CloudExporter extends BaseExporter {
     name: string;
-    private cloudConfig;
+    private readonly cloudConfig;
     private buffer;
     private flushTimer;
     private inFlightFlushes;

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

@@ -1 +1 @@
-{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../src/exporters/cloud.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EAEZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,aAAa,EACd,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAgLD,qBAAa,aAAc,SAAQ,YAAY;IAC7C,IAAI,SAAyC;IAE7C,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,eAAe,CAA4B;gBAEvC,MAAM,GAAE,mBAAwB;cA0D5B,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjE,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1C,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,cAAc;YAMR,mBAAmB;IAYjC,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,aAAa;YAoBP,WAAW;IAoDzB;;OAEG;YACW,WAAW;YAuBX,gBAAgB;IA+B9B,OAAO,CAAC,WAAW;IAUnB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAiChC"}
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../src/exporters/cloud.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EAEZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,aAAa,EACd,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA+LD,qBAAa,aAAc,SAAQ,YAAY;IAC7C,IAAI,SAAyC;IAE7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,eAAe,CAA4B;gBAEvC,MAAM,GAAE,mBAAwB;cAgE5B,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjE,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1C,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,cAAc;YAMR,mBAAmB;IAYjC,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,aAAa;YAoBP,WAAW;IAoDzB;;OAEG;YACW,WAAW;YAuBX,gBAAgB;IA+B9B,OAAO,CAAC,WAAW;IAUnB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAiChC"}

package/dist/index.cjs

@@ -15051,14 +15051,7 @@ var SIGNAL_PUBLISH_SUFFIXES = {
   scores: "/scores/publish",
   feedback: "/feedback/publish"
 };
-var SIGNAL_PUBLISH_PATHS = {
-  traces: "/ai/spans/publish",
-  logs: "/ai/logs/publish",
-  metrics: "/ai/metrics/publish",
-  scores: "/ai/scores/publish",
-  feedback: "/ai/feedback/publish"
-};
-var SIGNAL_PAYLOAD_KEYS = {
+var SIGNAL_PUBLISH_SEGMENTS = {
   traces: "spans",
   logs: "logs",
   metrics: "metrics",
@@ -15087,6 +15080,18 @@ function createInvalidEndpointError(endpoint, text, cause) {
     cause
   );
 }
+var VALID_PROJECT_ID = /^[a-zA-Z0-9_-]+$/;
+function createInvalidProjectIdError(projectId) {
+  return new error$1.MastraError({
+    id: `CLOUD_EXPORTER_INVALID_PROJECT_ID`,
+    text: "CloudExporter projectId must only contain letters, numbers, hyphens, and underscores.",
+    domain: error$1.ErrorDomain.MASTRA_OBSERVABILITY,
+    category: error$1.ErrorCategory.USER,
+    details: {
+      projectId
+    }
+  });
+}
 function resolveBaseEndpoint(baseEndpoint) {
   const normalizedEndpoint = trimTrailingSlashes(baseEndpoint);
   const invalidText = 'CloudExporter endpoint must be a base origin like "https://collector.example.com" with no path, search, or hash.';
@@ -15103,10 +15108,17 @@ function resolveBaseEndpoint(baseEndpoint) {
     throw createInvalidEndpointError(baseEndpoint, invalidText, error48);
   }
 }
-function buildSignalEndpoint(baseEndpoint, signal) {
-  return `${baseEndpoint}${SIGNAL_PUBLISH_PATHS[signal]}`;
+function buildSignalPath(signal, projectId) {
+  const signalSegment = SIGNAL_PUBLISH_SEGMENTS[signal];
+  if (!projectId) {
+    return `/ai/${signalSegment}/publish`;
+  }
+  return `/projects/${projectId}/ai/${signalSegment}/publish`;
+}
+function buildSignalEndpoint(baseEndpoint, signal, projectId) {
+  return `${baseEndpoint}${buildSignalPath(signal, projectId)}`;
 }
-function resolveExplicitSignalEndpoint(signal, endpoint) {
+function resolveExplicitSignalEndpoint(signal, endpoint, projectId) {
   const normalizedEndpoint = trimTrailingSlashes(endpoint);
   const invalidText = `CloudExporter ${signal}Endpoint must be a base origin like "https://collector.example.com" or a full ${signal} publish URL ending in "${SIGNAL_PUBLISH_SUFFIXES[signal]}".`;
   try {
@@ -15117,7 +15129,7 @@ function resolveExplicitSignalEndpoint(signal, endpoint) {
     const normalizedOrigin = trimTrailingSlashes(parsedEndpoint.origin);
     const normalizedPathname = trimTrailingSlashes(parsedEndpoint.pathname);
     if (!normalizedPathname || normalizedPathname === "/") {
-      return buildSignalEndpoint(normalizedOrigin, signal);
+      return buildSignalEndpoint(normalizedOrigin, signal, projectId);
     }
     if (normalizedPathname.endsWith(SIGNAL_PUBLISH_SUFFIXES[signal])) {
       return `${normalizedOrigin}${normalizedPathname}`;
@@ -15160,7 +15172,12 @@ var CloudExporter = class extends BaseExporter {
   inFlightFlushes = /* @__PURE__ */ new Set();
   constructor(config2 = {}) {
     super(config2);
+    if (config2.projectId !== void 0 && !VALID_PROJECT_ID.test(config2.projectId)) {
+      throw createInvalidProjectIdError(config2.projectId);
+    }
     const accessToken = config2.accessToken ?? process.env.MASTRA_CLOUD_ACCESS_TOKEN;
+    const rawProjectId = config2.projectId ?? process.env.MASTRA_PROJECT_ID;
+    const projectId = rawProjectId && VALID_PROJECT_ID.test(rawProjectId) ? rawProjectId : void 0;
     if (!accessToken) {
       this.setDisabled("MASTRA_CLOUD_ACCESS_TOKEN environment variable not set.");
     }
@@ -15168,19 +15185,19 @@ var CloudExporter = class extends BaseExporter {
     let baseEndpoint;
     let tracesEndpoint;
     if (tracesEndpointOverride) {
-      tracesEndpoint = resolveExplicitSignalEndpoint("traces", tracesEndpointOverride);
+      tracesEndpoint = resolveExplicitSignalEndpoint("traces", tracesEndpointOverride, projectId);
     } else {
       baseEndpoint = resolveBaseEndpoint(config2.endpoint ?? DEFAULT_CLOUD_ENDPOINT);
-      tracesEndpoint = buildSignalEndpoint(baseEndpoint, "traces");
+      tracesEndpoint = buildSignalEndpoint(baseEndpoint, "traces", projectId);
     }
     const resolveConfiguredSignalEndpoint = (signal, explicitEndpoint) => {
       if (explicitEndpoint) {
-        return resolveExplicitSignalEndpoint(signal, explicitEndpoint);
+        return resolveExplicitSignalEndpoint(signal, explicitEndpoint, projectId);
       }
       if (tracesEndpointOverride) {
         return deriveSignalEndpointFromTracesEndpoint(signal, tracesEndpoint);
       }
-      return buildSignalEndpoint(baseEndpoint, signal);
+      return buildSignalEndpoint(baseEndpoint, signal, projectId);
     };
     this.cloudConfig = {
       logger: this.logger,
@@ -15404,7 +15421,7 @@ var CloudExporter = class extends BaseExporter {
     const options = {
       method: "POST",
       headers,
-      body: JSON.stringify({ [SIGNAL_PAYLOAD_KEYS[signal]]: records })
+      body: JSON.stringify({ [SIGNAL_PUBLISH_SEGMENTS[signal]]: records })
     };
     await utils.fetchWithRetry(endpointMap[signal], options, this.cloudConfig.maxRetries);
   }