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