> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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` payload。每一行改为携带简短的 `inputPreview` 字符串，因此列表无需传输完整 prompt 即可呈现预览列。

同时呈现大量 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 payload 时，请使用 `listTraces()`。

## 为 Trace 评分

使用已注册的 Scorer 为特定 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/docs/observability/feedback)；有关完整 schema，请参阅[反馈参考](https://mastra.zisheng.pro/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/docs/observability/feedback)：了解如何创建、列出和查询反馈
- [反馈参考](https://mastra.zisheng.pro/reference/observability/feedback)：查看反馈 schema 和 HTTP 路由
- [Agents API](https://mastra.zisheng.pro/reference/client-js/agents)：了解会生成 Trace 的 Agent 交互
- [Workflows API](https://mastra.zisheng.pro/reference/client-js/workflows)：了解 Workflow 执行监控