Mastra Tracing with Future AGI: Auto-Instrumentation

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 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 ≥ 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) at the bottom.

1. Installation

Install Mastra’s observability packages, the OTLP/protobuf exporter, and @traceai/mastra.

npm install @mastra/core @mastra/observability @mastra/otel-exporter \
            @opentelemetry/exporter-trace-otlp-proto @traceai/mastra

2. Set Environment Variables

Add your Future AGI credentials to your .env. @traceai/mastra reads them automatically.

FI_API_KEY=your-futureagi-api-key
FI_SECRET_KEY=your-futureagi-secret-key

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

import { Mastra } from "@mastra/core";
import { createFIObservability } from "@traceai/mastra";

export const mastra = new Mastra({
  // ... 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

Run your Mastra agent as usual. Traces appear in your Future AGI project under Observability (service traceai-mastra-agent).

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:

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

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:

import { FITraceExporter, isFISpan } from "@traceai/mastra/legacy";

We recommend upgrading to Mastra v1 and the createFIObservability setup above.

Was this page helpful?

Questions & Discussion