Exporter Arize

Arize fournit des plateformes d'observabilité pour les applications d'IA avec Phoenix (open source) et Arize AX (entreprise). L'exporter Arize envoie les traces au moyen d'OpenTelemetry et des conventions sémantiques OpenInference, compatibles avec toute plateforme OpenTelemetry prenant en charge OpenInference.

Installation

npm

npm install @mastra/arize@latest

pnpm

pnpm add @mastra/arize@latest

Yarn

yarn add @mastra/arize@latest

Bun

bun add @mastra/arize@latest

Configuration

Configuration de Phoenix

Phoenix est une plateforme d'observabilité open source qui peut être auto-hébergée ou utilisée via Phoenix Cloud.

Prérequis

1. Instance Phoenix : déployez-la avec Docker ou inscrivez-vous à Phoenix Cloud
2. Point de terminaison : l'URL de votre point de terminaison Phoenix (elle se termine par /v1/traces)
3. Clé d'API : facultative pour les instances sans authentification, requise pour Phoenix Cloud
4. Variables d'environnement : définissez votre configuration

.env

# Required
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL

# Optional
PHOENIX_API_KEY=your-api-key  # For authenticated Phoenix instances
PHOENIX_PROJECT_NAME=mastra-service  # Defaults to 'mastra-service'

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 { ArizeExporter } from '@mastra/arize'

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

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 { ArizeExporter } from '@mastra/arize'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.PHOENIX_PROJECT_NAME || 'mastra-service',
        exporters: [
          new ArizeExporter({
            endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
            apiKey: process.env.PHOENIX_API_KEY,
            projectName: process.env.PHOENIX_PROJECT_NAME,
          }),
        ],
      },
    },
  }),
})

Démarrage rapide avec Docker

Effectuez un test local avec une instance Phoenix en mémoire :

docker run --pull=always -d --name arize-phoenix -p 6006:6006 \
  -e PHOENIX_SQL_DATABASE_URL="sqlite:///:memory:" \
  arizephoenix/phoenix:latest

Définissez PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces, puis exécutez votre Agent Mastra pour consulter les traces sur localhost:6006.

Configuration d'Arize AX

Arize AX est une plateforme d'observabilité d'entreprise qui offre des fonctionnalités avancées aux systèmes d'IA en production.

Prérequis

1. Compte Arize AX : inscrivez-vous sur app.arize.com
2. Identifiant d'espace : l'identifiant de l'espace de votre organisation
3. Clé d'API : générez-la dans les paramètres d'Arize AX
4. Variables d'environnement : définissez vos identifiants

.env

# Required
ARIZE_SPACE_ID=your-space-id
ARIZE_API_KEY=your-api-key

# Optional
ARIZE_PROJECT_NAME=mastra-service

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 { ArizeExporter } from '@mastra/arize'

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

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 { ArizeExporter } from '@mastra/arize'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.ARIZE_PROJECT_NAME || 'mastra-service',
        exporters: [
          new ArizeExporter({
            apiKey: process.env.ARIZE_API_KEY!,
            spaceId: process.env.ARIZE_SPACE_ID!,
            projectName: process.env.ARIZE_PROJECT_NAME,
          }),
        ],
      },
    },
  }),
})

Options de configuration

L'exporter Arize accepte une configuration avancée permettant d'ajuster précisément le comportement d'OpenTelemetry :

Configuration complète

new ArizeExporter({
  // Phoenix Configuration
  endpoint: 'https://your-collector.example.com/v1/traces', // Required for Phoenix

  // Arize AX Configuration
  spaceId: 'your-space-id', // Required for Arize AX

  // Shared Configuration
  apiKey: 'your-api-key', // Required for authenticated endpoints
  projectName: 'mastra-service', // Optional project name

  // Optional OTLP settings
  headers: {
    'x-custom-header': 'value', // Additional headers for OTLP requests
  },

  // Debug and performance tuning
  logLevel: 'debug', // Logging: debug | info | warn | error
  batchSize: 512, // Batch size before exporting spans
  timeout: 30000, // Timeout in ms before exporting spans

  // Custom resource attributes
  resourceAttributes: {
    'deployment.environment': process.env.NODE_ENV,
    'service.version': process.env.APP_VERSION,
  },
})

Options de traitement par lots

Contrôlez la mise en lots et l'exportation des traces :

new ArizeExporter({
  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
  apiKey: process.env.PHOENIX_API_KEY,

  // Batch processing configuration
  batchSize: 512, // Number of spans to batch (default: 512)
  timeout: 30000, // Max time in ms to wait before export (default: 30000)
})

Attributs de ressource

Ajoutez des attributs personnalisés à tous les spans exportés :

new ArizeExporter({
  endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT!,
  resourceAttributes: {
    'deployment.environment': process.env.NODE_ENV,
    'service.namespace': 'production',
    'service.instance.id': process.env.HOSTNAME,
    'custom.attribute': 'value',
  },
})

Métadonnées personnalisées

Les attributs de span non réservés sont sérialisés dans la charge utile OpenInference metadata et apparaissent dans Arize/Phoenix. Vous pouvez les ajouter au moyen de tracingOptions.metadata :

await agent.generate(input, {
  tracingOptions: {
    metadata: {
      companyId: 'acme-co',
      tier: 'enterprise',
    },
  },
})

Les champs réservés tels que input, output, sessionId, les identifiants de thread et d'utilisateur ainsi que les identifiants OpenInference sont automatiquement exclus.

Conventions sémantiques OpenInference

Cet exporter implémente les conventions sémantiques OpenInference pour les applications d'IA générative, ce qui fournit une structure de trace normalisée entre les différentes plateformes d'observabilité.

Voir aussi

• Présentation du tracing
• Documentation de Phoenix
• Documentation d'Arize AX
• Spécification OpenInference