Exporter Sentry

Sentry est une plateforme de surveillance des applications dotée de fonctionnalités de traçage propres à l’IA. L’exporter Sentry envoie vos traces à Sentry en appliquant les conventions sémantiques OpenTelemetry, ce qui fournit des informations sur les performances des modèles, l’utilisation des jetons et l’exécution des Tools.

Installation

npm

npm install @mastra/sentry@latest

pnpm

pnpm add @mastra/sentry@latest

Yarn

yarn add @mastra/sentry@latest

Bun

bun add @mastra/sentry@latest

Configuration

Prérequis

1. Compte Sentry : inscrivez-vous sur sentry.io
2. DSN : récupérez votre Data Source Name dans Project Settings → Client Keys
3. Variables d’environnement : définissez votre configuration

.env

SENTRY_DSN=https://...@...sentry.io/...

# Optional
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

Configuration automatique

Une fois les variables d’environnement définies, utilisez l’exporter sans configuration :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { SentryExporter } from '@mastra/sentry'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      sentry: {
        serviceName: 'my-service',
        exporters: [new SentryExporter()],
      },
    },
  }),
})

Configuration explicite

Vous pouvez également transmettre les identifiants directement ; ils prévalent sur les variables d’environnement :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { SentryExporter } from '@mastra/sentry'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      sentry: {
        serviceName: 'my-service',
        exporters: [
          new SentryExporter({
            dsn: process.env.SENTRY_DSN!,
            environment: 'production',
            tracesSampleRate: 1.0, // Send 100% of transactions to Sentry
          }),
        ],
      },
    },
  }),
})

Options de configuration

Configuration complète

new SentryExporter({
  // Required settings
  dsn: process.env.SENTRY_DSN!, // Data Source Name - tells the SDK where to send events

  // Optional settings
  environment: 'production', // Deployment environment (enables filtering issues and alerts by environment)
  tracesSampleRate: 1.0, // Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%)
  release: '1.0.0', // Version of your code deployed (helps identify regressions and track deployments)

  // Advanced Sentry options
  options: {
    // Any additional Sentry.NodeOptions
    integrations: [],
    beforeSend: event => event,
    // ... other Sentry SDK options
  },

  // Diagnostic logging
  logLevel: 'info', // debug | info | warn | error
})

Configuration de l’échantillonnage

Contrôlez le pourcentage de transactions envoyées à Sentry. Cette option est utile pour les applications à fort volume :

new SentryExporter({
  dsn: process.env.SENTRY_DSN!,
  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
})

astuce

Définissez la valeur sur 1.0 (100 %) en développement et entre 0.1 et 0.2 (10 à 20 %) pour les applications de production fortement sollicitées. Pour désactiver entièrement le traçage, ne définissez pas tracesSampleRate au lieu de lui attribuer 0.

Correspondance des types de span

Les types de span Mastra sont automatiquement associés aux opérations Sentry :

SpanType Mastra	Opération Sentry	Remarques
AGENT_RUN	gen_ai.invoke_agent	Contient les jetons du span enfant MODEL_GENERATION
MODEL_GENERATION	gen_ai.chat	Inclut les statistiques d’utilisation et les données de streaming
MODEL_STEP	(ignoré)	Ignoré pour simplifier la hiérarchie des traces
MODEL_CHUNK	(ignoré)	Données agrégées dans MODEL_GENERATION
TOOL_CALL	gen_ai.execute_tool	Exécution d’un Tool avec entrée et sortie
MCP_TOOL_CALL	gen_ai.execute_tool	Exécution d’un Tool MCP
WORKFLOW_RUN	workflow.run
WORKFLOW_STEP	workflow.step
WORKFLOW_CONDITIONAL	workflow.conditional
WORKFLOW_CONDITIONAL_EVAL	workflow.conditional
WORKFLOW_PARALLEL	workflow.parallel
WORKFLOW_LOOP	workflow.loop
WORKFLOW_SLEEP	workflow.sleep
WORKFLOW_WAIT_EVENT	workflow.wait
PROCESSOR_RUN	ai.processor
GENERIC	ai.span

Conventions sémantiques OpenTelemetry

L’exporter utilise les conventions sémantiques GenAI standard avec des attributs propres à Sentry :

Pour les spans MODEL_GENERATION :

• gen_ai.system : Provider du modèle (par exemple, openai, anthropic)
• gen_ai.request.model : identifiant du modèle (par exemple, gpt-5.4)
• gen_ai.response.model : modèle de la réponse
• gen_ai.response.text : réponse textuelle produite
• gen_ai.response.tool_calls : appels de Tool effectués pendant la génération (tableau JSON)
• gen_ai.usage.input_tokens : nombre de jetons en entrée
• gen_ai.usage.output_tokens : nombre de jetons en sortie
• gen_ai.request.temperature : paramètre de température
• gen_ai.request.stream : indique si le streaming a été demandé
• gen_ai.request.messages : messages ou instructions en entrée (JSON)
• gen_ai.completion_start_time : heure d’arrivée du premier jeton

Pour les spans TOOL_CALL :

• gen_ai.tool.name : identifiant du Tool
• gen_ai.tool.type : function
• gen_ai.tool.call.id : ID de l’appel de Tool
• gen_ai.tool.input : entrée du Tool (JSON)
• gen_ai.tool.output : sortie du Tool (JSON)
• tool.success : indique si l’appel de Tool a réussi

Pour les spans AGENT_RUN :

• gen_ai.agent.name : identifiant de l’Agent
• gen_ai.pipeline.name : nom de l’Agent (pour la vue IA de Sentry)
• gen_ai.agent.instructions : instructions de l’Agent
• gen_ai.response.model : modèle provenant de la génération enfant
• gen_ai.response.text : texte produit par la génération enfant
• gen_ai.usage.* : utilisation des jetons par la génération enfant

Fonctionnalités

• Traces hiérarchiques : conserve les relations parent-enfant
• Suivi des jetons : suit automatiquement l’utilisation des jetons pendant les générations
• Suivi des appels de Tool : capture les exécutions de Tools avec leurs entrées et sorties
• Prise en charge du streaming : agrège les réponses en streaming
• Suivi des erreurs : capture automatiquement l’état d’erreur et les exceptions
• Prise en charge des Workflows : suit les étapes d’exécution des Workflows
• Hiérarchie simplifiée : ignore les spans MODEL_STEP et MODEL_CHUNK pour réduire le bruit

Pages connexes

• Présentation du tracing
• Documentation Sentry
• Conventions sémantiques OpenTelemetry