Grafana k6 입문: 스크립트 작성부터 결과 해석까지

k6 설치와 HTTP 스크립트, VU·도착률 모델, 검사와 임계값, 의존 요청을 보호하는 사용자 여정을 살펴봅니다. 결과 출력과 애플리케이션 텔레메트리의 차이도 설명합니다.

모범 사례
소프트웨어 테스트와 측정, 품질 검증을 표현한 일러스트

Grafana k6는 코드로 부하를 정의하고 테스트 결과를 기록하는 도구입니다. 엔진은 Go로 구현됐으며 스크립트에는 JavaScript, 최신 버전에서는 TypeScript도 사용할 수 있습니다. 다만 Node.js에서 실행되지는 않습니다. 발생시킬 수 있는 부하는 스크립트, 프로토콜, 부하 발생기의 자원에 따라 달라지므로 특정 VU 수를 어디서나 보장할 수는 없습니다.

첫 테스트부터 성공의 의미를 분명히 해야 합니다. 기본 설정에서는 HTTP 302가 예상된 응답으로 집계돼도 직접 작성한 '상태 코드 200' 검사에는 실패할 수 있습니다. VU 목표도 초당 요청 수와 다릅니다. CI 통과 기준으로 쓰기 전에 이런 차이를 확인해야 합니다.

이 글은 공식 문서를 바탕으로 작성했으며 k6 부하 테스트나 성능 벤치마크를 실행하지 않았습니다. API와 데이터는 프로젝트에서 준비해야 합니다. Grafana Labs는 2021년에 k6를 인수했고(영문), 적절한 결과 저장소를 거쳐 Grafana에서 시각화할 수 있습니다.

k6를 사용하는 이유

스크립트를 Git에 넣고 코드 리뷰와 CI에 연결할 수 있습니다. 유용한 방식이지만 k6만의 기능은 아닙니다. JMeter도 GUI 없이 실행할 수 있고 Locust도 스크립트 기반입니다. 다른 도구는 모두 수동 클릭이 필요하다고 가정하기보다 언어, 프로토콜, 실행 모델과 유지 관리 방식을 비교합니다.

k6에는 자체 JS/TS 런타임이 있습니다. Node.js 내장 API에 의존하는 패키지를 그대로 복사해 실행할 수 있다고 보면 안 됩니다. 아래 예시는 프로토콜 수준의 HTTP 요청을 보내며 페이지 JavaScript를 실행하거나 렌더링하지 않습니다. 브라우저 테스트에는 해당 모듈과 별도의 자원 예산이 필요합니다.

설치와 실행

다음 예시를 script.js로 저장합니다. 실행 전에 허가받은 테스트 API의 기본 주소를 BASE_URL 환경 변수로 내보냅니다. 쿼리 문자열이나 프래그먼트는 넣지 않습니다. api.example.com 같은 이름은 설명용이며 공개 부하 테스트 API가 아닙니다.

# macOS 설치
brew install k6

# script.js와 내보낸 BASE_URL을 준비한 뒤 로컬 실행
k6 run script.js

# Docker 사용: 내보낸 BASE_URL을 전달하고 표준 입력으로 스크립트 읽기
docker run --rm -i -e BASE_URL grafana/k6:2.3.0 run - < script.js

Docker 예시는 확인한 2.3.0 태그를 고정합니다. 태그가 이미지 내용의 불변성까지 보장하지는 않으므로 필요하면 검증한 digest를 사용합니다. -i는 스크립트를 표준 입력으로 전달하기 위한 옵션입니다. 다른 로컬 파일이나 상대 경로 모듈은 별도 마운트가 필요합니다. Homebrew가 설치하는 버전은 다를 수 있으므로 k6 version으로 확인합니다. 설치(영문) · 스크립트 실행(영문)

첫 번째 스크립트

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

if (!__ENV.BASE_URL) throw new Error('Set BASE_URL to an authorized test API');
const baseUrl = __ENV.BASE_URL.replace(/\/+$/, '');

export const options = {
    vus: 20,          // 가상 사용자 20명이며 20 RPS라는 뜻은 아님
    duration: '30s',  // 고정 VU 시나리오의 실행 시간
    thresholds: {
        http_req_failed: ['rate<0.01'],
        http_req_duration: ['p(95)<500'],
        checks: ['rate>0.99'],
    },
};

export default function () {
    const res = http.get(`${baseUrl}/users`);
    check(res, {
        '상태 코드가 200': (r) => r.status === 200,
        '응답 시간이 500ms 미만': (r) => r.timings.duration < 500,
    });
    sleep(1);
}

vus와 duration은 고정 VU 시나리오의 축약 설정입니다. VU마다 요청과 sleep을 반복하므로 고정 RPS를 보장하지 않습니다. 종료 시점에는 graceful stop 등의 설정도 영향을 줍니다. /users 경로와 200 응답은 프로젝트가 제공해야 합니다.

check 실패는 결과를 기록하지만 그것만으로 프로세스가 실패 코드로 종료되지는 않습니다. CI 통과 여부에는 thresholds를 사용합니다. rate<0.01은 요청 실패율이 정확히 1%보다 작아야 하고, p(95)<500은 해당 시간 지표의 P95가 정확히 500ms보다 작아야 한다는 조건입니다. checks의 rate>0.99는 실행한 두 검사를 합친 통과율이 99%보다 커야 한다는 뜻이지 각 검사를 따로 99% 이상 만족시킨다는 뜻은 아닙니다. 개별 조건을 제한하려면 검사나 요청 태그에 맞는 임계값을 설정합니다.

http_req_failed는 기본적으로 200~399를 예상 응답으로 보는 규칙을 따릅니다. 직접 작성한 status === 200 검사와는 기준이 다릅니다. 필터가 없는 http_req_duration 임계값은 성공 응답이나 특정 API만이 아니라 그 지표의 모든 요청 샘플을 포함합니다. P95도 사용자 비율이 아닙니다. 이 시간은 전송·대기·수신의 합이며 최초 DNS 조회와 연결 설정 시간 등은 제외합니다.

수치는 구문 예시이며 모든 서비스에 통하는 SLO가 아닙니다. 소유하거나 허가받은 격리 환경에서 적은 VU로 시작해 데이터와 발생기 여유를 확인합니다. 일반 threshold는 즉시 중단 스위치가 아니므로 조기 종료에는 abortOnFail 등을 명시적으로 설정해야 합니다. 자원·비용 제한에는 해당 측정이나 외부 제어도 필요합니다. 주문 예시는 테스트 주문과 결제 샌드박스로 한정합니다. 검사와 임계값(영문) · 예상 응답(영문)

시간에 따라 VU 수 바꾸기

stages로 시간에 따른 VU 수를 지정할 수 있습니다. 아래는 앞의 options를 교체하는 설정입니다. 한 스크립트에 두 번 선언하거나 고정 시나리오의 vus/duration을 그대로 합치지 않습니다.

export const options = {
    stages: [
        { duration: '2m', target: 100 },  // 2분 동안 100 VU까지 증가
        { duration: '5m', target: 100 },  // 100 VU를 5분간 유지
        { duration: '2m', target: 0 },    // 2분 동안 0 VU까지 감소
    ],
};

target은 VU 수이며 초당 요청 수가 아닙니다. 응답 시간, 반복당 요청 수, 생각 시간이 바뀌면 같은 VU 수에서도 처리량이 달라집니다. 단계적 부하, spike, 장시간 soak 등의 패턴을 구성할 수 있습니다. 이 교체 예시에는 앞의 thresholds가 없으므로 같은 테스트 목적에 필요한 조건을 다시 추가해야 합니다. Ramping VUs(영문)

실패한 선행 요청 뒤의 작업은 멈추기

사용자 여정은 여러 API에 걸친 업무 흐름을 시험하기에 유용합니다. 단일 API 테스트도 용량이나 회귀를 조사할 때 가치가 있습니다. 다음은 별도의 독립 스크립트이며 프로젝트의 예시 계약을 가정합니다. 로그인은 JSON user/pass를 받고 200과 문자열 token을 반환하고, 상품은 sku가 있는 배열, 테스트 주문 생성은 201과 문자열 id를 반환합니다. k6가 제공하는 공개 API가 아니므로 실제 경로와 필드에 맞춰야 합니다.

BASE_URL 외에 TEST_USER, TEST_PASS, TEST_SKU를 준비하고 Docker에서도 명시적으로 전달합니다. 예시는 여정을 한 번만 실행합니다. 동시 부하로 확대하기 전에 분리된 계정, SKU, 테스트 데이터를 준비해야 합니다.

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

const required = ['BASE_URL', 'TEST_USER', 'TEST_PASS', 'TEST_SKU'];
if (required.some((key) => !__ENV[key])) {
    throw new Error('Set BASE_URL, TEST_USER, TEST_PASS, and TEST_SKU for your test API');
}
const baseUrl = __ENV.BASE_URL.replace(/\/+$/, '');
export const options = { vus: 1, iterations: 1, thresholds: { checks: ['rate==1'] } };

function jsonOrNull(response) {
    try { return response.json(); } catch (_) { return null; }
}

export default function () {
    const login = http.post(`${baseUrl}/login`, JSON.stringify({
        user: __ENV.TEST_USER, pass: __ENV.TEST_PASS,
    }), { headers: { 'Content-Type': 'application/json' } });
    const loginBody = jsonOrNull(login);
    const token = typeof loginBody?.token === 'string' ? loginBody.token : '';
    if (!check(login, { '로그인이 200과 token을 반환': (r) => r.status === 200 && token.length > 0 })) {
        sleep(1);
        return;
    }
    const params = { headers: {
        Authorization: `Bearer ${token}`, 'Content-Type': 'application/json',
    } };
    const products = http.get(`${baseUrl}/products`, params);
    const catalog = jsonOrNull(products);
    if (!check(products, { '상품 목록에 테스트 SKU가 있음': (r) => r.status === 200
        && Array.isArray(catalog) && catalog.some((item) => item?.sku === __ENV.TEST_SKU) })) {
        sleep(1);
        return;
    }
    const order = http.post(`${baseUrl}/orders`, JSON.stringify({
        sku: __ENV.TEST_SKU, qty: 1,
    }), params);
    const created = jsonOrNull(order);
    check(order, { '테스트 주문이 생성됨': (r) => r.status === 201
        && typeof created?.id === 'string' && created.id.length > 0 });
    sleep(2);
}

jsonOrNull은 JSON이 아닌 응답을 토큰 파싱 예외 대신 검사 실패로 처리할 수 있게 합니다. 인증이나 상품 검사가 실패하면 그 결과에 의존하는 주문을 보내지 않고 반환합니다. 주문 응답도 확인합니다. 여기의 checks 임계값은 실행한 검사 전부의 통과를 요구하지만, 업무상 정확성이나 테스트 데이터 정리, 처리량 목표까지 정해 주지는 않습니다.

어떤 대상을 센 결과인지 확인하기

내장 지표에서 요청, 반복, 검사를 구분합니다.

지표 의미
http_req_duration HTTP 전송·대기·수신 시간 분포. 최초 DNS/연결 설정은 제외하며 P90/P95는 요청 샘플의 백분위수
http_req_failed 예상 응답 규칙에 따른 실패 비율이며 모든 업무 오류와 같지는 않음
vus / iterations 현재 활성 VU 수 / 누적 반복 수. 한 여정에서 여러 요청을 보내거나 중간에 반환할 수 있음
checks 실행된 검사들의 통과율이며 요청 수·사용자 수와는 다른 기준

출력과 호환되는 결과 백엔드를 설정합니다. 현재 문서의 실험적 experimental-prometheus-rw 출력은 설정된 Prometheus remote-write 수신기로 메트릭을 전송합니다. Grafana는 그 저장소를 쿼리해 보여 주는 도구이지 임의의 --out을 받는 시계열 저장소가 아닙니다. 수신 주소, 인증, TLS, 버전 지원을 확인해야 합니다. 내장 지표(영문) · Prometheus remote write(영문)

각 실행의 시작·종료 시각, 애플리케이션 버전, 테스트 식별자를 기록하고 지연이 증가한 구간을 로그와 자원 지표에 맞춰 봅니다. 서버 내부 호출을 더 살펴보려면 테스트 대상 애플리케이션을 계측하고 Guance OpenTelemetry 수집(영문)을 설정한 뒤 수집된 하위 스팬을 확인합니다. k6 결과 출력과는 별개 경로입니다.

k6 태그가 자동으로 애플리케이션 로그나 스팬 필드가 되지는 않습니다. 테스트 식별자를 전달하려면 합의한 헤더와 애플리케이션의 기록 방식이 필요합니다. 트레이스 연결에도 컨텍스트 전파, 샘플링, 보존 기간, 접근 권한을 확인해야 합니다. 수집되지 않은 트레이스로 부하 테스트 전체를 복원할 수는 없습니다.

자주 묻는 질문

JMeter, Locust와 어떻게 비교하나요? 언어, 지원 프로토콜, 팀 경험을 비교합니다. k6는 자체 JS/TS 환경, Locust는 Python을 사용하며 JMeter는 GUI 없이 실행할 수 있습니다. 발생기 성능은 같은 시나리오에서 평가해야 하며 모든 스크립트에 더 많은 VU를 보장하는 도구는 없습니다.

반드시 sleep을 넣어야 하나요? 세션 모델에는 생각 시간이 필요할 수 있습니다. 도착률 실행기는 반복 시작률을 제어하므로 그 속도를 맞추려고 반복 끝에 추가 sleep을 넣는 방식은 보통 피합니다. 한 반복에 여러 HTTP 요청이 있으면 초당 반복 수와 HTTP RPS도 다릅니다. VU 수는 고정 RPS가 아니고 발생기 자체가 병목이 될 수도 있습니다.

어느 환경에서 시험하나요? 운영 환경과 비슷한 스테이징을 우선합니다. 운영에 직접 부하를 준다면 위험 평가, 부하 제한, 중단 수단을 준비해야 합니다. 스테이징의 자원, 데이터, 의존성이 다르다면 그 결과도 운영 용량의 보장이 되지는 않습니다.

공식 자료

기술 자료 확인일: 2026년 11월 5일. 예시 이미지는 2.3.0이며 버전을 바꿀 때 실행 방식과 출력 지원을 다시 확인합니다.

함께 읽기

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소