Observability API

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

특정 추적 얻기

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

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

필터링으로 추적 얻기

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

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를 전송하지 않고도 목록에 미리보기 열을 렌더링할 수 있습니다. 한 번에 많은 트레이스를 렌더링할 때마다 선호하고 행이 열릴 때만 전체 레코드를 가져옵니다.

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

득점 흔적

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

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

범위별 점수 얻기

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

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

피드백

피드백 메서드는 평점, 추천, 의견, 수정 사항과 같은 인간 참여형 신호를 생성하고 나열하며 쿼리합니다. 예시는 피드백 가이드를, 전체 스키마는 피드백 레퍼런스를 참조하세요.

피드백 만들기

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

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

피드백 그룹화

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

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

관련된

• 피드백 가이드: 피드백을 생성, 나열, 쿼리하는 방법을 알아보세요.
• 피드백 참조: 피드백 스키마 및 HTTP 경로 검토
• Agent API: 추적을 생성하는 Agent 상호작용에 대해 알아봅니다.
• Workflow API: Workflow 실행 모니터링 이해