Opik이 터미널 UX를 다시 설계한 이유

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

개발자가 제품 대시보드보다 에이전트가 실행되는 터미널을 작업의 출발점으로 삼으면서, Comet의 Opik은 Trace와 평가 결과를 터미널에서 읽을 수 있는 텍스트 워터폴 차트로 렌더링하는 실험을 진행했다. 10개의 Trace에 지연 급증, 재시도 폭주, 연쇄 실패를 넣고 사용자가 직접 실행하는 명령과 세션 중 LLM이 호출하는 도구 양쪽을 시험한 결과, 터미널 출력은 고정된 텍스트 블록이라 클릭·스크롤·반응형 폭·지속 참조를 제공하기 어려웠다. LLM이 차트를 요약문으로 바꾸거나 ANSI 색상 코드를 그대로 노출하는 문제도 생겨, 출력의 시각적 완성도보다 명령 경로·인증·세션·도구 선택을 포함한 전달 신뢰성이 더 큰 과제로 드러났다. 따라서 차트는 흑백을 기본으로 만들고 터미널 폭을 동적으로 계산하며 span 번호와 완결된 맥락을 제공해야 하고, 사람이 읽는 표현과 LLM이 해석할 구조화 데이터 사이의 차이도 함께 설계해야 한다.

섹션별 상세

개발자는 정보를 확인하려고 대시보드를 떠났다가 터미널로 돌아오기보다, 에이전트가 이미 실행되는 터미널을 제품 사용의 출발점으로 삼으려 합니다. Opik은 Comet이 만든 오픈소스 LLM 관측성·평가 플랫폼이며, 주요 사용자는 에이전트를 평가하고 디버깅하는 AI 개발자입니다. 제품의 목적이 에이전트 작업을 돕는 데 있다면 사용자를 에이전트가 있는 환경에서 다른 UI로 이동시키기보다 그 환경에 기능을 가져가야 한다는 문제의식에서 실험이 시작됐습니다.

코딩 에이전트를 이용해 Opik의 Trace 데이터를 터미널용 텍스트 차트로 바꾸고, 앱의 화면과 비슷한 워터폴 표현을 구현했습니다. 지연 급증, 재시도 폭주, 연쇄 실패처럼 서로 다른 실행 형태를 가진 Trace 10개를 생성한 뒤, 사용자가 입력하는 명령과 세션 중 LLM이 호출하는 도구 두 경로를 비교했습니다. 이 과정은 터미널 UX가 단순한 화면 축소가 아니라, 출력 매체와 도구 호출 주체가 바뀌는 설계 문제임을 드러냈습니다.

Opik MCP의 터미널 UX를 주제로 한 제목 카드와 Trace 워터폴 화면이 함께 배치되어 있습니다. — Screenshot이미지는 일반적인 제품 장식이 아니라 글에서 구현한 터미널 기반 Trace 표현을 직접 담고 있습니다. 오른쪽 화면에는 작업별 막대와 span 이름이 나타나며, 대시보드의 시각화를 정적 텍스트 환경으로 옮기는 글의 실험 맥락과 연결됩니다.

터미널의 도구 결과는 상호작용 가능한 화면이 아니라 한 번 출력되고 스크롤되는 정적인 텍스트 페이지입니다. 따라서 깊이나 hover에 의존하는 대신 공백과 정렬로 계층을 만들고, 각 출력 블록이 별도의 설명 없이도 완결된 정보를 담아야 합니다. 특히 200개에 이를 수 있는 span 중 중요한 일부를 선택하고 나머지를 잘라냈다는 사실까지 전달해야 하므로, 시각화보다 편집과 정보 우선순위 결정이 핵심 작업이 됩니다.

에이전트가 호출하는 도구는 사용자의 터미널 폭을 알 수 없어 80열을 기본값으로 사용했고, 실제 터미널이 222열이어도 이름이 불필요하게 잘리거나 행이 차트 중간에서 줄바꿈되는 문제가 생겼습니다. 색상 역시 직접 실행할 때는 작동했지만 코딩 에이전트가 도구를 호출하자 ANSI escape code가 문자 그대로 도착했고, 모델은 색상을 렌더링하지 못한 채 말로만 묘사했습니다. 그래서 고정 폭을 하드코딩하지 않고 폭을 계산하며, 색상 없이도 의미가 유지되는 형태와 사용자의 테마에 맞는 이름 기반 ANSI 색상을 우선해야 합니다.

터미널에서 Trace를 워터폴 형태로 표현한 화면으로, span 번호와 오류 표식, 작업 유형별 도형이 보입니다. — Screenshot화면은 research_agent_run의 전체 실행 경로를 행별로 나누고 각 작업의 시작 위치와 지속 시간을 막대로 표시합니다. 색상뿐 아니라 숫자 행 번호, 삼각형과 마름모 같은 도형, 오류 표식을 함께 사용해 색상이 사라져도 span 유형과 실패 지점을 구분하려는 설계가 글의 원칙을 구체화합니다.

터미널 출력에는 URL, 탐색 경로, 재방문 지점이 없어 한 번 지나간 결과를 쉽게 공유하거나 다시 열 수 없습니다. 모든 span에 번호를 붙이면 사용자가 이름을 복사하지 않고도 “row 14”처럼 특정 행을 지칭할 수 있으며, 잘린 차트도 인쇄물을 주석 처리하듯 이어서 다룰 수 있습니다. 막대는 끝부분을 잘라도 형태가 남지만 문장은 잘리는 순간 의미가 무너지므로, 시각 요소와 텍스트 요소에 서로 다른 clipping 규칙을 적용해야 합니다.

터미널 UX의 사용자는 화면을 읽는 사람만이 아니라 출력의 의미를 해석하고 다음 행동을 결정하는 LLM까지 포함합니다. 차트는 막대 위치와 길이를 눈으로 읽어야 하므로 모델이 두 단계가 겹치지 않는다고 잘못 판단했지만, 원시 수치로 전환하자 한 단계가 671.6ms에 끝나고 다음 단계가 672.6ms에 시작한다는 정확한 판단을 내렸습니다. 에이전트 중심 제품에서는 개발자에게 의미 있는 시각화와 모델이 안정적으로 처리할 구조화 데이터 사이의 간극을 함께 줄여야 합니다.

다음 설계에서는 차트 표시를 반드시 보장해야 할 때 LLM에게 실행 책임을 맡기지 않고, 모델이 결과를 문맥으로 읽도록 해야 합니다. 시각화는 흑백을 기본으로 하고 색상은 보강 요소로 두며, 전체 폭은 변경된 열 하나 때문에 정렬이 깨지지 않도록 계산해야 합니다. 또한 도구 설명은 모델이 해당 도구를 선택할지 결정하는 입력이므로, 좋은 렌더링뿐 아니라 도구 설명과 호출 경로의 명확성도 제품 경험의 일부가 됩니다.

터미널을 실시간으로 한눈에 확인하는 cockpit으로 만들려는 목표와, 한 번 출력되고 사라지는 정적 결과라는 매체의 성격은 아직 맞지 않습니다. coding app이나 MCP App으로 사용자를 유도하는 대신, 에이전트가 실제로 일하는 터미널에서 제약을 감수하고 기능을 제공하는 선택이 글의 방향입니다. 몇 시간 만에 읽기 어려운 차트를 개선했지만 안정적으로 사용자 앞에 도달시키는 과정에서는 오래된 세션, 경로 가정, 만료된 인증, 명령에 흡수되는 메시지 같은 문제가 더 많이 발생했으며, 최종 과제는 시각 디자인보다 신뢰성으로 귀결됩니다.

용어 해설

LLM 관측성(LLM Observability): — LLM 애플리케이션의 요청, 응답, 지연 시간, 오류, 토큰 사용량 같은 실행 데이터를 수집하고 추적하는 기능입니다. 개발자는 trace와 span을 통해 에이전트의 처리 경로를 재구성하고 병목이나 실패 지점을 찾아 품질과 운영 안정성을 높입니다.
Trace: — 하나의 요청이나 에이전트 실행이 시작된 뒤 여러 작업을 거쳐 응답을 반환하기까지의 전체 실행 기록입니다. 각 단계의 시작·종료 시점, 소요 시간, 호출 관계를 연결해 지연 급증이나 연쇄 실패의 원인을 파악하는 기반이 됩니다.
Span: — Trace 안에서 개별 작업 하나를 나타내는 실행 단위입니다. 검색, 도구 호출, LLM 호출, 안전성 검사처럼 세부 단계마다 시간과 상태를 기록하며, 여러 span의 위치와 길이를 비교하면 실행 순서와 병목을 확인할 수 있습니다.
MCP: — 에이전트가 외부 애플리케이션의 기능이나 데이터를 도구 형태로 호출하도록 연결하는 프로토콜입니다. 이 글에서는 개발자가 대시보드 대신 터미널에서 에이전트와 함께 Opik 기능을 사용하도록 만드는 접점으로 등장하며, 도구 호출 결과의 표현 방식이 핵심 과제가 됩니다.
워터폴 차트(Waterfall Chart): — 작업별 시작 시점과 지속 시간을 가로 막대의 위치와 길이로 나타내는 시각화 방식입니다. Trace에서는 span이 언제 실행됐고 서로 얼마나 겹쳤는지 한눈에 비교할 수 있지만, 터미널에서는 폭·색상·스크롤 제약 때문에 텍스트 기반 편집이 필요합니다.

기술

Opik
Comet
MCP
coding agent
LLM

활용 사례

터미널에서 에이전트 Trace의 지연과 실패 원인 디버깅
MCP 도구 호출 결과를 텍스트 워터폴 차트로 렌더링
LLM이 해석할 수 있는 구조화된 관측성 데이터 제공
대시보드 없이 에이전트 실행 흐름과 오류 span 참조