데이터 모델
이벤트(Event) 가장 작은 데이터 단위입니다. 하나의 이벤트는 에이전트가 수행한 단일 단계를 기록합니다:tool_use, model_request, hook_completed, error 등. 에이전트는 Python SDK를 통해 이벤트를 내보내며, Events 페이지에서 실시간으로 확인할 수 있습니다.
세션(Session)
session_id로 식별되는 하나의 에이전트 실행입니다. 세션은 동일한 id를 공유하는 모든 이벤트를 포함하며, Sessions 페이지에서 단일 행으로 집계되고 상세 페이지에서 실행 그래프로 표시됩니다. 세션은 일반적으로 agent_start로 시작하고 agent_end로 끝납니다.
에이전트(Agent)
agent_id로 식별되는, 실행 내의 명명된 행위자입니다. 하나의 실행에는 여러 에이전트가 관여할 수 있습니다. 예를 들어 요약 서브 에이전트를 생성하는 플래너 에이전트가 있을 수 있습니다. 서브 에이전트는 parent_id를 가지며, 이를 통해 Failproof AI Observability가 실행 그래프에서 각 에이전트를 별도의 레인으로 표시할 수 있습니다.
환경(Environment)
실행이 발생한 위치를 나타내는 레이블입니다: production, staging, dev. SDK를 설정할 때 한 번 지정합니다. 대시보드의 거의 모든 페이지에서 환경을 기준으로 필터링할 수 있습니다.
컨텍스트 윈도우 사용률(Context-window fill)
응답이 모델의 컨텍스트 윈도우를 얼마나 사용했는지를 나타내는 백분율입니다. Failproof AI Observability는 인식된 모델의 model_response 이벤트에 이 값을 기록하므로, 프롬프트 증가 추세와 임박한 압축(compaction) 상황을 이벤트 스트림에서 바로 확인할 수 있습니다.
품질
평가(Evaluation) 완료된 세션에 대해 직접 운영하는 채점 서비스가 생성한 품질 점수입니다. 평가는 선택 기능입니다. 평가기를 연결하기 전까지 세션은 기록되지만 점수가 매겨지지 않습니다. 각 평가는 여러 개의 명명된 점수(예:helpfulness, factuality, tool_efficiency)를 가질 수 있으며, 각 점수에는 짧은 근거 메모가 포함됩니다. 평가 스위트를 참고하세요.
점수 키(Score key)
평가기가 보고하는 하나의 측정 차원 이름입니다(예: helpfulness). 알림과 감사는 특정 점수 키를 시간 경과에 따라 모니터링할 수 있습니다.
평가기(Evaluator)
직접 운영하는 채점 서비스입니다. Failproof AI Observability는 완료된 실행의 트랜스크립트를 평가기에 POST하고 반환된 점수를 저장합니다. 기본 평가기는 제공하지 않으며, 채점 로직은 사용자가 직접 작성합니다.
장애 발견 및 수정
훅(Hook) 에이전트 프레임워크가 각 단계 주변에서 실행하는 가드레일 또는 부작용입니다: 콘텐츠 안전성 검사, PII 제거, 예산 감시 등. 훅은outcome(allow, deny, modify)과 함께 hook_triggered / hook_completed 이벤트를 내보내며, 전용 관찰 페이지를 제공합니다.
알림 규칙(Alert rule)
지정한 임계값을 메트릭이 초과할 때 발동하는 규칙입니다: 오류율, p95 지연 시간, 토큰 비용, 또는 평가기 점수. 규칙이 발동하면 인시던트가 열리고 선택한 채널(이메일, Slack, 웹훅, 대시보드 내)로 알림이 전송됩니다. 알림을 참고하세요.
인시던트(Incident)
알림 규칙이 발동될 때 생성되는 열린 이슈입니다. 인시던트는 수명 주기(확인, 할당, 해결)와 모든 활동을 기록하는 타임라인을 가집니다. 수동으로 열 수도 있습니다.
감사(Audit)
아직 규칙을 작성하지 않은 장애 패턴을 세션을 가로질러 로그에서 탐색하는 반복 조사입니다(시간 단위부터 주 단위까지). 오류 클러스터, 낮은 점수, 지연 시간 이상치, 도구 호출 루프, 완료되지 않은 실행 등을 발견합니다. 알림이 이미 알고 있는 메트릭을 모니터링한다면, 감사는 다음에 무엇을 살펴봐야 할지 알려줍니다. 감사를 참고하세요.
발견사항(Finding)
감사 실행에서 나온 순위가 매겨진 증거 기반 결과 하나입니다. 발견사항은 패턴을 명명하고, 그 근거가 된 정확한 세션에 링크하며, 트리아지 수명 주기(확인, 해결, 음소거, 기각)를 가집니다. Failproof AI Observability는 실행 간 발견사항을 중복 제거하여 알려진 패턴이 새로 쌓이지 않고 업데이트되도록 합니다.
AI 어시스턴트(The AI assistant)
대시보드 내 채팅으로, 사용자 본인의 데이터를 기반으로 에이전트에 대한 질문에 일반 언어로 답변합니다. 기본적으로 읽기 전용이며, 생성하는 모든 항목(저장된 쿼리, 대시보드)은 승인이 필요하고, 삭제는 절대 불가합니다. AI 어시스턴트를 참고하세요.
운영
조직(Organization, 테넌트) 격리된 워크스페이스입니다. 하나의 Failproof AI Observability 인스턴스는 각자의 사용자, 키, 데이터를 가진 여러 조직을 호스팅할 수 있습니다. 모든 대시보드 URL은 조직 슬러그 아래로 범위가 지정됩니다(/<org-slug>/…).
수집기(Collector)
agenteye-collector는 각 에이전트 머신에서 실행되는 경량 데몬으로, SDK가 디스크에 기록한 이벤트를 일괄 처리하여 서버로 전송합니다.
API 키(API key)
클라이언트를 서버에 인증하는 범위 지정 토큰입니다. 키는 세분화된 권한을 가집니다(예: 수집기용 events:add, 대시보드 키용 읽기 전용 범위). API 키를 참고하세요.
서버(Server)
수집 및 API 서비스입니다. 이벤트를 수집하고, 운영 상태를 데이터베이스에 저장하며, 대시보드와 CLI를 제공합니다.
대시보드(Dashboard)
웹 UI입니다. 모든 페이지는 조직 범위로 지정되며 서버 API를 통해 데이터를 읽습니다.
다음 단계
- 개요: 이 구성 요소들이 어떻게 맞물리는지 설명합니다.
- Observability: 관찰 화면(Events, Sessions, Models, Tools, Hooks, Errors).