Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 88 additions & 27 deletions src/pages/docs/integrations/traceai/mastra.mdx
Original file line number Diff line number Diff line change
@@ -1,58 +1,119 @@
---
title: "Mastra Integration with Future AGI TypeScript Agent Tracing"

Check warning on line 2 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
description: "Integrate Mastra with Future AGI for TypeScript agent observability. Configure trace export using the @traceai/mastra package for LLM monitoring."

Check warning on line 3 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
---

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

Check warning on line 11 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?

Check warning on line 11 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
`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.

Check warning on line 14 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
</Note>

## 1. Installation
First install the Mastra and traceAI packages.
Install Mastra's observability packages, the OTLP/protobuf exporter, and `@traceai/mastra`.

Check warning on line 18 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra's'?

```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

Check warning on line 39 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
exporter at Future AGI's collector, authenticates with your keys, and exports traces only

Check warning on line 40 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'AGI's'?
(Future AGI's collector does not accept the OTLP logs signal).

Check warning on line 41 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'AGI's'?

```typescript JS/TS
import { Mastra } from "@mastra/core";

Check warning on line 44 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
import { FITraceExporter, isFISpan } from "@traceai/mastra";
import { createFIObservability } from "@traceai/mastra";

export const mastra = new Mastra({

Check warning on line 47 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean '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, ... */ });

Check warning on line 77 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?

// 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. |

Check warning on line 94 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'eval'?
| `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). |

Check warning on line 100 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
| `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)

Check warning on line 110 in src/pages/docs/integrations/traceai/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?

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.
115 changes: 88 additions & 27 deletions src/pages/docs/tracing/auto/mastra.mdx
Original file line number Diff line number Diff line change
@@ -1,58 +1,119 @@
---
title: "Mastra Tracing with Future AGI: Auto-Instrumentation"

Check warning on line 2 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
description: "Set up auto-instrumentation for Mastra with Future AGI tracing. Configure @traceai/mastra to export TypeScript agent spans to Future AGI."

Check warning on line 3 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
---

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

Check warning on line 11 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?

Check warning on line 11 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
`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.

Check warning on line 14 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
</Note>

## 1. Installation
First install the Mastra and traceAI packages.
Install Mastra's observability packages, the OTLP/protobuf exporter, and `@traceai/mastra`.

Check warning on line 18 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra's'?

```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

Check warning on line 39 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
exporter at Future AGI's collector, authenticates with your keys, and exports traces only

Check warning on line 40 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'AGI's'?
(Future AGI's collector does not accept the OTLP logs signal).

Check warning on line 41 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'AGI's'?

```typescript JS/TS
import { Mastra } from "@mastra/core";

Check warning on line 44 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
import { FITraceExporter, isFISpan } from "@traceai/mastra";
import { createFIObservability } from "@traceai/mastra";

export const mastra = new Mastra({

Check warning on line 47 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean '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, ... */ });

Check warning on line 77 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?

// 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. |

Check warning on line 94 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'eval'?
| `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). |

Check warning on line 100 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?
| `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)

Check warning on line 110 in src/pages/docs/tracing/auto/mastra.mdx

View check run for this annotation

Mintlify / Mintlify Validation (futureagi) - vale-spellcheck

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

Did you really mean 'Mastra'?

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.
Loading