> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 개념

> FailproofAI Observability 개념 문서입니다.

이 페이지는 FailproofAI Observability에서 사용하는 용어를 정의합니다. 다른 가이드에서 낯선 용어를 만나면 여기에서 정의를 확인하세요. 처음부터 끝까지 읽을 필요는 없습니다. 훑어보거나, 특정 용어가 궁금할 때 돌아와 확인하면 됩니다.

***

## 데이터 모델

**이벤트(Event)**
데이터의 가장 작은 단위입니다. 하나의 이벤트는 에이전트가 수행한 단일 단계를 기록합니다: `tool_use`, `model_request`, `hook_completed`, `error` 등이 그 예입니다. 에이전트는 [Python SDK](/ko/agenteye/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](/ko/agenteye/evaluation-suite)를 참고하세요.

**점수 키(Score key)**
평가기가 보고하는 하나의 평가 차원 이름입니다(예: `helpfulness`). 알림과 감사는 특정 점수 키의 시간 변화를 모니터링할 수 있습니다.

**평가기(Evaluator)**
사용자의 채점 서비스입니다. FailproofAI Observability는 완료된 실행의 트랜스크립트를 평가기에 POST하고 반환된 점수를 저장합니다. 기본 평가기는 제공하지 않으며, 채점 로직은 사용자가 직접 구현합니다.

***

## 장애 발견 및 수정

**훅(Hook)**
에이전트 프레임워크가 특정 단계 전후로 실행하는 가드레일 또는 부수 효과입니다. 콘텐츠 안전성 검사, PII 제거, 예산 제한 등이 이에 해당합니다. 훅은 `outcome`(allow, deny, modify)이 포함된 `hook_triggered` / `hook_completed` 이벤트를 발생시키며, 별도의 관찰 페이지에서 확인할 수 있습니다.

**알림 규칙(Alert rule)**
사용자가 설정한 임계값을 지표가 초과할 때 발동하는 규칙입니다. 오류율, p95 지연 시간, 토큰 비용, 또는 평가기 점수를 기준으로 설정할 수 있습니다. 규칙이 발동되면 인시던트가 생성되고 지정된 채널(이메일, Slack, 웹훅, 대시보드 내)로 알림이 전송됩니다. [Alerts](/ko/agenteye/alerts)를 참고하세요.

**인시던트(Incident)**
알림 규칙이 발동될 때 생성되는 미해결 이슈입니다. 인시던트는 수명 주기(확인, 할당, 해결)와 모든 조치를 기록하는 활동 타임라인을 가집니다. 수동으로 생성할 수도 있습니다.

**감사(Audit)**
로그를 세션 전반에 걸쳐 분석하여 아직 규칙으로 정의하지 않은 장애 패턴을 찾는 정기 조사(시간별에서 주별까지)입니다. 오류 클러스터, 낮은 점수, 지연 시간 이상값, 툴 호출 루프, 완료되지 않은 실행 등을 감지합니다. 알림이 이미 알고 있는 지표를 감시하는 반면, 감사는 다음에 살펴봐야 할 사항을 알려줍니다. [Audits](/ko/agenteye/audits)를 참고하세요.

**발견 사항(Finding)**
감사 실행에서 나온 우선순위가 매겨진 증거 기반의 결과입니다. 발견 사항은 패턴을 명시하고, 관련된 정확한 세션에 링크하며, 트리아지 수명 주기(확인, 해결, 음소거, 기각)를 가집니다. FailproofAI Observability는 실행 간 발견 사항을 중복 제거하여 알려진 패턴은 새로 쌓이지 않고 업데이트됩니다.

**AI 어시스턴트(The AI assistant)**
대시보드 내 채팅 기능으로, 사용자 자신의 데이터를 기반으로 에이전트에 관한 질문에 자연어로 답변합니다. 기본적으로 읽기 전용이며, 생성하는 항목(저장된 쿼리, 대시보드)은 승인이 필요하고 삭제는 불가능합니다. [AI assistant](/ko/agenteye/assistant)를 참고하세요.

***

## 운영

**조직(Organization, 테넌트)**
독립된 워크스페이스입니다. 하나의 FailproofAI Observability 인스턴스는 각자의 사용자, 키, 데이터를 가진 여러 조직을 호스팅할 수 있습니다. 모든 대시보드 URL은 조직 슬러그(`/<org-slug>/…`) 하위로 범위가 지정됩니다.

**수집기(Collector)**
`agenteye-collector`는 각 에이전트 머신에서 실행되는 경량 데몬으로, SDK가 디스크에 기록한 이벤트를 배치로 묶어 서버로 전송합니다.

**API 키(API key)**
클라이언트가 서버에 인증하기 위한 범위가 지정된 토큰입니다. 키는 세분화된 권한을 가집니다(예: 수집기에 대한 `events:add`, 대시보드 키에 대한 읽기 전용 범위). [API keys](/ko/agenteye/api-keys)를 참고하세요.

**서버(Server)**
수집 및 API 서비스입니다. 이벤트를 수집하고, 데이터베이스에 운영 상태를 저장하며, 대시보드와 CLI에 서비스를 제공합니다.

**대시보드(Dashboard)**
웹 UI입니다. 모든 페이지는 특정 조직을 기준으로 범위가 지정되며 서버 API를 통해 데이터를 읽습니다.

***

## 다음 단계

* [Overview](/ko/agenteye/overview): 이 구성 요소들이 어떻게 연결되는지 확인합니다.
* [Observability](/ko/agenteye/observability): 관찰 화면(Events, Sessions, Models, Tools, Hooks, Errors)을 살펴봅니다.