특히 LLM에게 코드를 읽히는 워크플로우에서는 이 문제가 더 선명하게 드러납니다. 함수 하나를 이해하는 일은 어렵지 않습니다. 하지만 다음과 같은 질문은 쉽게 느려집니다.

• 주문 승인 같은 end-to-end 흐름은 어느 서비스들을 거치는가
• 여러 서비스가 공유하는 인프라는 어디에 묶여 있는가
• 설정과 DI 구성이 여러 파일에 흩어져 있을 때 전체 구조는 어떻게 생겼는가

이런 질문은 보통 grep과 파일 열람을 반복하면서 답하게 됩니다. 답은 얻을 수 있지만, 탐색 비용이 높습니다. 그래서 코드 인덱싱 기반 Knowledge Graph를 붙이면 이 비용을 줄일 수 있을지 실험해 봤습니다.

핵심 요약

문제 상황: 왜 기존 탐색은 특정 질문에서 느려질까

답이 한 파일에 있는 질문 — 직접 탐색이 빠름

• 특정 메서드 구현 상세를 묻는 질문
• 테스트 시나리오 목록처럼 한 파일 안에 답이 있는 질문
• 최신 변경 이유처럼 변경 이력이 더 중요한 질문

이 경우에는 파일 하나를 찾고 읽으면 끝납니다. 그래프를 거치는 순간 오히려 단계가 하나 늘어납니다.

답이 여러 파일에 흩어진 질문 — 구조적으로 느림

• 여러 서비스와 컴포넌트가 연결된 end-to-end 흐름
• cross-service shared infrastructure 식별
• 여러 Config 클래스에 흩어진 Bean 또는 설정 구조 파악

느린 이유는 단순합니다. 답이 한 파일에 없기 때문입니다. 탐색자는 여러 파일을 순차적으로 열고, 각 파일이 가리키는 다음 파일로 계속 이동해야 합니다. LLM도 똑같이 이 비용을 지불합니다.

flowchart LR
    A[질문 시작] --> B{답이 한 파일에 있는가?}
    B -- "예" --> C[Grep/Read로 즉시 해결]
    B -- "아니오" --> D[여러 파일 순차 탐색]
    D --> E[publisher 찾기]
    E --> F[client 찾기]
    F --> G[config 찾기]
    G --> H[adapter 찾기]
    H --> I[탐색 비용 누적]
    style C fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style I fill:#5f2d2d,stroke:#ff6b6b,color:#fff

실험 설계

두 가지 접근을 비교했습니다.

평가 기준은 세 가지였습니다.

• 정확도: 정답 품질이 유지되는가 (rubric 0~3점)
• 도구 호출 수: 세션 내 총 도구 호출 횟수
• 입력 토큰: 세션 전체 입력 토큰량

질문은 5개 범주로 나눴습니다.

pie title 질문 범주 분포
    "architecture" : 2
    "function" : 2
    "dependency (cross-service)" : 2
    "config" : 2
    "history (why)" : 2

실험 결과

전체 평균: 두 방식이 사실상 동등

해석: 두 그룹은 전체 평균 수준에서 사실상 동등합니다. 평균이 “동등”한 이유는 질문 유형마다 효율이 크게 다른데 이를 섞어서 평균을 냈기 때문입니다.

질문별 실측 데이터: 편차의 핵심

10개 질문 각각에 대해 두 방식의 도구 호출 수를 직접 비교했습니다.

xychart-beta
    title "질문별 도구 호출 수 비교"
    x-axis ["m1","m2","m3","m4","m5","m6","m7","m8","m9","m10"]
    y-axis "도구 호출 수" 0 --> 15
    bar [14, 8, 2, 7, 6, 10, 4, 5, 3, 3]
    line [5, 9, 6, 6, 11, 7, 10, 3, 5, 6]

패턴 요약:

카테고리별 집계

핵심 발견: architecture 카테고리만 카테고리 수준에서도 그래프 탐색이 뚜렷하게 우세했습니다. 나머지 카테고리는 질문별 편차가 커서 평균만으로 일괄 판단하기 어려웠습니다.

그래프가 유효했던 질문 — 구체 사례

사례 1: end-to-end 흐름 질문 (m1, -64%)

질문: “특정 비즈니스 흐름이 end-to-end로 어떻게 동작하는가?”

사례 2: cross-service 공유 인프라 질문 (m6, -30%)

질문: “여러 서비스가 공유하는 특정 인프라 컴포넌트를 나열하라”

그래프가 비효율적이었던 질문

의사결정: 질문 라우팅 규칙

Knowledge Graph의 가치는 “항상 쓰면 빨라진다”가 아니라, “특정 질문에만 선택적으로 쓸 때 이득이 커진다”는 데 있습니다.

그래프를 도입하는 것 자체보다 먼저 해야 할 일은 질문 라우팅 규칙을 만드는 것입니다.

라우팅 의사결정표

flowchart TD
    Q[질문 입력] --> D1{여러 서비스/컴포넌트가<br/>연관되어 있는가?}
    D1 -- "아니오" --> R1[직접 탐색<br/>Grep/Read]
    D1 -- "예" --> D2{답이 단일 파일에<br/>존재하는가?}
    D2 -- "예" --> R1
    D2 -- "아니오" --> D3{최신 변경 이력이<br/>핵심인가?}
    D3 -- "예" --> R2[Git history +<br/>설계 문서 확인]
    D3 -- "아니오" --> R3[Knowledge Graph<br/>우선 적용]
    style R3 fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style R1 fill:#1e293b,stroke:#8cc5ff,color:#fff
    style R2 fill:#1e293b,stroke:#8cc5ff,color:#fff

제한점 및 리스크

후속 액션

마무리

Knowledge Graph는 코드 탐색의 만능 해법이 아니었습니다. 하지만 그 점이 오히려 더 흥미로웠습니다. 정말 중요한 것은 “그래프를 썼는가”가 아니라 “언제 써야 하는가”였습니다.

LLM을 코드 탐색에 본격적으로 활용할수록, 검색 품질 못지않게 질문을 올바른 탐색 경로로 라우팅하는 설계가 중요해집니다. 이번 실험의 가장 큰 수확은 그래프 자체보다 그 운영 규칙이었습니다.

비슷한 실험을 하시려면, 그래프 구축부터 시작하지 않으셔도 됩니다. 먼저 팀의 질문 유형부터 정리해 보세요. 어떤 질문이 가장 자주 느린지 분류하는 순간, 그래프가 필요한 자리와 필요 없는 자리가 생각보다 빨리 드러납니다.

• rollout 중 간헐적인 UNAVAILABLE 에러
• 일부 Pod에만 트래픽이 몰리는 connection skew
• fan-out 요청에서 비정상적으로 높아지는 지연 시간

처음에는 각각 따로 해결해야 하는 문제처럼 보였습니다. 하나는 배포 문제, 하나는 load balancing 문제, 또 하나는 성능 문제였기 때문입니다.

그런데 실험을 진행할수록 세 문제를 하나로 묶는 공통 배경이 보이기 시작했습니다. 핵심은 long-lived connection이었습니다. gRPC의 HTTP/2 연결은 오래 살아 있고, service mesh는 그 연결 위에서 endpoint를 선택하고 유지합니다. 이 특성이 rollout, 분산, 성능에 연쇄적으로 영향을 줬습니다.

핵심 요약

문제-원인-해결 한눈에 보기

flowchart TD
    ROOT["long-lived connection<br/>(gRPC HTTP/2)"]
    ROOT --> P1["문제 1<br/>rollout 중 UNAVAILABLE"]
    ROOT --> P2["문제 2<br/>connection skew"]
    ROOT --> P3["문제 3<br/>fan-out 지연"]
    P1 --> F1["해결: shutdown timing 설계"]
    P2 --> F2["해결: endpoint selection 우선 조정"]
    P3 --> F3["해결: 호출 형태 재설계<br/>(batch API)"]
    style ROOT fill:#5f2d2d,stroke:#ff6b6b,color:#fff
    style F1 fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style F2 fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style F3 fill:#2d5f2d,stroke:#4a9eff,color:#fff

배경: HTTP/1.1 vs gRPC (HTTP/2) 핵심 차이

flowchart LR
    subgraph "HTTP/1.1"
        direction TB
        H1C1[연결 1] --> H1P1[Pod A]
        H1C2[연결 2] --> H1P2[Pod B]
        H1C3[연결 3] --> H1P1b[Pod A]
    end
    subgraph "gRPC (HTTP/2)"
        direction TB
        G2C1["연결 1 (장기)"] --> G2P1["Pod A<br/>100% 고착"]
        G2S1[stream 1] --> G2C1
        G2S2[stream 2] --> G2C1
        G2S3[stream 3] --> G2C1
    end
    style G2P1 fill:#5f2d2d,stroke:#ff6b6b,color:#fff

문제 1: rollout은 성공했지만 요청은 불안정했다

현상

애플리케이션은 graceful shutdown을 하도록 설정했는데도, rollout 시점에 gRPC UNAVAILABLE가 간헐적으로 발생했습니다. 애플리케이션 로그만 보면 종료가 천천히 진행되는 것처럼 보였지만, 실제 네트워크 경로에서는 더 빨리 무언가가 사라지고 있었습니다.

원인

이 문제를 이해하려면 애플리케이션만 보면 안 됩니다. service mesh sidecar까지 포함한 종료 순서를 같이 봐야 합니다.

• app보다 sidecar가 먼저 연결 정리를 끝내는 경우
• endpoint 제거가 전파되기 전에 종료 중인 Pod로 트래픽이 한 번 더 들어오는 경우
• 에러가 난 endpoint를 mesh가 바로 격리하지 못하는 경우

즉, 애플리케이션 하나의 graceful shutdown만으로는 충분하지 않았습니다. Kubernetes lifecycle, service registry 반영 타이밍, sidecar drain, client retry가 함께 맞물려야 했습니다.

실측: Fix 적용 전후 비교

Baseline (Fix 적용 전)

분석: gRPC client retry(maxAttempts=3)가 Envoy 레벨 에러를 마스킹하고 있었습니다. 1건의 느린 요청(1.41s)은 retry가 실제로 발생했음을 시사합니다 (정상 응답 ~0.03s 대비).

Fix 후 단일 서비스 배포

Fix 전후 비교

Multi-hop gRPC Chain 동시 배포 검증

시나리오 A: 2개 서비스 동시 배포

시나리오 B: Multi-hop chain 양쪽 동시 배포

분석: Multi-hop chain의 양쪽 끝을 동시 재배포해도 에러 0건. 시나리오 A에서는 느린 요청도 0건으로, Fix 후 Envoy drain이 정상 작동하여 retry 자체가 불필요해졌습니다.

해결: 종료 타이밍 시간관계 설계

종료 관련 설정은 독립 값이 아니라 시간 관계로 봐야 합니다.

gantt
    title Pod 종료 시퀀스 (정상 설계)
    dateFormat X
    axisFormat %s초

    section Kubernetes
    SIGTERM 수신             :done,   k1, 0, 0
    terminationGracePeriod   :active, k2, 0, 180

    section Sidecar
    drain 시작               :done,   s1, 0, 0
    활성 연결 0 시 즉시 종료  :s2, 0, 30
    drain 대기 (최대 30s)     :active, s3, 0, 30

    section App
    preStop sleep            :done,   a1, 0, 20
    Spring graceful shutdown  :active, a2, 20, 100
    gRPC server shutdown      :active, a3, 20, 95

핵심 부등식:

preStop(20s) < sidecar drain(30s) < app shutdown(80s) < terminationGracePeriod(180s)

영향 범위

문제 2: 연결을 끊어도 트래픽은 다시 같은 Pod로 향했다

현상

요청 분포를 확인해 보니 일부 상황에서 트래픽이 특정 Pod에 거의 고정되었습니다.

초기 시도와 한계

처음에는 gRPC의 장기 연결 특성 때문이라고 생각했습니다. 그래서 가장 먼저 시도한 것은 연결 rotation이었습니다.

실험 1: Baseline (설정 없음, 2-Pod)

gantt
    title Rolling Restart 시계열 (Baseline, 2-Pod)
    dateFormat X
    axisFormat %s초

    section Pod-1 (기존)
    트래픽 100% 유지     :done, p1, 0, 60
    종료                  :milestone, p1e, 60, 60

    section Pod-2 (신규)
    대기                  :active, p2, 0, 60
    트래픽 100% 이동      :done, p2a, 60, 120

실험 2: maxRequestsPerConnection=1000

1000회 요청 후 연결을 재생성하여 장기 분산 개선을 시도했습니다.

시계열 (1000, Rolling restart):

시간    Pod1    Pod2    Pod3    Pod4    Pod5
+56s    27      25       0       0       0   ← 기존 Pod
+91s     0       0      50       0       0   ← restart 후 → Pod A
+170s    0       0       0       0      52   ← 1000req rotation → Pod B
+260s    0      52       0       0       0   ← rotation → 다른 Pod

해석: 장기적 분산은 개선되었으나, 각 시점에서는 여전히 단일 Pod에 집중합니다.

실험 3: maxRequestsPerConnection=50 (2-Pod)

50회 요청(~10초)마다 rotation하여 순간 분산도 개선을 시도했습니다.

시계열 (50, Rolling restart):

시간    Pod1(기존) Pod2(기존) Pod3(신규) Pod4(신규)
+11s      24        24         0         0   ← 기존 2개에 균등
+45s      31        18         0         0   ← rotation마다 전환
+113s      0        29         0        21   ← 과도기: 기존1 + 신규1
+158s      0         0        30        19   ← 신규 2개에 즉시 균등
+294s      0         0        23        28   ← 끝까지 균등 유지

해석: 2-Pod에서는 rotation 빈도 증가로 분산이 개선됩니다.

실험 4: 전환점 — 4-Pod에서 가설 기각

4-Pod 실측 데이터:

27번 연결을 끊고 다시 맺었지만, 매번 동일한 Pod를 선택했습니다.

근본 원인: Locality-Aware Load Balancing

flowchart TD
    subgraph "문제: Locality-Aware LB"
        direction TB
        CL1[Client] -->|"priority 0"| P1["Pod 1<br/>(동일 AZ)"]
        CL1 -.->|"priority 1<br/>(사용 안 함)"| P2[Pod 2]
        CL1 -.->|"priority 1"| P3[Pod 3]
        CL1 -.->|"priority 1"| P4[Pod 4]
    end
    subgraph "해결: distribute 설정"
        direction TB
        CL2[Client] -->|"25%"| PP1["Pod 1<br/>(AZ-a)"]
        CL2 -->|"25%"| PP2["Pod 2<br/>(AZ-b)"]
        CL2 -->|"25%"| PP3["Pod 3<br/>(AZ-c)"]
        CL2 -->|"25%"| PP4["Pod 4<br/>(AZ-d)"]
    end
    style P1 fill:#5f2d2d,stroke:#ff6b6b,color:#fff
    style PP1 fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style PP2 fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style PP3 fill:#2d5f2d,stroke:#4a9eff,color:#fff
    style PP4 fill:#2d5f2d,stroke:#4a9eff,color:#fff

문제는 연결이 오래 살아서만이 아니라, 재연결할 때도 같은 locality 집합으로 돌아간다는 점이었습니다. 연결을 끊는 것 자체는 재분배를 보장하지 않습니다.

해결: endpoint selection을 먼저 조정

적용 순서가 중요합니다. 순서를 바꾸면 안 됩니다.

1. endpoint selection 정책 확인 — locality/priority 편향 확인
2. locality-aware distribution 명시적 조정 — cross-zone 균등 분배
3. connection rotation은 보조 수단 — 위 두 단계가 맞을 때만 의미 있음

영향 범위

문제 3: 오류는 없었지만 fan-out 요청의 지연은 컸다

현상

특정 API는 내부적으로 downstream gRPC를 매우 많이 fan-out하고 있었습니다. 기능적으로는 정상이고 오류도 없었지만, 지연 시간은 예상보다 컸습니다.

원인

장기 연결 하나 위에 많은 stream이 몰리면 packet density가 높아지고, service mesh proxy의 event loop가 그 부하를 직렬화된 형태로 받는 순간이 생깁니다.

flowchart LR
    subgraph "Before: 1000회 fan-out"
        GW1[Gateway] -->|"1000회 호출"| PR1[Proxy]
        PR1 -->|"단일 연결에<br/>stream 1000개"| SVC1[Downstream Service]
    end
    subgraph "After: 배치 API"
        GW2[Gateway] -->|"1회 호출<br/>(batch)"| PR2[Proxy]
        PR2 -->|"stream 1개"| SVC2[Downstream Service]
    end
    style PR1 fill:#5f2d2d,stroke:#ff6b6b,color:#fff
    style PR2 fill:#2d5f2d,stroke:#4a9eff,color:#fff

해결: 호출 형태 재설계

실측 요약

fan-out 자체가 과하면, 가장 큰 이득은 더 많은 튜닝이 아니라 호출 수를 줄이는 방향에서 나옵니다.

영향 범위

공통 원인: 세 문제를 하나로 묶는 관점

flowchart TD
    CORE["long-lived connection<br/>(gRPC HTTP/2 특성)"]
    CORE --> C1["연결은 오래 산다<br/>→ 재분배 기회 적음"]
    CORE --> C2["endpoint 선택이<br/>연결 생성 시점에 결정됨"]
    CORE --> C3["proxy는 단순 전달자가 아님<br/>→ drain, balancing, pool 동작이<br/>실제 행태를 바꿈"]
    C1 --> P1["문제 1: rollout 중<br/>sidecar 종료 타이밍 충돌"]
    C2 --> P2["문제 2: locality 편향이<br/>재연결에도 고착"]
    C1 --> P3["문제 3: 단일 연결에<br/>stream 과밀집"]
    C3 --> P1
    C3 --> P2
    C3 --> P3
    style CORE fill:#5f2d2d,stroke:#ff6b6b,color:#fff

운영 체크리스트

Rollout

• app graceful shutdown만 보고 있지 않은가 — sidecar drain 시간도 함께 설계했는가
• sidecar drain 시간이 preStop보다 충분히 긴가
• readiness 제거와 endpoint 전파 시간을 고려했는가
• retry가 문제를 숨기고만 있지는 않은가 — retry 없이도 에러가 0인가

Load Distribution

• skew가 connection lifetime 문제인지, selection policy 문제인지 분리했는가
• locality-aware policy가 특정 집합에 과도한 우선순위를 주고 있지 않은가
• reconnect가 실제 분산으로 이어지는지 메트릭으로 확인했는가

Performance

• high fan-out 요청이 proxy에서 density 문제를 만들고 있지 않은가
• connection pool 튜닝 전에 호출 수 자체를 줄일 수 있는가
• batch API로 바꾸면 병목을 더 크게 줄일 수 있지 않은가

리스크 및 예외 케이스

후속 액션

마무리

운영 문제는 대개 증상 단위로 관측됩니다. 배포 오류, skew, 성능 저하처럼 각각 다른 이름으로 드러나지만, 원인을 따라가 보면 같은 구조적 특성이 여러 형태로 나타나는 경우가 있습니다.

gRPC + service mesh 환경에서 이 문제들을 관통하는 공통 배경은 long-lived connection이었습니다.

이 관점을 얻고 나니 해결 순서도 달라졌습니다. rollout은 종료 타이밍의 문제로, skew는 endpoint selection의 문제로, fan-out 지연은 호출 구조의 문제로 다시 분리해서 볼 수 있었습니다. 그리고 각각의 설정값보다 먼저, 시스템이 연결을 어떻게 만들고 얼마나 오래 유지하며 어디로 보내는지를 이해하는 쪽이 훨씬 중요하다는 점을 배웠습니다.

비슷한 현상을 겪고 계시다면, 문제를 세 개로 나누기 전에 먼저 하나의 질문을 던져 보세요.

이 시스템의 long-lived connection은 지금 어디에서, 어떤 방식으로, 얼마나 오래 영향을 미치고 있는가?

대개 해답의 절반은 그 질문 안에 들어 있습니다.