Mastra

Permitech supports logging traces from Mastra applications using OpenTelemetry.

Set up OpenTelemetry

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

Add the OpenTelemetry packages to your application

Add the Mastra OTel Exporter and OpenTelemetry packages to your Mastra application project.

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

Create environment variables for your Permitech settings

Set environment variables for your Permitech settings, for example in a .env file:

# Your Permitech API key
PERMITECH_API_KEY="your-permitech-api-key"

# Your Permitech project name
PERMITECH_PROJECT="your-permitech-project-name"

# The name of the Log stream you want to use for logging
PERMITECH_LOG_STREAM="your-permitech-log-stream "

Get your endpoint

The OTel endpoint is different from Permitech’s regular API endpoint and is specifically designed to receive telemetry data in the OTLP format.If you are using:

Permitech Cloud at permi.tech, then you don’t need to provide a custom OTel endpoint. The default endpoint https://permi.tech/api/otel/traces will be used automatically.
A self-hosted Permitech deployment, replace the https://permi.tech/api/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.permitech.example.com, the OTel endpoint would be https://api.permitech.example.com/otel/traces
if your console URL is https://console-permitech.apps.mycompany.com, the OTel endpoint would be https://api-permitech.apps.mycompany.com/otel/traces

Configure OpenTelemetry in your Mastra instance

In your Mastra configuration file, add the observability configuration with the Permitech OTel exporter:

TypeScript

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.PERMITECH_API_URL || "https://permi.tech/api";

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

Run your application

Your application is now configured to send telemetry to Permitech using OpenTelemetry. Run your application to see traces in your Log stream.

What gets logged

Mastra spans are automatically sent to Permitech 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 .

Overview

Get Started

Observability

Evaluation Metrics

Signals

AI Assistant

Luna Studio

Experiments

Agent Control

Annotations

Integrations

Security

References

Set up OpenTelemetry

What gets logged

​Set up OpenTelemetry

​What gets logged

Set up OpenTelemetry

What gets logged