---
title: Mastra
description: Export OpenTelemetry GenAI spans from Mastra to Coralogix for full visibility into agent runs, model generations, and tool calls.
url: https://coralogix.com/docs/integrations/ai-observability/mastra/
product: ai
feature: AI App Catalog
feature_id: ai-app-catalog
feature_identifier: ai/ai-app-catalog
last_updated: '2026-09-03'
---

# Mastra

Export OpenTelemetry GenAI spans from [Mastra](https://mastra.ai) to Coralogix for full visibility into agent runs, model generations, and tool calls. The `@mastra/coralogix` exporter integrates with Mastra's observability layer and supports both simple agent workflows and nested multi-agent architectures.

## What you need

* Node.js 22.13.0 or newer.
* A Coralogix [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys.md).
* A Mastra application.

## Installation

```
pnpm add @mastra/coralogix

# or

npm install @mastra/coralogix
```

## Configuration

Configure the exporter using environment variables or pass options directly to `CoralogixExporter`.

### Environment variables

| Variable              | Required | Description                                                                                                                                                                                                                                    |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CX_TOKEN`            | Yes      | Your Coralogix API key                                                                                                                                                                                                                         |
| `CX_ENDPOINT`         | Yes      | Select the <!-- -->ingress.:443<!-- --> endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain.md) using the domain selector at the top of the page. |
| `CX_APPLICATION_NAME` | No       | Application name (defaults to `Unknown`)                                                                                                                                                                                                       |
| `CX_SUBSYSTEM_NAME`   | No       | Subsystem name (defaults to `Unknown`)                                                                                                                                                                                                         |

### Constructor options

Pass configuration directly to `CoralogixExporter`:

```
import { CoralogixExporter } from '@mastra/coralogix';



const exporter = new CoralogixExporter({

  token: process.env.CX_TOKEN,

  endpoint: process.env.CX_ENDPOINT,

  applicationName: 'ai-application',

  subsystemName: 'ai-subsystem',

  debug: false,

});
```

## Usage

The exporter supports two integration modes depending on your agent architecture.

### Exporter mode

Use exporter mode for simple, single-agent workflows. Pass the exporter to Mastra's `Observability` class:

```
import { Mastra } from '@mastra/core';

import { CoralogixExporter } from '@mastra/coralogix';



const exporter = new CoralogixExporter({

  token: process.env.CX_TOKEN,

  endpoint: process.env.CX_ENDPOINT,

  applicationName: 'ai-application',

  subsystemName: 'ai-subsystem',

});



const mastra = new Mastra({

  observability: {

    exporters: [exporter],

  },

});
```

### Bridge mode

Use bridge mode for nested agent calls where multiple agents coordinate. The bridge automatically propagates OpenTelemetry trace context through `executeInContext()` calls, so all agent activity is collected under a single unified trace.

```
import { CoralogixExporter } from '@mastra/coralogix';



const exporter = new CoralogixExporter({

  token: process.env.CX_TOKEN,

  endpoint: process.env.CX_ENDPOINT,

});



// Pass exporter as an ObservabilityBridge in your Mastra setup
```

## Span structure

Each agent execution produces a flat span structure exported to Coralogix:

* **Agent run span**: One per agent invocation. Root of the trace. Aggregates model name, provider, and token usage from descendant model generation spans.
* **Model generation spans**: One per LLM call. Includes model name, provider, temperature, and token usage. Appears as a sibling under the root agent run span.
* **Tool call spans**: One per tool invocation. Includes tool name, arguments, result, and success status.

Internal workflow spans are excluded by default. All exported spans are flattened as siblings under the root agent run span and ordered chronologically.

## GenAI attributes

| Attribute                    | Type    | Description                                                     |
| ---------------------------- | ------- | --------------------------------------------------------------- |
| `gen_ai.operation.name`      | string  | Operation type: `agent_run`, `model_generation`, or `tool_call` |
| `gen_ai.agent.name`          | string  | Name of the agent                                               |
| `gen_ai.agent.instructions`  | string  | Instructions passed to the agent                                |
| `gen_ai.agent.tools`         | string  | Tools available to the agent                                    |
| `gen_ai.request.model`       | string  | Model requested by the agent                                    |
| `gen_ai.provider.name`       | string  | LLM provider name                                               |
| `gen_ai.request.temperature` | float   | Temperature parameter                                           |
| `gen_ai.usage.input_tokens`  | int     | Tokens consumed by the prompt                                   |
| `gen_ai.usage.output_tokens` | int     | Tokens generated in the response                                |
| `gen_ai.prompt`              | string  | Prompt sent to the model                                        |
| `gen_ai.completion`          | string  | Model response                                                  |
| `tool.name`                  | string  | Name of the invoked tool                                        |
| `tool.arguments`             | string  | Arguments passed to the tool                                    |
| `tool.result`                | string  | Result returned by the tool                                     |
| `tool.success`               | boolean | Whether the tool call succeeded                                 |

## Next steps

Once your integration is set up, explore the [AI Center Overview](https://coralogix.com/docs/user-guides/ai/monitor.md) to monitor performance, costs, quality issues, and security across all your AI applications, and to set up [Guardrails](https://coralogix.com/docs/user-guides/ai/guardrails.md) for real-time policy enforcement.