초보개발자도 10분만에 따라하는 Locust 서버 부하테스트 완벽 가이드

2025년 09월 04일 by Nuuthang 40

초보개발자도 10분만에 따라하는 Locust 서버 부하테스트 완벽 가이드에 대한 img

처음으로 서버 부하 테스트를 해야 했던 순간이 기억납니다. 갑자기 늘어난 사용자로 인해 서버가 다운되는 장애를 겪은 후, 개발팀에서는 "앞으로는 미리 부하 테스트를 해보자"라는 결론을 내렸죠. 그때 만난 것이 바로 Locust였습니다. 복잡한 설정 없이 파이썬 코드 몇 줄로 시작할 수 있어서 초보자인 저도 쉽게 접근할 수 있었거든요.

🌐 개념/정의

Locust는 파이썬으로 작성된 오픈소스 부하 테스트 도구입니다. 메뚜기(Locust)가 떼를 지어 몰려드는 것처럼, 수많은 가상 사용자를 생성해서 웹 애플리케이션에 동시 접속을 시뮬레이션하는 것이 핵심 아이디어죠.

핵심 특징:

파이썬 기반의 직관적 스크립트 작성 - 익숙한 파이썬 문법으로 테스트 시나리오 구현
웹 기반 실시간 모니터링 - 브라우저에서 테스트 진행 상황과 결과를 실시간 확인
분산 테스트 지원 - 여러 서버에서 동시에 부하를 생성하여 대규모 테스트 가능
유연한 시나리오 설정 - 사용자별 다른 행동 패턴과 가중치 설정
상세한 성능 지표 제공 - 응답 시간, 처리량, 실패율 등 다양한 메트릭 제공

📜 공식 정책/가이드라인

시스템 요구사항

Python 3.7 이상 필수
Windows 사용자는 Microsoft C++ Build Tools 추가 설치 필요
기본 포트: 8089번 포트 사용

설치 방법

# 기본 설치
pip install locust

# 설치 확인
locust --version

⚠️ Windows 사용자 주의사항: 설치 중 오류 발생 시 Microsoft C++ Build Tools를 먼저 설치하세요.

✅ 실무 적용 조건/단계

1단계: 기본 테스트 스크립트 작성

locustfile.py 파일을 생성하고 다음과 같이 작성합니다:

from locust import HttpUser, task, between

class WebsiteUser(HttpUser):
    wait_time = between(1, 5)  # 요청 간 1-5초 대기
    
    @task(3)  # 가중치 3 (더 자주 실행)
    def view_homepage(self):
        self.client.get("/")
    
    @task(1)  # 가중치 1
    def view_product(self):
        self.client.get("/product/1")

2단계: 테스트 실행

# 기본 실행 (현재 디렉토리의 locustfile.py 사용)
locust

# 특정 파일 지정
locust -f your_path/locustfile.py

# 호스트 미리 지정
locust --host=http://localhost:8000

3단계: 웹 UI에서 테스트 설정

브라우저에서 http://localhost:8089 접속
Number of users: 최대 동시 사용자 수 설정
Spawn rate: 초당 증가할 사용자 수 설정
Host: 테스트할 서버 주소 입력
Start swarming 버튼 클릭하여 테스트 시작

4단계: 결과 분석

테스트 진행 중 다음 지표들을 실시간으로 확인할 수 있습니다:

RPS (Requests Per Second): 초당 처리 요청 수
Response Time: 평균/최대/최소 응답 시간
Failure Rate: 실패한 요청의 비율
Current Users: 현재 활성 사용자 수

💡 주요 성공/실패 사례

성공 사례: 전자상거래 API 테스트

한 개발팀에서 쿠폰 발급 API의 동시성 문제를 해결하기 위해 Locust를 활용했습니다. 1000명의 동시 사용자로 테스트한 결과, 중복 쿠폰 발급 버그를 발견하고 수정할 수 있었습니다.

@task
def get_coupon(self):
    with self.client.post('/coupon/issue', 
                         json={'user_id': self.user_id},
                         catch_response=True) as response:
        if response.status_code != 200:
            response.failure(f"Failed to get coupon: {response.status_code}")

실패 사례: 설정 미숙으로 인한 잘못된 결과

초기에 wait_time 설정 없이 테스트했더니 비현실적으로 높은 RPS가 나와서 잘못된 결론을 내린 사례가 있었습니다. 실제 사용자 패턴을 반영한 적절한 대기 시간 설정이 중요합니다.

블록체인 부하 테스트 성공 사례

SK Planet에서는 각 사용자마다 고유한 지갑을 생성하여 블록체인 트랜잭션 처리량 테스트를 성공적으로 수행했습니다:

def on_start(self):
    # 각 사용자별 고유 지갑 생성
    self.wallet = create_unique_wallet()
    self.name = generate_unique_name()

❓ 자주 묻는 질문(FAQ)

Q1. Locust 실행 시 "No module named 'locust'" 오류가 발생해요.

A1. pip로 설치했는지 확인하고, 가상환경을 사용한다면 해당 환경이 활성화되어 있는지 체크하세요. pip list | grep locust로 설치 여부를 확인할 수 있습니다.

Q2. 테스트 중 응답 시간이 비정상적으로 높게 나와요.

A2. 네트워크 지연, 서버 리소스 부족, 또는 테스트 클라이언트의 성능 한계일 수 있습니다. 로컬 환경에서 테스트하거나 더 강력한 머신에서 실행해보세요.

Q3. 여러 종류의 요청에 다른 비율을 적용하고 싶어요.

A3. @task(가중치) 데코레이터를 사용하세요. 예를 들어 @task(3)과 @task(1)을 사용하면 3:1 비율로 실행됩니다.

Q4. 로그인이 필요한 서비스는 어떻게 테스트하나요?

A4. on_start() 메서드에서 로그인을 수행하고 세션을 유지하거나, 각 요청에 인증 토큰을 포함하세요.

Q5. 테스트 결과를 파일로 저장할 수 있나요?

A5. 네, --csv 옵션을 사용하면 됩니다. locust --csv=result로 실행하면 CSV 파일로 결과가 저장됩니다.

Q6. Windows에서 설치 시 빌드 오류가 계속 발생해요.

A6. Microsoft C++ Build Tools를 설치하고, Visual Studio Installer에서 "C++ build tools" 워크로드를 선택해 설치하세요.

Q7. 한 번에 몇 명까지 테스트할 수 있나요?

A7. 클라이언트 머신의 성능에 따라 다르지만, 일반적으로 단일 머신에서 수천 명까지 가능합니다. 더 많은 사용자가 필요하면 분산 모드를 사용하세요.

Q8. 실제 서비스 배포 전 적정 동시 접속자 수는 어떻게 정하나요?

A8. 예상 트래픽의 2-3배 수준으로 테스트하는 것이 일반적입니다. 점진적으로 사용자 수를 늘려가며 서버 응답 시간이 급격히 증가하는 지점을 찾으세요.

⚡ 추가 팁/주의점

1. 현실적인 사용자 행동 패턴 모방

wait_time = between(1, 5)  # 너무 짧은 대기시간은 비현실적

실제 사용자는 페이지를 읽고 생각하는 시간이 필요합니다. 0.1초마다 요청을 보내는 것은 비현실적이니 적절한 대기 시간을 설정하세요.

2. 단계적 부하 증가 전략

처음부터 높은 부하를 주지 말고, 10명 → 50명 → 100명 순으로 점진적으로 늘려가며 서버의 한계점을 찾아보세요. Spawn rate를 낮게 설정하여 서버가 적응할 시간을 주는 것이 중요합니다.

3. 네트워크와 서버 리소스 모니터링

Locust 결과만 보지 말고, 서버의 CPU, 메모리, 디스크 I/O, 네트워크 대역폭도 함께 모니터링하세요. 병목 지점을 정확히 파악할 수 있습니다.

4. 테스트 환경 격리

운영 서버에 직접 부하 테스트를 하면 절대 안 됩니다. 반드시 별도의 스테이징 환경에서 테스트하고, 운영과 동일한 스펙으로 구성해야 의미 있는 결과를 얻을 수 있습니다.

5. 에러 처리와 로깅

with self.client.get('/api/data', catch_response=True) as response:
    if response.status_code != 200:
        response.failure(f"Got status code {response.status_code}")

예상치 못한 응답에 대한 처리를 미리 구현해 두세요. 단순히 성공/실패만 보는 것이 아니라 어떤 종류의 에러가 발생하는지 파악하는 것이 중요합니다.

6. 분산 테스트 시 네트워크 고려사항

여러 머신에서 분산 테스트를 할 때는 각 워커 머신의 네트워크 대역폭도 고려해야 합니다. 클라이언트 측 네트워크가 병목이 되어 잘못된 결과가 나올 수 있거든요.

10만명 초당 1000명 테스트 단일 fast api 컨테이너+redis