document-haness/docs/keycloak-session-store/final/.techviz/observation-points/spec.json

{
  "version": "1.1",
  "id": "observation-points",
  "title": "관측을 어디에 둘 것인가",
  "question": "밖에서만 재면 무엇을 놓치는가",
  "type": "architecture",
  "direction": "LR",
  "audience": [
    "장애 실험의 관측을 설계하는 엔지니어"
  ],
  "summary": "외부 curl 은 사용자가 겪는 것만 본다. 분단된 노드가 스스로 빠지면 밖에서는 아무 일도 없다.",
  "alt": "외부 curl, Prometheus 지표, PostgreSQL 직접 조회 세 지점이 같은 시스템의 서로 다른 층을 보는 구성.",
  "long_description": "처음에는 외부 curl 로만 쟀다. A-1 에서 7800 을 끊었는데 외부 응답이 전부 200 이었다. 장애가 없어서가 아니라 분단된 노드가 readiness 실패로 스스로 로드밸런서에서 빠졌기 때문이다. 그래서 관측 지점을 셋으로 늘렸다. up 지표도 신뢰할 수 없었다 — A-2 에서 503 이 나는 동안에도 1이었다. 프로세스가 살아 있고 metrics 가 응답하면 up 은 1이며 살아 있지만 쓸모없는 상태를 못 본다.",
  "source_context": {
    "document": "docs/keycloak-session-store/final/document.md",
    "document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
    "anchor": {
      "kind": "heading",
      "value": "관측을 어디에 둘 것인가",
      "line": 140
    }
  },
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": [
      "payment-event-flow"
    ],
    "rationale": "같은 시스템을 세 지점에서 보아야 한다는 것이 지배적 질문이다. 관측 경로의 배치이므로 component-flow 를 골랐다."
  },
  "groups": [],
  "nodes": [
    {
      "id": "system",
      "label": "Keycloak 클러스터",
      "kind": "service",
      "role": "source",
      "emphasis": "primary",
      "description": "측정 대상.",
      "details": [
        "두 노드"
      ],
      "evidence": [
        {
          "start_line": 141,
          "end_line": 146
        }
      ],
      "assumption": false
    },
    {
      "id": "curl",
      "label": "외부 curl",
      "kind": "process",
      "role": "target",
      "emphasis": "normal",
      "description": "사용자가 겪는 것.",
      "details": [
        "분단돼도 200 이 나올 수 있다"
      ],
      "evidence": [
        {
          "start_line": 143,
          "end_line": 147
        }
      ],
      "assumption": false
    },
    {
      "id": "prom",
      "label": "Prometheus 지표",
      "kind": "process",
      "role": "target",
      "emphasis": "primary",
      "description": "클러스터 내부 상태.",
      "details": [
        "vendor_cluster_size · agroal_*"
      ],
      "evidence": [
        {
          "start_line": 143,
          "end_line": 147
        }
      ],
      "assumption": false
    },
    {
      "id": "psql",
      "label": "PostgreSQL 직접 조회",
      "kind": "process",
      "role": "target",
      "emphasis": "primary",
      "description": "실제로 무엇이 저장됐는가.",
      "details": [
        "OFFLINE_USER_SESSION"
      ],
      "evidence": [
        {
          "start_line": 143,
          "end_line": 147
        }
      ],
      "assumption": false
    }
  ],
  "edges": [
    {
      "id": "s-c",
      "from": "system",
      "to": "curl",
      "label": "외부 응답",
      "kind": "read",
      "evidence": [
        {
          "start_line": 143,
          "end_line": 147
        }
      ],
      "assumption": false
    },
    {
      "id": "s-p",
      "from": "system",
      "to": "prom",
      "label": "내부 지표",
      "kind": "read",
      "evidence": [
        {
          "start_line": 143,
          "end_line": 147
        }
      ],
      "assumption": false
    },
    {
      "id": "s-d",
      "from": "system",
      "to": "psql",
      "label": "저장 결과",
      "kind": "read",
      "evidence": [
        {
          "start_line": 143,
          "end_line": 147
        }
      ],
      "assumption": false
    }
  ],
  "legend": [],
  "metadata": {
    "rationale": "세 지점이 서로 다른 층을 본다는 것과, 각 지점이 못 보는 것을 함께 담았다."
  }
}