---
name: benchmark-checklist
description: "보고하거나 조치하기 전에 성능 측정 (제한자, 튜닝, 한계, 오류, 반복성, 관련성, 작업 발생 여부)을 검증하세요. 벤치마크를 실행하거나 측정한 속도 향상 또는 회귀를 보고할 때 사용하세요."
disable-model-invocation: true
---

# Benchmark checklist

성능 숫자를 생성할 때 이것을 사용하세요: PR의 이전과 이후, 회귀 주장, hillclimb 하니스, 또는 라이브러리나 구성 선택. 코드에 대한 추측이 아니라 실행의 증거로 각 질문에 답하세요.

사용자가 요청한 빠른 ballpark의 경우 한 번의 실행으로 충분합니다. 여전히 질문 4와 7을 확인하고 한 번의 실행이라고 말하세요. 해당 실행이 잘못 보이지 않는 한 나머지는 건너뛰세요. 옵션 간의 선택은 절대 ballpark가 아닙니다.

## 무엇이든 실행하기 전에

- 배송할 단어로 예상하는 주장을 적으세요 ("내보내기는 60k 행 데이터 세트에서 p50에서 30% 더 빠릅니다"). 질문은 그 문장을 테스트합니다.
- 측정 스크립트를 읽으세요. 무엇을 시간 측정하고 카운트하고 무시하는지 주목하세요.
- `uptime`으로 로드 평균을 확인하고 `nproc`로 코어 수를 확인하세요. 머신이 바쁘면 무엇이 실행 중인지 확인하세요. 멈출 수 없다면 양쪽이 동일한 노이즈를 보도록 인터리브하고 보고서에서 그렇게 말하세요.

## 질문

1. **왜 두 배가 아닌가?** 제한자를 명명하세요. 보고하지 않는 실행에서 프로파일링하세요. 프로파일러와 트레이서가 작업을 느리게 만들기 때문입니다. 프로세스당 CPU (`top`, `pidstat`), 런타임 프로파일러 (`node --cpu-prof`, `py-spy`, `perf`), I/O 대기, 그리고 시스템 호출 카운트 (Linux에서 `strace -c`)를 사용한 다음 핫 스팟을 소스에 매핑하세요. 로드 생성기도 확인하세요: 먼저 포화되면 로드 생성기를 측정한 것입니다. 변경이 숫자를 움직이지 않았다면 제한자가 이유를 설명하므로 변경이 쓸모없다고 말하기 전에 찾으세요.
2. **튜닝되었나?** 프로덕션이 실행하는 방식으로 모든 측면을 실행하세요: 릴리스 빌드, 프로덕션 플래그 및 환경, 배치 및 트랜잭션 설정, 연결 풀, 프로덕션이 보는 것처럼 따뜻하거나 차가운 캐시, 그리고 동일한 버전과 데이터. 한쪽이 기본값으로 실행되면 구현이 아니라 구성을 비교한 것입니다. 설정인 제한자 (행당 커밋, 디버그 빌드, 누락된 인덱스)는 해당 측면이 튜닝되지 않았음을 의미합니다. 튜닝하고 승자를 선택하기 전에 다시 측정하세요. 튜닝할 수 없다면 해당 실행에서 승자를 선택하지 마세요. 사용자가 무엇을 채택할지 선택할 때, 주장을 오늘의 코드로 좁히는 것은 이것을 고치지 않습니다. 왜냐하면 그들은 오늘의 설정이 아니라 옵션을 채택하기 때문입니다.
3. **한계를 깼나?** 산술을 수행하세요. 초당 바이트를 디스크 및 네트워크 대역폭과 비교하고, 초당 작업 수에 작업당 비용을 곱한 것을 코어와 비교하고, 절약된 시간을 변경된 조각이 소요한 시간과 비교하세요. 실행의 10%를 차지하는 조각을 제거하면 실행을 최대 약 11% 더 빠르게 만들 수 있습니다. 측정된 한계를 넘은 결과는 캐시, no-op 또는 버그와 같은 다른 것을 측정했습니다.
4. **오류가 발생했나?** 실패 및 비성공 응답을 카운트하고 출력이 단지 존재하는 것이 아니라 올바른지 확인하세요. 거부는 종종 빠르고 타임아웃과 재시도는 느립니다. 스크립트가 오류를 카운트하지 않으면 카운트를 추가하세요.
5. **재현되나?** 각 측면을 최소 5번 실행하고 교대로 (A, B, A, B 등) 실행하여 워밍업, 지연 초기화, 캐시 및 드리프트가 어느 쪽도 선호하지 않도록 하세요. 중앙값과 범위를 보고하세요. 실행 간 변동보다 작은 간격은 측정 가능한 차이가 없습니다. 호출이 가까우면 순위 합 테스트 또는 하니스 자체 통계를 사용하세요.
6. **중요한가?** 마이크로 결과 옆에 사용자가 기다리는 엔드 투 엔드 경로를 측정하고, 현실적인 데이터 크기와 동시성으로 측정하고, 마이크로 결과를 전체의 일부로 보고하세요. 요청의 1%를 차지하는 헬퍼는 헬퍼가 얼마나 빨라지든 요청을 최대 1% 더 빠르게 만들 수 있습니다.
7. **실제로 발생했나?** 작업이 시간 측정된 영역 내에서 실행되었는지 확인하세요: 요청이 서버에 도달했고, 행이 작성되었고, 바이트가 읽혔고, 코드가 결과를 사용했습니다. 지연 코드 (아무도 반복하지 않는 제너레이터, 아무도 기다리지 않는 프로미스, JIT가 버릴 수 있는 결과)와 타임아웃은 발생하지 않은 작업에 대한 숫자를 생성합니다.

## 보고

- 평결로 시작하세요: 더 빠름, 더 느림, 측정 가능한 차이 없음 또는 불확정.
- 단위, 실행 횟수, 범위 및 제한자와 함께 숫자를 제공하세요. 예를 들어, "p50 41 ms → 33 ms, 측면당 7회 실행의 중앙값, 이후 32~35 ms 범위, 하나의 코어에서 JSON 파싱으로 바인딩됨."
- 차이를 주장하지만 제한자를 명명할 수 없을 때, 한쪽이 튜닝되지 않은 상태로 실행되었을 때, 또는 질문 4와 7을 확인할 수 없었을 때 평결을 불확정이라고 하세요. 격차를 명명하세요.
- PR 본문을 하나의 주요 숫자로 유지하세요. **Opening a PR** playbook에 따라. 실행, 범위 및 제한자 증거를 연결된 아티팩트 또는 노트 파일에 넣으세요.

## 기타 성능 자료

- **Perf issue** playbook이 그것으로부터 계획하기 전에 playbook의 베이스라인을 검증하고, 그 후의 모든 숫자를 검증하세요.
- **Hillclimb** playbook의 하니스를 고정하기 전에 검증하세요. 고정된 하니스는 오류 및 작업 카운트를 출력하므로 각 유지 또는 되돌리기는 무료로 질문 4와 7을 확인합니다.