[sglang] 커널 내부를 들여다보는 법: SGLang JIT 커널에 IKET/%clock 기반 In-kernel 이벤트 트레이싱 도입
PR 링크: sgl-project/sglang#50374 상태: Merged | 변경: +1119 / -1
들어가며
GPU 커널을 최적화할 때 보통 두 가지 도구를 씁니다. CUDA event timing은 커널이 빨라졌는지를 알려주고, PC sampling(Nsight Compute)은 어느 instruction에서 stall이 생기는지를 알려줍니다. 하지만 둘 다 답하지 못하는 질문이 있습니다.
- 한 warp 안에서 load 단계와 compute 단계가 각각 얼마나 걸리는가?
- SM당 동시에 resident한 warp는 몇 개인가?
- CTA는 어떤 속도로 교체(turnover)되는가?
이 PR은 SGLang의 JIT 커널에 디버깅 전용 in-kernel tracer를 추가해 이 질문에 직접 답할 수 있게 합니다. 핵심 설계 원칙은 두 가지입니다. 첫째, 트레이싱이 꺼져 있으면 SASS에 흔적이 전혀 남지 않는다. 둘째, 백엔드를 두 개 둔다. NVIDIA의 IKET(Hopper 이상, closed source)와 어떤 아키텍처에서도 동작하는 %clock 기반 naive 백엔드입니다.
코드 분석
1. sgl_kernel/debug/trace.cuh — 매크로 API
커널 작성자는 다음처럼 사용합니다(문서 performance-cuda.md에서 인용).
#include <sgl_kernel/debug/trace.cuh>
SGL_TRACE_DECLARE_RANGE(load); // push / pop range
SGL_TRACE_DECLARE_SPAN(stage); // start / end, may cross loop iterations
SGL_TRACE_DECLARE_MARK(issued); // point event
__global__ void kernel(...) {
SGL_TRACE_KERNEL(); // naive: first statement (IKET: no-op)
{ SGL_TRACE_SCOPE(load); ... } // or SGL_TRACE_PUSH(load); ...; SGL_TRACE_POP();
if (elect_one_lane()) { SGL_TRACE_MARK(issued); ... }
SGL_TRACE_SYNC(); // naive: after marks made by some lanes only
}
Before에는 커널 내부 phase를 재려면 직접 clock64()를 박고 버퍼를 관리해야 했습니다. After에는 선언 + scope 매크로만으로 끝납니다. 중요한 점은 모든 매크로가 SGLANG_JIT_DEBUG_TRACE가 설정되지 않으면 빈 매크로라는 것입니다. 또한 이 환경변수가 빌드 캐시 키에 포함되어, 트레이싱 빌드와 일반 빌드가 섞이지 않습니다. PR의 검증 항목에도 "Tracing off: no clock reads, PMTRIG, REDUX or ELECT in the SASS"가 명시되어 있습니다.
이벤트 ID는 __COUNTER__로 생성되는데, 그래서 문서에 "declare every name right after the include"라는 규칙이 있습니다. tvm-ffi나 CCCL 헤더도 __COUNTER__를 쓰기 때문에 사이에 끼면 ID가 건너뛰어집니다. 작은 디테일이지만 매크로 기반 설계에서 흔히 놓치는 함정입니다.
naive 백엔드의 핵심 트릭: kernel-scope PTX register cursor
naive 모드에서는 warp별 cursor를 kernel-scope PTX register에 보관합니다. 각 lane이 cursor를 들고 있고, 모든 active lane이 cursor를 함께 증가시키되 elected lane 하나만 실제로 기록합니다. 이 덕분에:
- stack / local memory 사용 없음
- returning atomic 없음
- 이벤트당
STG.E.64한 번 (naive-debug는RED(G).E.ADD.64)
대가로 cursor는 warp-uniform이어야 합니다. divergent 영역에서는 한쪽 path만 mark해야 하고, reconverge 후 SGL_TRACE_SYNC()를 호출해야 합니다. 규칙을 어기면 레코드가 조용히 덮어써지므로 naive-debug가 fire-and-forget atomic으로 overwrite를 감지해 디코딩 시 보고합니다. "빠른 경로는 무검사, 검증용 경로는 별도 빌드"라는 전형적이고 좋은 패턴입니다.
2. python/sglang/kernels/jit/debug/trace.py — 호스트 측 수집기
IKET 백엔드는 run-iket wrapper 없이 libiket_injection.so의 C ABI를 ctypes로 직접 호출합니다.
class _Options(ctypes.Structure):
_fields_ = [
("struct_size", ctypes.c_uint32),
("flags", ctypes.c_uint32),
("max_ts_per_warp", ctypes.c_uint64),
...
("log_level", ctypes.c_uint32),
]
assert ctypes.sizeof(_Options) == 56
C 구조체 레이아웃을 Python에서 미러링할 때 sizeof assert로 ABI 불일치를 import 시점에 잡아내는 것은 훌륭한 방어 코드입니다. 세션 호출도 일관된 헬퍼로 감쌉니다.
def _check(self, name: str, *args) -> None:
fn = getattr(self._lib, f"IketProfilingSession{name}")
fn.restype = ctypes.c_uint32
status = fn(*args)
if status != 0:
raise RuntimeError(f"IketProfilingSession{name} failed with status {status}")
사용자 API는 백엔드와 무관하게 동일합니다.
with trace.capture() as cap:
op(x); torch.cuda.synchronize()
print(cap.trace.summary())
cap.trace.save_chrome_trace("t.json") # ui.perfetto.dev
summary()는 kernel span, SM당 resident warp, CTA turnover, range별 percentile을 출력하고, save_chrome_trace()로 Perfetto에서 타임라인을 볼 수 있습니다.
3. 리뷰를 통해 다듬어진 부분
리뷰어(BBuf Review Agent)가 두 가지 실질적 버그를 지적했습니다.
- 트레이싱 hook이 없는 모듈 등록 문제:
SGLANG_JIT_DEBUG_TRACE=naive에서add_constant같은 일반 JIT op도 등록되어,sgl_trace_set_configexport가 없으니capture()가 블록 진입 전에 실패했습니다. 수정 후register_naive_module은implements_function으로 해당 export가 있는 모듈만 등록합니다. - OOM 시 dangling device pointer: 뒤 모듈의 버퍼 할당이 실패하면 앞 모듈들은 이미 해제된 버퍼의 포인터를 가진 채 남고, 이후 launch가 재활용된 tensor storage에 쓸 수 있었습니다. 이는 디버깅 도구가 오히려 메모리 오염을 일으키는 최악의 시나리오입니다. 수정 후 버퍼 할당과 config 설치가
try안으로 들어가고,finally에서 synchronize 후 모든 설치된 모듈을 base 0으로 리셋한 다음에야 버퍼가 해제됩니다.
두 번째 지적은 "GPU에 넘긴 raw pointer의 수명은 Python GC와 별개"라는 점을 상기시키는 좋은 사례입니다.
왜 이게 좋은가
PR에 보고된 측정치:
| 항목 | 결과 |
|---|---|
| 빈 naive range 비용 | 29 cycles (sm_86, sm_100a), naive-debug 54 cycles |
| 정확도 검증 | dependent FFMA chain에서 iteration당 4.44 cycles, 두 GPU 일치 |
IKET overhead (GB300, per_token_group_quant_8bit_v2) |
lifetime-only baseline 대비 +0.5% (group 32) ~ +10% (group 128) |
| IKET per event | 4 instructions, load 시점에 IKET이 rewrite |
일반적 교훈:
- Zero-cost when off: 매크로를 빈 확장으로 만들고 캐시 키를 분리하면, 계측 코드를 넣어도 프로덕션 빌드에 영향이 없습니다. 그리고 이를 SASS 검사로 증명했습니다.
- 측정 도구 자체의 비용을 측정하라: 빈 range 비용, lifetime-only baseline 비교 등 perturbation을 정량화하는 방법을 문서화했습니다. 또한 "range around loads measures their issue"처럼 무엇을 재는지 명확히 합니다.
- 검증 모드 분리: 빠른 경로의 불변식(warp-uniform cursor)을 런타임에 검사하지 않고, 별도 debug 빌드에서 overwrite를 탐지합니다.
- 판정은 여전히 event timing: 문서가 강조하듯 트레이서는 '어디서 시간이 가는가'를 설명할 뿐, 빨라졌는지는 계측되지 않은 커널로 판단해야 합니다.
참고 자료
- PTX ISA: Special Registers %clock — naive 백엔드가 읽는 cycle 카운터
- PTX ISA: Special Registers %globaltimer — IKET 백엔드의 ns 타이머
- Python ctypes — libiket_injection.so C ABI 호출에 사용
- Perfetto UI — save_chrome_trace 출력 확인 도구
⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.
관련 포스트
PR Analysis 의 다른글
- 이전글 [sglang] gfx1250에서 RCCL을 넘어서다: ring_simple all-reduce와 unrolled 2shot_push 분석
- 현재글 : [sglang] 커널 내부를 들여다보는 법: SGLang JIT 커널에 IKET/%clock 기반 In-kernel 이벤트 트레이싱 도입
- 다음글 [sglang] SGLang Unified Memory 스케줄러의 Admission 호스트 작업 줄이기: 같은 질문은 한 번만 묻는다
댓글