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

# Observability API

Observability API는 추적을 검색하고, 애플리케이션 성능을 모니터링하고, 평가를 위해 추적에 점수를 매기고, 추적 및 범위에 연결된 피드백을 기록하는 메서드를 제공합니다.

## 특정 추적 얻기

모든 범위 및 세부정보를 포함하여 해당 ID로 특정 추적을 검색합니다.

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

## 필터링으로 추적 얻기

선택적 필터링을 사용하여 페이지가 매겨진 추적 루트 범위 목록을 검색합니다.

```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)
```

## 목록 보기의 추적 나열

`listTracesLight()`는 Trace 목록과 동일한 행을 반환하지만 `input`, `output`, `attributes` 페이로드는 제외합니다. 각 행에는 대신 짧은 `inputPreview` 문자열이 포함되므로, 전체 Prompt를 전송하지 않고도 목록에 미리보기 열을 렌더링할 수 있습니다. 한 번에 많은 트레이스를 렌더링할 때마다 선호하고 행이 열릴 때만 전체 레코드를 가져옵니다.

```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()`를 사용하세요.

## 득점 흔적

평가를 위해 등록된 채점자를 사용하여 특정 추적에 점수를 매깁니다.

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

## 범위별 점수 얻기

추적 내의 특정 범위에 대한 점수를 검색합니다.

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

## 피드백

피드백 메서드는 평점, 추천, 의견, 수정 사항과 같은 인간 참여형 신호를 생성하고 나열하며 쿼리합니다. 예시는 [피드백 가이드](https://mastra.zisheng.pro/ko/docs/observability/feedback)를, 전체 스키마는 [피드백 레퍼런스](https://mastra.zisheng.pro/ko/reference/observability/feedback)를 참조하세요.

### 피드백 만들기

추적 또는 범위에 연결된 피드백 레코드를 만듭니다.

```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',
})
```

### 피드백 그룹화

Observability 차원별로 숫자 피드백을 그룹화합니다.

```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/ko/docs/observability/feedback): 피드백을 생성, 나열, 쿼리하는 방법을 알아보세요.
- [피드백 참조](https://mastra.zisheng.pro/ko/reference/observability/feedback): 피드백 스키마 및 HTTP 경로 검토
- [Agent API](https://mastra.zisheng.pro/ko/reference/client-js/agents): 추적을 생성하는 Agent 상호작용에 대해 알아봅니다.
- [Workflow API](https://mastra.zisheng.pro/ko/reference/client-js/workflows): Workflow 실행 모니터링 이해