Apache JMeter 완전 가이드

JMeter란?

Apache JMeter는 1998년 처음 출시된 검증된 오픈소스 부하 테스트 도구입니다. GUI 기반의 Test Plan 설계, 다양한 프로토콜 지원, 플러그인 생태계, 내장 분산 테스트 기능으로 엔터프라이즈 환경에서 널리 사용됩니다.

지원 프로토콜

• HTTP / HTTPS
• FTP, JDBC (데이터베이스)
• LDAP, SMTP, POP3, IMAP
• JMS (Java Messaging Service)
• TCP, WebSocket (플러그인)

설치

1. Java 설치 (필수)

JMeter는 Java 11+ 이 필요합니다.

# macOS
brew install openjdk@17

# Ubuntu/Debian
sudo apt install openjdk-17-jdk

# 버전 확인
java -versionbash

2. JMeter 다운로드 & 실행

# 공식 다운로드 (Apache 미러)
wget https://downloads.apache.org/jmeter/binaries/apache-jmeter-5.6.3.tgz
tar -xzf apache-jmeter-5.6.3.tgz
cd apache-jmeter-5.6.3/bin

# GUI 실행
./jmeter          # macOS/Linux
jmeter.bat        # Windowsbash

GUI 기본 사용법

Test Plan

Test Plan은 JMeter 테스트의 최상위 컨테이너입니다. 모든 테스트 요소(Thread Group, Sampler, Listener 등)는 Test Plan 아래에 위치합니다.

• User Defined Variables — 전역 변수 정의 (BASE_URL, TOKEN 등)
• Functional Test Mode — 응답 데이터를 모두 저장 (성능 테스트 시 비활성화 권장)

Thread Group

실제 가상 사용자(VU)를 시뮬레이션하는 핵심 요소입니다.

Sampler — 요청 정의

실제 서버로 전송되는 요청을 정의합니다. HTTP Request Sampler가 가장 많이 사용됩니다.

HTTP Request Sampler 주요 설정

• Protocol: http 또는 https
• Server Name: api.example.com
• Method: GET, POST, PUT, DELETE
• Path: /api/users
• Body Data: JSON, XML, Form 데이터
• Headers: HTTP Header Manager로 공통 헤더 추가

HTTP Header Manager 예시

# Header Manager에 추가할 헤더
Content-Type: application/json
Authorization: Bearer ${TOKEN}
Accept: application/jsontext

Listener — 결과 분석

Assertions — 응답 검증

Response Assertion

• Response Code — 200, 201, 404 등 상태 코드 확인
• Response Body — 특정 텍스트 포함 여부
• Response Headers — Content-Type 등 헤더 확인

JSON Assertion

# JSON Path Expression 예시
$.data[0].id          # 첫 번째 항목의 id 필드
$.status              # status 필드
$.users.length()      # 배열 길이text

Duration Assertion

응답이 지정된 시간(ms) 내에 완료되지 않으면 실패 처리합니다.

Duration: 2000ms  # 2초 초과 시 실패text

변수 & 파라미터

User Defined Variables

BASE_URL = https://api.example.com
API_TOKEN = your-secret-token
THREAD_COUNT = 100text

CSV Data Set Config — 데이터 드리븐 테스트

외부 CSV 파일에서 사용자, 상품 ID 등 동적 데이터를 읽어 테스트합니다.

# users.csv
user1@example.com,password1
user2@example.com,password2
user3@example.com,password3csv

• Filename: ./data/users.csv
• Variable Names: username,password
• Delimiter: ,
• Sharing mode: All threads

정규식 추출 (Regex Extractor)

# 응답에서 토큰 추출
Reference Name: auth_token
Regular Expression: "token":"([^"]+)"
Template: $1$text

플러그인

JMeter Plugin Manager를 통해 기능을 확장할 수 있습니다.

# Plugin Manager JAR 다운로드 후 lib/ext에 복사
wget https://jmeter-plugins.org/get/ -O JMeterPlugins-Extras.jar
cp JMeterPlugins-Extras.jar $JMETER_HOME/lib/ext/bash

주요 플러그인

CLI (Non-GUI) 실행

실제 부하 테스트는 GUI가 없는 CLI 모드로 실행해야 정확한 결과를 얻을 수 있습니다.

# 기본 CLI 실행
jmeter -n -t test-plan.jmx -l results.jtl

# 옵션 설명
# -n  : Non-GUI 모드
# -t  : .jmx 파일 경로
# -l  : 결과 파일 (.jtl 또는 .csv)
# -e  : HTML 리포트 생성
# -o  : HTML 리포트 출력 디렉토리

# 완전한 명령어 (HTML 리포트 포함)
jmeter -n -t test-plan.jmx -l results/results.jtl -e -o results/html-report

# JVM 메모리 설정 (대규모 테스트)
JAVA_OPTS="-Xms1g -Xmx4g" jmeter -n -t test-plan.jmx -l results.jtlbash

커맨드라인 변수 오버라이드

jmeter -n -t test-plan.jmx \
  -JBASE_URL=https://staging.example.com \
  -JTHREAD_COUNT=200 \
  -JRAMP_UP=60 \
  -l results.jtlbash

분산 테스트

단일 머신으로 충분한 부하를 생성하기 어려울 때 여러 JMeter 인스턴스를 사용합니다.

구성

• Controller (Master) — 테스트를 조율하고 결과를 수집
• Agent (Slave) — 실제 부하를 생성하는 워커 노드

Agent 서버 설정

# Agent 서버에서 실행
$JMETER_HOME/bin/jmeter-server

# jmeter.properties 설정 (Agent)
server.rmi.localport=4000
server_port=1099bash

Controller에서 분산 실행

# jmeter.properties (Controller)
remote_hosts=192.168.1.10:1099,192.168.1.11:1099,192.168.1.12:1099

# 분산 실행 명령어
jmeter -n -t test-plan.jmx -r -l results.jtl
# -r : remote_hosts에 정의된 모든 Agent 사용

# 특정 Agent만 사용
jmeter -n -t test-plan.jmx -R 192.168.1.10,192.168.1.11 -l results.jtlbash

HTML 리포트 생성

# .jtl 파일에서 HTML 리포트 생성
jmeter -g results.jtl -o html-report/

# 리포트에 포함되는 내용:
# - 요청/응답 통계 (처리량, 에러율)
# - 응답 시간 분포 (히스토그램)
# - 퍼센타일 차트 (P50, P90, P95, P99)
# - 시간별 활성 스레드 수
# - 에러 요약bash

CI/CD 통합

GitHub Actions

name: JMeter Load Test

on:
  push:
    branches: [main]

jobs:
  jmeter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Download JMeter
        run: |
          wget -q https://downloads.apache.org/jmeter/binaries/apache-jmeter-5.6.3.tgz
          tar -xzf apache-jmeter-5.6.3.tgz
          echo "JMETER_HOME=$(pwd)/apache-jmeter-5.6.3" >> $GITHUB_ENV

      - name: Run JMeter Test
        run: |
          $JMETER_HOME/bin/jmeter -n \
            -t tests/load-test.jmx \
            -JBASE_URL=${{ secrets.STAGING_URL }} \
            -l results.jtl \
            -e -o html-report

      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: jmeter-report
          path: html-report/yaml