khseon7 님의 블로그

[EKS/Istio] 버전 기반 라우팅을 넘어 실전 카나리 배포와 모니터링 환경 구축하기

khseon7 — Tue, 12 May 2026 17:44:58 +0900

지난 포스팅에서는 AWS EKS 클러스터 위에 서비스를 배포하고, 별도의 라우팅 설정 없이 트래픽이 흐르는 모습을 관찰했다. 당시 Istio 내부 설정이 없어 EKS 내부의 쿠버네티스 서비스는 모든 파드에 트래픽을 균등하게 배분하는 라운드 로빈 방식으로 동작했다.

이번 포스팅에서는 이 기본 모드를 해제하고, 엔지니어가 직접 가중치를 조정해보는 과정을 기록한다. Istio의 VirtualService를 적용하여 트래픽의 비율을 정교하게 제어하는 카나리 배포를 수행하고, 이 통제가 의도대로 이루어지는지 Prometheus와 Grafana를 통해 기술적 근거를 확보해 보겠다.

1. 카나리 배포(Canary Deployment)란?

카나리 배포는 새로운 소프트웨어 버전을 전체 사용자에게 한꺼번에 배포하기 전, 일부 사용자에게만 소량의 트래픽을 노출시켜 안정성을 검증하는 점진적 배포 전략이다.

핵심 메커니즘

그룹 분리: 동일한 서비스 이름 아래 기존 버전(v1)과 신규 버전(v2)의 파드를 동시에 운영
가중치 제어: 시스템 설정을 통해 트래픽의 비율을 결정
지표 분석: Prometheus와 Grafana 같은 모니터링 도구를 사용하여 v2의 성공률, 응답 속도 등을 실시간으로 감시
최종 전환 또는 롤백: v2이 안정적이면 가중치를 높여 100%까지 전환하고, 문제가 발견되면 즉시 가중치를 0으로 낮춰 장애 차단

장점

리스크의 계량화: 신규 버전에 결함이 있더라도 피해 범위를 설정한 가중치 이내로 한정할 수 있다.
데이터 기반 의사결정: 실제 운영 환경에서 수집된 에러율과 지연 시간 데이터를 근거로 배포 지속 여부를 결정한다.
무중단 배포: 사용자는 서비스 중단을 경험하지 않으며, 백그라운드에서 조용히 시스템의 세대교체가 일어난다.

EKS와 Istio 환경에서의 구현

DestinationRule: 파드의 라벨을 기준으로 v1, v2라는 논리적 그룹을 정의한다.
VirtualService: 각 그룹으로 향할 트래픽의 구체적인 가중치를 명시한다.

2. 카나리 배포 진행 과정

기본 라운드 로빈 방식으로 흐르던 트래픽을 제어하기 위해, 다음과 같은 YAML 파일을 작성했다.

apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: reviews
spec:
  host: reviews
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2
---
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: reviews
spec:
  hosts:
  - reviews
  http:
  - route:
    - destination:
        host: reviews
        subset: v1
      weight: 90
    - destination:
        host: reviews
        subset: v2
      weight: 10

위 YAML 파일을 확인해 보면 DestinationRule에서는 reviews 서비스의 subsets가 v1, v2로만 정의하고 있습니다. 이로 인해 기존 bookinfo.yaml 에 포함되어 있는 v3는 라우팅 대상에서 완전히 제외되어 격리된다.

또한, VirtualService를 통해 정의된 각 subset에 대해 90:10의 가중치로 트래픽을 분리하도록 설정했다.

질문: 이미 배포된 서비스에 영향 없이 트래픽 비율만 바꿀 수 있나?
- 답변: 쿠버네티스의 선언적 방식 덕분에 VirtualService 파일에서 weight 필드만 수정하여 apply 하면, 파드 재시작 없이도 Envoy 프락시들이 즉시 새로운 교통 지침을 수행한다.
질문: 새로운 서비스는 기존 환경에 영향 없이 어떻게 추가하나?
- 답변: EKS 클러스터에 version: v2 라벨을 가진 파드를 독립적으로 배치한 뒤 Istio의 DestinationRule로 이를 논리적 그룹(Subset)으로 정의하고, 최종적으로 VirtualService를 통해 새 그룹으로 흐를 트래픽 비중을 결정함으로써 기존 환경에 영향 없이 새 버전을 준비시키는 과정이다.

3. 모니터링을 통한 가시성 확보

위와 같은 설정을 통해 실제 productpage에 들어가서 새로고침을 반복해 본 결과, 화면에 나타나는 리뷰의 별점에서 빨간색만 표시되지 않는 것을 확인할 수 있었다. v3 파드는 클러스터 내에 엄연히 존재하지만, DestinationRule의 서브셋 정의와 VirtualService의 라우팅 경로에서 의도적으로 제외했기에 단 한 건의 트래픽도 도달하지 않았음을 실제 화면을 통해 1차적으로 증명한 것이다.

이제 보이지 않는 인프라 하단의 데이터를 Grafana 대시보드로 시각화해 보았다.

SSH 터널링

AWS EKS 환경 내부의 메트릭을 관찰하기 위해 SSH 터널링 기법을 적용했다. istio-manager(EC2)와 내 로컬 PC를 연결하여, 클러스터 내부의 Grafana 대시보드를 내 로컬 PC로 가져왔다. 이후 지표를 분석한 결과 다음과 같다.

실제 트래픽 분산(v1:v2:v3=90:10:0) 이후 대시보드

정교한 트래픽 분산 비율: Incoming Requests By Destination 패널을 보면 reviews-v1은 약 1.5 ops/s를 기록하는 반면, reviews-v2는 0.1~0.2 ops/s 내외의 낮은 수치를 유지하는 것을 보면 위에서 설정한 90:10의 가중치가 인프라 하단에서 정확히 실현되고 있음을 보여준다.
시스템 안정성 증명: Incoming Success Rate 지표에서 두 버전 모두 100%의 성공률을 기록하고 있다. 이를 통해 신규 버전인 v2가 실시간 트래픽을 받았음에도 결함 없이 동작하고 있다는 것을 확인했다.
v3의 완벽한 격리: 대시보드 하단 범례를 확인하면 reviews-v3의 수치는 0에 수렴하여 선조차 보이지 않는 것을 보면 위 라우팅 설정이 v3로 가는 길을 완벽히 차단했음을 증명한다.

다중 가중치 설정을 통한 트래픽 핸들링

카나리 배포가 단순히 두 버전 사이의 전환을 넘어, 여러 버전의 파드에 대해 엔지니어가 의도한 대로 트래픽을 쪼개어 보낼 수 있다는 것을 확인하기 위해, Destination의 subset에 v3를 추가하고 VirtualService의 subset 추가 및 가중치를 v1(60%):v2(30%):v3(10%)으로 설정하고 그 결과를 관찰했다.

실제 트래픽 분산(v1:v2:v3=60:30:10) 이후 대시보드

의도한 비율대로 정렬된 트래픽 곡선: Incoming Requests By Destination 패널을 보면, 가장 높은 위치의 초록색 선(v1), 중간의 노란색 선(v2), 그리고 가장 낮은 파란색 선(v3)이 뚜렷한 층을 이루고 있다. 이는 각 버전에 흐르는 요청 수가 설정한 비율을 정확히 추종하여 계단식 구조를 형성하고 있음을 보여준다.
다중 버전의 동시 검증: 이전 단계에서 격리했던 v3까지 포함하여 세 버전을 동시에 운영하면서도, 신규 버전들(v2, v3)에 노출되는 트래픽을 각각 30%와 10%로 차등 제어함으로써 리스크를 분산했다.
지표의 일관성: 트래픽 양은 서로 다르지만, Incoming Success Rate 패널에서 세 버전 모두 100%의 성공률을 기록하고 있다. 이는 가중치 변화와 상관없이 전체 시스템이 안정적인 상태를 유지하고 있는 것을 확인할 수 있다.

후기

이번 실습은 AWS EKS와 Istio를 활용해 인프라의 기본 설정을 넘어 엔지니어의 명시적 통제권을 확보하는 과정이었다. VirtualService 가중치 설정을 통해 트래픽 흐름을 직접 설계하고, 해당 결과를 Prometheus/Grafana를 통해 설계가 시스템 하단에 정확히 투영되었음을 확인했다. 다음번에는 단순 배포를 넘어, 지표를 근거로 안정성을 확언할 수 있는 역량을 강화하기 위해 지표 기반 자동 롤백과 조건부 라우팅을 실습하고 결과를 공유할 예정이다.

[EKS/Istio] 서비스 메시와 Istio를 활용한 버전 기반 라우팅 실습

khseon7 — Mon, 11 May 2026 17:05:13 +0900

서비스 메시란? - 서비스 메시 설명 - AWS

서비스 메시란 무엇이고 비즈니스에서 서비스 메시를 사용하는 방법 및 이유와 AWS를 통해 서비스 메시를 사용하는 방법을 알아봅니다.

aws.amazon.com

istio/samples/bookinfo/platform/kube/bookinfo.yaml at master · istio/istio

Connect, secure, control, and observe services. Contribute to istio/istio development by creating an account on GitHub.

github.com

얼마 전 참여했던 Dev Meetup에서 가장 흥미롭게 들었던 부분은 Service Mesh 중 Istio 였다. "애플리케이션 코드 수정 없이 네트워크를 제어한다"는 개념은 매우 매력적인 주제였다. Meetup에서 간단히 이론을 듣는 것에 그치지 않고, 직접 AWS EKS 환경 위에 Istio를 올리고 istio에서 제공하는 bookinfo를 바탕으로 3개의 서비스 버전을 제어하며 가졌던 의문과 해답들을 정리해본다.

1. 서비스 메시(Service Mesh)란?

서비스 메시는 마이크로서비스 아키텍처(MSA)에서 각 서비스 간의 통신을 관리하기 위한 전용 소프트웨어 계층으로, 애플리케이션의 비즈니스 로직과 분리되어 네트워크 통신을 제어하며, 가시성, 보안, 안정성을 제공한다.

https://d2908q01vomqb2.cloudfront.net/1b6453892473a467d07372d45eb05abc2031647a/2018/11/28/appmesh-proxy-1024x341.png

주요 기능 및 이점

서비스 검색: 메시 내 서비스들을 동적으로 추적하여 서비스 위치에 관계없이 서로를 찾고 통신할 수 있게 한다.
로드 밸런싱: 요청을 여러 인스턴스에 지능적으로 분산하여 리소스 활용도를 최적화한다.
트래픽 관리: 카나리 배포, 요청 미러링 등을 통해 안전한 배포와 테스트를 지원한다.
보안: 상호 TLS 암호화를 통해 데이터 기밀성을 보장하고, 서비스 간 인증 및 권한 부여를 처리한다.
모니터링 및 관찰성: 지연 시간, 오류율 등의 지표 수집과 분산 추적을 통해 시스템 상태를 상세히 파악한다.

작동 원리

데이터 영역: 각 서비스 옆에 사이드카 형태로 배치된 프록시들로 구성된다. 실제 서비스 간 모든 트래픽을 가로채고 전달하는 역할
제어 영역: 관리자가 정책과 구성을 정의하는 중앙 관리 계층으로 정의된 설정을 데이터 영역의 프록시들에 배포하여 동작을 제어한다.

도입 시 고려사항

데이터 플레인 리소스 (사이드카 오버헤드)
- 메모리 및 CPU 소모: 서비스 메시는 각 마이크로서비스마다 사이드카 프록시를 하나씩 배치하는데 이 때문에 서비스가 많을 경우 전체 클러스터에서 무시할 수 없는 수준의 인프라 비용이 추가된다.
- 네트워크 지연: 트래픽이 반드시 프록시를 거쳐야 하므로, 홉이 늘어남에 따라 미세한 네트워크 지연이 발생한다.
컨트롤 플레인 부하
- 설정 배포 부하: 마이크로서비스의 개수가 수천 개로 늘어나면, 컨트롤 플레인이 모든 사이드카 프록시에 실시간으로 설정을 전파하는 과정에서 부하가 급증한다.
- 관리 복잡도: 컨트롤 플레인 자체가 고가용성을 유지해야 하므로, 이를 관리하기 위한 운영 인력과 모니터링 비용이 추가로 발생한다.

2. EKS 클러스터 구축

먼저 AWS에서 실제로 전체 인프라를 조종할 물리 서버(EC2)를 생성하고, eksctl을 활용해 t3.medium 인스턴스 2개 규모의 클러스터를 생성했다. 인프라 재현성을 위해 모든 과정은 Bash 스크립트로 자동화했다.

# eksctl을 활용한 클러스터 생성
eksctl create cluster \
  --name istio-lab \
  --region ap-northeast-2 \
  --nodegroup-name istio-nodes \
  --node-type t3.medium \
  --nodes 2 \
  --managed

질문: 노드는 2개인데, 어떻게 서비스 버전은 3개가 돌아가는가?
- 통찰: 노드는 하위 계층에서 CPU와 메모리를 제공하는 물리적 자원 풀이며, 서비스 버전은 그 위에서 구동되는 논리적 객체이다. 따라서 노드의 개수는 서비스의 가짓수가 아닌, 시스템의 장애 내성을 결정하는 통제 변수로 이해해야 한다.

3. Istio 설치와 사이드카 패턴 확인

EKS 구축 후 Istio를 설치하고 네임스페이스(default)에 자동 주입 설정을 마친 뒤, Bookinfo 샘플 앱을 배포했다.

# default 네임스페이스에 배포되는 모든 Pod에 Istio 프록시가 자동으로 붙도록 라벨 설정
kubectl label namespace default istio-injection=enabled

# Istio 샘플 디렉토리에 있는 bookinfo.yaml 배포
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml

질문: Bookinfo 앱 배포 후 kubectl get pods에서 보이는 2/2 는 무엇을 의미하는가?
- 통찰: 하나의 Pod 안에 비즈니스 앱 컨테이너와 Istio 프록시 컨테이너가 하나로 묶여 있기 때문에 2/2로 표시된다. 해당 Pod 내부에 있는 프록시가 앱의 입출구 역할을 대신해주기 때문에 통제권이 인프라 계층으로 넘어오게 된다.

4. Bookinfo 앱을 통한 트래픽 제어 확인

배포 후 웹 페이지를 새로고침할 때마다 별점 모양(없음/검은별/빨간별)이 순차적으로 바뀌는 것을 확인했다.

질문: 새로고침할 때마다 바뀌는 이유는?
- 통찰: 새로고침마다 화면이 바뀌는 것은 라벨로 묶인 여러 파드들 사이를 Istio가 라운드 로빈 방식으로 연결해주기 때문이다. 즉, 서비스의 외적인 변화는 하단의 메타데이터 관리와 트래픽 분배 정책에 의해 결정된다.

5. 후기

Meetup에서의 호기심으로 시작한 실습은 EC2-Pod-Container로 이어지는 수직적 구조와, 이를 관통하는 Istio의 통제 방식을 직접 경험하는 시간이었다. 이제 깔끔하게 정리된 내용 위에, 다음 번에는 카나리 배포를 통한 세밀한 트래픽 전환과 프로메테우스/그라파나 기반의 정밀 모니터링을 실습하고 결과를 공유할 예정이다.

[논문 리뷰] TurboQuant: Online Vector Quantization with Near-optimalDistortion Rate

khseon7 — Tue, 21 Apr 2026 14:06:34 +0900

https://arxiv.org/abs/2504.19874

TurboQuant: Online Vector Quantization with Near-optimal Distortion Rate

Vector quantization, a problem rooted in Shannon's source coding theory, aims to quantize high-dimensional Euclidean vectors while minimizing distortion in their geometric structure. We propose TurboQuant to address both mean-squared error (MSE) and inner

arxiv.org

AI 모델이 커질수록 가장 먼저 문제가 되는 것은 단순한 연산량이 아니다. 실제 서비스 환경에서는 메모리 사용량, GPU 대역폭, 그리고 데이터 이동 비용이 더 큰 병목이 된다. 특히 LLM은 모델 파라미터 자체도 크지만, 추론 과정에서 생성되는 KV Cache와 중간 activation까지 포함하면 막대한 자원을 요구한다. 이 때문에 최근 AI 인프라에서는 모델을 더 빠르게 만드는 기술만큼 벡터를 얼마나 효율적으로 저장하고 저장하고 전송하느냐가 중요해졌다.

이 지점에서 등장하는 기술이 바로 Quantization이다. 그리고 이번에 소개하는 TurboQuant는 단순히 숫자의 정밀도를 낮추는 수준을 넘어, 고차원 벡터를 매우 적은 비트로 압축하면서도 성능 저하를 최소화하는 새로운 방식의 Vector Quantization 알고리즘이다.

왜 벡터 양자화가 중요한가?

현대 AI 시스템은 대부분 벡터를 중심으로 동작한다. LLM 내부의 attention key/value 벡터, 검색 시스템의 embedding 벡터, 추천 시스템의 사용자 표현값, 멀티모달 모델의 이미지 특징값까지 모두 고차원 벡터이다.

문제는 이 벡터들이 대부분 float16, float32 형태로 저장된다는 점이다. 차원이 커질수록 메모리 사용량은 급격히 증가하고, GPU 내부 메모리(HBM)와 연산 캐시(SRAM) 사이에서 데이터를 옮기는 비용도 커진다. 결국 모델이 느려지는 이유는 계산이 아니라 데이터를 읽고 쓰는 과정인 경우가 많다.

그래서 많은 연구들이 벡터를 int8, int4처럼 더 작은 정밀도로 압축하려고 시도한다. 하지만 단순히 숫자 비트만 줄이면 벡터의 의미 구조가 망가질 수 있다. 예를 들어 원래 비슷했던 두 벡터가 압축 후에는 멀어질 수 있고, 검색 정확도나 attention score도 크게 흔들릴 수 있다.

즉, 핵심은 단순 압축이 아니라, 벡터의 기하학적 구조를 유지하면서 압축하는 것이다.

기존 방식의 한계

기존의 대표적인 벡터 양자화 방식으로는 Product Quantization(PQ)이 있습니다. PQ는 벡터를 여러 구간으로 나눈 뒤 각각을 codebook 기반으로 압축하는 방식인데, 벡터 검색 분야에서는 오랫동안 표준처럼 사용되어 왔다.

다만 PQ는 사전에 학습된 codebook이 필요하고, 데이터셋마다 다시 최적화해야 하며, 대규모 인덱싱 시간이 길다는 단점이 있다. 검색 시스템에서는 유용하지만, 실시간으로 계속 생성되는 KV Cache 같은 환경에서는 적용이 쉽지 않다.

반대로 좌표별로 단순하게 int8/int4로 줄이는 방식은 매우 빠르고 구현도 쉽다. 하지만 고차원 벡터의 거리나 내적 구조를 제대로 보존하지 못해 품질 저하가 자주 발생한다.

결국 기존 기술은 대체로 두 갈래였다. 정확하지만 느리거나, 빠르지만 손실이 컸다.

TurboQuant의 출발점

TurboQuant는 이 두 문제를 동시에 해결하려는 시도이다. 논문은 "빠르고, 온라인 적용 가능하며, GPU 친화적이면서도 이론적으로 거의 최적 수준의 distortion을 달성하는 양자화기를 만들 수 있는가?"라는 질문에서 출발한다.

여기서 말하는 이론적 최적 수준이란, 어떠한 압축 알고리즘도 도달할 수 없는 절대적 한계치인 Shannon Lower Bound를 의미한다. 놀랍게도 TurboQuant는 모든 비트 폭과 차원에 걸쳐 이 수학적 하한선과 불과 약 2.7배 이내의 차이밖에 나지 않는 완벽에 가까운 최적화를 이뤄냈다.

그리고 그 해답으로 제시한 방식이 매우 흥미롭다. 복잡한 codebook 탐색 대신, 입력 벡터를 먼저 랜덤하게 회전시키고, 각 좌표를 독립적으로 처리하는 구조를 사용한다.

언뜻 단순해 보이지만, 고차원 공간에서는 이 접근이 놀라울 정도로 강력하게 작동한다.

랜덤 회전이 왜 중요한가

TurboQant는 먼저 입력 벡터($\mathcal{x}$)에 랜덤 회전을 적용한다.

$$\mathcal{y}=\Pi\mathcal{x}$$

여기서 $\PI$는 직교행렬이며, 벡터의 길이는 유지한 채 좌표축만 무작위로 바꾸는 역할을 한다.

이 과정을 거치면 특정 좌표 하나에 큰 값이 몰려 있던 벡터도 전체 차원에 값이 비교적 고르게 퍼지게 된다. 다시 말해 outlier가 완화되고, 각 좌표가 비슷한 통계적 성질을 갖게 된다.

이는 매우 중요하다. 기존에는 벡터 전체를 한 번에 다뤄야 했지만, 회전 이후에는 좌표 하나하나를 독립적으로 양자화해도 성능이 잘나온다.

즉 복잡한 고차원 문제를 단순한 1차원 문제 여러 개로 바꾸는 셈이다.

좌표 분포와 Beta Distsribution

논문은 랜덤 회전된 고차원 unit vector의 각 좌표가 특정 형태의 Beta 분포를 따른다는 사실을 활용한다. 고차원에서는 좌표값들이 중심에 몰리고, 서로 거의 독립적인 것처럼 행동한다.

이 성질 덕분에 각 좌표마다 최적의 scalar quantizer를 설계할 수 있다. 즉 벡터 전체를 위해 거대한 codebook을 만들 필요 없이, 좌표별 최적값만 계산하면 된다.

이것이 TurboQuant가 빠르면서도 정확한 이유이다.

독립적으로 변환된 각 좌표가 따르는 Beta 분포

Lloyd-Max Quantizer를 활용한 좌표별 최적화

TubeoQuant는 각 좌표에 대해 Lloyd-Max quantizer를 적용한다. 이는 주어진 확률분포에서 평균 제곱 오차(MSE)를 최소화하는 대표적인 스칼라 양자화 방식이다.

예를 들어 2bit라면 4개의 대표값을 만들고, 입력 좌표가 어느 구간에 속하는지에 따라 가장 가까운 대표값으로 치환한다. 3bit라면 8개 대표값을 사용한다.

이 과정은 GPU에서 병렬 처리하기 매우 좋다. 차원마다 독립적으로 계산하면 되기 때문에 SIMD 구조와도 잘 맞고, lookup 기반으로 매우 빠르게 동작한다.

그런데 MSE만 좋다고 끝이 아니다

벡터를 잘 복원하는 것과, 벡터 간 관계를 잘 보존하는 것은 다른 문제이다.

LLM의 attention score나 벡터 검색은 결국 두 벡터의 내적 값으로 결정된다.

$$\mathcal{x}^\mathrm{T}\mathcal{y}$$

즉 압축 후 벡터가 원본과 비슷해 보여도, 내적이 틀어지면 검색 결과나 모델 성능이 무너질 수 있다.

논문은 MSE 기준으로 최적인 양자화기가 inner product estimation에는 bias를 만들 수 있다고 지적한다.

$$\mathrm{E}[\hat{\mathcal{x}}^\mathrm{T}\mathcal{y}]\neq\mathcal{x}^\mathrm{T}\mathcal{y}$$

이 차이는 실제 서비스에서 상당히 치명적일 수 있다.

Figure 1: Error distribution of TurboQuant_prod and TurboQuant-mse

TurboQuant의 두 번째 핵심: Residual 보정

TurboQuant는 이 문제를 2단계 구조로 해결한다.

먼저 MSE 기준으로 벡터를 압축한 뒤, 남은 오차를 계산한다.

$$\mathcal{r=x-\hat{x}}$$

그리고 이 residual에 대해 1-bit Quantized Johnson-Lindenstrauss(QJL) 기법을 적용한다.

QJL은 랜덤 projection 후 부호만 저장하는 매우 가벼운 방식인데, 놀랍게도 inner product에 대해 unbiased estimator 성질을 제공한다.

여기서 핵심은 비트 예산(Bit-budget)의 분배이다. 만약 목표 압축 용량이 b비트라면, 1단계에 b-1비트를 할당하여 오차를 최소화하고, 남은 1비트를 2단계에 사용하여 정확히 목표 용량 b비트를 맞추게 된다.

즉 TurboQuant는 추가적인 메모리 낭비 없이 벡터 자체는 정확히 복원하면서도, 내적 계산의 편향까지 동시에 잡아낸다.

실험 결과

논문에서는 LLM KV Cache 압축 실험에서 3.5bit 수준만으로 full precision과 거의 동일한 품질을 달성했다고 보고한다. 2.5bit에서도 성능 저하는 매우 제한적이었다.

이는 단순 계산으로도 메모리를 4배 이상 절약할 수 있다는 뜻이다. 긴 context 모델이나 동시 사용자 수가 많은 서비스에서는 엄청난 차이이다.

또한 벡터 검색 실험에서는 기존 Product Quantization 대비 더 높은 recall을 보이면서도, 인덱싱 시간은 거의 0에 가깝다고 설명합니다. 즉 검색 품질과 구축 속도를 동시에 가져간 셈이다.

Evaluation of Llama-3.1-8B-Instruct on the "Needle-In-A-Haystack" test

Quantization time (in seconds)

[K8s] K8s 환경에서 Python 애플리케이션 모니터링 구축

khseon7 — Thu, 16 Apr 2026 18:08:38 +0900

기존에 docker-compose로 간단히 구축하던 Personal AI Dispatcher 서비스를 쿠버네티스(Minikube) 환경으로 이관하여 가시성을 확보하기 위해 모니터링 시스템을 구축했다. 단순 설치를 넘어 k8s 네트워크 계층과 Prometheus Operator의 동작 원리를 이해했던 내용들을 정리한다.

1. Application Layer: Prometheus Metrics 서버 구축

먼저 Python 앱에서 지표를 노출하기 위해, prometheus_client 라이브러리를 활용해 메트릭 서버를 별도의 스레드로 실행했다.

지표 정의와 'Lazy Initialization'의 함정

프로메테우스의 Counter는 선언만 한다고 데이터가 생성되지 않는다. 실제로 데이터가 기록되기 전까지는 Endpoint에 나타나지 않는 Lazy Initialization 특성이 있다. 이를 해결하지 않으면 봇이 처음 가동될 때 그라파나에서 지표를 찾을 수 없는 현상이 발생한다.

from prometheus_client import start_http_server, Counter

# 지표 정의 (라벨을 사용하여 브리핑 종류 구분)
BRIEFING_SENT = Counter('briefing_sent_total', 'Total number of briefings sent', ['type'])

def start_metrics_server():
    # 8000번 포트로 HTTP 서버 시작
    start_http_server(8000)
    
    # [핵심] 초기값 0.0을 생성하여 프로메테우스가 즉시 인식하게 함
    BRIEFING_SENT.labels(type='morning').inc(0)
    
    logger.info("Prometheus metrics server started on port 8000")
    
# 실제 메시지 전송 로직 수행 후 카운트 증가
BRIEFING_SENT.labels(type='count').inc()

2. Infra Layer: Kubernetes 객체 설계

애플리케이션이 포트를 열었다면, k8s 클러스터 내부에서 이를 찾을 수 있게 다리를 놓아야 한다.

Service: 통로 개설

Pod의 IP는 유동적이다. 따라서 고정적인 Cluster IP를 부여하는 Service 객체가 필요하다. 이때 포트의 name을 metrics로 명시하는 것이 중요하다. 그 이유는 ServiceMonitor가 이 이름을 보고 데이터를 긁어갈 대상을 찾기 때문이다.

ServiceMonitor: 자동 탐지

Prometheus Operator를 사용한다면 ServiceMonitor가 핵심이다. 여기서 가장 중요한 것은 labels 섹션의 release 값이다. 현재 설치된 프로메테우스 헬름 차트의 릴리스 이름과 일치해야 오퍼레이터가 이 설정을 읽어간다. 만약 이 레이블이 다를 경우 오퍼레이터가 설정을 무시한다.

spec:
  selector:
    matchLabels:
      app: dispatcher # Deployment의 레이블과 일치해야 함
  endpoints:
  - port: metrics     # Service에 정의된 포트 이름
    path: /metrics
    interval: 30s

3. 최종 결과 확인 방법

모든 설정이 완료되었다면 다음 경로를 통해 시스템이 정상인지 확인하면된다.

Metrics 엔드포인트 확인
8000번 포트로 포워딩 후 http://localhost:8000/metrics 접속. briefing_sent_total{type="count"} 1.0 같은 문구가 보이면 성공이다.(앱 가동시에
prometheus Targets 확인
9090번 포트로 포워딩 후 Targets 메뉴 진입 후 설정한 monitor가 UP 상태인지 확인한다. 만약 여기서 안보인다면 ServiceMonitor의 레이블 셀렉터 문제 혹은 포트 포워딩 오류일 수 있다.
Grafana 대시보드
3000번 포트로 포워딩 후 접속하여 Explore 메뉴에서 briefing_sent_total 쿼리를 실행한다. 봇이 브리핑을 보낼 때마다 그래프가 상승하는 것을 볼 수 있다.

Prometheus Targets 내부에서 serviceMonitor가 켜져있는 경우

Grafana에서 briefing_sent_total 에 대해서 쿼리 조회를 한 결과

4. 트러블슈팅 - Connection Refused

port-forward 도중 발생한 에러로, 터널은 뚫렸지만 정작 포드 안의 파이썬 프로세스가 크래시 나거나 포트가 열리지 않았을 때 발생한다. 이를 통해 "kubectl logs로 프로세스 생존 여부 확인" 과 "lsof 로 포트를 점유하고 있는 서비스 여부를 확인하는 습관"이 중요함을 배웠다.

Swap 메모리로 1GB RAM 맷집 키우기

khseon7 — Tue, 14 Apr 2026 19:20:37 +0900

Oracle Cloud와 같은 클라우드 무료 티어나 저가형 서버를 쓰다 보면 당황스러운 순간이 온다. Docker를 올리거나 Nginx 설정을 바꾸는데 갑자기 터미널이 멈추고 서버 접속이 끊겨버리는 경우가 있다.

원인은 명확하다. 1GB라는 미니미한 RAM 용량 때문입니다. 서버가 처리할 데이터는 많은데 담을 그릇이 부족하니 결국 서버가 '기절'해버리는 것이다. 오늘은 이 좁은 그릇을 대신해 하드디스크의 일부를 메모리처럼 사용하는 Swap(스왑) 설정으로 서버에 8GB급 맷집을 키워보자.

️ 1GB RAM 서버 심폐소생술 (Swap 7GB 설정)

1. 7GB 크기의 빈 공간 확보하기

서버 안에 7GB짜리 거대한 빈 파일을 만든다. 약 10~20초 정도 소요

sudo fallocate -l 7G /swapfile

2. "나만 볼 거야" 권한 설정

이 파일은 메모리 대용이라 보안이 중요합니다. 다른 사용자가 함부로 읽지 못하도록 권한을 제한

sudo chmod 600 /swapfile

3. 파일을 '스왑용'으로 변신시키기

그냥 빈 파일이었던 것을 리눅스 시스템이 메모리처럼 인식할 수 있게 포맷하는 과정

sudo mkswap /swapfile

4. 스왑 엔진 가동

이제 실제로 리눅스 시스템이 이 공간을 메모리처럼 사용 시작

sudo swapon /swapfile

5. 재부팅해도 유지되도록 영구 저장

위의 설정들은 서버를 껐다 켜면 사라집니다. 재부팅 시에도 자동으로 적용되도록 설정 파일(fstab)에 내용을 기록

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

✅ 제대로 됐는지 검사하기

모든 명령어를 입력했다면, 아래 명령어로 최종 확인을 하면 다음과 같이 뜨는 것을 볼 수 있다.

free -h

swap 엔진 가동 후 결과

[K8s] 메모리 고갈로 인한 OOMKilled 테스팅

khseon7 — Mon, 6 Apr 2026 18:07:52 +0900

대규모 언어 모델을 포함한 AI 서빙 환경에서 가장 치명적인 위협은 CPU 부하가 아닌 메모리 고갈(OOM, Out Of Memory)이다. CPU 부하는 서비스의 지연을 초래하지만, 메모리 임계치 초과는 쿠버네티스 커널에 의한 컨테이너 즉시 사살로 이어지기 때문이다.

이번 실습에서는 의도적으로 메모리 부하를 일으켜 k8s의 Self-healing 메커니즘과 메모리 기반 HPA(Horizontal Pod Autoscaler)의 실제 동작 방식을 분석했다.

실험 환경 구축

Infra: Minikube (Metrics Server 활성화)
Monitoring: Prometheus & Grafana (w. Helm)
App: Flask 기반의 'Mock-LLM' 서버 (요청 시마다 20MB씩 메모리 점유하는 로직 구현)

핵심 설정: Deployment & HPA

장애 상황을 정밀하게 관측하기 위해 메모리 임계치를 타이트하게 설정했다.

# Deployment 리소스 설정
resources:
  requests:
    memory: "100Mi"
  limits:
    memory: "300Mi" # 300MB 초과 시 즉시 종료(OOMKilled)

# HPA 설정 (v2)
metrics:
- type: Resource
  resource:
    name: memory
    target:
      type: Utilization
      averageUtilization: 60 # 메모리 사용량 60% 도달 시 스케일 아웃

장애 재현 및 관측

curl loop를 통해 부하 테스트를 진행해본 결과 급격한 메모리 점유가 유도했ㅇ르 때, 다음과 같은 시스템 변화가 포착되었다.

# kubectl get pods -w 관측 로그
mock-app-xxx   1/1   Running            1    (2s ago)   8m22s
mock-app-xxx   0/1   OOMKilled          1    (4m29s ago)   12m
mock-app-xxx   0/1   CrashLoopBackOff   1    (15s ago)     13m
mock-app-xxx   1/1   Running            2    (16s ago)     13m

재시작 후 연결 단절 문제

포드가 Running 상태로 복구되었음에도 불구, 로컬 터미널에서 connect 에러가 발생했다.

원인 분석: kubectl port-forward는 특정 프로세스와의 1:1 터널링이다. 프로세스가 OOM으로 종료되는 순간 이 터널은 파괴된다. 터미널에 출력된 Broken Pipe 에러가 이를 증명했습니다.
해결: 기존 포트 포워딩 세션을 종료하고 재성립함으로써 연결을 복구했습니다. 이는 인프라의 휘발성을 보여주는 전형적인 사례이다.

Engineering Insights

HPA와 OOM 사이의 골든 타임
HPA가 메트릭을 수집하고 새 포드를 준비하는 속도보다 메모리가 차오르는 속도가 더 빠르면 오토스케일링이 작동하기 전에 서버가 먼저 죽는다는 것을 확인했습니다. 이를 방지하기 위해 실무에서는 Requests와 Limits 사이의 충분한 Buffer 설계가 필수적임을 알게되었다.
Running과 Ready의 엄격한 구분
컨테이너가 다시 살아나도 내부 애플리케이션이 런타임을 준비하는 Warm-up 시간이 필요했다. 이를 위해 Readiness Probe를 설정하여, 서비스가 실제로 요청을 받을 준비가 되었을 때만 트래픽을 유입시키는 설계의 중요성을 이해했다.
Self-healing의 한계와 보완
쿠버네티스가 포드를 살려내더라도 기존 네트워크 세션은 유실된다. 따라서 시스템 안정성을 위해서는 인프라의 복구뿐만 아니라, 클라이언트 레벨의 재시도 로직과 로드밸런서의 정밀한 헬스 체크가 병행되어야 함을 알게되었다.

결론

안정적인 인프라란 단순히 장애가 없는 상태가 아니라, 장애가 발생했을 때 시스템이 얼마나 예측 가능하게 반응하고 자동으로 복구되느냐에 달려 있다. 이번 실습을 통해 리소스 설계와 관측 가능성의 중요성을 다시 한번 확인할 수 있었습니다.

[K8s] Minikube 환경에서 HPA와 k6로 구현하는 부하 테스트

khseon7 — Thu, 2 Apr 2026 18:14:17 +0900

로컬 환경인 Minikube에서 쿠버네티스의 핵심 기능 중 하나인 HPA(Horizontal Pod Autoscaler)가 실제로 어떻게 동작하는지를 확인하기 위해, k6를 이용해 트래픽 부하를 주고, Prometheus 와 Grafana로 모니터링하며 Pod가 자동으로 확장되는 과정을 정리해본다.

1. 환경 세팅: Minikube

먼저 맥북의 자원을 효율적으로 사용하기 위해 Docker 드라이버를 사용하여 minikube를 시작한다.

Minikube 설치 및 시작

brew install minikube

# Docker 데스크탑 설정에서 CPU 4, Memory 8GB 이상으로 설정 권장
minikube start --driver=docker --cpus=4 --memory=8192mb

2. 모니터링 구축: Prometheus & Grafana

쿠버네티스의 상태를 한눈에 파악하기 위해 kube-prometheus-stack을 설치한다.

brew install helm

# 리포지토리 추가 및 업데이트
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

# Prometheus Stack 설치 (수집+시각화+알림 패키지)
helm install my-release prometheus-community/kube-prometheus-stack

Grafana 접속

설치가 완료되면 포트 포워딩을 통해 대시보드에 접속한다.

# Grafana 서비스 이름 확인
kubectl get svc -l "app.kubernetes.io/name=grafana"

# 포트 포워딩 (3000번 포트)
kubectl port-forward svc/my-release-grafana 3000:80

ID: admin
Password: 초기 비밀번호는 아래 명령어로 확인 가능하다.

kubectl get secret --namespace default my-release-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

3. 테스트용 앱 배포 및 HPA 설정

부하를 테스트할 앱으로 CPU를 의도적으로 많이 소모하는 php-apache를 사용

# 앱 배포
kubectl apply -f https://k8s.io/examples/application/php-apache.yaml

# HPA 설정: CPU 사용량이 50%를 넘으면 Pod를 최대 10개까지 증설
kubectl autoscale deployment php-apache --cpu=50% --min=1 --max=10

4. 부하 테스트: k6 활용

이제 k6를 설치하고 자바스크립트 기반의 테스트 스크립트를 작성하여 트래픽을 쏴보자

brew install k6

import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 50 }, // 30초 동안 사용자 50명까지 증가
    { duration: '1m', target: 100 },  // 1분 동안 100명 유지 (Peak 부하)
    { duration: '30s', target: 0 },  // 종료 시점까지 서서히 감소
  ],
};

export default function () {
  http.get('http://localhost:8080'); // 포트 포워딩 주소
  sleep(0.1);
}

테스트를 실행하기 전에 Host PC에서 트래픽을 보낼 수 있게 포트 포워딩은 까먹지 말자

kubectl port-forward svc/php-apache 8080:80
# 실행
k6 run script.js

5. 트러블슈팅: 왜 HPA가 작동하지 않을까?

분명 위 스크립트를 바탕으로 부하를 강하게 줬는데도 kubectl get hpa 를 쳤을 때 TARGETS 값이 <unknown>으로 뜨고 Pod가 늘어나지 않았다.

확인 결과 쿠버네티스는 자체적으로 각 Pod의 자원 사용량을 알지 못해, metrics-server 애드온이 켜져 있어야만 HPA가 "아, 지금 CPU가 50%를 넘었구나!"라고 인지하고 스케일 아웃을 진행한다.

# metrics-server 활성화
minikube addons enable metrics-server

# 정상 작동 확인
kubectl get pods -n kube-system | grep metrics-server

변화 확인

상태	kubectl get hpa 결과(TARGETS)	비고
애드온 추가 전	<unkown> / 50%	HPA가 자원량을 몰라 멍하니 있음
애드온 추가 후	85% / 50%	사용량 감지 즉시 Pod 개수 증가 시작

6. 파드가 늘어났는데도 왜 여전히 느릴까?

metrics-server를 켜서 파드가 정상적으로 5개로 늘어나는 것을 확인했는데도 다음 그림과 같이 20초 이상의 지연 시간과 타임아웃이 발생했다. 이것에 대한 원인을 분석해본 결과 다음과 같았다.

kubectl port-forward는 대규모 트래픽용이 아니다.
우리가 localhost:8080 으로 쏘고 있는 트래픽은 사실 매우 좁은 통로를 지나고 있다. port-forward는 개발자가 디버깅 용도로 쓰라고 만든 임시 통로이다.
- 병목 현상: 이 통로는 100 VU(Virtual User) 같은 대량의 동시 접속을 처리하도록 설계되지 않았다. Pod가 아무리 많아도 맥북과 Minikube 사이를 잇는 이 통로에서 트래픽이 다 막힌것이다.
- 해결책: 실제 minikube service php-apache --url 명령어로 나오는 실제 IP와 포트로 직접 트래픽을 쏘거나, Ingress를 통해 접근해야한다.
HPA는 사후 처방이다. (Scaling Lag)
HPA가 파드를 늘리는 과정을 시간순으로 복기해보면 다음과 같다.
1. 트래픽 폭주 발생 (0초)
2. 기존 파드가 응답 지연 시작 (5~10초)
3. Metrics-server가 부하 감지 (30초~1분)
4. HPA가 증설 결정 및 파드 생성 (1분~1분 30초)
5. 새 파드가 Ready 상태가 되어 트래픽 분산 (2분 내외)

→ 우리의 테스트는 보통 2~3분 내외로 끝난다. 즉, 새 파드들이 일을 시작하려고 할 때 이미 테스트는 끝물이거나, 기존 통로가 이미 포화 상태에 빠진 뒤여서 Pod가 늘어나도 트래픽 분산이 정상적으로 이뤄지지 않은것으로 보인다.

k6를 통해 실제 트래픽 테스트한 결과

7. Ingress를 통한 트래픽 분산

Ingress 활성화하고, 다음 yaml 파일을 생성한 후 터널을 열어둔다.

minikube addons enable ingress

# 파일 이름 예시: ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: php-apache-ingress
  spec:
    # Nginx Ingress Controller를 사용하겠다는 설정입니다.
    ingressClassName: nginx
spec:
  rules:
  - host: fake.test  # 브라우저나 k6에서 접속할 가짜 도메인
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: php-apache  # 아까 확인한 서비스 이름과 똑같아야 함
            port:
              number: 80

# 쿠버네티스에 배포
kubectl apply -f ingress.yaml

맥북에서 가짜 도메인 인식시키기

현재 쿠버네티스 안에서 fake.test라는 문은 생겼지만, Host 맥북은 그 주소가 어디인지 모르기에 이걸 연결해줘야한다.

# 터미널에서 명령어 입력
sudo vi /etc/hosts

# 파일 맨 아래에 다음 내용 추가
127.0.0.1 fake.test

Ingress tunnel 열기

맥북은 보안상 Ingress가 기본적으로 닫혀 있어 별도의 명령어를 열고 아래 명령어를 계속 켜두면된다.

minikube tunnel

Ingress로 변경 후 테스트 결과

Ingress 추가 후 테스트를 해본 결과 이전과의 결과를 비교하면 다음 표로 나타낼 수 있다.

항목	Port-forward	Ingress	의미
에러율	6~8%	0.00%	타임아웃 없이 모든 요청을 다 받아냈다.
처리량	약 300회	1,005회 (3배 이상)	시스템이 3배 이상의 일을 소화함
중간값	20초 이상	415ms (0.4초)	대다수 사용자가 매우 쾌적함을 느낄 수 있음
평균 응답	24초	7.09초	전체적으로 시스템 안정성 대폭 개선

위 표를 볼때 Ingress에서 중간값은 0.4초인데 반해 평균 응답이 7초인 이유는 다음과 같다.

초반: 테스트 직후, 파드가 1개일 때는 트래픽 감당을 못 해 응답 시간이 치솟음
중반: HPA가 작동해서 파드가 5~10개로 늘어난 시점부터는 응답 속도가 0.4초로 뚝 떨어졌다.

→ 시스템이 스스로 판단하고 확장해서 안정을 찾았다.

그리고 추가적으로 kubectl get hpa -w 결과를 바탕으로 트래픽이 줄어들며 자원을 다시 반납하는 것까지 확인할 수 있었다.

Post-forwarding을 Ingress로 변경 후 트래픽 테스팅 결과

명령어를 통한 CPU 사용량에 따른 REPLICAS 변화량 추이

[Git/GitHub] 계정 전환 오류 해결: 왜 자꾸 이전 계정으로 요청을 보낼까?

khseon7 — Fri, 20 Mar 2026 18:28:58 +0900

GitHub 계정을 여러 개 사용하다 보면, 분명 로그인은 새 계정으로 했는데 Git은 여전히 이전 계정의 권한을 사용하려다 403 Forbidden 오류를 내뱉는 경우가 많습니다.

오늘은 **이전 계정(Old)**에서 **신규 계정(New)**으로 깔끔하게 갈아타는 5단계 해결법을 정리합니다.

이번 가이드의 설정 기준

블로그를 보시는 분들은 아래 명칭에 본인의 계정명을 대입해 주세요.

OLD_USER: 이전에 사용하던 계정
NEW_USER: 새로 사용하려는 계정

1단계: GitHub CLI(gh) 현재 상태 확인

먼저 GitHub CLI가 현재 어떤 계정을 'Active(활성)' 상태로 잡고 있는지 확인합니다.

gh auth status

확인: Active account가 본인의 **NEW_USER**인지 체크하세요.
해결: 만약 다른 계정이 활성화되어 있다면 아래 명령어로 즉시 전환합니다.

gh auth switch

2단계: 인증 캐시 완전 초기화 (핵심! ⭐)

상태 확인 후에도 계정이 꼬인다면, 기존의 인증 정보를 완전히 밀어버리고 다시 로그인하는 것이 가장 확실합니다.

# 1. 기존 세션 로그아웃
gh auth logout --hostname github.com

# 2. 신규 계정(NEW_USER)으로 다시 로그인
gh auth login

로그인 시 주의사항

- Account: NEW_USER 계정 정보 입력

- Protocol: 반드시 HTTPS 선택

- Authentication: Web 브라우저 인증 방식 권장

3단계: Git Credential Helper 설정 정돈

Git이 gh 도구 외에 다른 자격 증명 관리자(Windows 자격 증명 등)를 이중으로 참조하면 계정이 꼬일 수 있습니다.

# 현재 설정된 헬퍼 확인
git config --global credential.helper

정상: !gh auth git-credential 하나만 출력되어야 함.
설정이 꼬여있다면? 아래 명령어로 초기화 후 다시 설정하세요.

# 기존 설정 모두 제거
git config --global --unset credential.helper

# gh 전용 헬퍼로 재설정
git config --global credential.helper '!gh auth git-credential'

4단계: Remote URL(원격 주소) 점검

간혹 로컬 저장소의 원격 주소(Remote URL) 자체에 이전 계정 정보가 포함되어 있는 경우가 있습니다.

git remote -v

올바른 형태: https://github.com/NEW_USER/repository-name.git
만약 주소에 OLD_USER가 포함되어 있다면 아래 명령어로 수정하세요.

git remote set-url origin https://github.com/NEW_USER/repository-name.git

5단계: 강제 인증 거부(Reject) 및 최종 Push

마지막으로 메모리에 남아있을지 모르는 이전 계정의 잔재를 강제로 밀어내고(Reject) 다시 시도합니다.

# 기존 인증 정보 거부 요청
git credential reject <<EOF
protocol=https
host=github.com
EOF

# 이제 새 계정으로 Push!
git push -u origin main

마무리하며

이 과정을 모두 마치면 Git은 더 이상 구 계정(OLD_USER)을 찾지 않고, 새롭게 인증된 NEW_USER 계정으로 정상적인 요청을 보내게 됩니다.

계정 전환이 잦은 환경이라면 gh auth status를 수시로 확인하는 습관을 들이면 좋습니다!

[논문 리뷰] TERMINAL-BENCH:BENCHMARKING AGENTS ON HARD, REALISTICTASKS IN COMMAND LINE INTERFACES

khseon7 — Wed, 18 Mar 2026 12:37:50 +0900

Terminal-Bench: Benchmarking Agents on Hard, Realistic Tasks in Command Line Interfaces

AI agents may soon become capable of autonomously completing valuable, long-horizon tasks in diverse domains. Current benchmarks either do not measure real-world tasks, or are not sufficiently difficult to meaningfully measure frontier models. To this end,

arxiv.org

Task Formulation

Terminal-Bench의 테스크는 에이전트가 현실적인 터미널 환경에서 상호작용하며 문제를 해결하도록 설계되었습니다.

구성 요소:
- 각 테스크는 지시 사항
- 초기 환경이 세팅된 Docker 이미지
- 정답을 확인할 수 있는 테스트 세트
- 인간이 작성한 예제 솔루션
- 시간 제한
결과 중심적 평가: 테스트는 에이전트가 입력한 명령어 세트나 콘솔 출력을 검사하는 것이 아니라, 최종적으로 컨테이너의 상태가 지시 사항을 충족했는지만을 평가한다.
상호작용적 탐색: 에이전트는 제공된 Bash 명령어 등 다양한 도구를 사용해 스스로 환경을 탐색하고 조작하며 목표를 달성해야 합니다. 이 과정은 Harbor 프레임워크를 통해 실행되며 Cluade Code, Codex CLI 등 다양한 에이전트를 지원합니다.

Terminal-Bench task architecture

Verification

데이터셋의 품질을 보장하기 위해 각 테스크는 평균 3시간 가량의 철저한 다단계 검증 과정을 거쳤습니다.

3대 품질기준
1. 구체성: 테스크가 모든 올바른 최종 상태를 명시하고, 테스트가 이를 정확히 포착하는지 확인합니다.
2. 해결 가능성: 수동으로 작성된 예제 솔루션을 실행했을 때 모든 테스트가 통과되는지 확인합니다.
3. 무결성: 에이전트가 미래의 Git 커밋 내역을 미리 보는 등 현실에 없는 '편법'을 써서 테스트를 통과할 수 없도록 차단합니다.
검토 프로세스: 기여자들의 체크리스트 작성, LLM을 활용한 자동화된 실수 검토, 자동화된 솔루션 테스트 외에도, 여러 최신 모델을 통해 테스크를 직접 실행해 보거나 적대적 공격 에이전트를 투입해 시스템의 허점을 악용할 수 있는지 검사하는 과정을 거쳤습니다.

검증 프로세스 흐름도

Composition

초기 제출된 229개의 테스크 중 엄격한 심사를 통과한 89개의 테스크로 구성되어 있습니다.

다양한 도메인: 소프트웨어 엔지니어링을 비롯해 시스템 관리, 데이터 과학, 보안, 기계 학습, 비디오 처리 등 매우 광범위한 분야를 다룬다.
실제적인 복잡성: 단순히 패키지를 설치하는 것을 넘어, 'Python 비동기 작업 관리 시 키보드 인터럽트 처리', '레거시 COBOL 코드를 Python으로 완벽히 재작성하기' 등 고도의 작업이 포함되어 있습니다.
소요 시간의 현실성: 전문가의 경우 95% 이상의 테스크를 1일 이내에 해결할 수 있도록 설계되었으나, 주니어 엔지니어 기준으로는 하루에서 최대 일주일 이상이 걸리는 테스크(OCaml 가비지 콜렉터 버그 수정)도 포함되어 있어 모델의 긴 호흡(long-horizon) 능력을 요구한다.

벤치마크에 포함된 도메인 분포

주니어 엔지니어와 도메인 전문가 기준 테스크를 해결하는데 걸리는 예상 소요 시간 분포

Results

16개의 최신 모델과 6개의 에이전트 조합을 통해 3만 번 이상의 테스트를 수행한 결과입니다.

성능 순위: 상위권 모델도 65% 미만의 해결률을 보였습니다. GPT-5.2와 Codex CLI 조합(63%)이 1위를 차지했으며, Terminus 2 에이전트 기반의 Claude Opus 4.5(58%), Gemini 3 Pro(57%)가 뒤를 이었습니다. 오픈 소스 모델 중에서는 Kimi K2 Thinking이 36%로 가장 높았습니다.
에이전트보다 모델의 역량이 중요: 동일한 에이전트를 사용하더라도 모델을 상위 버전으로 교체했을 때 성능 향상 폭이 훨씬 커, 에이전트 스캐폴딩보다 기반 모델 자체의 능력이 더 중요함을 시사합니다.
체감 난이도 차이: 인간이 '어려움'으로 평가한 테스크의 93.3%는 모델에게도 실제로 어려웠습니다. 반면, 인간이 '보통'이라고 평가한 테스크의 54.5%를 모델은 풀지 못했는데, 이는 패턴 인식보다는 창의적이거나 적대적인 추론이 필요한 경우 모델이 취약함을 보여줍니다.
모델별 맞춤형 오류 패턴: 최상위 폐쇄형 모델들은 주로 지시사항을 무시하거나 같은 단계를 무의미하게 반복하는 '실행 오류'가 압도적으로 많이 발생합니다. 반면 오픈소스 모델은 실행, 일관성 유지, 결과 검증 등 모든 영역에서 고르게 실패하는 패턴을 보였습니다.
명령어 단위의 가장 흔한 실패 원인: 에이전트가 입력한 명령어의 실패율은 모델에 따라 9.2%~26.7%까지 다양하게 나타납니다. 전체 실패 원인 중 'Command not found'이 24.1%로 1위를 차지했는데, 이는 에이전트들이 설치되지 않은 패키지나 경로에 없는 실행 파일을 무작정 호출하려다 가로막히는 기초적인 환경 인식 오류를 자주 범하고 있음을 보여줍니다.

다양한 언어 모델과 에이전트 조합이 달성한 최종 테스크 해결률

모델 출시일에 따른 벤치마크 성능 변화 추이

사람이 예측한 난이도와 모델이 풀며 나타난 난이도 간 상관관계

LLM 종류별 오류 비중

에이전트가 실패한 개별 명령어를 시각화한 원형 차트

Limitations

벤치마크의 현실성을 극대화하기 위해 인터넷 접속을 허용하면서 발생한 불가피한 한계들입니다.

재현성의 문제: 의존성 패키지나 외부 API 환경이 시간이 지남에 따라 변동될 수 있으며, 실행되는 기기의 하드웨어 리소스 차이로 인해 결과가 달라질 수 있습니다.
부정행위 및 데이터 오염 위험: 에이전트가 인터넷에서 벤치마크의 정답을 직접 검색하여 부정행위를 할 가능성이 존재합니다. 또한, LLM 개발사들이 이 데이터셋을 학습에 사용할 위험을 막기 위해 '카나리아 문자열'을 삽입했으나, 의도적인 학습 오염을 완벽히 막기엔 한계가 있습니다.
잔존 오류 가능성: 테스크당 3시간 이상의 방대한 수작업 검증과 LLM 검토를 거쳤음에도 불구하고, 과제들이 워낙 다양하고 복잡하여 여전히 일부 테스트 스펙이나 지시 사항에 결함이 남아있을 가능성을 배제할 수 없습니다.

[kotlin/JVM] 힙 메모리는 충분한데 왜 OOM이 뜰까?

khseon7 — Tue, 24 Feb 2026 23:14:47 +0900

최근 운영중인 Kotlin 기반 WAS 시스템에서 java.lang.OutOfMemoryError: Java heap space가 발생했습니다. 처음에는 단순한 메모리 누수(Memory Leak)라고 생각했지만, 분석 결과 범인은 JVM 내부의 GCLocker였습니다. 주니어 개발자로서 이 문제를 어떻게 분석하고 해결했는지 기록을 남깁니다.

Generated with Google Gemini

1. 문제 현상 및 분석

[현상]

특정 시점에 스레드가 급증(Thread Explosion)함.
충분한 Heap 메모리가 할당되어 있음에도 불구하고 GC가 수행되지 않고 OOM 발생.
로그 확인 결과, JNI(Java Native Interface) 호출과 관련된 지점에서 병목 현상 발견.

[원인: GCLocker란?]

GCLocker는 Java 코드에서 JNI를 통해 Native 코드를 실행할 때, Native 코드에서 참조하는 Java 객체가 GC에 의해 위치가 바뀌거나 삭제되지 않도록 GC를 일시적으로 차단(Lock)하는 메커니즘입니다.

문제의 연결고리:
1. 스케줄러가 짧은 주기로 수많은 Task를 생성하며 JNI 임계 구역(Critical Section)에 진입.
2. GCLocker가 활성화되어 GC가 트리거되지 못하고 대기 상태에 빠짐.
3. 그 사이 Heap에는 계속해서 객체가 쌓이고, 결국 GC가 돌기도 전에 메모리가 꽉 차버려 OOM이 발생.

2. 해결 과정: 최적화 전략

문제를 해결하기 위해 크게 두 가지 방향으로 접근했습니다.

① ThreadPoolExecutor 도입 (Concurrency Control)

무분별하게 생성되던 스레드를 제어하기 위해 ThreadPoolExecutor를 적용했습니다. 스레드 개수를 제한함으로써 JNI 임계 구역에 동시에 머무는 스레드 수를 조절했고, 이는 GCLocker가 해제될 틈을 만들어 주었습니다.

② 객체 생성 최소화 (Object Allocation Optimization)

매 루프마다 불필요하게 생성되던 객체들을 재사용하거나 생성을 억제했습니다.

Before: 반복문 내에서 매번 새로운 객체 할당 → GC 부하 증가
After: 싱글톤 패턴이나 객체 풀링(Pooling) 개념을 적용하여 Heap 할당량 자체를 줄임

3. 마치며: 배운 점

이번 장애를 통해 단순히 "메모리가 부족하면 늘린다"는 식의 접근이 얼마나 위험한지 깨달았습니다. JVM의 GC 메커니즘, 특히 Native 영역과의 상호작용(GCLocker)이 Java Heap 영역에 어떤 영향을 주는지 깊이 이해할 수 있는 계기가 되었습니다.

특히 주니어 단계에서 겪기 힘든 OOM 디버깅과 스레드 최적화를 직접 경험하며, 시스템의 안정성은 코드 한 줄뿐만 아니라 런타임 환경에 대한 이해에서 온다는 것을 다시 한번 확인했습니다.