Faultline: Self-hosted SigNoz를 활용한 에이전트 실행 조사 콘솔 구축

에이전트 시스템은 전통적인 애플리케이션과는 다른 방식으로 실패합니다. 요청이 구문론적으로 유효하고, 한 에이전트가 성공적으로 재시도(retry)를 수행하더라도, 눈에 보이는 결과물이 너무 비싸거나 미묘하게 틀릴 수 있습니다. 중요한 질문은 대개 "서비스 에러율이 얼마인가?"가 아닙니다. "이 실행(run)의 이 단계에서 어떤 일이 일어났으며, 다음에 무엇을 조사해야 하는가?"입니다.

Faultline은 바로 그 질문을 중심으로 구축된 작은 운영 콘솔(operator console)입니다. 이 시스템은 실제 OpenAI 호환 모바일 앱 생성 워크플로우를 실행하고, 결과물을 Expo 앱으로 렌더링하며, 셀프 호스팅된 SigNoz를 표준 텔레메트리(telemetry) 백엔드로 사용합니다.

제품의 경계 (The Product Boundary)

Faultline은 범용 대시보드가 아닙니다. SigNoz는 이미 더 강력한 대시보드, 트레이스 탐색기(trace explorer), 로그 탐색기(log explorer) 및 알림(alerting) 기능을 갖추고 있습니다. 데모 내에서 이를 재현하는 것은 노이즈를 추가하고 통합을 약화시킬 뿐입니다.

대신, Faultline은 에이전트 특화 조사 흐름(agent-specific investigation flow)을 담당합니다:

조사할 가치가 있는 실행(run)을 찾습니다.
인과 관계 경로(causal path)를 따라갑니다.
문제가 발생한 에이전트를 선택합니다.
실제 프롬프트(prompt), 출력(output), 재시도 컨텍스트(retry context) 및 아티팩트(artifact)를 읽습니다.
가공되지 않은 증거가 필요할 때 정확한 SigNoz 트레이스(trace), 로그(logs) 또는 알림(alert)으로 에스컬레이션합니다.

Architecture

러너(The Runner): 의도적으로 작게 설계된 워크플로우

러너는 고정된 워크플로우를 사용합니다: 플래너(Planner), 아키텍처(Architecture), 디자인 시스템(Design system), 그리고 기본 화면(Primary screen). 실행(run)은 즉시 메모리에 삽입된 후 백그라운드에서 실행됩니다. 이를 통해 콘솔은 마지막에만 해결되는 스피너(spinner) 대신 유용한 라이브 상태를 제공할 수 있습니다.

const run: Run = {
  id,
  scenario,
...

에이전트가 시작되면, Faultline은 타입화된 실행 이벤트(typed execution event)를 기록합니다. 따라서 UI는 "이전 단계 대기 중", "워크스페이스 시작됨", "재시도 중", "모델 응답 수신됨", "아티팩트 기록됨" 등을 구분할 수 있습니다.

별도의 텔레메트리 제품 없이 완전한 에이전트 컨텍스트 확보

가장 유용한 디버깅 컨텍스트는 토큰 차트가 아닙니다. 그것은 정확한 작업 프롬프트 (task prompt), 시스템 지침 (system instruction), 응답 (response), 그리고 현재의 아티팩트 (artifact)를 이끌어낸 결정들입니다.

Faultline은 실행 (run)과 함께 이러한 운영 문서 (operational dossier)를 유지하며, 그에 상응하는 구조화된 OTLP 로그를 SigNoz로 방출합니다. 콘솔은 즉각적인 라이브 렌더링을 위해 이 문서를 사용하며, SigNoz는 내구성이 있는 텔레메트리 (telemetry) 조사를 위한 권위 있는 데이터 소스로 남습니다.

logEvent(taskPrompt, {
  'faultline.event': 'model.request',
  'faultline.run_id': run.id,
...

선택된 에이전트 (selected-agent) 엔드포인트는 콘솔에 정규화된 형태 (normalized shape)를 반환합니다. 이 엔드포인트는 의도적으로 SigNoz 쿼리 언어 (query language)나 일반적인 대시보드 컨트롤을 노출하지 않습니다.

GET /api/runs/:runId/agents/:agentId

{
...

세 가지 증거 캡슐 (Three Evidence Capsules)

콘솔은 SigNoz 통합을 세 가지 사람이 읽을 수 있는 신호 (signals)로 제한합니다:

캡슐 (Capsule)	답변하는 질문	네이티브 에스컬레이션 (Native escalation)
트레이스 (Trace)	실행이 상관관계가 있고 완료되었는가?	정확한 트레이스 (Exact trace)
...

이러한 제약은 중요한 제품 결정입니다. 콘솔은 차분하고 작업에 특화된 상태를 유지하는 반면, SigNoz는 가짜 화면 위의 로고가 아닌 실제 관측 가능성 (observability) 시스템으로서 가시성을 유지합니다.

OpenTelemetry 설계

루트 스팬 (root span)은 agent.run입니다. 자식 스팬 (child spans)은 각 에이전트, LLM 요청 (request), 재시도 (retry), 아티팩트 쓰기 (artifact write), 그리고 프리뷰 게시 (preview publication)를 다룹니다. 공유 속성 (shared attributes)을 통해 모든 신호에 걸쳐 트레이스 (traces)와 로그 (logs)를 탐색할 수 있습니다:

await inSpan('agent.architecture', {
  'faultline.run_id': run.id,
  'faultline.agent_id': 'architecture',
...

주입된 인시던트 (incident)는 두 가지 실제 효과를 발생시킵니다:

Architecture는 명시적인 타임아웃 (timeout) 이벤트를 수신하고, 실제 모델 요청을 하기 전에 재시도합니다.
실행 (run)의 토큰 예산 (token budget)은 관찰된 모델 사용량보다 의도적으로 낮게 설정되어, 예산 초과 (budget-breach) 메트릭 (metric)과 위험 상태 (risk state)를 생성합니다.

이것은 데모를 연극적인 것이 아닌 인과적인 것으로 만듭니다. 운영자는 Faultline과 SigNoz 모두에서 동일한 재시도 및 예산 조건을 확인하게 됩니다.

에이전트 출력에서 작동하는 모바일 프리뷰까지

아티팩트(artifact) 목록이 앱 프리뷰(app preview)는 아닙니다. 이제 Faultline은 실제 실행(run)으로부터 제한된 MobilePlan을 생성합니다. 이 플랜에는 제품 카피(product copy), 잔액 또는 헤드라인 지표(headline metric), 카테고리, 활동(activity), 그리고 인사이트(insight)가 포함됩니다. Expo는 해당 플랜을 홈(Home), 활동(Activity), 인사이트(Insights), 프로필(Profile) 뷰를 갖춘 대화형 모바일 템플릿으로 렌더링합니다.

type MobilePlan = {
  appName: string;
  balance: string;
...
}

이는 의도적으로 제한된 생성(constrained generation) 방식입니다. 이를 통해 모델이 생성한 임의의 안전하지 않은 코드가 로컬 프리뷰 서버에서 실행되는 것을 허용하지 않으면서도, 실제 모바일 경험을 안정적으로 보여줄 수 있습니다.

Expo에 자체적인 런타임 경로가 필요했던 이유

Faultline은 더 넓은 범위의 로컬 워크스페이스(workspace) 내에 위치합니다. Expo SDK 52는 React 18과 Node 20을 요구합니다. 상위 워크스페이스에서 React 19를 해석(resolving)하면서 호환되지 않는 React 요소가 생성되었고, 이로 인해 프리뷰가 빈 화면으로 나타나는 문제가 발생했습니다.

해결 방법은 세 부분으로 구성됩니다:

Faultline 전반에 걸쳐 React 18.3.1, React DOM 18.3.1, 그리고 React Native 0.76.9 버전을 고정(pin)합니다.
프리뷰 로컬 전용 Metro 설정을 유지합니다.
셸(shell)의 기본값이 더 최신 버전의 Node 릴리스로 설정되어 있더라도, 설치된 Node 20 nvm 런타임을 찾아 Expo를 시작하는 스크립트를 통해 실행합니다.

const runtime = join(versionsDirectory, node20, 'bin', 'node');
const child = spawn(runtime, [expoCli, 'start', '--web'], { stdio: 'inherit' });

다음 단계

논리적인 다음 구현 단계는 지속 가능한 실행 메타데이터(durable run metadata), 프로덕션 프롬프트를 위한 레드액션(redaction) 규칙, 구성 가능한 파이프라인 그래프(pipeline graph), 네이티브 SigNoz 대시보드 프로비저닝(provisioning), 그리고 브라우저 수준의 회귀 테스트(regression tests)입니다. 핵심 교훈은 이미 유용합니다. 에이전트 관측성(agent observability)은 운영자가 이해할 수 있는 인과 관계 이야기(causal story)에서 시작하여, 그 후에야 가공되지 않은 텔레메트리(raw telemetry)로 내려갈 수 있을 때 가장 강력해집니다.

코드 및 상세 정보: https://www.dailybuild.xyz/project/201-faultline

Insights