> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.
# trace 모니터링 (Opticon)
> Opticon → Tracing을 사용하여 모든 Guard 평가와 그 동작, 정책 적중, 메타데이터를 확인합니다.
**Opticon**은 Starfort의 모니터링 앱입니다. 모든 Guard 평가에 대해 **trace**를 기록하므로, 각 요청이 정확히 무엇이었고 Guardian이 어떻게 판단했는지 확인할 수 있습니다.
프로젝트(또는 해당 Guardian)에서 **Opticon** 링크를 통해 Opticon을 연 다음, 왼쪽 내비게이션에서 **Tracing**을 선택합니다.
## trace 목록
각 행은 하나의 Guard API / Desktop Agent 호출이며, 입력, Guardian의 출력, 지연 시간, **tags**, 그리고 **scores**를 보여줍니다. Desktop Agent 호출의 경우, 트레이스의 **session**은 매칭된 [Control Profile](/ko/v1.3/admin/control-profiles) 이름이고, 그 **metadata**에는 요청의 URL, HTTP 메서드, Content-Type, 헤더가 담깁니다. 입력 호출과 그 출력 호출은 **하나의 Trace ID**를 공유하므로, 전체 요청→응답 주기를 하나의 트레이스로 볼 수 있습니다. API 호출의 경우, session은 호출자의 `session_id`이며, 호출자는 동일한 `trace_id`를 전달하여 두 호출을 연결할 수 있습니다.
tags와 scores를 사용하면 쉽게 필터링하고 집계할 수 있습니다:
* 동작 — `PASS`, `MASK`, `BLOCK`
* 정책 결과 — 예: `PII Masking Policy:MASK`, `TOPIC:BLOCK`
* 호출자 — 예: API 키 이름
* 단계 — `process_type:input`
* **scores** — 정책 이름별로, 정책 유형별로 집계됨
## trace 상세 정보
trace를 열면 전체 내용을 확인할 수 있습니다: 원본 입력, `processed_content`(마스킹된 출력), 결정된 `action`, 감지된 모든 항목, 그리고 호출 **metadata**(API 키, 모델 구성, process type).
`BLOCK` 또는 `MASK` 태그로 필터링하여 정확히 무엇이 포착되었고 어떤 정책이 포착했는지 검토하세요 — 정책을 조정하거나 [문제를 해결](/ko/v1.3/desktop/troubleshooting)할 때 매우 유용합니다.
## Opticon Fail-Safe (Fail-Open / Fail-Closed)
트레이스 기록은 원래 **비동기**입니다. Opticon이 다운되거나 무응답이어도 Guard 판정(PASS / MASK / BLOCK)은 그대로 반환되고 기록만 유실됩니다 — 관측 평면은 fail-open입니다. 그러나 감사가 필수인 운영에서는 이 공백이 문제가 됩니다. 기록되지 않은 요청은 감사할 수 없는 요청이기 때문입니다.
v1.3부터는 트레이스 기록이 끝내 실패할 때의 동작을 **Project Settings → General**의 **Opticon Fail-Safe** 설정으로 **프로젝트 단위**로 선택할 수 있습니다:
| 모드 | 기록 방식 | 기록이 끝내 실패하면 | 우선 가치 |
| ------------------- | ----------------------- | ------------------------------ | ------ |
| **Fail-Open** (기본값) | 비동기 best-effort — 기존 동작 | 기록만 유실, 판정은 그대로 반환 | 가용성·지연 |
| **Fail-Closed** | 기록 성공이 응답의 **선행 조건**이 됨 | 해당 요청을 **BLOCK**으로 강등 — 내용 미전달 | 감사성 |
Fail-Closed의 기록 시도는 \*\*제한적(bounded)\*\*입니다 — 시간 상한과 재시도 상한 안에서만 진행되므로, Opticon이 무응답이어도 응답이 무한정 매달리지 않고 BLOCK으로 귀결됩니다. Opticon이 정상으로 복귀하면 별도 조작 없이 자동으로 정상 통과로 돌아옵니다.
이 정책이 **프로젝트 단위**인 이유는 트레이스가 프로젝트의 Opticon 바인딩을 통해 기록되기 때문입니다 — 어떤 Project Guardian에도 매핑되지 않고 프로젝트에 도달해 관찰·로깅만 되는 패킷도 이 바인딩으로 기록됩니다. 같은 회사 안에서도 프로젝트별로 감사 자세가 다를 수 있습니다.
**적용되지 않는 경우** — Fail-Closed는 트레이스가 *있어야 하는데* 기록하지 못한 경우에만 적용됩니다. 애초에 트레이스를 만들지 않는 요청은 영향을 받지 않습니다:
* Opticon 로깅을 명시적으로 끈 entry (의도된 opt-out이지 장애가 아님)
* 애초에 트레이스를 생성하지 않는 경로 (인증 실패, deterministic 게이트, 미지원 입력, 한도 초과 거부)
* Opticon 바인딩이 구성되지 않은 프로젝트
차단 방식은 다른 fail-closed 차단과 동일합니다. API 호출자는 차단 응답을 받고, Desktop Agent는 패킷을 전달하지 않습니다(설정 시 사용자 알림 표시).
## 보존 기간과 Opticon이 하지 않는 일
Opticon은 런타임 데이터만 보여줍니다. 조직, 프로젝트, 구성원 관리는 모두 Console에 있으며 — Opticon에서는 이를 **생성하거나 삭제할 수 없고**(Starfort가 단일 진실 공급원입니다), Console의 역할이 여기로 이어집니다.
트레이스 \*\*보존 기간(retention)\*\*은 Opticon에서 설정하지만, 트레이스는 **수동으로 절대 삭제되지 않습니다** — 트레이스별 또는 일괄 삭제가 없고, 프로젝트를 삭제해도 그 트레이스가 제거되지 않으며, 오직 보존 주기만이 이를 제거합니다. 기록이 온전하게 유지되도록 의도된 설계입니다. (거버넌스 변경 — 누가 구성을 변경했는가 — 은 별도의 [Audit Log](/ko/v1.3/admin/audit-log)에 있습니다.)