> For the complete documentation index, see [llms.txt](https://uclix.gitbook.io/run-ai-rca-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uclix.gitbook.io/run-ai-rca-docs/ko/ontology-guide.md).

# 온톨로지 및 데이터 적재 가이드

> **쉽게 말하면:** 온톨로지는 플랫폼과 검토된 경험에 이름표를 붙인 지도입니다. 지하철 노선도처럼 어디가 연결되는지는 알려 주지만, 지금 막힌 곳을 알기 위해서는 여전히 실시간 교통 정보, 즉 live evidence가 필요합니다.

TypeDB는 Run:AI RCA가 선택적으로 사용하는 관계형 지식 계층입니다. "지금 무슨 일이 벌어지고 있는가"는 collector가 확인하고, 온톨로지는 정리된 플랫폼 구조(토폴로지)와 운영자가 승인한 과거 사례를 보태 줍니다. TypeDB를 사용할 수 없어도 Agent는 YAML/Python 경로로 계속 동작하며 그 공백을 기록합니다.

## 0. 한 장짜리 멘탈 모델

하나만 기억한다면 이 그림입니다 — 3개 층, 1개 체인:

```mermaid
flowchart LR
  subgraph INFRA["인프라 층 (어디서)"]
    N[node] --- W[workload]
  end
  subgraph INCIDENT["인시던트 층 (무슨 일이)"]
    I[incident] --- RUNX[analysis_run] --- D[diagnosis]
  end
  subgraph KNOWLEDGE["지식 층 (우리가 아는 것)"]
    K[keywords] --> SY[symptom] --> F[root-cause family]
    SY --> AC[action]
  end
  INFRA -.-> INCIDENT
  INCIDENT -.-> KNOWLEDGE
```

한 문장으로: **관찰된 keywords가 symptom에 매칭되고, symptom이 family(메커니즘)를 지목하며 확인된 action을 들고 있다.** 나머지 전부 — runbook, probe, 사례, 패키지 — 는 이 체인을 채우거나 검증하기 위해 존재합니다. 큐레이션 YAML, 운영자 승인 인시던트, 벤더 서포트 외부 케이스가 전부 *같은* 체인으로 저장되므로 검색 경로도 하나입니다.

## 1. 서로 연결된 네 가지 지식 계층

```mermaid
flowchart TB
  T[토폴로지: 컴포넌트, 노드, 워크로드] --> R[관계]
  C[큐레이션 카드: 증상, XID, 조치] --> R
  H[승인 사례 + 외부 서포트 케이스] --> R
  R --> Q[읽기 전용 TypeDB 함수]
  Q --> P[플래너와 합성]
  P --> L[Live collector]
  L --> V[증거 기반 판정]
```

| 계층            | 저장하는 것                       | 중요한 이유         |
| ------------- | ---------------------------- | -------------- |
| 토폴로지          | 컴포넌트와 의존성                    | 합리적인 점검 순서를 제공 |
| 큐레이션 지식       | 증상, 패밀리, 조치, XID 체인, runbook | 시그니처를 질문으로 바꿈  |
| 승인 이력         | 검토된 인시던트와 실행                 | 레이블된 비교 문맥 제공  |
| Live evidence | 현재 collector 관찰              | 현재 증명의 유일한 근거  |

그림은 위에서 아래로 읽으면 됩니다. 그래프는 *어디를 볼지* 추천할 수 있지만, 현재 증거 없이 리포트에 *무슨 일이 있었는지* 말해 줄 수는 없습니다.

## 2. TypeDB 스키마: entity, relation, role

```mermaid
erDiagram
  INCIDENT ||--o{ ANALYSIS_RUN : has
  ANALYSIS_RUN ||--o{ DIAGNOSIS : "run role"
  INCIDENT ||--o{ DIAGNOSIS : "incident role"
  ROOT_CAUSE ||--o{ DIAGNOSIS : "cause role"
  DIAGNOSIS ||--o{ SUPPORTED_BY : claim
  EVIDENCE ||--o{ SUPPORTED_BY : proof
  DIAGNOSIS ||--o{ RESOLUTION : claim
  ACTION ||--o{ RESOLUTION : remedy
  COMPONENT ||--o{ DEPENDS_ON : dependent
  COMPONENT ||--o{ DEPENDS_ON : dependency
  INCIDENT ||--o{ HAS_SYMPTOM : incident
  SYMPTOM ||--o{ HAS_SYMPTOM : symptom
  SYMPTOM ||--o{ INDICATES : symptom
  ROOT_CAUSE ||--o{ INDICATES : cause
  SYMPTOM ||--o{ RESOLVED_BY : symptom
  ACTION ||--o{ RESOLVED_BY : remedy
```

| 스키마 용어    | 뜻                    | 예시                                                    |
| --------- | -------------------- | ----------------------------------------------------- |
| Entity    | 이름을 가진 대상            | incident, control\_plane\_component, evidence, action |
| Attribute | 대상의 속성               | `incident_id`, confidence, 마스킹된 summary               |
| Relation  | 의미 있는 연결             | `supported_by`, `depends_on`                          |
| Role      | relation 안에서 참여자의 역할 | diagnosis는 주장, evidence는 증명                           |

`root_cause`는 `gpu_hardware_error` 같은 재사용 가능한 family입니다. `diagnosis`는 하나의 인시던트에 대해 한 run이 한 주장입니다. evidence는 전체 family가 아니라 그 diagnosis를 지지합니다. `indicates`와 `resolved_by`가 지식 체인이고(symptom → family, symptom → 확인된 action), `has_symptom`은 인시던트가 보인 증상을 연결합니다. `resolution`은 운영자가 `resolved` 또는 `mitigated`를 기록했을 때만 작성됩니다.

현재 스키마는 **운영 family 16개 + 보조 상태 3개**입니다. `failure_modes.yaml`의 16개는 운영자용 taxonomy이고, `platform_version_bug`, `expected_known_behavior`, `insufficient_evidence`는 보조 분류 상태입니다. `cause_instance sub root_cause`까지 포함하면 `root_cause` subtype은 총 20개이며, 닫힌 vocabulary 자체는 변경하지 않습니다.

runbook은 의도적으로 두 겹입니다: 실행 가능한 runbook 하나가 모든 diagnostic step을 담고(walk와 모든 probe ID가 여기 있음), 도메인별 runbook (`…:domain:gpu_stack`, `…:domain:runai_scheduling`, …)이 같은 step을 묶어서 브라우징할 때 "Kubernetes만 있다"가 아니라 실제 커버리지가 보이게 합니다. 외부 서포트 케이스는 벤더 스레드가 실제로 밟은 진단 절차를 케이스별 playbook runbook(`ext:…:playbook`)으로 추가하며, 각 step에는 `outcome`(`diagnostic` 또는 `preventive`)과 그 step에서 스레드가 실제로 관찰한 내용을 담은 `interpretation`이 함께 찍힙니다. `runbook_for` edge가 이 playbook을 해당 incident와 연결하므로, `steps_for_family` 함수는 live 조사가 실제로 매치한 케이스 하나가 아니라 전체 케이스북에서 하나의 root-cause family에 속한 모든 step을 끌어올 수 있습니다 — 분석 도중에는 `steps_lookup` tool로 노출됩니다 ([RCA Pipeline](/run-ai-rca-docs/ko/rca-pipeline.md#4-per-collector-autonomous-drill-down) 참고).

실행 가능한 트리의 최신 분기 3개 — `backend_nfs_unresponsive_retry`, `runai_stale_workload_reference`, `thanos_receive_ingestion_pressure` — 는 바로 이런 케이스별 playbook 항목으로 시작했습니다. 그 패턴이 처음 드러난 케이스 하나뿐 아니라 앞으로의 모든 인시던트에서도 점검할 가치가 있다고 판명되자, 큐레이터가 이를 자체 match 조건·probe·차등 `alternatives`를 갖춘 완전한 실행형 노드로 승격했습니다.

## 3. 안전한 지식이 TypeDB로 들어오는 과정

```mermaid
flowchart LR
  Y[버전 관리 YAML] --> L[스키마와 지식 loader]
  L --> T[(TypeDB)]
  I[인시던트 + analysis run] --> A{user_approved_at이 있는가?}
  A -->|아니오| N[적재하지 않고, 유사 사례(prior)로도 검색되지 않음]
  A -->|예| E{해결됨 및 grace 조건을 충족하는가?}
  E -->|예| M[마스킹된 승인 snapshot + evidence 참조]
  E -->|아니오| U[양성 승격 없이 unresolved 문맥 유지]
  M --> T
```

| 출처          | 게이트                                 | 안전 속성                                                                                          |
| ----------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
| 스키마/함수/카탈로그 | 버전 관리 load job                      | 파일 매처와 같은 큐레이션 사실                                                                              |
| 인시던트/RCA    | 운영자 승인, 보통 해결 및 grace               | 미승인 분석은 prior가 되지 않음                                                                           |
| 검증된 조치      | 승인된 non-abstained 결과                | 현재 증명이 아닌 과거 안내                                                                                |
| 외부 서포트 케이스  | 저장소의 큐레이터 승인 번들, ingest CronJob이 적재 | 신뢰하는 벤더 지식: 같은 symptom→family→action 체인으로 저장, 서포트가 확인한 조치만 `resolved_by`, 진단 절차는 케이스별 playbook |

ingest CronJob은 승인 시점에 고정된 스냅샷(CaseSnapshot)을 사용하고, 이후에 실행된 run으로 그 내용을 덮어쓰지 않습니다. 재분석은 해당 run의 이전 diagnosis/support edge를 교체합니다. 원시 artifact, 토큰, 자격 증명, 임의 명령은 제외되고 TypeDB에는 마스킹된 summary와 `{run_id}:E##` 참조만 들어갑니다.

## 4. Live 분석 중 검색 과정

```mermaid
flowchart LR
  A[알림 텍스트, 로그, pod/workload 이름] --> S[모든 family의 시그니처 매치]
  A --> C[컴포넌트 identity 조회]
  S --> K[큐레이션 symptom/XID/known-issue 카드]
  C --> T[토폴로지 의존성 경로]
  K --> D[Diagnostic directive]
  T --> D
  D --> P[플래너]
  P --> E[읽기 전용 증거 에이전트]
  E --> B[Evidence blackboard]
  B --> R[근거 있는 RCA]
```

| 함수 사용                                                      | 결과                   | 경계                  |
| ---------------------------------------------------------- | -------------------- | ------------------- |
| `causes_for_symptom`                                       | 큐레이션 후보 family       | 여전히 live 매치 필요      |
| `dependencies_for_component` / `checks_for_component_path` | 의존성 인식 점검            | 장애 주장 아님            |
| `_BLAST_QUERY`                                             | blast-radius 문맥      | 인과 증명 아님            |
| `_PRIOR_QUERY` → `_CASE_CARD_QUERY`                        | 레이블된 과거 CaseCard 문맥  | evidence gate 통과 불가 |
| `_KNOWLEDGE_QUERY`(큐레이션 symptom. alertname 승격은 폐기·비활성)     | symptom별 remediation | 여전히 live 매치 필요      |
| `_FN_DIAGNOSTIC_TRANSITIONS`                               | diagnostic tree 전이   | 읽기 전용 planner 안내    |

정밀 시그니처 매치가 검색의 시작점입니다. failure-mode symptom, NVIDIA XID 코드, alert text, known issue를 모든 family에서 찾습니다. family ranker는 후보 순서와 설명만 제공할 뿐입니다. 대상 component 이름도 독립적으로 토폴로지에 도달합니다. 예를 들어 driver daemonset alert은 오류 라인이 없어도 GPU Operator 의존성을 보여 줄 수 있습니다.

플래너는 안내를 `diagnostic_directive`로 바꿉니다. 여기에는 질문, 점검, 대안 분기, 반증, 선언형 probe template이 들어갑니다. alert scope의 placeholder만 해결되며 directive 자체는 아무것도 실행하지 않습니다. 각 Agent에 등록된 tool set이 권한을 강제하는 경계입니다.

검색은 plan 시점에 고정되지 않습니다. 분석 도중에도 모든 증거 Agent는 5개의 읽기 전용 tool — `knowledge_lookup`, `case_lookup`, `xid_lookup`, `component_checks`, `steps_lookup` — 로 같은 지식을 그때그때 끌어올 수 있습니다. 각 tool은 live 온톨로지를 먼저 조회하고 버전 관리되는 카탈로그로 폴백합니다(`steps_lookup`은 그래프 전용입니다 — 케이스별 playbook step은 YAML로 미러링되지 않으므로 저하될 폴백 자체가 없습니다). 이 tool들의 답변은 검증할 안내일 뿐 결코 증거가 아닙니다. artifact가 되지 않으므로 시그니처 매처가 우리 카탈로그를 클러스터가 보고한 내용으로 되읽을 수 없습니다. 전체 tool 표와 `source` 어휘는 [RCA Pipeline](/run-ai-rca-docs/ko/rca-pipeline.md#4-per-collector-autonomous-drill-down)을 참고하세요.

## 5. 전체 예시: NVIDIA Xid 79

| 단계    | 시스템 동작                               | 운영자가 보는 결과                             |
| ----- | ------------------------------------ | -------------------------------------- |
| 알림 도착 | `NVRM: Xid ... 79`가 XID/시그니처 카드에 매치  | 구체적인 GPU hardware 후보                   |
| 문맥 발견 | 카드와 토폴로지가 driver/GPU Operator 점검을 식별 | 순서가 있는 점검과 반증 조건                       |
| 증거 수집 | 관련 Agent가 로그, 노드 상태, 메트릭을 읽음         | 출처/범위가 있는 시간 기반 evidence 카드            |
| 판정    | blackboard가 지지와 반증을 비교               | Evidence ID 또는 `insufficient_evidence` |

덕분에 뭉뚱그린 “GPU 문제”가 아니라 구체적인 후보에서 출발하지만, Xid 텍스트만으로 판정을 내리지는 않습니다. 대상 범위가 없거나 해결 후 관찰이거나 live evidence가 모순되면 증명이 아니라 문맥으로 남습니다.

조사 도중 *다른* XID를 만난 drill-down Agent는 새 plan을 기다릴 필요가 없습니다. `xid_lookup` tool을 직접 호출해 그 코드의 정체와 escalation chain을 그 자리에서 가져올 수 있습니다.

## 6. Studio 점검과 운영

스키마 적용과 승인 사례 적재가 끝난 뒤 상태를 확인할 때는 읽기 전용 CLI를 사용합니다.

```bash
kubectl exec -n <ns> deploy/<release>-agent -- python -m ontology.query --recent 20
kubectl exec -n <ns> deploy/<release>-agent -- python -m ontology.query --incident INC-...
kubectl exec -n <ns> deploy/<release>-agent -- python -m ontology.query --count
```

### 자세히 보기: 런타임 쿼리와 Studio 참고

| 런타임 경로                                                     | 묻는 내용                                           |
| ---------------------------------------------------------- | ----------------------------------------------- |
| `causes_for_symptom`                                       | 하나의 live-matched symptom에 맞는 큐레이션 family는 무엇인가? |
| `dependencies_for_component` / `checks_for_component_path` | 이 컴포넌트는 무엇에 의존하며 무엇을 점검해야 하는가?                  |
| `_BLAST_QUERY`                                             | 노드의 blast radius는 무엇인가?                         |
| `_PRIOR_QUERY` → `_CASE_CARD_QUERY`                        | 이전 동일-alert 인시던트의 CaseCard는 무엇인가?               |
| `_KNOWLEDGE_QUERY`(큐레이션 symptom. alertname 승격은 폐기·비활성)     | live symptom에 맞는 조치는 무엇인가?                      |
| `_FN_DIAGNOSTIC_TRANSITIONS`                               | 이 diagnostic tree를 이어 가는 전이는 무엇인가?              |

```typeql
# 하나의 run에 속한 주장과 이를 지지하는 evidence
match
  $r isa analysis_run, has run_id "ANL-...";
  $d isa diagnosis, links (run: $r, incident: $i, cause: $c);
  $s isa supported_by, links (claim: $d, proof: $e);
  $e has evidence_id $eid, has source $source, has summary $summary;
  $c has subtype $family;
select $family, $eid, $source, $summary;
```

Helm schema hook은 ingest CronJob보다 먼저 추가형 스키마/함수를 적용합니다. `runai_rca`를 다시 만들지 마세요. 임시 데이터베이스로 검증하고 삭제해야 TypeDB Studio에 테스트 데이터베이스가 쌓이지 않습니다.

## 용어집 (Glossary)

| 용어                            | 뜻                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------ |
| Ontology                      | 대상과 의미 있는 관계를 함께 나타낸 지도                                                        |
| TypeDB                        | 그 지도를 저장하고 질의하는 선택 사항 데이터베이스                                                   |
| Entity / relation / attribute | 대상 / 대상 간 연결 / 대상의 속성                                                          |
| Family                        | 카탈로그가 공유하는 넓은 root-cause 분류                                                    |
| Signature                     | symptom 또는 known issue를 알아보는 구체적 텍스트나 코드                                       |
| Symptom                       | XID나 scheduling event처럼 이름 붙은 관찰 패턴                                            |
| Known issue                   | 버전 인식 문맥이 있는 큐레이션 제품 동작/버그                                                     |
| Probe                         | 범위가 정해진 하나의 읽기 전용 evidence 점검                                                  |
| Knowledge tool                | 모든 증거 Agent가 분석 도중 호출할 수 있는 읽기 전용 조회. 온톨로지 우선, 카탈로그 폴백, 현재 run의 증거로는 절대 쓰이지 않음 |
| Diagnostic directive          | 질문, 점검, 분기, 안전한 template을 담은 플래너 안내                                            |
| Blackboard                    | 지지 증거와 반증 증거를 나란히 놓고 비교하는 증거 장부                                                |
| Evidence card                 | 하나의 probe 관찰을 운영자가 읽을 수 있게 만든 기록                                               |

[Knowledge Base](/run-ai-rca-docs/ko/knowledge-base.md), [Learning and Ontology](/run-ai-rca-docs/ko/learning-and-ontology.md), [RCA Pipeline](/run-ai-rca-docs/ko/rca-pipeline.md)을 참고하세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://uclix.gitbook.io/run-ai-rca-docs/ko/ontology-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.