@mastra/observability 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @mastra/observability
 
+## 1.9.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), [`3db852b`](https://github.com/mastra-ai/mastra/commit/3db852bff74e29f60d415a7b0f1583d6ce2bad92)]:
+  - @mastra/core@1.24.1
+
+## 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

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);
   }