> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 추적

> LLM 요청 처리 과정을 단계별로 추적 — 입출력 확인, 지연 시간 분석, LLM 기반 리포트 생성

<Info>관리자 › 평가 › 추적</Info>

추적(Tracing)은 AI 요청이 처리되는 **전 과정을 단계별로 기록**합니다.

* 어떤 문서를 검색했는지, 어떤 도구를 호출했는지, LLM에 어떤 프롬프트가 전달됐는지 — 모든 단계를 투명하게 확인할 수 있습니다.

<Frame caption="관리자 > 평가 > 추적 — Chat ID 또는 Message ID로 트레이스를 검색합니다">
  <img src="https://mintcdn.com/cloocus/Nim6rqpdwJuim_F0/images/monitoring/tracing-main.png?fit=max&auto=format&n=Nim6rqpdwJuim_F0&q=85&s=9e1577f200fc98e4bc563626ccc7f711" alt="추적 추적 검색 화면" width="2880" height="1800" data-path="images/monitoring/tracing-main.png" />
</Frame>

**예시 — 추적이 없을 때 vs 있을 때**

> 에이전트가 "해당 정보를 찾을 수 없습니다"라고 답변함

| 상태    | 할 수 있는 것             | 결과                       |
| ----- | -------------------- | ------------------------ |
| 추적 없음 | 추측만 가능               | 원인 파악 불가                 |
| 추적 활용 | Run 트리에서 검색 결과 0건 확인 | KB 문서 누락이 원인 → 문서 추가로 해결 |

<Note>
  추적은 라이선스 기능입니다. `trace` 피처가 활성화된 라이선스가 필요합니다.
</Note>

***

## 추적 개념

사용자 메시지 하나가 처리되는 과정에는 여러 단계가 포함됩니다.

* 추적은 이 모든 단계를 **Trace > Run** 계층 구조로 기록합니다.

```mermaid theme={null}
flowchart TB
    A[사용자 메시지] --> B[Trace 시작]
    B --> C[Response Chain]
    C --> D[가드레일 체크]
    C --> E[RAG 검색]
    C --> F[LLM 호출]
    C --> G[도구 실행]
    F --> H[응답 생성]
    H --> L[Trace 완료]

    A -.-> BG[background_tasks 트레이스]
    BG --> I[제목 생성]
    BG --> J[태그 생성]
    BG --> K[검색 쿼리 생성]
```

| 개념         | 설명                      |
| ---------- | ----------------------- |
| **Trace**  | 하나의 메시지에 대한 전체 처리 과정    |
| **Run**    | Trace 내의 개별 처리 단계       |
| **Run 트리** | 부모-자식 관계로 구성된 Run 계층 구조 |

***

## 추적 진입 방법

세 경로 모두 **평가 › 추적** 화면으로 이어집니다 — ①·② 버튼은 누르면 자동 이동, ③은 ID로 직접 검색입니다.

| 방법            | 적합한 상황                   | 진입 경로                           |
| ------------- | ------------------------ | ------------------------------- |
| **① 대화 로그에서** | 관리자가 운영 중 특정 대화를 조사 (정석) | 모니터링 › 대화 로그 › 대화 선택 › **추적**   |
| **② 채팅에서 바로** | 대화 중 방금 받은 응답을 즉시 확인     | 채팅 응답 액션바 › **추적 보기** 버튼        |
| **③ ID로 검색**  | 전달받은 ID로 특정 트레이스를 조사     | 평가 › 추적 › Chat ID·Message ID 검색 |

<Tabs>
  <Tab title="① 대화 로그에서 (관리자)">
    관리자가 운영 화면에서 특정 대화를 골라 추적으로 진입하는 정석 경로입니다.

    <Steps>
      <Step title="대화 로그 열기">
        **모니터링 › 대화 로그**로 이동합니다.
      </Step>

      <Step title="대화 선택">
        조사할 대화(요청) 행을 클릭해 상세를 엽니다.

        <Frame caption="대화를 펼치면 우측에 '추적' 버튼이 표시됩니다">
          <img src="https://mintcdn.com/cloocus/ZXRqlJ18bFKKL0k-/images/monitoring/tracing-entry-conversation-logs.png?fit=max&auto=format&n=ZXRqlJ18bFKKL0k-&q=85&s=5898f366de1cb54b95f70c0f73825347" alt="대화 로그에서 추적 버튼으로 진입" width="1369" height="981" data-path="images/monitoring/tracing-entry-conversation-logs.png" />
        </Frame>
      </Step>

      <Step icon="location-dot" title="평가 › 추적 도착">
        상세에서 **추적** 버튼을 클릭하면 자동으로 [**평가 › 추적**](#eval-trace-arrival) 화면이 열립니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="② 채팅에서 바로">
    채팅에서 방금 받은 응답을 그 자리에서 바로 추적하는 경로입니다.

    <Steps>
      <Step title="응답에서 '추적 보기' 클릭">
        추적하려는 응답 메시지 하단 액션바의 **추적 보기** 버튼을 누릅니다.

        <Frame caption="응답 하단 액션바의 '추적 보기' 버튼">
          <img src="https://mintcdn.com/cloocus/ZXRqlJ18bFKKL0k-/images/monitoring/tracing-entry-chat.png?fit=max&auto=format&n=ZXRqlJ18bFKKL0k-&q=85&s=b0801a7b188b23ebe8edf230fb3cd9f5" alt="채팅 응답의 추적 보기 버튼" width="1369" height="983" data-path="images/monitoring/tracing-entry-chat.png" />
        </Frame>

        표시되는 버튼은 권한에 따라 다릅니다.

        | 권한                 | 표시되는 버튼                             |
        | ------------------ | ----------------------------------- |
        | 관리자 또는 평가 읽기/쓰기 권한 | **추적 보기** → 평가 › 추적으로 이동            |
        | 그 외 사용자            | **Message ID 복사** → 관리자에게 전달해 조사 요청 |
      </Step>

      <Step icon="location-dot" title="평가 › 추적 도착">
        **추적 보기**를 누르면 자동으로 [**평가 › 추적**](#eval-trace-arrival) 화면이 열립니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="③ ID로 검색">
    Chat ID 또는 Message ID를 직접 입력해 트레이스를 찾습니다. 일반 사용자가 복사해 전달한 ID를 관리자가 조사할 때 주로 씁니다.

    <Steps>
      <Step title="Chat ID 확보">
        채팅 URL은 `https://<도메인>/c/{Chat ID}` 형태입니다. 주소창에서 `/c/` 다음 UUID(아래 파란 선택 영역)가 그 채팅의 Chat ID입니다 — 이 값을 복사합니다. (또는 사용자가 전달한 Message ID를 확보)

        <Frame caption="채팅 URL 주소창 — /c/ 다음의 파란 선택 영역이 Chat ID입니다">
          <img src="https://mintcdn.com/cloocus/Jjr6o_i720oXQtQO/images/monitoring/tracing-entry-id-search.png?fit=max&auto=format&n=Jjr6o_i720oXQtQO&q=85&s=c246d44f78a60cc392d53f0f4edd2a71" alt="채팅 URL 주소창에서 Chat ID가 파란색으로 선택된 화면" width="952" height="680" data-path="images/monitoring/tracing-entry-id-search.png" />
        </Frame>
      </Step>

      <Step icon="location-dot" title="평가 › 추적에서 조회">
        관리자 패널 › [**평가 › 추적**](#eval-trace-arrival) 검색창에 붙여넣어 조회합니다.
      </Step>
    </Steps>

    <Note>
      채팅 URL의 Chat ID는 채널 소유자·사용자가 보유합니다. 관리자는 사용자에게 URL(또는 **Message ID 복사**)을 요청해 전달받은 뒤 조사하세요.
    </Note>
  </Tab>
</Tabs>

<div id="eval-trace-arrival" />

<Card title="종착지 · 평가 › 추적" icon="location-dot">
  세 경로 어디로 진입하든, 도착지는 아래 **평가 › 추적** 화면 하나입니다.

  <Frame caption="평가 › 추적 도착 화면 — 검색 목록(메시지 카드)">
    <img src="https://mintcdn.com/cloocus/ZXRqlJ18bFKKL0k-/images/monitoring/tracing-arrival-search.png?fit=max&auto=format&n=ZXRqlJ18bFKKL0k-&q=85&s=d42aa6b9b654766cbb9c7b853b524f58" alt="평가 › 추적 — 메시지 카드 목록" width="1125" height="980" data-path="images/monitoring/tracing-arrival-search.png" />
  </Frame>
</Card>

도착하면 [검색 목록(메시지 카드)](#트레이스-검색)에서 트레이스를 골라 [상세 화면](#트레이스-상세-화면-읽는-법)을 엽니다.

***

## 트레이스 검색

평가 › 추적 화면에서 **Chat ID 또는 Message ID로 검색**하면, 위 화면처럼 **메시지 카드 목록**이 나옵니다.

* 카드 하나가 사용자 메시지 하나의 트레이스 요약이고, **카드를 클릭하면 [상세 화면](#트레이스-상세-화면-읽는-법)이 열립니다.**

검색 기준과 카드 항목 표는 아래에 접어 두었습니다.

<AccordionGroup>
  <Accordion title="검색 기준 — Chat ID vs Message ID" icon="magnifying-glass">
    | 검색 기준          | 찾는 범위             | 값을 얻는 곳                         |
    | -------------- | ----------------- | ------------------------------- |
    | **Chat ID**    | 그 채팅의 모든 메시지 트레이스 | 채팅 URL의 `/c/` 다음 부분             |
    | **Message ID** | 특정 메시지 하나의 트레이스   | 사용자가 메시지 옵션에서 **Message ID 복사** |

    <Note>
      검색은 입력한 ID에 해당하는 모든 트레이스를 기간 제한 없이 가져옵니다. (날짜·상태 같은 별도 필터는 없습니다.)
    </Note>
  </Accordion>

  <Accordion title="메시지 카드 항목" icon="address-card">
    | 카드 항목       | 설명                                      |
    | ----------- | --------------------------------------- |
    | **사용자 메시지** | 원본 입력 (최대 2줄)                           |
    | **트레이스 ID** | 식별자 축약 표시 (예: `3fb13ae9…`)              |
    | **시각**      | 요청 시각 (`MM/DD HH:MM:SS`)                |
    | **지연 시간**   | 전체 처리 시간 (초)                            |
    | **종류 배지**   | 포함된 단계 종류 — `Agent` · `LLM` · `Embed` 등 |
    | **Run 수**   | 단계 개수 (예: `3 runs`)                     |
  </Accordion>
</AccordionGroup>

***

## 트레이스 상세 화면 읽는 법

여기가 추적의 핵심입니다.

* 한 메시지가 **어떤 단계를 거쳐 처리됐는지**, 각 단계에 **무엇이 들어가고 나왔는지**를 모두 여기서 봅니다.

(배지·기호 같은 세부 표기는 각 탭 안에 접어 두었습니다 — 처음 보는 표시를 만났을 때 펼쳐 보세요.)

<Frame caption="트레이스 상세 — 좌측 Run 트리에서 단계를 고르면 우측에 그 단계의 입·출력이 표시됩니다">
  <img src="https://mintcdn.com/cloocus/KEDVv5ut_6sqAaDJ/images/monitoring/tracing-detail-modal.png?fit=max&auto=format&n=KEDVv5ut_6sqAaDJ&q=85&s=57c9aa30cebf2ddeb95b076c8a9bfe9b" alt="트레이스 상세 모달 — 좌측 Run 트리, 우측 상세 패널" width="2832" height="1748" data-path="images/monitoring/tracing-detail-modal.png" />
</Frame>

화면은 **좌측 Run 트리**(처리 단계를 순서·계층대로 나열, 상단에 전체 지연·총 토큰)와 **우측 상세 패널**(고른 단계의 입·출력·토큰)로 나뉩니다.

한 메시지는 보통 — 에이전트(`CH`)가 `LM` 추론과 도구 호출을 반복해 데이터를 모으고, 마지막에 `final_answer`(`LM`)가 답을 씁니다.

<Tabs>
  <Tab title="좌측 — Run 트리">
    각 줄(Run)은 **색 배지 + 이름 + ● 상태 + 지연 시간**으로 표시됩니다. 자주 보이는 배지만 알면 트리를 읽을 수 있습니다. (색 포함 전체 종류는 아래 범례를 펼쳐 보세요.)

    |    배지   | 하는 일                                                 |
    | :-----: | ---------------------------------------------------- |
    |  **CH** | 에이전트 실행 — 메시지 처리 전체를 감싸는 단계 (이름은 에이전트명, 예 `dv_test`) |
    |  **LM** | LLM 호출 — 추론하거나 최종 답 작성(`final_answer`)               |
    |  **TL** | 도구 실행 — SQL 조회·함수 호출(`run_sql_read` 등)               |
    |  **EM** | 임베딩 — 검색용 벡터 생성                                      |
    | **ACT** | 작업 그룹 — 도구 + 하위 단계 묶음 (화살표로 펼침)                      |

    * **● 상태** — 초록이면 정상, 빨강이면 그 단계에서 오류.
    * **옆 시간** — 그 단계의 지연. 값이 가장 큰 단계가 병목입니다.

    <Note>
      제목·태그·검색 쿼리 자동 생성 같은 보조 작업은 응답과 별개로 `background_tasks` 트레이스에 따로 기록됩니다.
    </Note>

    <AccordionGroup>
      <Accordion title="Run 종류 전체 (색상 범례)" icon="table-cells">
        상세 트리는 단계 종류를 색 배지로 구분합니다. (검색 결과 카드에서는 `Agent`·`LLM`·`Embed` 같은 라벨로 묶여 표시됩니다.)

        |    배지   | 종류         |  색  | 설명                            |
        | :-----: | ---------- | :-: | ----------------------------- |
        |  **CH** | Chain      |  보라 | 복합 작업 — 메시지 처리 전체/에이전트 실행     |
        |  **LM** | LLM        |  파랑 | LLM 호출 (추론·최종 답변)             |
        |  **TL** | Tool       |  초록 | 도구 실행 (SQL·함수 등)              |
        |  **RG** | Retrieval  |  주황 | 지식 기반 문서 검색                   |
        |  **WB** | Web Search |  시안 | 웹 검색                          |
        |  **GD** | Guardrail  |  빨강 | 가드레일 점검                       |
        |  **EM** | Embedding  |  노랑 | 임베딩(벡터) 생성                    |
        |  **FL** | Filter     |  분홍 | 필터 함수 실행                      |
        |  **PP** | Pipeline   |  남색 | 파이프라인 처리                      |
        |  **TK** | Task       |  회색 | 백그라운드 태스크                     |
        |  **IM** | Image      |  회색 | 이미지 생성 (전용 색 없이 회색으로 표시)      |
        | **ACT** | Action     |  보라 | 도구 + 하위 단계 그룹 (펼치기 가능, 합성 배지) |
      </Accordion>

      <Accordion title="상태 표시 (● 기호·색)" icon="circle-dot">
        | 상태          |  기호 |  색  |
        | ----------- | :-: | :-: |
        | **Success** |  ●  |  초록 |
        | **Error**   |  ●  |  빨강 |
        | **Running** |  ◐  |  노랑 |
        | **Pending** |  ○  |  회색 |

        <Note>
          트레이스 전체 상태는 포함된 Run 중 **하나라도 Error면 Error**, Error가 없고 Running이 있으면 Running으로 표시됩니다.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="우측 — 상세 패널">
    트리에서 단계를 클릭하면 우측에 그 단계의 상세가 표시됩니다.

    | 섹션              | 내용                                                 |
    | --------------- | -------------------------------------------------- |
    | **상단 요약**       | 상태 · 지연 시간 · 사용 모델                                 |
    | **Inputs**      | 입력 (시스템 프롬프트, 정규화된 질문 등)                           |
    | **Outputs**     | 출력 (응답, 검색된 출처 수 `sources_count`·`source_names` 등) |
    | **Token Usage** | **Input · Output · Total** 토큰                      |

    * **Tree · JSON · Text** 토글로 입·출력을 트리/원본 JSON/평문으로 전환합니다.
    * Outputs의 **Search…** 칸으로 긴 출력에서 텍스트를 찾을 수 있습니다.

    <Accordion title="입·출력 보기 모드 · 텍스트 검색" icon="code">
      | 보기 모드    | 설명          |
      | -------- | ----------- |
      | **Tree** | 계층적 트리 (기본) |
      | **JSON** | 원본 JSON     |
      | **Text** | 평문 텍스트      |

      Outputs 영역에서는 텍스트 검색이 됩니다. 검색어를 입력하면 하이라이트되고, **Enter**로 다음·**Shift+Enter**로 이전 매치로 이동하며, 검색창 옆에 `1/5`처럼 매치 수가 표시됩니다.
    </Accordion>
  </Tab>
</Tabs>

### 두 단계(Phase)로 읽기

에이전트 응답은 **두 단계**로 나눠 읽으면 원인을 빨리 찾을 수 있습니다.

```mermaid theme={null}
flowchart TD
    A["CH 에이전트 실행 — Phase 1: 데이터 수집"] --> B["LM 추론 — 어떤 도구를 쓸지 판단"]
    B --> C["TL run_sql_read — DB 조회"]
    B --> D["TL get_table_details — 스키마 확인"]
    B --> E["LM 추론 — 다음 단계 판단"]
    A --> F["LM final_answer — Phase 2: 최종 답변 작성"]
```

|      단계     | 무엇을                                          | 여기서 보는 것              |
| :---------: | -------------------------------------------- | --------------------- |
| **Phase 1** | 에이전트(`CH`)가 `LM` 추론으로 도구(`TL`)를 호출하며 데이터를 모음 | 어떤 도구를 썼나, 결과가 비지 않았나 |
| **Phase 2** | `final_answer`(`LM`)가 모은 데이터로 답을 작성          | 모은 데이터가 답에 제대로 반영됐나   |

### 디버깅 포인트

<AccordionGroup>
  <Accordion title="에이전트가 도구(지식 기반·DB)를 쓰지 않았다면?" icon="magnifying-glass">
    Phase 1의 **LM 추론 Run**의 Inputs에서 `active_capabilities`(그 시점에 쓸 수 있는 도구·기능)를 확인하세요.

    * **원하는 도구가 목록에 없음** → 에이전트에 해당 기능(지식 기반·DB 등)이 연결되지 않음
    * **도구가 있는데 호출 안 함** → 모델이 질문과 도구의 관련성을 낮게 판단. 도구·기능 설명을 더 구체적으로 수정
  </Accordion>

  <Accordion title="검색은 됐는데 답변이 부정확하다면?" icon="file-circle-question">
    `final_answer`(**LM**) Run의 Outputs에서 `sources_count`와 `source_names`를 확인하세요. (검색 결과는 별도 Run이 아니라 이 출력에 담깁니다.)

    * **`sources_count`가 0** → 검색이 0건. 지식 기반 문서 누락 또는 검색 설정(Top K·Reranker 등) 점검 필요
    * **출처는 있는데 답이 엉뚱** → 같은 Run의 Inputs에서 전달된 내용을 확인하고 답변 프롬프트를 조정
  </Accordion>

  <Accordion title="도구 실행이 실패했다면?" icon="circle-exclamation">
    빨간색 ● 표시된 **TL (Tool) Run**을 클릭해 Outputs의 오류 내용과 Inputs로 전달된 파라미터를 함께 확인하세요.
  </Accordion>

  <Accordion title="응답이 너무 느리다면?" icon="clock">
    Run 트리에서 각 단계 옆의 <strong>지연 시간</strong>을 비교하세요. 가장 오래 걸린 단계가 병목입니다.

    * **LM**이 느림 → 더 빠른 모델로 변경 고려
    * **TL/EM**이 느림 → 도구·검색 설정 또는 외부 서비스 확인
    * **GD**(가드레일)가 느림 → LLM 판정 비활성화 또는 빠른 모델로 변경
  </Accordion>
</AccordionGroup>

## 트레이스 분석 리포트

트레이스 데이터를 LLM으로 분석하여 **문제의 근본 원인을 자동으로 파악**하는 기능입니다.

<Steps>
  <Step title="분석 시작">
    트레이스 상세 모달 상단의 **트레이스 분석**(Analyze Trace) 버튼을 클릭합니다.

    | 입력 항목     | 설명             | 필수 |
    | --------- | -------------- | -- |
    | **분석 모델** | 분석에 사용할 LLM 모델 | 필수 |
    | **문제 설명** | 관찰된 문제 상황 기술   | 선택 |

    <Note>
      분석 모델 목록에는 base\_model\_id가 설정된 모델(커스텀 모델), 프리셋 모델, 아레나 모델은 표시되지 않습니다. 기본(base) 모델만 선택할 수 있습니다.
    </Note>
  </Step>

  <Step title="분석 결과 확인">
    LLM이 트레이스 데이터 + 에이전트 설정 + 대화 이력 + KB/DB/가드레일 설정을 종합 분석하여 구조화된 리포트를 생성합니다.

    | 리포트 섹션         | 내용                                  |
    | -------------- | ----------------------------------- |
    | **요약**         | 분석 결과 2\~3문장 핵심 요약                  |
    | **트레이스 개요**    | ID, 상태, 지연시간, 토큰, Run 수, 오류 수       |
    | **근본 원인 분석**   | 주요 원인 + 기여 요인                       |
    | **Phase 1 분석** | 도구 선택이 적절했는지, 사용 가능한 도구 vs 실제 호출 비교 |
    | **Phase 2 분석** | 수집된 데이터 대비 최종 답변의 적절성               |
    | **프롬프트/설정 이슈** | 시스템 프롬프트, 모델 선택 문제                  |
    | **KB/RAG 이슈**  | 검색 설정, 문서 품질, 필터 문제                 |
    | **DB/SQL 이슈**  | NL-to-SQL 변환, 스키마 문제                |
    | **가드레일 이슈**    | 과도한 차단, 오탐                          |
    | **오류 분석**      | Error Run 상세 진단                     |
    | **개선 권장사항**    | 즉시 조치, 설정 변경, 데이터 개선                |

    <Tip>
      문제 설명을 입력하면 해당 맥락에 집중한 분석이 가능합니다. 예: "KB에서 문서를 찾았는데 답변에 반영되지 않음"
    </Tip>
  </Step>

  <Step title="리포트 저장/공유">
    | 기능       | 설명                 |
    | -------- | ------------------ |
    | **복사**   | 클립보드에 전체 텍스트 복사    |
    | **다운로드** | 마크다운 파일(.md)로 다운로드 |
  </Step>
</Steps>

<Note>
  이전에 분석한 리포트가 있는 경우, **"리포트 보기"** 버튼으로 재분석 없이 바로 확인할 수 있습니다.
</Note>

***

## 트레이스 관리

### 권한

| 역할         | 권한                   |
| ---------- | -------------------- |
| **일반 사용자** | 자신의 트레이스만 조회 가능      |
| **관리자**    | 모든 사용자의 트레이스 조회 및 관리 |

### 데이터 정리

오래된 트레이스는 `/api/traces/cleanup` **개발자용 API**로 정리합니다.

* 타임스탬프(밀리초, ms 단위)로 특정 시점 이전의 트레이스를 일괄 삭제합니다.

<Warning>
  트레이스 삭제는 복구할 수 없습니다. 삭제 전 필요한 분석 리포트를 먼저 다운로드하세요.
</Warning>

***

## 활용 사례

<AccordionGroup>
  <Accordion title="응답 품질 디버깅" icon="magnifying-glass-chart">
    1. 채팅 메시지의 **추적 보기** 버튼을 클릭합니다
    2. 좌측 Run 트리에서 `final_answer`(**LM**) 단계를 선택합니다
    3. **Outputs**에서 `sources_count`·`source_names`로 검색 결과 반영 여부를 확인합니다
    4. **Inputs**에서 모델에 전달된 내용을 확인합니다
    5. **트레이스 분석 리포트**를 생성하여 근본 원인을 자동 파악합니다
  </Accordion>

  <Accordion title="지연 시간 분석" icon="clock">
    1. 느린 응답의 트레이스를 엽니다
    2. Run 트리에서 각 단계 옆의 <strong>지연 시간</strong>을 비교합니다
    3. 가장 오래 걸린 단계를 식별합니다 (예: 도구 0.8s, LLM 3.2s)
    4. 해당 단계를 최적화합니다 (검색 설정 조정, 모델 변경 등)
  </Accordion>

  <Accordion title="도구 실행 오류 추적" icon="circle-exclamation">
    1. 문제가 의심되는 트레이스를 엽니다
    2. 빨간색 ● 표시된 **TL (Tool) Run**을 선택합니다
    3. **Outputs**에서 오류 내용을 확인합니다
    4. **Inputs**에서 전달된 파라미터를 검증합니다
  </Accordion>

  <Accordion title="토큰 사용량 분석" icon="coins">
    1. 상세 화면 상단의 **총 토큰**으로 트레이스 전체 사용량을 확인합니다
    2. Run 트리에서 LM Run별 **Token Usage**(Input/Output/Total)를 비교합니다
    3. Phase 1(에이전트 실행)과 Phase 2(`final_answer`)의 토큰 비율을 확인합니다
    4. 불필요하게 큰 프롬프트나 반복 호출이 있는지 식별합니다
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="추적은 자동으로 기록되나요?" icon="circle-question">
    네, 메시지 추적이 활성화되어 있으면 (기본값: 활성) 모든 AI 요청이 자동으로 기록됩니다. 별도 설정이 필요 없습니다.
  </Accordion>

  <Accordion title="트레이스 데이터는 얼마나 보존되나요?" icon="circle-question">
    기본 보존 기간은 **30일**입니다. 관리자가 설정을 변경하거나 수동으로 정리할 수 있습니다.
  </Accordion>

  <Accordion title="추적이 응답 속도에 영향을 주나요?" icon="circle-question">
    트레이스 기록은 백그라운드로 비동기 처리되므로 응답 속도에 거의 영향을 주지 않습니다.
  </Accordion>

  <Accordion title="분석 리포트도 토큰을 소비하나요?" icon="circle-question">
    네, 트레이스 분석은 별도의 LLM 호출이며 사용량이 `trace_analysis`로 별도 추적됩니다. 분석은 수동으로 트리거할 때만 실행됩니다.
  </Accordion>
</AccordionGroup>

***

## 관련 페이지

<Columns cols={3}>
  <Card title="가드레일 로그" icon="shield-check" href="/ko/monitoring/guardrail-logs">
    가드레일 탐지 이벤트 전용 로그
  </Card>

  <Card title="자동 평가" icon="chart-line" href="/ko/monitoring/auto-evaluations">
    에이전트 응답 품질 자동 평가 결과
  </Card>

  <Card title="사용량" icon="coins" href="/ko/monitoring/usage">
    토큰 사용량 및 비용 분석
  </Card>
</Columns>