웹 서비스의 대규모 트래픽 대비를 위해 부하 테스트를 진행하다가 사용자 수(VU)가 늘어나자마자 타임아웃이나 Connection Refused 에러가 터지는 상황을 경험해봤을 것이다.
다만 많은 개발자들은 단순한 연산으로 동시 요청 수만 올리고, 정확한 동시성 제어나 대기 시간(wait_time)을 설정하지 않은 채 인터넷에서 복사한 스크립트를 그대로 실행하곤 한다.
이번에는 Python 기반의 부하 테스트 도구인 Locust를 활용해 부하 시나리오를 제대로 작성하는 방법부터 타임아웃 원인 해결, 그리고 실무에서 바로 적용 가능한 성능 검증 기준까지 완벽하게 정리해서 소개하겠다.
Locust는 Python 코드로 부하 테스트 시나리오를 정의하는 오픈소스 성능 테스트 도구다.
JMeter나 Gating 같은 기존 GUI/XML 기반 도구와 달리, 순수 Python 코드로 모든 시나리오를 제어할 수 있어 비동기 요청이나 복잡한 사용자 행위를 자유롭게 구현할 수 있다.
부하 테스트를 제대로 수행하려면 다음 세 가지 핵심 개념을 명확히 이해해야 한다.
| 개념 | 설명 | 실무 설정 팁 |
|---|---|---|
| VU (Virtual User) | 서버에 접속하는 가상 사용자 수 | 목표 동시 접속자 수에 맞게 분산 조정 |
| Spawn Rate (Hatch Rate) | 초당 새로 생성되는 가상 사용자 수 | 급격한 부하 방지를 위해 단계적으로 설정 |
| wait_time | 요청과 요청 사이 가상 사용자의 대기 시간 | 실제 사용자 행동 패턴 반영(between 함수 활용) |
부하 테스트 도중 타임아웃(Timeout Error)이 발생하는 원인은 크게 두 가지다.
첫째는 테스트 대상 서버의 리소스(CPU, 데이터베이스 커넥션 등)가 고갈된 경우고, 둘째는 Locust를 실행하는 부하 발생기(Local Machine)의 스레드 및 소켓 소진 문제다.
대부분의 개발자들이 범하는 실수는 대기 시간(wait_time) 없이 무한 반복문처럼 HTTP 요청을 연달아 쏘는 것이다.
실제 사용자는 페이지를 이동하거나 버튼을 누를 때 일정 시간 읽고 생각하는 시간이 존재하는데, 이를 무시하면 서버가 아닌 부하 테스트 실행 장비에서 먼저 커넥션 타임아웃이 발생하게 된다.
실제 커머스 서비스의 상품 목록 조회 및 로그인 시나리오를 작성할 때, 잘못된 코드와 올바른 코드를 비교해 보자.
대기 시간 설정이 전혀 없고, 에러 응답이 돌아와도 성공으로 처리되어 정확한 성능 측정이 불가능하다.
from locust import HttpUser, task
class WrongLoadTest(HttpUser):
# wait_time이 없어서 CPU 자원을 100% 사용하며 무한 요청을 보냄
@task
def get_products(self):
# 응답 상태 코드 검증이 없어서 500/504 에러도 성공으로 집계됨
self.client.get("/api/v1/products")
@task
def login(self):
# 세션이나 헤더 관리 없이 무작위 연사 요청
self.client.post("/api/v1/login", json={"user": "test"})between 함수로 자연스러운 사용자 유예 시간을 부여하고, catch_response 옵션을 통해 응답 지연 및 에러 상태를 정확히 검증한다.
from locust import HttpUser, task, between, events
import logging
class CorrectLoadTest(HttpUser):
# 각 요청 사이 1초에서 3초 사이의 무작위 대기 시간 부여
wait_time = between(1, 3)
def on_start(self):
# 테스트 시작 시 1회 수행되는 로그인 절차 (토큰 발급)
response = self.client.post("/api/v1/login", json={
"username": "test_user",
"password": "password123"
})
if response.status_code == 200:
token = response.json().get("access_token")
self.client.headers.update({"Authorization": f"Bearer {token}"})
@task(3)
def get_product_list(self):
# 비중 3으로 가장 자주 실행되는 상품 목록 조회
with self.client.get("/api/v1/products", catch_response=True, timeout=5) as response:
if response.status_code == 200:
response.success()
else:
response.failure(f"상품 목록 조회 실패 상태코드: {response.status_code}")
@task(1)
def view_cart(self):
# 비중 1로 실행되는 장바구니 조회
with self.client.get("/api/v1/cart", catch_response=True, timeout=5) as response:
if response.elapsed.total_seconds() > 2.0:
response.failure("장바구니 조회 응답 시간 2초 초과")
else:
response.success()
# 테스트 종료 후 성공 기준(Threshold) 검증 이벤트
@events.quitting.add_listener
def _(environment, **kw):
if environment.stats.total.fail_ratio > 0.01:
logging.error("[FAIL] 전체 요청 중 에러율이 1%를 초과했습니다.")
environment.process_exit_code = 1
elif environment.stats.total.get_response_time_percentile(0.95) > 2000:
logging.error("[FAIL] 95% 응답 시간이 2000ms(2초)를 초과했습니다.")
environment.process_exit_code = 1
else:
logging.info("[PASS] 모든 성능 기준(Threshold)을 만족했습니다.")# CLI 모드로 사용자 100명, 초당 생성 10명, 1분간 테스트 진행
locust -f load_test.py --headless -u 100 -r 10 --run-time 1m --host=https://api.example.comType Name # reqs # fails | Avg Min Max Med | req/s failures/s
--------|-------------------|-----------|---------|---------|-------|------|------|--------|-----------
GET /api/v1/cart 1240 0(0.00%)| 180 45 1250 120 | 20.60 0.00
GET /api/v1/products 3710 2(0.05%)| 145 32 2100 98 | 61.80 0.03
--------|-------------------|-----------|---------|---------|-------|------|------|--------|-----------
Aggregated 4950 2(0.04%)| 154 32 2100 105 | 82.40 0.03
[PASS] 모든 성능 기준(Threshold)을 만족했습니다.
부하 테스트를 진행할 때 흔히 발생하는 3가지 문제점과 올바른 대응 전략을 살펴보자.
✗ **잘못된 방식**: 온-프레미스나 단일 노트북에서 VU 10000명을 한 번에 생성하여 테스트 진행.
✓ **올바른 방식**: 단일 인스턴스는 OS의 오픈 파일 레지스트리(ulimit) 및 네트워크 소켓 한계가 존재하므로, Locust의 Master-Worker 분산 모드를 활용해 여러 인스턴스에서 분산 부하를 일으킨다.
✗ **잘못된 방식**: 부하 테스트 대상 서버에 테스트 데이터가 없어서 404 에러만 계속 반환되는데 평균 응답 시간만 체크.
✓ **올바른 방식**: catch_response=True를 사용해 HTTP 200 이외의 응답은 명시적으로 실패 처리하고, 에러 비율(Fail Ratio)을 집계 기준에 포함한다.
✗ **잘못된 방식**: Spawn Rate를 100/s처럼 너무 높게 설정해 가상 사용자가 접속하자마자 서버 DDOS 공격 형태로 인프라가 락(Lock)되는 현상 발생.
✓ **올바른 방식**: Ramp-up 기간을 충분히 두고 초당 5~10명씩 완만하게 가상 사용자를 늘려가면서 스파이크 타임아웃 구간을 정확히 측정한다.
성공적인 부하 테스트를 위해 기억해야 할 핵심 사항은 다음과 같다.
1. **wait_time 필수 설정**: between(1, 3)을 통해 실 사용자 동작 시뮬레이션 및 로컬 장비의 소켓 고갈 방지
2. **catch_response 활용**: 응답 상태 코드 및 지연 시간을 엄격히 평가하여 에러 수집
3. **이벤트 기반 Threshold 구현**: CI/CD 파이프라인 연동을 위해 95% Percentile 시간 및 에러율 기준 자동 검증 코드 포함
Locust를 활용한 부하 테스트 시나리오 작성은 서비스의 실제 한계를 파악하고 트래픽 폭주에 미리 대비하는 필수 과정이다. 정밀하게 설계된 가상 사용자 시나리오와 적절한 대기 시간 설정이라는 작은 습관이 모여서 서버의 정확한 보틀넥을 찾아내는 큰 효과를 만든다는 점을 잊지 말자. 이 글의 실전 시나리오 코드와 임계값 검증 설정을 참고해 여러분의 서비스에 부하 테스트를 직접 적용해 보면, 대규모 이벤트 시에도 흔들리지 않는 안정적인 백엔드 시스템을 구축할 수 있을 것이다.