메인 콘텐츠로 건너뛰기
에이전트가 엉뚱한 답변을 했을 때, “왜 이렇게 답했는지” 알 수 없어 답답한 경험이 있으신가요? 트레이싱은 AI 요청이 처리되는 전 과정을 단계별로 추적합니다. 어떤 문서를 검색했는지, 어떤 도구를 호출했는지, LLM에 어떤 프롬프트가 전달됐는지 — 모든 단계를 투명하게 확인할 수 있습니다.

​
예시

에이전트가 “해당 정보를 찾을 수 없습니다”라고 답변함
상태할 수 있는 것결과
트레이싱 없음추측만 가능원인 파악 불가
트레이싱 활용Run tree에서 RAG 검색 → 0건 반환 확인KB 문서 누락이 원인 → 문서 추가로 해결
관리자 > 평가 > 트레이싱 탭에서 접근합니다.
트레이싱 메인 화면
트레이싱은 라이선스 기능입니다. trace 피처가 활성화된 라이선스가 필요합니다.

​
트레이싱 개념

사용자 메시지 하나가 처리되는 과정에는 여러 단계가 포함됩니다. 트레이싱은 이 모든 단계를 Trace > Run 계층 구조로 기록합니다.
개념설명
Trace하나의 메시지에 대한 전체 처리 과정
RunTrace 내의 개별 처리 단계
Run 트리부모-자식 관계로 구성된 Run 계층 구조

​
트레이스 검색

​
검색 방법

검색 타입설명
Chat ID특정 채팅의 모든 트레이스 조회
Message ID특정 메시지의 트레이스만 조회

​
필터 옵션

필터옵션
기간최근 1일, 7일, 30일, 전체
상태Success, Error, Running, Pending
유형Chain, LLM, Tool, Retrieval, Web Search, Guardrail, Embedding
사용자특정 사용자별 필터링 (관리자 전용)
Chat ID 또는 Message ID로 검색할 때는 날짜 필터가 적용되지 않습니다. 해당 ID에 대한 모든 트레이스가 기간과 관계없이 조회됩니다.
채팅 화면에서 메시지 옵션 메뉴의 **“트레이싱 보기”**를 클릭하면 해당 메시지의 트레이스 화면으로 바로 이동할 수 있습니다.

​
메시지 카드

검색 결과는 메시지 카드 목록으로 표시됩니다.
항목설명
사용자 메시지원본 입력 메시지 (최대 2줄)
Message ID메시지 식별자 (축약 표시)
시간요청 시간
총 지연시간전체 처리 시간 (ms)
총 토큰전체 토큰 사용량 (prompt + completion)
트레이스 배지각 Run 유형별 상태 표시

​
트레이스 상세 조회

메시지 카드를 클릭하면 상세 트레이스 모달이 열립니다. 좌측에 Run 트리, 우측에 선택된 Run의 상세 정보가 표시됩니다.
트레이스 상세 모달

​
Run 트리 구조

좌측 패널에서 처리 단계가 트리 구조로 표시됩니다. 
[CH] Response               2.34s
  ├─ [GD] guardrail:보안    0.05s
  ├─ [RG] KnowledgeBase     0.32s
  ├─ [LM] GPT-4             1.89s
  └─ [TL] web_search        0.13s

​
Run 타입

약어타입색상설명
CHChain보라복합 작업 (메시지 처리 전체)
LMLLM파랑LLM API 호출
TLTool초록도구 실행
RGRetrieval주황RAG 문서 검색
WBWeb Search시안웹 검색
GDGuardrail빨강가드레일 체크
EMEmbedding노랑임베딩 생성
IMImage남색이미지 생성
ACTAction보라도구 + 하위 작업 그룹 (펼치기 가능)
TKTask회색백그라운드 태스크

​
상태 표시

상태기호색상
Success●초록
Error●빨강
Running◐노랑
Pending○회색
트레이스 전체 상태는 포함된 Run 중 하나라도 Error가 있으면 Error, Error가 없고 Running이 있으면 Running으로 표시됩니다.

​
Run 상세 정보

우측 패널에서 선택한 Run의 상세 정보를 확인합니다.
섹션설명
Status상태, 지연시간, 모델 ID
Inputs입력 데이터 (시스템 프롬프트, 사용자 메시지 등)
Outputs출력 데이터 (AI 응답, 검색 결과 등)
Error오류 메시지 (오류 발생 시)
Token Usageprompt_tokens, completion_tokens, total_tokens (LLM 타입)

​
뷰 모드

Inputs/Outputs는 세 가지 형식으로 볼 수 있습니다.
모드설명
Tree계층적 트리 구조 (기본)
JSON원본 JSON 형식
Text평문 텍스트

​
텍스트 검색

Outputs 영역에서 텍스트를 검색할 수 있습니다.
동작방법
검색검색어 입력 시 노란색 하이라이트
다음 매치Enter
이전 매치Shift + Enter
매치 수검색창 옆 1/5 형식으로 표시

​
트레이스 유형

​
메인 응답

사용자 메시지에 대한 AI 응답 생성 과정입니다.
유형설명
Response전체 응답 생성 (최상위 Chain)
LLMLLM API 호출
RAG지식기반 검색
Tool도구 실행
Search웹 검색
Guard가드레일 체크

​
백그라운드 작업

채팅 보조 기능을 위한 백그라운드 작업입니다.
유형설명
Title채팅 제목 자동 생성
Tag채팅 태그 자동 생성
QueryRAG 검색 쿼리 생성
Emoji채팅 이모지 생성
Autocomplete자동완성 제안
Function함수 호출 판단

​
Run 트리 읽는 법

에이전트의 Run 트리는 2단계(Phase)로 구성됩니다. 이 구조를 이해하면 문제의 원인을 빠르게 찾을 수 있습니다.
PhaseRun 이름하는 일
Phase 1react_agent (CH)LLM이 도구를 호출하며 데이터를 수집하는 단계. KB 검색, DB 조회, 웹 검색 등이 여기서 실행됨
Phase 2final_answer (LM)수집된 데이터를 종합하여 최종 답변을 작성하는 단계

​
디버깅 포인트

Phase 1의 첫 번째 LM Run의 Inputs를 확인하세요. tool_descriptions에 지식기반 도구가 포함되어 있는지 확인합니다.
  • 도구가 목록에 없음 → 에이전트에 지식기반이 연결되지 않았거나 도구 설명이 비어 있음
  • 도구가 있는데 호출 안 함 → LLM이 질문과 도구의 관련성을 낮게 판단. 도구 설명(Tool Description)을 더 구체적으로 수정
RG (Retrieval) Run의 Outputs에서 검색된 문서 내용을 확인하세요.
  • 검색 결과가 관련 없음 → KB 문서 품질 문제 또는 검색 설정(Top K, Reranker) 조정 필요
  • 검색 결과는 좋은데 답변이 엉뚱함 → Phase 2 final_answer LM Run의 Inputs에서 전달된 context를 확인. 답변 포맷 프롬프트 조정 필요
빨간색 ● 표시된 TL (Tool) Run을 클릭하여 Error 섹션을 확인하세요. Inputs에서 전달된 파라미터도 함께 검증합니다.
Run 트리에서 각 단계 옆의 **지연시간(ms)**을 비교하세요. 가장 오래 걸린 단계가 병목입니다.
  • LM Run이 느림 → 더 빠른 모델로 변경 고려
  • RG/TL Run이 느림 → 검색 설정 또는 외부 서비스 확인
  • GD Run이 느림 → LLM Judge 비활성화 또는 빠른 모델로 변경

​
트레이스 분석 리포트

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

분석 시작

트레이스 상세 모달 상단의 “트레이스 분석” 버튼을 클릭합니다.
입력 항목설명필수
분석 모델분석에 사용할 LLM 모델필수
문제 설명관찰된 문제 상황 기술선택
분석 모델 목록에는 base_model_id가 설정된 모델(커스텀 모델), 프리셋 모델, 아레나 모델은 표시되지 않습니다. 기본(base) 모델만 선택할 수 있습니다.
2

분석 결과 확인

LLM이 트레이스 데이터를 분석하여 구조화된 리포트를 생성합니다.LLM이 트레이스 데이터 + 에이전트 설정 + 대화 이력 + KB/DB/가드레일 설정을 종합 분석하여 리포트를 생성합니다.
리포트 섹션내용
요약분석 결과 2~3문장 핵심 요약
트레이스 개요ID, 상태, 지연시간, 토큰, Run 수, 오류 수
근본 원인 분석주요 원인 + 기여 요인
Phase 1 분석도구 선택이 적절했는지, 사용 가능한 도구 vs 실제 호출 비교
Phase 2 분석수집된 데이터 대비 최종 답변의 적절성
프롬프트/설정 이슈시스템 프롬프트, 모델 선택 문제
KB/RAG 이슈검색 설정, 문서 품질, 필터 문제
DB/SQL 이슈NL-to-SQL 변환, 스키마 문제
가드레일 이슈과도한 차단, 오탐
오류 분석Error Run 상세 진단
개선 권장사항즉시 조치, 설정 변경, 데이터 개선
문제 설명을 입력하면 해당 맥락에 집중한 분석이 가능합니다. 예: “KB에서 문서를 찾았는데 답변에 반영되지 않음”
3

리포트 저장/공유

기능설명
복사클립보드에 전체 텍스트 복사
다운로드마크다운 파일(.md)로 다운로드
이전에 분석한 리포트가 있는 경우, “리포트 보기” 버튼으로 재분석 없이 바로 확인할 수 있습니다.

​
트레이스 관리

​
권한

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

​
데이터 정리

오래된 트레이스는 관리자가 /api/traces/cleanup API를 통해 정리할 수 있습니다. 타임스탬프(밀리초, ms 단위)로 특정 시점 이전의 트레이스를 일괄 삭제합니다.
트레이스 삭제는 복구할 수 없습니다. 삭제 전 필요한 분석 리포트를 먼저 다운로드하세요.

​
활용 사례

  1. 채팅 메시지의 “트레이싱 보기” 버튼을 클릭합니다
  2. 문제 메시지의 Run 트리를 펼칩니다
  3. RG (Retrieval) Run → Outputs에서 검색된 문서를 확인합니다
  4. LM (final_answer) Run → Inputs에서 전달된 context를 확인합니다
  5. 트레이스 분석 리포트를 생성하여 근본 원인을 자동 파악합니다
  1. 느린 응답의 트레이스를 조회합니다
  2. Run 트리에서 각 단계 옆의 **지연시간(ms)**을 비교합니다
  3. 가장 오래 걸린 단계를 식별합니다 (예: RAG 0.8s, LLM 3.2s)
  4. 해당 단계를 최적화합니다 (검색 설정 조정, 모델 변경 등)
  1. Error 상태로 필터링합니다
  2. 빨간색 ● 표시된 실패 Run을 선택합니다
  3. Error 섹션에서 오류 메시지를 확인합니다
  4. Inputs에서 전달된 파라미터를 검증합니다
  1. 메시지 카드의 총 토큰 수를 확인합니다
  2. Run 트리에서 LM Run별 prompt_tokens / completion_tokens를 비교합니다
  3. Phase 1(react_agent)과 Phase 2(final_answer)의 토큰 비율을 확인합니다
  4. 불필요하게 큰 프롬프트나 반복 호출이 있는지 식별합니다

​
채팅에서 트레이싱 접근

채팅 화면에서 메시지 옵션 메뉴의 “트레이싱 보기” 버튼을 클릭하면 해당 메시지의 트레이스 화면으로 바로 이동합니다.
권한표시되는 버튼
관리자 또는 평가 읽기/쓰기 권한트레이싱 보기 → 트레이스 화면으로 이동
그 외 사용자Message ID 복사 → 관리자에게 전달하여 조사 요청
일반 사용자가 응답에 문제를 발견하면 Message ID를 복사하여 관리자에게 전달하세요. 관리자가 해당 ID로 트레이스를 조회하여 원인을 파악할 수 있습니다.

​
FAQ

네, 메시지 트레이싱이 활성화되어 있으면 (기본값: 활성) 모든 AI 요청이 자동으로 기록됩니다. 별도 설정이 필요 없습니다.
기본 보존 기간은 30일입니다. 관리자가 설정을 변경하거나 수동으로 정리할 수 있습니다.
트레이스 기록은 백그라운드로 비동기 처리되므로 응답 속도에 거의 영향을 주지 않습니다.
네, 트레이스 분석은 별도의 LLM 호출이며 사용량이 trace_analysis로 별도 추적됩니다. 분석은 수동으로 트리거할 때만 실행됩니다.

​
관련 페이지

가드레일 로그

가드레일 탐지 이벤트 전용 로그

자동 평가

에이전트 응답 품질 자동 평가 결과

사용량

토큰 사용량 및 비용 분석