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

# Mastra 플랫폼의 Trace Intelligence

Trace Intelligence는 Agent의 상호 작용 전반에서 반복되는 패턴을 찾습니다. Mastra Observability에서 캡처한 추적을 분석하고, 4차원에 대한 추적 신호를 생성하고, 유사한 추적 신호를 테마로 클러스터링합니다.

Trace Intelligence를 사용하여 다음과 같은 질문을 조사하세요.

- 사용자는 무엇을 달성하려고 합니까?
- 어떤 목표가 성공하거나, 해결되지 않거나, 차단되는 경향이 있습니까?
- 성공적인 상호작용과 실패한 상호작용에는 어떤 Agent 행동이 나타나나요?
- 사용자 감정은 목표 및 결과와 어떤 관련이 있습니까?

:::비공개 베타 경고 Trace Intelligence는 선택된 Mastra 플랫폼 프로젝트에 대한 초대를 통해 제공됩니다. :::

## 액세스하기

1. 액세스를 요청하려면 [Trace Intelligence 비공개 베타 양식](https://mastra.ai/trace-intelligence)을 제출합니다.
2. [Mastra 플랫폼 Observability](https://mastra.zisheng.pro/ko/docs/mastra-platform/observability)가 활성화되어 있고 완료된 Agent Trace가 **Traces** 아래에 표시되는지 확인합니다.
3. 최소 `@mastra/core@1.53.0` 및 `mastra@1.20.2`가 필요합니다. 프로젝트를 업그레이드한 다음 등록된 프로젝트의 Studio를 배포하거나 다시 배포하세요. 비공개 베타 기간에는 로컬 Studio와 Server 전용 배포가 지원되지 않습니다.
4. 배포된 Studio를 열고 사이드바에서 **Intelligence**를 선택합니다.
5. Agent에 대표적인 트래픽을 보내고 분석할 시간을 둡니다. Mastra가 프로젝트를 등록하면 Agent 정의나 통화를 변경할 필요가 없습니다.

### 데이터를 사용할 수 있는 경우

Trace Intelligence에서 반복 패턴을 식별하려면 하나의 Agent에서 처리된 Trace가 충분히 많아야 합니다. 초기 테마는 일반적으로 해당 Agent의 **100 completed traces** 이상이 처리된 후 나타납니다. 분석 파이프라인이 비동기적으로 실행되므로 Trace Intelligence가 준비되기 전에 **Traces** 수가 100에 도달할 수 있습니다. 임계값에 도달한 후 처리에는 몇 분이 걸릴 수 있습니다. 분석할 수 없는 Trace는 집계에 포함되지 않으므로 100은 정확한 UI 트리거가 아니라 최솟값입니다. 더 많은 추적이 도착하면 추적 인텔리전스가 자동으로 업데이트됩니다. Studio에서 관계 흐름을 표시하려면 최소한 두 가지 추적 신호 유형에 대한 테마가 필요합니다.

대표 트래픽을 사용하세요. 반복되는 테스트 Prompt의 작은 세트는 하나의 광범위한 테마 또는 대부분 소음과 같은 대표성이 없는 결과를 생성할 수 있습니다.

## 분석 이해

분석 가능한 각 완성 추적은 4개의 추적 신호를 생성합니다.

| Trace 신호                                                                                                            | 의미                                                        |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Goal**                                                                                                            | 사용자가 달성하거나 완료하려는 목표입니다.                                   |
| **Outcome**                                                                                                         | 완료, 부분 완료, 차단, 실패, 미해결 또는 불명확한 최종 상태입니다.                  |
| **Behavior**                                                                                                        | Tool 사용, 누락, 재시도, 실패, 복구를 포함하여 관찰할 수 있는 Agent의 행동과 패턴입니다. |
| **Sentiment**                                                                                                       | 사용자의 감정 상태 또는 태도입니다.                                      |
| 테마는 유사한 추적 신호에서 생성된 클러스터입니다. 클러스터링은 각 추적 신호 유형에 대해 독립적으로 발생합니다. 하나의 추적은 목표, 결과, 행동, 감정 등 모든 차원에서 별도의 주제에 속할 수 있습니다. |                                                           |

### 주제와 관계

순서도는 인접한 추적 신호 열의 주제를 연결합니다.

- **node**는 테마를 나타냅니다. 노드의 개수는 선택한 스냅샷에서 해당 테마에 할당된 서로 다른 Trace의 수입니다.
- **ribbon**은 인접한 두 열의 테마에 모두 할당된 Trace를 연결합니다. 리본의 너비는 공유된 Trace 수를 나타냅니다.
- 노드나 리본 위에 마우스를 올리거나 초점을 맞춰 해당 관계만 분리해 확인할 수 있습니다. 흐름은 원인이나 실행 순서가 아닌 연관성을 보여줍니다. 예를 들어 목표와 결과 사이의 리본은 두 테마가 모두 동일한 추적에서 발생했음을 의미합니다. 목표가 결과를 초래했다는 것을 보여주지는 않습니다.

### 분포, 기타 및 노이즈

흐름 아래의 카드는 각 추적 신호의 테마 분포를 보여줍니다.

- **추적 수**: 선택한 스냅샷의 테마에 할당된 개별 추적 수입니다.
- **무대 점유율**: 테마에 할당된 해당 추적 신호에 대해 분석된 추적의 백분율입니다.

Studio는 각 Trace 신호 유형에서 가장 일반적인 테마를 보여줍니다. 차트가 지나치게 복잡해지지 않으면서 합계를 유지하도록 더 작은 테마를 **Other**로 묶을 수 있습니다. **소음**선택한 스냅샷의 반복 테마와 일관되게 일치하지 않는 요약이 포함되어 있습니다. 반드시 오류나 품질이 낮은 상호 작용을 나타내는 것은 아닙니다. 소음에는 드문 요청과 새로운 패턴이 포함될 수 있습니다. 또한 모호한 상호 작용이나 관련 없는 사례가 포함될 수도 있습니다. 노이즈 점유율이 크다는 것은 트래픽이 매우 다양하거나 안정적인 테마에 대한 데이터가 부족하다는 것을 의미할 수 있습니다.

### 스냅샷

스냅샷은 일련의 추적에 대한 이동 분석 창입니다. 스냅샷은 겹칠 수 있으므로 추적 수를 함께 추가하지 마세요. 트래픽 양은 창 간에 변경될 수 있으므로 추적 수와 단계 공유를 함께 비교하십시오.

테마는 스냅샷 전체에 걸쳐 유지, 사라지기, 분할, 병합 또는 반환될 수 있습니다. 테마 이름과 설명을 고정된 분류가 아닌 생성된 요약으로 처리합니다.

## 추적 인텔리전스 페이지 사용

1. **Agent** 선택기를 사용하여 분석이 제공되는 Agent 간에 전환합니다. 첫 번째 테마가 준비되기 전까지는 Agent가 표시되지 않습니다.
2. 흐름에서 테마를 선택하여 모든 열을 해당 테마가 포함된 Trace로 필터링합니다.
3. **View theme details**를 선택하여 설명, Trace 수, 단계별 비중, 생성된 예시 및 기록을 살펴봅니다.
4. **Clear filter**를 선택하여 전체 흐름을 복원합니다. 다음을 수행할 수도 있습니다.

- 분포 카드에서 테마를 선택하여 세부 정보와 생성된 예시 요약을 엽니다.
- 분포 카드에서 **Noise**를 선택하여 분포와 생성된 예시 요약을 살펴봅니다.
- 분포 카드를 드래그하여 Trace 신호 열의 순서를 바꾸고 관계를 다른 관점에서 확인합니다.
- 타임라인을 사용하여 스냅샷을 선택하거나 **Play**를 선택하여 시간에 따라 테마가 변하는 모습을 확인합니다.
- 테마 기록을 열어 지속성과 범위가 어떻게 변경되었는지 확인합니다. 트레이스가 2,000개가 넘는 스냅샷의 경우 테마별로 흐름을 필터링할 수 없습니다. 다른 스냅샷을 선택하거나 활성 필터를 지워 전체 흐름으로 돌아갑니다. 테마 및 소음 세부 정보는 배포 카드에서 계속 확인할 수 있습니다.

## 문제 해결

### 인텔리전스는 사이드바에 없습니다.

Mastra가 올바른 프로젝트를 등록했는지, 베타 호환 Mastra 버전을 사용하고 있는지, Studio를 재배포했는지 확인하세요. 비공개 베타는 로컬 Studio를 지원하지 않습니다.

### Agent가 누락되었습니다.

완료된 Trace가 **Traces** 아래에 나열되어 있는지 확인하세요. Agent는 첫 번째 테마가 준비된 후에만 표시됩니다. 최근 Trace가 100개에 도달했다면 비동기 처리가 완료될 때까지 기다리세요.

### 관계 흐름을 사용할 수 없습니다.

흐름에는 두 개 이상의 추적 신호 유형에 대한 테마가 필요합니다. 계속해서 대표 트래픽을 보내고 처리가 완료되도록 허용합니다.

### 대부분의 요약은 노이즈입니다.

더 많은 대표적인 트래픽을 수집하고 이후의 스냅샷을 비교하세요. 다양하거나 드문 상호 작용은 그룹화하기 어려운 반면, 반복되는 테스트 Prompt는 대표적인 분포를 생성할 수 없습니다.

## 비공개 베타 제한 사항

- Trace Intelligence는 배포된 Studio에 등록된 프로젝트에만 사용할 수 있습니다.
- 초기 분석에는 Agent당 처리된 추적이 100개 이상 필요합니다. 일부 Agent은 더 많은 금액을 요구할 수도 있습니다.
- 결과는 캡처된 추적의 다양성과 품질에 따라 달라집니다.
- 베타 기간 동안 추적 신호 요약, 테마 레이블, 클러스터링, 임계값 및 UI 동작이 변경될 수 있습니다.

피드백을 보고할 때 조직 ID, 프로젝트 ID, Agent ID, 선택한 스냅샷, 문제를 설명하는 테마 또는 소음 예시를 포함하세요.

## 관련된

- [Mastra 플랫폼의 Observability](https://mastra.zisheng.pro/ko/docs/mastra-platform/observability)
- [Mastra 플랫폼의 스튜디오](https://mastra.zisheng.pro/ko/docs/mastra-platform/studio)