Trace Mastra applications

​

Installation

npm install @mastra/core @mastra/langsmith @mastra/observability @mastra/libsql

​

Setup

1. Set your LangSmith API key and (optionally) a LangSmith project name:
   export LANGSMITH_API_KEY=<your_langsmith_api_key>
   export LANGCHAIN_PROJECT=<your_project_name> # optional
   
   If LANGCHAIN_PROJECT is not set, traces will be sent to the default project.
2. If you plan to use OpenAI models, also ensure you have an OpenAI API key available at runtime:
   export OPENAI_API_KEY=<your_openai_api_key>
   
3. In your project directory, create the following project structure and files:
   src/
       mastra.ts
       agent.ts
       index.ts
   

​

Configure Mastra with the LangSmith exporter

import { Mastra } from "@mastra/core";
import { LibSQLStore } from "@mastra/libsql";
import { LangSmithExporter } from "@mastra/langsmith";

import { echoAgent } from "./agent";

export const mastra = new Mastra({
  agents: { echoAgent },

  storage: new LibSQLStore({
    url: "file:./mastra.db",
  }),

  observability: {
    configs: {
      langsmith: {
        serviceName: "mastra-langsmith-demo",
        exporters: [
          new LangSmithExporter({
            apiKey: process.env.LANGSMITH_API_KEY,
          }),
        ],
      },
    },
  },

  // Disable deprecated telemetry system
  telemetry: {
    enabled: false,
  },
});

• Storage is required for tracing (even when exporting traces externally).
• The LangSmith exporter reads credentials from environment variables.
• The deprecated telemetry system is disabled to avoid warnings.
• No separate instrumentation file is required when running Mastra outside of the Mastra server. For more details, refer to the Mastra docs.

​

Define an agent

import { Agent } from "@mastra/core/agent";

export const echoAgent = new Agent({
  name: "echoAgent",
  instructions: "You are a helpful assistant.",
  model: "openai/gpt-4o-mini",
});

​

Run the agent

1. Add the following to an index.ts file:
   import { mastra } from "./mastra";
   
   async function main() {
   const agent = mastra.getAgent("echoAgent");
   const result = await agent.generate("Say hello and explain what Mastra is.");
   console.log(result.text);
   }
   
   main();
   
2. Run your application:
   npx ts-node src/index.ts
   

​

View traces in LangSmith

1. Open the LangSmith UI.
2. Select your project. For example, the value of LANGCHAIN_PROJECT.
3. Locate the trace corresponding to echoAgent.generate.

• Model inputs and outputs
• Agent execution steps
• Timing and error information