> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Observability API

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

## 取得指定 Trace

按 ID 取得指定 Trace，包括所有 span 及詳情：

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

## 篩選 Trace

取得 Trace 根 span 的分頁清單，並可選擇篩選條件：

```typescript
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` 承載資料。每列改為包含簡短的 `inputPreview` 字串，讓清單可顯示預覽欄而毋須傳送完整提示詞。

如需一次顯示大量 Trace，應優先使用此方法，並只在開啟個別列時才取得完整記錄：

```typescript
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 承載資料，請使用 `listTraces()`。

## 為 Trace 評分

使用已註冊的評分器為指定 Trace 評分，以供評估：

```typescript
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 的評分：

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

## 意見回饋

意見回饋方法可建立、列出及查詢評分、讚好／不讚好、留言及修正等人工介入訊號。範例請參閱[意見回饋指南](https://mastra.zisheng.pro/zh-HK/docs/observability/feedback)，完整結構描述則請參閱[意見回饋參考](https://mastra.zisheng.pro/zh-HK/reference/observability/feedback)。

### 建立意見回饋

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

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

### 列出意見回饋

取得意見回饋記錄的分頁清單，並可選擇篩選條件：

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

### 彙總意見回饋

彙總數值意見回饋，例如評分，或以 `1` 及 `-1` 表示的讚好／不讚好：

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

### 分組意見回饋

按可觀測性維度將數值意見回饋分組：

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

### 按時間查詢意見回饋

按時間間隔將數值意見回饋分桶：

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

### 查詢意見回饋百分位數

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

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

## 相關內容

- [意見回饋指南](https://mastra.zisheng.pro/zh-HK/docs/observability/feedback)：了解如何建立、列出及查詢意見回饋
- [意見回饋參考](https://mastra.zisheng.pro/zh-HK/reference/observability/feedback)：查看意見回饋結構描述及 HTTP 路由
- [Agents API](https://mastra.zisheng.pro/zh-HK/reference/client-js/agents)：了解會產生 Trace 的 Agent 互動
- [Workflows API](https://mastra.zisheng.pro/zh-HK/reference/client-js/workflows)：了解如何監察 Workflow 執行