SOP & Runbook: Pengayaan Pengetahuan AI & Manajemen Aturan Deklaratif (Declarative Rulepacks)¶
Dokumen ini merupakan panduan operasional standar (Standard Operating Procedure / Runbook) bagi Operator SRE dalam memperkaya (knowledge enrichment), mengevaluasi (gatekeeping review), mengimpor (hot-reload ingestion), dan mengelola basis aturan diagnosis deklaratif (Declarative Rulepacks) pada platform Tomcat Diagnostic Service.
ποΈ Arsitektur Alur Tata Kelola Pengetahuan (Knowledge Governance)¶
Sistem mengadopsi prinsip Human-in-the-Loop Governance di mana kecerdasan buatan (AI) bertindak sebagai akselerator sintesis log error, sedangkan Operator SRE memegang kendali penuh sebagai penjamin mutu (gatekeeper) sebelum aturan baru diaktifkan ke dalam production runtime.
flowchart TD
subgraph SRE_Env["Laptop Operator SRE (Remote / Local)"]
MC["<b>Master Rules Catalog</b><br/>(master-rules.json)"]
PROMPT["<b>AI Prompt Formulation</b><br/>(Domain / Log Evidence)"]
QA["<b>SRE QA Review</b><br/>(Pattern & SOP Check)"]
end
subgraph AI_Env["External AI Engine"]
LLM["<b>LLM Analyzer</b><br/>(Gemini / Claude / GPT)"]
end
subgraph Runtime_Env["Monitoring Platform Network"]
API["<b>Diagnostic Service REST API</b><br/>POST /api/v1/rules<br/>(Port 8443 TLS)"]
GUARD["<b>5-Layer Ingestion Guard</b><br/>Auth β’ Schema β’ Collision<br/>Immutability β’ Payload Size"]
ENGINE["<b>Dynamic Rule Evaluator</b><br/>(In-Memory RAM Engine)"]
DB[("<b>SQLite Database</b><br/>(custom_rules table)")]
end
MC --> PROMPT
PROMPT -->|"Kirim Konteks"| LLM
LLM -->|"JSON Rulepack"| QA
QA -->|"REST API / curl / CLI"| API
API --> GUARD
GUARD -->|"Hot-Reload"| ENGINE
GUARD -->|"Persistensi"| DB
DB -.->|"GET /api/v1/rules"| MC
π Empat Pilar Tata Kelola Operasional¶
- AI sebagai Akselerator Analisis: Bertugas merumuskan pola log (regex/substring), kategori failure domain, dan langkah mitigasi SOP berbasis data forensik insiden atau taksonomi domain kegagalan.
- Operator SRE sebagai Otoritas Tertinggi (Gatekeeper): Memverifikasi keabsahan logika diagnosis, memeriksa keunikan pola, dan mengeksekusi ingestion dengan kredensial resmi.
- 5-Layer Ingestion Defense-in-Depth: Memastikan setiap aturan yang masuk melalui API tervalidasi secara ketat terhadap autentikasi token, kepatuhan skema JSON, pencegahan tabrakan branch bawaan (
TD-01s/dTD-08), batas ukuran memori (maks. 64 KB), dan sifat append-only. - Zero-Downtime Hot-Reload & Domain Categorization: Aturan yang berhasil di-ingest langsung aktif seketika di memori engine (RAM), diklasifikasikan ke dalam kategori failure domain resmi, dan tersimpan permanen di database SQLite
custom_rulestanpa perlu me-restart container layanan.
π Dua Mode Pengayaan Pengetahuan (Enrichment Modes)¶
Operator dapat memperkaya basis pengetahuan diagnosis melalui dua pendekatan komplementer:
flowchart LR
subgraph Mode_A["Mode A: Pengayaan Proaktif"]
direction TB
DOM["<b>7 Failure Domains</b><br/>Memory β’ Database β’ Concurrency<br/>Network β’ App β’ OS β’ Security"] --> PROMPT_A["<b>Formulasi Batch Prompt AI</b><br/>Sintesis 3-5 Pola per Domain"]
PROMPT_A --> INGEST_A["<b>Batch Ingest JSON Array</b><br/>(scripts/ingest-rule.sh)"]
end
subgraph Mode_B["Mode B: Pengayaan Reaktif"]
direction TB
INC["<b>Insiden TomcatDown Baru</b><br/>Status: Undetermined (TD-08)"] --> EXTRACT["<b>Ekstrak Bukti Log Forensik</b><br/>catalina.out / thread dump"]
EXTRACT --> PROMPT_B["<b>Formulasi Prompt Reaktif AI</b><br/>Analisis Root Cause Spesifik"]
PROMPT_B --> INGEST_B["<b>Single Ingest JSON Object</b><br/>(scripts/ingest-rule.sh)"]
end
1. Mode A: Pengayaan Proaktif (Pre-emptive Domain Engineering)¶
Pengayaan proaktif bertujuan melengkapi pustaka aturan diagnosis sebelum insiden nyata terjadi di lingkungan produksi. Ketika insiden pertama kali muncul, sistem langsung memberikan diagnosis deterministik (confirmed_cause) dan SOP mitigasi seketika tanpa jatuh ke status UNDETERMINED.
mindmap
root((Tomcat & JVM<br/>Failure Domains))
Concurrency & Threading
Thread Starvation
Java Thread Deadlock
Thread Pool Saturation
Database & Persistence
Backend Lock Contention
SQL Query Timeout
HikariCP Pool Timeout
DBCP Connection Leak
JVM & Memory
GC Overhead Limit
Metaspace Exhaustion
DirectBuffer OOM
Java Heap Space OOM
Network & Integration
Connection Reset by Peer
DNS Lookup Failure
SSL Handshake Failure
Socket Read Timeout
Application Lifecycle
BeanCreationException
Circular Dependency
Missing Required Properties
Spring Context Failure
Storage & OS Limits
Disk Space Exhaustion
Permission Denied
File Descriptor Limit
2. Mode B: Pengayaan Reaktif (Incident-Driven Post-Mortem)¶
Pengayaan reaktif dilakukan saat Diagnostic Service menerima insiden baru yang belum terpetakan dalam basis aturan (unmapped failure pattern), sehingga diklasifikasikan sebagai UNDETERMINED (Branch TD-08):
sequenceDiagram
autonumber
actor SRE as Operator SRE
participant DS as Diagnostic Service
participant AI as External AI Engine
Note over SRE,DS: Terjadi insiden dengan pola error baru
SRE->>DS: Ekspor Ringkasan Bukti Forensik Insiden
DS-->>SRE: Cuplikan Log Error (catalina.out / hs_err_pid)
SRE->>AI: Kirim Log Error + Prompt Sintesis Rulepack
AI-->>SRE: Declarative Rulepack JSON (misal: TD-19)
SRE->>SRE: SRE QA Review (Checklist Validasi)
SRE->>DS: POST /api/v1/rules (Ingest dengan Bearer Token)
DS-->>SRE: 201 Created (Rulepack Aktif Seketika)
Note over DS: Insiden serupa berikutnya terpetakan secara otomatis
π§ Implementation & Operating Plan¶
| Tahap | Rencana Operasional |
|---|---|
| Export Master Catalog | Mengambil salinan berkas katalog master aktif dari Diagnostic Service ke PC lokal operator. |
| Formulate AI Prompting Context | Menyusun konteks prompt terstruktur (proaktif per domain atau reaktif per insiden) ke AI Engine. |
| Conduct SRE QA Review | Melakukan evaluasi kepatuhan (gatekeeping review) terhadap JSON Rulepack yang dihasilkan AI. |
| Ingest Rulepack via API | Mengimpor berkas JSON (single rule / batch array) ke Diagnostic Service dengan Bearer Token. |
| Verify Hot-Reload & Sync | Memverifikasi ketersediaan aturan di runtime dan menyinkronkan kembali katalog master lokal di PC. |
βοΈ Prosedur Standar Operasional (Implementation Stages)¶
Export & Backup Master Catalog¶
Action: Mengambil salinan seluruh aturan diagnosis aktif atau memeriksa daftar kategori dari Diagnostic Service REST API (https://<DIAGNOSTIC_HOST>:8443/api/v1/rules) dan menyimpannya ke berkas kerja lokal operator (~/master-rules.json).
Opsi A: Menggunakan REST API Langsung (Universal curl dari laptop SRE mana saja)¶
# 1. Ekspor seluruh katalog master aktif ke berkas lokal
curl -k -s -H "Authorization: Bearer test-token-12345" \
https://localhost:8443/api/v1/rules > ~/master-rules.json
# 2. Atau ekspor per kategori failure domain spesifik
curl -k -s -H "Authorization: Bearer test-token-12345" \
"https://localhost:8443/api/v1/rules?category=database_persistence"
Opsi B: Menggunakan Helper CLI (dari direktori repositori tomcat-monitoring)¶
# 1. Menampilkan daftar ringkasan seluruh kategori aktif beserta jumlah aturan
./scripts/export-rules.sh --categories
# 2. Ekspor seluruh katalog aturan aktif ke berkas lokal
./scripts/export-rules.sh > ~/master-rules.json
# 3. Atau ekspor per kategori failure domain spesifik
./scripts/export-rules.sh --category database_persistence
Expected Result
Operator menerima respons HTTP 200 OK dan berkas ~/master-rules.json tersimpan di PC lokal operator dalam format JSON terstruktur yang memuat seluruh deklarasi aturan aktif (TD-09 s/d TD-18) beserta kategori domainnya.
Formulate AI Prompting Context¶
Action: Menyusun prompt terstandarisasi dengan menyertakan isi berkas master-rules.json (hasil ekspor dari Langkah 1) sebagai basis data pembanding katalog master, menentukan target domain kegagalan atau menempelkan cuplikan log insiden riil, serta memberikan batasan kontrak skema JSON yang wajib dipatuhi AI Engine.
A. Template Prompt Proaktif (Per Domain)¶
Kamu adalah Principal JVM & Tomcat SRE Architect.
Saya sedang melakukan PROACTIVE KNOWLEDGE ENRICHMENT untuk Tomcat Diagnostic Service.
Berikut adalah Katalog Master Rule aktif yang diekspor dari sistem (master-rules.json):
~/master-rules.json
Catatan Arsitektur:
- Branch TD-01 s/d TD-08 adalah built-in system rules yang bersifat immutable (jangan gunakan ID ini).
- Periksa nomor branch kustom terakhir pada berkas master-rules.json di atas untuk menentukan ID branch lanjutan.
--- TUGAS PROAKTIF ---
Rancang kumpulan Declarative Rulepack baru untuk domain: [PILIH DOMAIN: Misal storage_os_limits / application_lifecycle / network_integration].
Rumuskan 3-5 failure patterns baru yang paling sering terjadi di level production dan belum ada pada katalog master di atas.
--- KONTRAK SCHEMA (WAJIB DIPATUHI) ---
1. "branch": ID branch baru kelanjutan setelah branch tertinggi di master-rules.json (misal: "TD-19", "TD-20", dst).
2. "ruleName": Nama unik PascalCase/camelCase deskriptif.
3. "category": Wajib salah satu dari 8 kategori: "jvm_memory", "concurrency_threading", "database_persistence", "network_integration", "application_lifecycle", "storage_os_limits", "security_session", "general".
4. "targetSource": "local_file"
5. "pattern": Substring unik atau regex aman (tidak boleh mengandung nested quantifier).
6. "assessment": Ringkasan akar masalah dalam 1 kalimat padat.
7. "classification": Wajib "confirmed_cause" atau "probable_cause".
8. "confidence": "high" (jika confirmed_cause) atau "medium" (jika probable_cause).
9. "recommendedActions": Array 4 langkah mitigasi SOP Bahasa Indonesia terstruktur.
10. "createdBy": "sre-proactive-enrichment"
Keluarkan HANYA satu blok Array JSON valid: [ {...}, {...} ] tanpa teks pengantar di luar blok.
Lalu simpan output jsonnya kedalam file ~/proactive-rules.json
B. Template Prompt Reaktif (Berdasarkan Insiden Riil)¶
Kamu adalah Enterprise SRE Expert untuk platform Tomcat Diagnostic.
Terdapat insiden kegagalan baru yang saat ini berstatus UNDETERMINED.
Berikut adalah Katalog Master Rule aktif yang diekspor dari sistem (master-rules.json):
~/master-rules.json
Catatan Arsitektur:
- Branch TD-01 s/d TD-08 adalah built-in system rules yang bersifat immutable (jangan gunakan ID ini).
- Periksa nomor branch kustom terakhir pada berkas master-rules.json di atas untuk menentukan ID branch lanjutan.
--- BUKTI LOG ERROR INSIDEN ---
<TEMPELKAN CUPLIKAN LOG ERROR ATAU STACK TRACE DI SINI>
--- TUGAS REAKTIF ---
1. Analisis bukti log error di atas dan tentukan akar masalah utamanya.
2. Buatkan 1 Declarative Rulepack JSON valid dengan nomor branch lanjutan baru setelah master-rules.json (misal: "TD-19").
3. Pilih "category" domain yang tepat ("jvm_memory", "concurrency_threading", "database_persistence", "network_integration", "application_lifecycle", "storage_os_limits", "security_session", "general").
4. Pastikan pola "pattern" unik, spesifik untuk mencocokkan error tersebut, dan belum pernah ada di master-rules.json.
5. Sertakan 4 langkah mitigasi SOP Bahasa Indonesia terstruktur.
6. Keluarkan HANYA satu blok JSON tunggal {...} sesuai kontrak skema.
Lalu simpan output jsonnya kedalam file ~/rule-td19.json
Expected Result
AI Engine menghasilkan output berupa blok JSON mentah (single object atau batch array) yang mematuhi skema formal termasuk properti category tanpa teks naratif di luar blok JSON.
Conduct SRE QA & Gatekeeping Review¶
Action: Melakukan tinjauan kualitas dan keamanan (quality assurance & gatekeeping) terhadap output JSON yang dihasilkan AI sebelum dieksekusi ke runtime Diagnostic Service.
Daftar Periksa Kepatuhan (Verification Checklist):
* [x] Branch Safety: Nilai branch tidak menggunakan rentang terproteksi TD-01 s/d TD-08.
* [x] Category Validity: Nilai category sesuai salah satu enum domain resmi sistem.
* [x] Pattern Precision: Pola pattern spesifik dan tidak menimbulkan potensi salah deteksi (false positive).
* [x] ReDoS Prevention: Pola regex bebas dari konstruksi rawan ledakan komputasi (nested quantifier seperti (a+)+ atau ([a-z]+)*).
* [x] Classification & Confidence Mapping: Nilai klasifikasi selaras dengan tingkat keyakinan (confirmed_cause wajib berpasangan dengan high).
* [x] Operational Actionability: Rekomendasi mitigasi pada recommendedActions jelas, aman, terurut secara logis, dan dapat dieksekusi operator.
Expected Result
Seluruh butir daftar periksa terpenuhi (100% compliant) dan berkas JSON siap untuk proses ingestion.
Ingest Rulepack via Diagnostic API¶
Action: Mengirimkan payload JSON yang telah divalidasi ke endpoint POST /api/v1/rules pada Diagnostic Service menggunakan HTTP POST Bearer Token resmi operator.
Opsi A: Menggunakan REST API Langsung (Universal curl dari laptop SRE mana saja)¶
# 1. Ingest Berkas Batch Array (Mode Proaktif)
curl -k -s -X POST https://localhost:8443/api/v1/rules \
-H "Authorization: Bearer test-token-12345" \
-H "Content-Type: application/json" \
-d @~/proactive-rules.json
# 2. Ingest Berkas Tunggal (Mode Reaktif)
curl -k -s -X POST https://localhost:8443/api/v1/rules \
-H "Authorization: Bearer test-token-12345" \
-H "Content-Type: application/json" \
-d @~/rule-td19.json
Opsi B: Menggunakan Helper CLI (dengan fitur validasi & auto-skip duplikasi)¶
# 1. Ingest Berkas Batch Array (Mode Proaktif)
BEARER_TOKEN="test-token-12345" ./scripts/ingest-rule.sh ~/proactive-rules.json
# 2. Ingest Berkas Tunggal (Mode Reaktif)
BEARER_TOKEN="test-token-12345" ./scripts/ingest-rule.sh ~/rule-td19.json
# 3. Ingest Langsung via Stdin Pipe
cat ~/new-rule.json | BEARER_TOKEN="test-token-12345" ./scripts/ingest-rule.sh -
Expected Result
Endpoint mengembalikan HTTP status 201 Created. Aturan baru langsung ter-rehidrasi di memori DynamicRuleEvaluator secara hot-reload dan tercatat permanen di tabel SQLite custom_rules. Pada mode batch via CLI, aturan yang sudah terdaftar akan dilewati (409 Conflict) tanpa memutus alur aturan lainnya.
Verify Hot-Reload & Synchronize Master Catalog¶
Action: Memverifikasi ketersediaan aturan baru di lingkungan runtime dan menyinkronkan kembali berkas master catalog di PC lokal operator.
Opsi A: Menggunakan REST API Langsung (Universal curl)¶
# 1. Verifikasi aturan spesifik yang baru di-ingest
curl -k -s -H "Authorization: Bearer test-token-12345" \
https://localhost:8443/api/v1/rules/TD-19
# 2. Sinkronkan seluruh katalog master ke PC lokal operator
curl -k -s -H "Authorization: Bearer test-token-12345" \
https://localhost:8443/api/v1/rules > ~/master-rules.json
Opsi B: Menggunakan Helper CLI¶
# 1. Verifikasi aturan spesifik yang baru di-ingest
./scripts/export-rules.sh TD-19
# 2. Periksa daftar ringkasan kategori aktif terbaru
./scripts/export-rules.sh --categories
# 3. Sinkronkan seluruh katalog master ke PC lokal operator
./scripts/export-rules.sh > ~/master-rules.json
Expected Result
Diagnostic Service menyajikan metadata aturan TD-19 secara presisi termasuk kategori domainnya, daftar ringkasan kategori terbarui, dan berkas ~/master-rules.json di PC lokal operator berada dalam status mutakhir (up-to-date).
π Matriks Master Knowledge Base Terkurasi (18 Branches)¶
Tabel berikut merangkum 18 cabang aturan diagnosis aktif yang saat ini telah terverifikasi di lingkungan DevOps Lab:
| Branch | Kategori Domain | Nama Rule (Rule Identifier) | Pola Bukti Error (Pattern) | Klasifikasi & Keyakinan | SOP Rekomendasi Mitigasi Operator |
|---|---|---|---|---|---|
TD-01 |
network_integration |
ScrapeTlsUnavailable (Built-in) |
Port 9404 unreachable / TLS fail | confirmed_cause(high) |
Periksa port binding, sertifikat TLS, dan konektivitas scraper Prometheus. |
TD-02 |
jvm_memory |
OOMKilled (Built-in) |
Exit 137 / cgroup OOM event | confirmed_cause(high) |
Periksa limit memori container host, alokasi JVM, dan cgroup bounds. |
TD-03 |
jvm_memory |
JvmCrash (Built-in) |
hs_err_pid*.log / SIGSEGV / exit 134 |
confirmed_cause(high) |
Analisis fatal crash dump JVM dan kompatibilitas native library APR. |
TD-04 |
network_integration |
PortBindConflict (Built-in) |
BindException: Address already in use |
confirmed_cause(high) |
Periksa port collision pada host port 8080/9404 dan proses zombie. |
TD-05 |
application_lifecycle |
OrderlyShutdown (Built-in) |
Exit 143 / SIGTERM orderly stop | confirmed_cause(high) |
Verifikasi proses deployment atau shutdown terjadwal yang disengaja. |
TD-06 |
storage_os_limits |
ContainerExitedUnknown (Built-in) |
Container exited tanpa bukti spesifik | undetermined(none) |
Periksa status cgroup, runtime container engine, dan log host. |
TD-07 |
general |
ContradictingState (Built-in) |
Telemetri saling bertentangan | undetermined(none) |
Lakukan verifikasi manual langsung ke target endpoint runtime aplikasi. |
TD-08 |
general |
UndeterminedEvidence (Built-in) |
Bukti tidak cukup / pola asing | undetermined(none) |
Ekspor data forensik insiden ke AI untuk perumusan rulepack baru. |
TD-09 |
database_persistence |
DatabasePoolExhausted (Enriched) |
CannotGetJdbcConnectionException |
confirmed_cause(high) |
Periksa utilisasi database backend, kapasitas maxTotal, dan connection leak. |
TD-10 |
concurrency_threading |
ThreadPoolExhausted (Enriched) |
RejectedExecutionException: Thread pool is exhausted |
confirmed_cause(high) |
Ambil thread dump JVM, sesuaikan parameter maxThreads, dan evaluasi traffic spike. |
TD-11 |
jvm_memory |
JavaHeapSpaceOOM (Enriched) |
OutOfMemoryError: Java heap space |
confirmed_cause(high) |
Analisis heap dump (.hprof) via Eclipse MAT, naikkan alokasi -Xmx. |
TD-12 |
jvm_memory |
MetaspaceOOM (Enriched) |
OutOfMemoryError: Metaspace |
confirmed_cause(high) |
Periksa ClassLoader leak, batasi dynamic bytecode generator, naikkan -XX:MaxMetaspaceSize. |
TD-13 |
network_integration |
SSLHandshakeFailure (Enriched) |
javax.net.ssl.SSLHandshakeException |
confirmed_cause(high) |
Periksa validitas sertifikat backend, perbarui truststore /conf/truststore.p12. |
TD-14 |
database_persistence |
HikariPoolTimeout (Enriched) |
Connection is not available, request timed out |
confirmed_cause(high) |
Aktifkan leakDetectionThreshold, tingkatkan maximumPoolSize, periksa database lock. |
TD-15 |
application_lifecycle |
ContextInitFailure (Enriched) |
LifecycleException: Failed to start component |
confirmed_cause(high) |
Periksa berkas web.xml, Spring context, kelengkapan WEB-INF/lib, dan file permission. |
TD-16 |
concurrency_threading |
JavaThreadDeadlock (Enriched) |
Found one Java-level deadlock |
confirmed_cause(high) |
Ambil thread dump (jstack), analisis siklus lock graph, perbaiki urutan sinkronisasi kode. |
TD-17 |
network_integration |
SocketReadTimeout (Enriched) |
SocketTimeoutException: Read timed out |
confirmed_cause(high) |
Periksa latency upstream API, sesuaikan connectTimeout/readTimeout, pasang Circuit Breaker. |
TD-18 |
database_persistence |
SQLQueryTimeout (Enriched) |
java.sql.SQLTimeoutException |
confirmed_cause(high) |
Analisis slow query log, periksa missing index via EXPLAIN ANALYZE, periksa row lock. |
π‘οΈ Panduan Respon & Penanganan Error 5-Layer Guard¶
| HTTP Status | Kode Error (Error Code) | Akar Masalah | Tindakan Perbaikan Operator |
|---|---|---|---|
201 |
Created |
Payload valid, aturan berhasil di-ingest. | Tidak ada tindakan lanjutan. Aturan langsung aktif secara hot-reload. |
401 |
unauthorized |
Header Authorization: Bearer <token> salah, kedaluwarsa, atau tidak dikirim. |
Pastikan variabel BEARER_TOKEN yang dikirim cocok dengan token rahasia yang terkonfigurasi. |
400 |
invalid_rule_schema |
Struktur JSON tidak lengkap, tipe data salah, atau nilai enum category/classification tidak valid. |
Periksa apakah seluruh properti wajib (branch, ruleName, category, targetSource, pattern, assessment, classification, confidence, recommendedActions, createdBy) telah lengkap dan sesuai enum yang diizinkan. |
400 |
unsafe_regex_pattern |
Pola pattern mengandung konstruksi regex berbahaya yang berisiko ReDoS. |
Sederhanakan pola regex atau gunakan pencocokan substring teks langsung. |
409 |
rule_branch_conflict |
ID branch bertabrakan dengan branch built-in (TD-01 s/d TD-08) atau branch kustom yang telah tersimpan. |
Gunakan nomor branch baru yang belum pernah terdaftar sebelumnya (misal: TD-19). |
413 |
payload_too_large |
Ukuran payload JSON melebihi ambang batas keamanan 64 KB. | Ringkas instruksi teks rekomendasi mitigasi atau perpendek pola pencocokan. |
405 |
Method Not Allowed |
Endpoint diakses menggunakan method HTTP yang tidak diizinkan (PUT, DELETE, PATCH). |
Basis aturan bersifat append-only (immutable). Gunakan method POST untuk menambahkan aturan baru. |