> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galileo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastra

> Learn how to integrate a Mastra project with Galileo using OpenTelemetry

{/*<!-- markdownlint-enable MD044 -->*/}

Galileo supports logging traces from [Mastra](https://mastra.ai/) applications using OpenTelemetry.

## Set up OpenTelemetry

To log Mastra applications using Galileo, the first step is to set up OpenTelemetry.

<Steps>
  <Step title="Add the OpenTelemetry packages to your application">
    Add the Mastra OTel Exporter and OpenTelemetry packages to your Mastra application project.

    <CodeGroup>
      ```bash Terminal theme={null}
      npm install @mastra/otel-exporter \
            @opentelemetry/exporter-trace-otlp-proto
      ```
    </CodeGroup>
  </Step>

  <Step title="Create environment variables for your Galileo settings">
    Set environment variables for your Galileo settings, for example in a `.env` file:

    <CodeGroup>
      ```ini .env theme={null}
      # Your Galileo API key
      GALILEO_API_KEY="your-galileo-api-key"

      # Your Galileo project name
      GALILEO_PROJECT="your-galileo-project-name"

      # The name of the Log stream you want to use for logging
      GALILEO_LOG_STREAM="your-galileo-log-stream "
      ```
    </CodeGroup>
  </Step>

  <Step title="Get your endpoint">
    The OTel endpoint is different from Galileo's regular API endpoint and is specifically designed to receive telemetry data in the OTLP format.

    If you are using:

    * **Galileo Cloud** at [app.galileo.ai](https://app.galileo.ai), then you don't need to provide a custom OTel endpoint.
      The default endpoint `https://api.galileo.ai/otel/traces` will be used automatically.

    * A **self-hosted Galileo deployment**, replace the `https://api.galileo.ai/otel/traces` endpoint with your deployment URL. The format of this URL is based on your console URL, replacing `console` with `api` and appending `/otel/traces`.

    For example:

    * if your console URL is `https://console.galileo.example.com`, the OTel endpoint would be `https://api.galileo.example.com/otel/traces`
    * if your console URL is `https://console-galileo.apps.mycompany.com`, the OTel endpoint would be `https://api-galileo.apps.mycompany.com/otel/traces`
  </Step>

  <Step title="Configure OpenTelemetry in your Mastra instance">
    In your Mastra configuration file, add the observability configuration with the Galileo OTel exporter:

    ```typescript TypeScript theme={null}
    import { SamplingStrategyType } from "@mastra/core/ai-tracing";
    import { 
        Observability,
        SamplingStrategyType
    } from '@mastra/observability';
    import { OtelExporter } from "@mastra/otel-exporter";
    import { Mastra } from "@mastra/core/mastra";
    import { env } from "node:process";

    const ObservabilityEndpoint = env.GALILEO_API_URL || "https://api.galileo.ai";

    export const mastra = new Mastra({
      // Your agents, workflows, etc.
      agents: {
        /* ... */
      },
      workflows: {
        /* ... */
      },
      // Configure observability with Galileo
      observability: new Observability({
          configs: {
            otel: {
              sampling: { type: SamplingStrategyType.ALWAYS },
              serviceName: 'galileo-mastra-agent',
              exporters: [
                new OtelExporter({
                  provider: {
                    custom: {
                      endpoint: `${ObservabilityEndpoint}/otel/v1/traces`,
                      headers: {
                        'Galileo-API-Key': process.env.GALILEO_API_KEY ?? '',
                        'project': env.GALILEO_PROJECT ?? '',
                        'logstream': env.GALILEO_LOG_STREAM ?? '',
                      },
                      protocol: 'http/protobuf',
                    }
                  },
                }),
              ]
            }
          }
      }),
    });
    ```
  </Step>

  <Step title="Run your application">
    Your application is now configured to send telemetry to Galileo using OpenTelemetry. Run your application to see traces in your Log stream.
  </Step>
</Steps>

## What gets logged

Mastra spans are automatically sent to Galileo through the OpenTelemetry integration. The following information is captured:

* **Agent executions**: Complete agent runs with input/output messages
* **LLM calls**: Model interactions with prompts and responses
* **Tool executions**: Tool invocations with arguments and results
* **Workflows**: Multi-step workflow executions

For a complete working example with tools and workflows, see the [Galileo SDK examples repository](https://github.com/rungalileo/sdk-examples/tree/main/typescript/agent/mastra-template-csv-to-questions).