Ontology Observability

본 가이드는 Epic #1232 M3 Step 2 에서 도입된 Ontology Layer 관측성 (Prometheus 메트릭 + Grafana 대시보드) 을 다룹니다.

메트릭 5종

메트릭	종류	라벨	의미
`gend_ontology_class_count`	Gauge	`layer`	layer 별 활성 Class 수. lifespan startup 시 seed + 후속 PR (M3 Step 3) 의 background scheduler 가 30분 주기 refresh.
`gend_ontology_class_mutations_total`	Counter	`action`	mutation 빈도. action ∈ `class_create / class_update / class_delete / class_put_with_properties / relation_create / relation_delete / instance_create`
`gend_ontology_validation_failures_total`	Counter	`class_name`, `error_type`	SHACL violation 빈도. M1 Step 4 validator + M2 Step 1 instance create 의 fail-closed gate.
`gend_ontology_mapper_suggestions_total`	Counter	`result`	auto-mapper LLM 결과 분기. result ∈ `success / empty / error`.
`gend_ontology_grant_evaluations_total`	Counter	`decision`	ABAC 평가 결과. decision ∈ `allow / deny / no_grant / role_fallback` (M3 Step 1 engine).

기존 메트릭 유지:

UID: gend-ontology-overview — Grafana provisioning 으로 자동 등록.

Active Classes by layer (Stat) — gend_ontology_class_count 시리즈
Mutation rate (5m) (Time series) — rate(gend_ontology_class_mutations_total[5m]) action 별
Mapper result breakdown (1h) (Pie) — increase(gend_ontology_mapper_suggestions_total[1h]) result 별
ABAC deny rate (5m) (Stat, percent) — deny / total 비율, 0.1 (10%) 이상 빨강 임계값
ABAC decisions over time (Time series) — decision 별 rate
SHACL validation failures (5m) (Time series) — class_name 별 rate
Version snapshots created (24h) (Bar gauge) — scope 별 increase

gend_ontology_validation_failures_total 의 1h rate > 10/min → "SHACL 위반 급증" 알람
ABAC deny rate > 50% (5m) → "권한 정책 너무 좁음" 알람
gend_ontology_mapper_suggestions_total{result=\"error\"} 의 15m rate > 0 → "LLM mapper 가용성" 알람

Counter	emit 위치
`class_create / class_update / class_delete / class_put_with_properties`	`routers/ontology.py` 의 각 핸들러 성공 path
`relation_create / relation_delete`	`routers/ontology.py` 의 Relation 핸들러 성공 path
`instance_create`	`routers/ontology.py::create_ontology_instance` 성공 path
`validation_failures_total`	`routers/ontology.py::create_ontology_instance` 의 `except OntologyValidationError`
`mapper_suggestions_total{result=success/empty/error}`	`routers/ontology.py::suggest_ontology_mapping` 3 분기
`grant_evaluations_total{decision}`	`services/ontology/abac.py::_emit_decision_metric` (engine 내부)
`class_count` (Gauge)	`services/ontology/observability.py::refresh_class_count_gauge` (lifespan + 30분)

모든 emit 는 silent — prometheus_client import 실패해도 서비스 정상 동작 (테스트 환경 호환).

파일	범위
`apps/api/tests/test_ontology_metrics.py`	메트릭 등록 + emit (mutation/mapper/validation/grant_eval) + Gauge refresh + Grafana JSON 검증 — 11
`apps/api/tests/test_ontology_abac.py`	M3 Step 1 회귀 유지 (grant_eval emit 검증 포함)