release(docs): Mastra v1 integration

src/pages/docs/integrations/traceai/mastra.mdx

@@ -1,58 +1,119 @@
 ---
 title: "Mastra Integration with Future AGI TypeScript Agent Tracing"
 description: "Integrate Mastra with Future AGI for TypeScript agent observability. Configure trace export using the @traceai/mastra package for LLM monitoring."
 ---
 
+Integrate Future AGI observability into your [Mastra](https://mastra.ai) agents and
+workflows. Every agent run, tool call, and LLM interaction is exported to Future AGI
+for monitoring, evaluation, and debugging.
+
+<Note>
+This guide targets **Mastra v1** (`@mastra/core` &ge; 1.16). Mastra v1 removed the old
+`telemetry:` config key, so the previous `FITraceExporter` setup no longer exports any
+spans. Use `createFIObservability` from `@traceai/mastra` as shown below. Still on
+Mastra v0.x? See [Legacy (Mastra v0.x)](#legacy-mastra-v0x) at the bottom.
+</Note>
+
 ## 1. Installation
-First install the Mastra and traceAI packages.
+Install Mastra's observability packages, the OTLP/protobuf exporter, and `@traceai/mastra`.
 
 ```bash JS/TS
-npm install @mastra/core @traceai/mastra @traceai/fi-core
+npm install @mastra/core @mastra/observability @mastra/otel-exporter \
+            @opentelemetry/exporter-trace-otlp-proto @traceai/mastra
 ```
 
 ---
 
 ## 2. Set Environment Variables
 
-Configure your Future AGI credentials.
+Add your Future AGI credentials to your `.env`. `@traceai/mastra` reads them automatically.
 
-```typescript JS/TS
-process.env.FI_API_KEY = "your-futureagi-api-key";
-process.env.FI_SECRET_KEY = "your-futureagi-secret-key";
+```bash .env
+FI_API_KEY=your-futureagi-api-key
+FI_SECRET_KEY=your-futureagi-secret-key
 ```
 
 ---
 
-## 3. Configure Mastra Telemetry Export
-Use the custom exporter from `@traceai/mastra` to send traces to Future AGI. You can optionally filter out non-LLM spans using `isFISpan`.
+## 3. Configure Observability
+Wire Future AGI into your Mastra instance with `createFIObservability`. It points the
+exporter at Future AGI's collector, authenticates with your keys, and exports traces only
+(Future AGI's collector does not accept the OTLP logs signal).
 
 ```typescript JS/TS
 import { Mastra } from "@mastra/core";
-import { FITraceExporter, isFISpan } from "@traceai/mastra";
+import { createFIObservability } from "@traceai/mastra";
 
 export const mastra = new Mastra({
-  // ... other config
-  telemetry: {
-    serviceName: "traceai-mastra-agent", // customize the service name
-    enabled: true,
-    export: {
-      type: "custom",
-      exporter: new FITraceExporter({
-        url: "https://app.futureagi.com/tracer/v1/traces",
-        headers: {
-          "x-api-key": process.env.FI_API_KEY as string,
-          "x-secret-key": process.env.FI_SECRET_KEY as string,
-        },
-        // Optional: filter out non-LLM/node spans from being sent to Future AGI
-        spanFilter: isFISpan,
-      }),
-    },
-  },
+  // ... your agents, workflows, etc.
+  observability: createFIObservability({
+    serviceName: "traceai-mastra-agent", // appears in the Future AGI trace list
+  }),
 });
 ```
 
+No changes are needed to your agent code. Every span is mapped to OpenTelemetry
+`gen_ai.*` conventions, given the right span kind (LLM / agent / tool / chain), and
+its input/output is captured — so the trace renders fully in Future AGI.
+
 ---
 
 ## 4. Run your Agent
-Once configured, run your Mastra agent as usual. The exporter will automatically send trace data to your Future AGI project.
+Run your Mastra agent as usual. Traces appear in your Future AGI project under
+**Observability** (service `traceai-mastra-agent`).
+
+```typescript JS/TS
+const agent = mastra.getAgent("yourAgent");
+const result = await agent.generate("What's the weather in Bangalore?");
+```
+
+<Note>
+**Short-lived scripts & serverless.** Spans are batched, so a process that exits
+immediately may drop them. Keep a reference to the observability instance and flush
+before exit:
+
+```typescript JS/TS
+export const observability = createFIObservability({ serviceName: "traceai-mastra-agent" });
+export const mastra = new Mastra({ observability /* , agents, ... */ });
+
+// at the end of your script / request handler:
+await observability.shutdown(); // flushes buffered spans
+```
+</Note>
+
+---
+
+## Configuration Options
+
+`createFIObservability(options)` accepts:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `serviceName` | `"mastra-app"` | Service name; also the default Future AGI **project** name. |
+| `projectName` | `serviceName` (or `FI_PROJECT_NAME`) | Future AGI project the traces are filed under. |
+| `projectType` | `"observe"` | `"observe"` for tracing, `"experiment"` for eval runs. |
+| `apiKey` | `process.env.FI_API_KEY` | Future AGI API key. |
+| `secretKey` | `process.env.FI_SECRET_KEY` | Future AGI secret key. |
+| `baseUrl` | `https://api.futureagi.com` | Collector base URL (`/tracer/v1/traces` is appended). |
+| `endpoint` | — | Full traces endpoint URL; overrides `baseUrl`. |
+| `headers` | — | Extra headers merged into the export request. |
+| `excludeSpanTypes` | `[MODEL_CHUNK]` | Mastra span types to drop before export (chunk spans are noise). |
+| `timeout` | `30000` | Export request timeout (ms). |
+| `batchSize` | — | Spans per batch. |
+
+If you need to compose the exporter into your own `Observability` config, use
+`createFIMastraExporter(options)` instead — it returns a pre-configured exporter you
+can drop into `new Observability({ configs: { otel: { exporters: [...] } } })`.
+
+---
+
+## Legacy (Mastra v0.x)
+
+The old `telemetry:` + `FITraceExporter` integration is deprecated and does **not** work
+on Mastra v1. If you are still on Mastra v0.x, import it from the `/legacy` subpath:
+
+```typescript JS/TS
+import { FITraceExporter, isFISpan } from "@traceai/mastra/legacy";
+```
 
+We recommend upgrading to Mastra v1 and the `createFIObservability` setup above.

src/pages/docs/tracing/auto/mastra.mdx

@@ -1,58 +1,119 @@
 ---
 title: "Mastra Tracing with Future AGI: Auto-Instrumentation"
 description: "Set up auto-instrumentation for Mastra with Future AGI tracing. Configure @traceai/mastra to export TypeScript agent spans to Future AGI."
 ---
 
+Auto-instrument your [Mastra](https://mastra.ai) agents and workflows with Future AGI.
+Every agent run, tool call, and LLM interaction is exported to Future AGI for monitoring,
+evaluation, and debugging — no manual span code required.
+
+<Note>
+This guide targets **Mastra v1** (`@mastra/core` &ge; 1.16). Mastra v1 removed the old
+`telemetry:` config key, so the previous `FITraceExporter` setup no longer exports any
+spans. Use `createFIObservability` from `@traceai/mastra` as shown below. Still on
+Mastra v0.x? See [Legacy (Mastra v0.x)](#legacy-mastra-v0x) at the bottom.
+</Note>
+
 ## 1. Installation
-First install the Mastra and traceAI packages.
+Install Mastra's observability packages, the OTLP/protobuf exporter, and `@traceai/mastra`.
 
 ```bash JS/TS
-npm install @mastra/core @traceai/mastra @traceai/fi-core
+npm install @mastra/core @mastra/observability @mastra/otel-exporter \
+            @opentelemetry/exporter-trace-otlp-proto @traceai/mastra
 ```
 
 ---
 
 ## 2. Set Environment Variables
 
-Configure your Future AGI credentials.
+Add your Future AGI credentials to your `.env`. `@traceai/mastra` reads them automatically.
 
-```typescript JS/TS
-process.env.FI_API_KEY = "your-futureagi-api-key";
-process.env.FI_SECRET_KEY = "your-futureagi-secret-key";
+```bash .env
+FI_API_KEY=your-futureagi-api-key
+FI_SECRET_KEY=your-futureagi-secret-key
 ```
 
 ---
 
-## 3. Configure Mastra Telemetry Export
-Use the custom exporter from `@traceai/mastra` to send traces to Future AGI. You can optionally filter out non-LLM spans using `isFISpan`.
+## 3. Configure Observability
+Wire Future AGI into your Mastra instance with `createFIObservability`. It points the
+exporter at Future AGI's collector, authenticates with your keys, and exports traces only
+(Future AGI's collector does not accept the OTLP logs signal).
 
 ```typescript JS/TS
 import { Mastra } from "@mastra/core";
-import { FITraceExporter, isFISpan } from "@traceai/mastra";
+import { createFIObservability } from "@traceai/mastra";
 
 export const mastra = new Mastra({
-  // ... other config
-  telemetry: {
-    serviceName: "traceai-mastra-agent", // customize the service name
-    enabled: true,
-    export: {
-      type: "custom",
-      exporter: new FITraceExporter({
-        url: "https://app.futureagi.com/tracer/v1/traces",
-        headers: {
-          "x-api-key": process.env.FI_API_KEY as string,
-          "x-secret-key": process.env.FI_SECRET_KEY as string,
-        },
-        // Optional: filter out non-LLM/node spans from being sent to Future AGI
-        spanFilter: isFISpan,
-      }),
-    },
-  },
+  // ... your agents, workflows, etc.
+  observability: createFIObservability({
+    serviceName: "traceai-mastra-agent", // appears in the Future AGI trace list
+  }),
 });
 ```
 
+No changes are needed to your agent code. Every span is mapped to OpenTelemetry
+`gen_ai.*` conventions, given the right span kind (LLM / agent / tool / chain), and
+its input/output is captured — so the trace renders fully in Future AGI.
+
 ---
 
 ## 4. Run your Agent
-Once configured, run your Mastra agent as usual. The exporter will automatically send trace data to your Future AGI project.
+Run your Mastra agent as usual. Traces appear in your Future AGI project under
+**Observability** (service `traceai-mastra-agent`).
+
+```typescript JS/TS
+const agent = mastra.getAgent("yourAgent");
+const result = await agent.generate("What's the weather in Bangalore?");
+```
+
+<Note>
+**Short-lived scripts & serverless.** Spans are batched, so a process that exits
+immediately may drop them. Keep a reference to the observability instance and flush
+before exit:
+
+```typescript JS/TS
+export const observability = createFIObservability({ serviceName: "traceai-mastra-agent" });
+export const mastra = new Mastra({ observability /* , agents, ... */ });
+
+// at the end of your script / request handler:
+await observability.shutdown(); // flushes buffered spans
+```
+</Note>
+
+---
+
+## Configuration Options
+
+`createFIObservability(options)` accepts:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `serviceName` | `"mastra-app"` | Service name; also the default Future AGI **project** name. |
+| `projectName` | `serviceName` (or `FI_PROJECT_NAME`) | Future AGI project the traces are filed under. |
+| `projectType` | `"observe"` | `"observe"` for tracing, `"experiment"` for eval runs. |
+| `apiKey` | `process.env.FI_API_KEY` | Future AGI API key. |
+| `secretKey` | `process.env.FI_SECRET_KEY` | Future AGI secret key. |
+| `baseUrl` | `https://api.futureagi.com` | Collector base URL (`/tracer/v1/traces` is appended). |
+| `endpoint` | — | Full traces endpoint URL; overrides `baseUrl`. |
+| `headers` | — | Extra headers merged into the export request. |
+| `excludeSpanTypes` | `[MODEL_CHUNK]` | Mastra span types to drop before export (chunk spans are noise). |
+| `timeout` | `30000` | Export request timeout (ms). |
+| `batchSize` | — | Spans per batch. |
+
+If you need to compose the exporter into your own `Observability` config, use
+`createFIMastraExporter(options)` instead — it returns a pre-configured exporter you
+can drop into `new Observability({ configs: { otel: { exporters: [...] } } })`.
+
+---
+
+## Legacy (Mastra v0.x)
+
+The old `telemetry:` + `FITraceExporter` integration is deprecated and does **not** work
+on Mastra v1. If you are still on Mastra v0.x, import it from the `/legacy` subpath:
+
+```typescript JS/TS
+import { FITraceExporter, isFISpan } from "@traceai/mastra/legacy";
+```
 
+We recommend upgrading to Mastra v1 and the `createFIObservability` setup above.