트라젝토리 뷰와 중지

트라젝토리는 하나의 LLM 작업 흐름에 참여한 트랜잭션을 mtid 기준으로 묶은 단위입니다. 트랜잭션이 여러 개 묶여 있거나 흐름이 여러 프로세스를 거쳐도 트라젝토리 하나로 봅니다.

이 문서에서는 실행 중인 트라젝토리를 목록과 실행 흐름 차트로 확인하는 방법과, 문제가 있는 트라젝토리를 화면에서 중지하는 방법을 안내합니다.

노트

트라젝토리 중지는 Python SDK 2.2.1 이상에서 사용할 수 있습니다. Java SDK는 중지를 지원하지 않습니다.

진입 경로

화면	여는 방법
액티브 트라젝토리 목록	종합 현황 대시보드나 AI 에이전트 메인 대시보드의 액티브 트라젝토리 위젯에서 궤도 차트(전체 목록), 등급 행(해당 등급 목록), 헤더의 상세 아이콘(전체 목록)을 클릭합니다. 대시보드가 실시간일 때만 열 수 있으며, 건수가 0인 등급은 클릭할 수 없습니다.
트라젝토리 뷰	액티브 트라젝토리 목록에서 그룹 헤더나 트랜잭션 행을 클릭하거나, 액티브 LLM API 위젯의 실행 중 호출 목록에서 호출을 선택합니다.
트라젝토리 뷰 탭	LLM 트레이스 상세에서 트라잭토리 뷰 탭을 선택합니다. 해당 트랜잭션이 속한 트라젝토리를 표시합니다.

대시보드에서 연 목록과 뷰는 창(모달)으로 열립니다. 창 헤더의 새 창 열기 버튼을 클릭하면 별도 창으로 띄울 수 있으며, 등급으로 거른 목록은 별도 창에서도 같은 등급으로 열립니다. 별도 창으로 띄운 목록에서 트라젝토리를 선택하면 같은 창이 트라젝토리 뷰로 바뀌고, 뒤로 가기 버튼을 클릭하면 목록으로 돌아갑니다.

액티브 트라젝토리 목록

지금 실행 중인 트랜잭션을 트라젝토리별로 묶어 보여 주는 목록입니다. 창 제목은 "액티브 트라잭토리"로 표시됩니다.

• 목록 위쪽에 트라젝토리 수와 트랜잭션 수, CSV 다운로드 버튼, 검색 입력란(이름 / 사용자 / 세션)이 있습니다. 검색어는 트랜잭션 이름, 사용자, 세션, mtid에서 찾습니다.

• 트라젝토리마다 그룹 헤더가 있고, 그 아래에 묶인 트랜잭션이 행으로 표시됩니다. 그룹 헤더나 트랜잭션 행을 클릭하면 그 트라젝토리의 트라젝토리 뷰가 열립니다.

• 목록은 트라젝토리별 스텝 합계가 많은 순으로 정렬되어 열립니다. 트랜잭션은 최대 100건까지 조회됩니다.

• 진행 중인 트랜잭션만 표시합니다. 끝난 트랜잭션은 목록에서 빠집니다.

그룹 헤더

항목	설명
등급	Light, Middle, Heavy. 트라젝토리 전체에 매기는 등급이며 속도나 실행 시간을 뜻하지 않습니다. 등급 경계값은 SDK 옵션에 설정한 기준을 따릅니다. 등급 정보가 없으면 Unknown으로 표시합니다.
mtid	트라젝토리를 묶는 키. mtid가 없는 단독 흐름은 "단독 실행"으로 표시합니다.
tx N	묶인 트랜잭션 수. 검색으로 거른 경우 남은 트랜잭션 수입니다.
사용자, 세션	로그에 부착된 user_id, session_id. 값이 없으면 -로 표시합니다.
정지	트라젝토리를 중지합니다. 트라젝토리 중지를 참조하세요.

트랜잭션 행

컬럼	설명
트랜잭션	트랜잭션 이름. [Workflow], [Agent] 같은 접두어를 포함한 원문입니다.
스텝	트랜잭션이 수행한 스텝 수
에이전트	트랜잭션이 실행한 AI 서브에이전트 수. 없으면 -로 표시합니다.
LLM 호출 수	트랜잭션 안에서 발생한 LLM 호출 수
경과	트랜잭션 시작 후 경과 시간

노트

CSV 파일에는 화면의 컬럼 외에 상태, mtid, 사용자, 세션 컬럼이 행마다 들어갑니다. 상태 값은 진행 상태가 아니라 그 트랜잭션이 속한 트라젝토리의 등급(Light, Middle, Heavy, Unknown)입니다.

시간 컨트롤

목록은 연 시점에 멈춘 상태로 열립니다. 목록을 읽는 동안 정렬 순서가 바뀌지 않게 하기 위해서입니다.

• 재생 버튼을 클릭하면 설정한 주기마다 목록을 갱신합니다. 다시 클릭하면 그 시점에서 멈춥니다.

• 새로고침 버튼을 클릭하면 현재 시점으로 한 번만 갱신합니다.

• 설정 버튼을 클릭하고 자동 갱신(초) 값을 바꾸면 갱신 주기를 10~30초(5초 단위, 기본 10초)로 정할 수 있습니다.

트라젝토리 뷰

트라젝토리 하나의 실행 흐름을 차트로 보여 주는 화면입니다. 창 제목은 "트라잭토리 뷰"로 표시됩니다.

• 상단 도구: 프로젝트 선택과 시간 컨트롤이 있습니다. 프로젝트 선택에서는 현재 프로젝트와 함께 조회할 AI Agent Observability 프로젝트를 고를 수 있습니다. 시간 컨트롤은 목록과 같이 연 시점에 멈춘 상태로 열립니다. 트라젝토리가 끝나면 시간 선택과 갱신 주기 설정이 비활성화되고 완료 또는 실패 태그가 붙습니다.

• 헤더: 루트 트랜잭션 이름, 상태 태그(실행 중, 완료, 실패), 정지 버튼이 있습니다.

• 정보 줄: mtid(없으면 단독 실행), 사용자, 세션, 경과 시간을 표시합니다. 사용자와 세션은 값이 있을 때만 표시합니다.

실행 흐름 차트

• 세로축은 시간, 가로축은 위임 깊이입니다. 긴 공백 구간은 접어서 표시합니다.

• 카드 하나가 트랜잭션 하나입니다. 카드에는 종류(WORKFLOW, AGENT, LLM API), 이름, 경과 시간, 스텝 수, 상태(실행 중, 완료, 에러, 미수집)가 표시됩니다. 종류 태그가 없는 트랜잭션도 AGENT로 표시됩니다.

• 같은 부모 아래에서 동시에 시작하거나 순서대로 이어진 트랜잭션이 4건 이상이면, 또는 하위 위임이 4단계 이상 이어지면 앞의 3건만 카드로 표시하고 나머지는 "+N · 동시", "+N · 순차", "+N · 하위 위임" 타일로 접습니다. 타일을 클릭하면 펼쳐지고, "트랜잭션 N · 접기"를 클릭하면 다시 접힙니다.

• 부모 트랜잭션이 수집되지 않았으면 그 자리에 "(미수집)" 카드를 표시합니다. 조회 결과에서 하위 트랜잭션 일부가 생략되면 그 부모 아래에 "+N건 미표시" 카드를 표시합니다.

• 트라젝토리를 찾지 못하면 "트라잭토리를 찾을 수 없습니다."가 표시됩니다.

• 이미 끝난 트라젝토리는 차트 대신 트랜잭션 보기 버튼이 표시되며, 클릭하면 LLM 트레이스 상세가 열립니다. LLM 트레이스 상세의 트라잭토리 뷰 탭에서는 끝난 트라젝토리도 차트로 표시합니다.

스텝 상세

차트에서 카드를 클릭하면 오른쪽에 그 트랜잭션의 스텝 상세가 열립니다. 상세가 열린 동안에도 뒤의 차트를 클릭하거나 스크롤할 수 있습니다.

• 진행 중인 트랜잭션은 테이블 뷰 탭 하나만 표시하며, 마지막 행에 "진행 중"이 표시됩니다. 카드를 클릭한 시점의 내용이며 자동으로 갱신하지 않습니다.

• 진행 상황을 계속 따라가려면 상세 헤더의 새 창 열기 버튼을 클릭하세요. "트라잭토리 상세" 창이 열리며, 이 창의 시간 컨트롤로 갱신할 수 있습니다.

• 끝난 트랜잭션은 LLM 트레이스 상세와 같이 레코드 요약, 테이블 뷰 탭을 표시합니다.

• 테이블 뷰의 LLM API 스텝에는 직전 호출 대비 프롬프트 변화(프롬프트 델타)가 함께 표시됩니다. 자세한 내용은 프롬프트 델타를 참조하세요.

트라젝토리 중지

실행 중인 트라젝토리를 화면에서 중지할 수 있습니다. 반복 호출로 비용이 계속 늘어나거나, 잘못된 요청으로 시작된 흐름을 끊을 때 사용합니다. 중지는 트라젝토리 단위로 요청하며, 화면에 표시된 그 트라젝토리의 진행 중인 트랜잭션이 중지 대상입니다.

중지되는 범위

• 진행 중인 LLM 호출을 끊고 해당 트랜잭션을 종료합니다.

• 이후 같은 트라젝토리에서 발생하는 LLM 호출도 차단합니다.

• 중지 지점은 트랜잭션 트레이스에 WhaTap: LLM trajectory stopped by control 메시지 스텝으로 기록되어 애플리케이션 오류와 구분할 수 있습니다. LLM 트레이스 상세의 테이블 뷰에서 확인하세요.

주의

중지는 되돌릴 수 없습니다. 확인 창에서 대상 트라젝토리와 트랜잭션 수를 확인한 뒤 실행하세요.

중지하기

1. 다음 중 한 곳에서 정지 버튼을 클릭합니다.

   • 액티브 트라젝토리 목록: 트라젝토리 그룹 헤더 오른쪽 끝

   • 트라젝토리 뷰: 제목 줄 오른쪽 끝

   • LLM 트레이스 상세의 트라잭토리 뷰 탭: 제목 줄 오른쪽 끝(같은 트라젝토리에 진행 중인 트랜잭션이 있을 때)

2. "트라잭토리 정지" 확인 창에서 대상 이름과 mtid · tx N을 확인합니다. N은 실제로 중지 요청을 보낼 트랜잭션 수입니다.

3. 시크릿키를 입력합니다. 눈 아이콘을 클릭하면 입력한 키를 확인할 수 있습니다.

4. 정지를 클릭합니다. 입력란에서 Enter 키를 눌러도 실행됩니다.

5. 결과와 관계없이 창이 닫히고, 화면 위쪽에 결과 메시지가 표시됩니다.

액티브 LLM API 위젯의 실행 중 호출 목록에는 정지 버튼이 없습니다. 목록에서 호출을 선택해 트라젝토리 뷰로 이동한 뒤 중지하세요.

결과 메시지

결과	메시지	의미와 조치
성공	성공	모든 대상이 중지를 수락했거나 이미 중지 중입니다.
확인되지 않음	중지를 요청했지만 SDK가 확인해 주지 않았습니다. 목록을 새로고침해 확인하세요.	요청은 SDK에 전달됐지만 3초 안에 응답이 없었습니다. 실제로는 중지됐을 수 있으며, 다시 시도해도 안전합니다. Java SDK는 항상 이 메시지가 표시됩니다.
키 오류	보안키가 잘못되었습니다.	SDK가 시크릿키를 거부했습니다. 키를 확인하고 다시 시도하세요.
대상 없음	활성 트랜잭션이 없습니다.	SDK에 대상 트랜잭션이 없습니다. 그 사이 트랜잭션이 끝났을 수 있습니다.
전달 실패	SDK와 연결되어 있지 않아 중지 요청을 보내지 못했습니다. SDK 상태를 확인한 뒤 다시 시도해 주세요.	요청이 SDK에 전달되지 않아 중지되지 않았습니다. SDK 상태를 확인한 뒤 다시 시도하세요.
기타 실패	알 수 없는 에러가 발생했습니다.	서버가 요청을 거부했거나, SDK에서 예외가 발생했거나, 요청이 서버에 전달되지 못했습니다.

• 서버가 요청을 거부했거나 요청이 서버에 전달되지 못한 경우를 제외하면, 실패와 경고 메시지 끝에 해당 애플리케이션명이 괄호로 붙습니다.

• 대상이 여러 개면 가장 나쁜 결과 하나만 표시합니다. 일부만 중지된 경우에는 성공으로 표시하지 않습니다.

정지 버튼이 보이지 않거나 비활성인 경우

상태	원인
버튼이 보이지 않음	mtid가 없는 단독 흐름(단독 실행)이거나, 진행 중인 소속 트랜잭션이 없습니다.
버튼이 비활성(회색)	현재 프로젝트에 수정 권한이 없습니다. 버튼에 마우스를 올리면 "수정 권한이 없습니다."가 표시됩니다.

유의 사항

• 목록에서 검색어로 거른 상태로 중지하면 화면에 남은 트랜잭션만 대상이 됩니다.

• 트라젝토리 뷰에서 여러 프로젝트를 함께 선택한 경우 중지 요청을 프로젝트별로 나눠 보냅니다. 그중 한 요청이라도 거부되면 나머지 요청이 받아들여졌더라도 "알 수 없는 에러가 발생했습니다."가 표시됩니다.

• SDK가 중지를 비동기로 처리하므로 성공한 뒤에도 목록이나 뷰에서 바로 빠지지 않을 수 있습니다.

• 중지된 트라젝토리에 별도의 "중지됨" 상태는 없습니다. 이후에는 완료 또는 실패로 표시되므로, 중지 여부는 LLM 트레이스 상세의 메시지 스텝으로 확인하세요.

참고: 사용자 차단과의 차이

특정 사용자의 LLM 호출을 막는 사용자 차단도 Python SDK 2.2.1 이상에서 지원합니다. 두 기능은 대상, 시점, 동작이 다릅니다.

구분	트라젝토리 중지	사용자 차단
대상	실행 중인 트라젝토리 하나	지정한 사용자 ID의 모든 LLM 호출
방법	화면의 정지 버튼	SDK 옵션 llm_blocked_users
시점	실행 중인 흐름을 사후에 끊음	호출 전에 차단
동작	진행 중인 LLM 호출을 끊고 트랜잭션을 종료하며, 이후 같은 트라젝토리의 LLM 호출을 차단	해당 사용자의 LLM 호출을 차단하고 LLM 클라이언트 라이브러리의 연결 오류(예: APIConnectionError)로 반환
트레이스 기록	WhaTap: LLM trajectory stopped by control	WhaTap: LLM call blocked for user …

사용자 차단 설정은 Python SDK 설정을 참조하세요.