Observability API

Observability API 提供用於取得 Trace、監控應用效能、為 Trace 評分以進行評估，以及記錄與 Trace 和 span 關聯的意見回饋的方法。

取得特定 Trace

透過 ID 取得特定 Trace，包括其所有 span 和詳細資訊：

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

篩選並取得 Trace

取得選用篩選的 Trace 根 span 分頁清單：

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)

為清單視圖列出 Trace

listTracesLight() 傳回與 Trace 清單相同的行，但不包含 input、output 和 attributes payload。每一行改為攜帶簡短的 inputPreview 字串，因此清單不必傳輸完整 prompt 即可呈現預覽列。

同時呈現大量 Trace 時應優先使用它，且僅在打開某一行時取得完整記錄：

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)

它接受與 listTraces() 相同的篩選、排序和增量輪詢參數。確實需要完整 span payload 時，請使用 listTraces()。

為 Trace 評分

使用已註冊的 Scorer 為特定 Trace 評分，以進行評估：

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
  ],
})

依 span 取得評分

取得 Trace 中特定 span 的評分：

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

意見回饋

意見回饋方法用於建立、列出和查詢人工參與的訊號，例如評分、讚／倒讚、評論和糾正。有關範例，請參閱意見回饋指南；有關完整 schema，請參閱意見回饋參考。

建立意見回饋

建立與 Trace 或 span 關聯的意見回饋記錄：

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

列出意見回饋

取得選用篩選的意見回饋記錄分頁清單：

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

彙總意見回饋

彙總數值型意見回饋值，例如評分或以 1 和 -1 編碼的讚／倒讚：

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

對意見回饋分組

依可觀測性維度對數值型意見回饋分組：

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

依時間查詢意見回饋

依時間間隔對數值型意見回饋分組：

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

查詢意見回饋百分位數

傳回數值型意見回饋值的百分位數序列：

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

相關內容

• 意見回饋指南：瞭解如何建立、列出和查詢意見回饋
• 意見回饋參考：查看意見回饋 schema 和 HTTP 路由
• Agents API：瞭解會產生 Trace 的 Agent 互動
• Workflows API：瞭解 Workflow 執行監控