Observability API

L'API Observability fournit des méthodes permettant de récupérer des Traces, de surveiller les performances d'une application, d'évaluer des Traces et d'enregistrer des retours associés aux Traces et aux spans.

Récupération d'une Trace précise

Récupérez une Trace précise à partir de son identifiant, avec tous ses spans et leurs détails :

const trace = await mastraClient.getTrace('trace-id-123')

Récupération de Traces avec filtrage

Récupérez une liste paginée des spans racines de Trace avec un filtrage facultatif :

const traces = await mastraClient.getTraces({
  pagination: {
    page: 1,
    perPage: 20,
    dateRange: {
      start: new Date('2024-01-01'),
      end: new Date('2024-01-31'),
    },
  },
  filters: {
    name: 'weather-agent', // Filter by trace name
    spanType: 'agent', // Filter by span type
    entityId: 'weather-agent-id', // Filter by entity ID
    entityType: 'agent', // Filter by entity type
  },
})

console.log(`Found ${traces.spans.length} root spans`)
console.log(`Total pages: ${traces.pagination.totalPages}`)

// To get the complete trace with all spans, use getTrace
const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId)

Répertorier les Traces dans une vue en liste

listTracesLight() renvoie les mêmes lignes qu'une liste de Traces, sans les charges utiles input, output et attributes. Chaque ligne contient à la place une courte chaîne inputPreview. Une liste peut donc afficher une colonne d'aperçu sans transférer l'intégralité du prompt.

Privilégiez cette méthode lorsque vous affichez de nombreuses Traces à la fois et ne récupérez l'enregistrement complet qu'à l'ouverture d'une ligne :

const list = await mastraClient.listTracesLight({
  pagination: { page: 0, perPage: 25 },
  filters: { entityType: 'agent' },
})

for (const span of list.spans) {
  console.log(span.name, span.inputPreview)
}

// Fetch the full payload only for the trace the user selects
const selected = await mastraClient.getTrace(list.spans[0].traceId)

Elle accepte les mêmes arguments de filtrage, de tri et d'interrogation différentielle que listTraces(). Utilisez listTraces() lorsque vous avez réellement besoin des charges utiles complètes des spans.

Évaluation des Traces

Évaluez des Traces précises au moyen des scorers enregistrés :

const result = await mastraClient.score({
  scorerName: 'answer-relevancy',
  targets: [
    { traceId: 'trace-1', spanId: 'span-1' }, // Score specific span
    { traceId: 'trace-2' }, // Score specific span which defaults to the parent span
  ],
})

Récupération des scores par span

Récupérez les scores d'un span précis au sein d'une Trace :

const scores = await mastraClient.listScoresBySpan({
  traceId: 'trace-123',
  spanId: 'span-456',
  page: 1,
  perPage: 20,
})

Retours

Les méthodes de retour permettent de créer, de répertorier et d'interroger des signaux avec intervention humaine tels que des notes, des pouces, des commentaires et des corrections. Consultez le guide des retours pour obtenir des exemples et la référence des retours pour connaître les schémas complets.

Création d'un retour

Créez un enregistrement de retour associé à une Trace ou à un span :

const response = await mastraClient.createFeedback({
  feedback: {
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})

Liste des retours

Récupérez des enregistrements de retour paginés avec des filtres facultatifs :

const feedback = await mastraClient.listFeedback({
  filters: {
    feedbackType: 'rating',
    feedbackSource: 'studio',
  },
  pagination: { page: 0, perPage: 20 },
  orderBy: { field: 'timestamp', direction: 'DESC' },
})

Agrégation des retours

Agrégez les valeurs numériques des retours, comme les notes ou les pouces codés sous la forme 1 et -1 :

const averageRating = await mastraClient.getFeedbackAggregate({
  feedbackType: 'rating',
  aggregation: 'avg',
  comparePeriod: 'previous_day',
})

Regroupement des retours

Regroupez les retours numériques selon les dimensions d'observabilité :

const ratingsByAgent = await mastraClient.getFeedbackBreakdown({
  feedbackType: 'rating',
  groupBy: ['entityName'],
  aggregation: 'avg',
})

Interrogation des retours au fil du temps

Regroupez les retours numériques par intervalle :

const ratingsOverTime = await mastraClient.getFeedbackTimeSeries({
  feedbackType: 'rating',
  interval: '1h',
  aggregation: 'avg',
  groupBy: ['feedbackSource'],
})

Interrogation des percentiles des retours

Renvoie des séries de percentiles pour les valeurs numériques des retours :

const ratingPercentiles = await mastraClient.getFeedbackPercentiles({
  feedbackType: 'rating',
  percentiles: [0.5, 0.95],
  interval: '1d',
})

Voir aussi

• Guide des retours : découvrez comment créer, répertorier et interroger des retours
• Référence des retours : consultez les schémas des retours et les routes HTTP
• API Agents : découvrez les interactions des Agents qui génèrent des Traces
• API Workflows : comprenez la surveillance de l'exécution des Workflows