Observability for Mastra With Litefuse

This guide shows you how to integrate Litefuse with Mastra for observability and tracing. By following these steps, you’ll be able to monitor and debug your Mastra agents in the Litefuse dashboard.

What is Mastra? Mastra is the TypeScript agent framework designed to provide the essential primitives for building AI applications. It enables developers to create AI agents with memory and tool-calling capabilities, implement deterministic LLM workflows, and leverage RAG for knowledge integration.

What is Litefuse? Litefuse is an open-source LLM engineering platform. It offers tracing and monitoring capabilities for AI applications.

Integration

Create a Mastra project

If you don’t have a Mastra project yet, you can create one using the Mastra CLI:

npx create-mastra

Move into the project directory:

cd your-mastra-project

You can get the full Mastra installation instructions here

Set up Litefuse project

Create a project in Litefuse and get your API keys from the project settings page.

Add environment variables

Create or update your .env.development (or .env) file with the following variables:

# Your LLM API key
OPENAI_API_KEY=your-api-key
 
# Langfuse credentials
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_BASE_URL=https://litefuse.cloud # Optional. Defaults to https://litefuse.cloud

Install the `@mastra/langfuse` package

Add the @mastra/langfuse package to your project:

npm install @mastra/langfuse

Set up an agent

Create an agent in your project. For example, create a file agents/chefAgent.ts:

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
export const chefAgent = new Agent({
  name: "chef-agent",
  instructions:
    "You are Michel, a practical and experienced home chef " +
    "You help people cook with whatever ingredients they have available.",
  model: openai("gpt-4o-mini"),
});

You can use any model provider from ai-sdk.

Register agent and configure Litefuse

Create or update your Mastra instance configuration to register the agent and configure Litefuse integration. For example, create a file mastra.ts:

import { Mastra } from "@mastra/core";
import { LangfuseExporter } from "@mastra/langfuse";
import { chefAgent } from "./agents/chefAgent";
 
export const mastra = new Mastra({
  agents: { chefAgent },
  observability: {
    configs: {
      langfuse: {
        serviceName: "my-service",
        exporters: [
          new LangfuseExporter({
            publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
            secretKey: process.env.LANGFUSE_SECRET_KEY!,
            baseUrl: process.env.LANGFUSE_BASE_URL,
            options: {
              environment: process.env.NODE_ENV,
            },
          }),
        ],
      },
    },
  },
});

Run mastra dev server

Start the Mastra development server:

npm run dev

Head over to the developer playground with the provided URL and start chatting with your agent.

View traces in Litefuse

Head over to your Litefuse dashboard and you’ll see the traces from your agent interactions. You can analyze the prompts, completions, and other details of your AI interactions.

Here’s an example of a trace:

Mastra trace in Litefuse UI

Configuration Options

Realtime vs Batch Mode

The Litefuse exporter supports two modes for sending traces:

Realtime (development): Flushes after each event for immediate visibility.

new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  realtime: true, // Flush after each event
})

Batch (production, default): Buffers and sends in batches for better throughput.

new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  realtime: false, // Default behavior
})

Complete Configuration

new LangfuseExporter({
  // Required credentials
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
 
  // Optional settings
  baseUrl: process.env.LANGFUSE_BASE_URL, // Defaults to https://litefuse.cloud
  realtime: process.env.NODE_ENV === "development",
  logLevel: "info", // debug | info | warn | error
 
  // Langfuse-specific options
  options: {
    environment: process.env.NODE_ENV,
    version: process.env.APP_VERSION,
    release: process.env.GIT_COMMIT,
  },
})

Troubleshooting

NextJS Integration Issues: If you encounter issues when using Mastra with Litefuse in NextJS applications, refer to the Mastra NextJS tracing documentation for NextJS-specific configuration and setup instructions.
No Traces in Litefuse: Ensure that your credentials are correct and follow this troubleshooting guide

References

LlamaIndex Workflows Microsoft Agent Framework

Was this page helpful?

Support