우리는 Go PDF 라이브러리에 일련의 커스텀 정적 분석(Static Analysis) 체크(SlopGuard - WIP)를 실행했습니다. 그 결과 226개의 이슈가 발견되었고, 그중 218개가 실제 문제였습니다. 우리는 이 218개를 모두 수정했습니다.

우리가 무엇을 배웠는지, 실제 수정 전/후의 코드는 어떠했는지, 그리고 우리의 PDF가 얼마나 더 빨라졌는지에 대해 설명하겠습니다.

설정 (The Setup)

GoPDFSuit은 대량의 PDF 생성(인보이스, 보고서, 서명된 문서, 태그된 구조를 가진 표 중심의 PDF 등)에 최적화되어 있습니다. 초당 수천 개의 문서를 찍어낼 때는 매 마이크로초(microsecond)가 모여 큰 차이를 만듭니다.

우리는 몇 주 동안 프로파일링(Profiling)과 최적화(Optimization)를 진행해 왔습니다. 버퍼 풀링(Buffer pooling), 압축 파이프라인(Compression pipelines), 구조 트리 재작성(Structure tree rewrites) 등 쉬운 문제들은 이미 해결된 상태였습니다. 우리는 더 정밀한 작업이 필요했습니다.

이때 우리가 직접 만든 도구(코드명 SlopGuard)를 도입했습니다. 이 도구는 커스텀 분석기(Analyzers)를 사용하여 Go AST(Abstract Syntax Tree)를 스캔하고 알려진 성능 안티 패턴(Performance anti-patterns)을 찾아냅니다. 예를 들어 "루프 내부에서 정규식(Regex)을 컴파일하고 있습니다"라거나 "정적 문자열에 fmt.Sprintf를 호출했습니다. 대신 errors.New를 사용하세요"와 같은 사항들을 지적해 줍니다.

도구를 실행하자 프로젝트 전체에서 226개의 결과가 나왔습니다. 8개의 CWE 보안 전용 항목을 필터링한 후, 우리가 해결해야 할 실행 가능한 성능 이슈는 218개였습니다.

우리가 정확히 무엇을 발견했고, 어떻게 조치했는지 소개합니다.

루프 내부의 정규식 컴파일 (Regex Compilation Inside Loops) (20개 수정)

이것은 가장 쉽게 얻을 수 있는 성과였습니다. Go의 regexp.MustCompile은 비용이 많이 듭니다. 패턴을 파싱하고, NFA(Nondeterministic Finite Automaton)를 구축하며, 내부 상태를 할당합니다. 루프의 매 반복마다 이 작업을 수행하는 것은 매우 비효율적입니다.

수정 전. 멤버 루프의 매 반복마다 4개의 정규식이 컴파일되었습니다:

for i := range members {
    nameRe := regexp.MustCompile(`/T\s*(?:\(([^)]*)\)|<([0-9A-Fa-f\s]+)>)`)
    if nameMatch := nameRe.FindSubmatch(objContent); nameMatch != nil {
...

수정 후. 루프가 시작되기 전에 4개 모두 한 번만 컴파일됩니다:

nameRe := regexp.MustCompile(`/T\s*(?:\(([^)]*)\)|<([0-9A-Fa-f\s]+)>)`)
kidsRe := regexp.MustCompile(`/Kids\s*\[(.*?)\]`)
refRe := regexp.MustCompile(`(\d+)\s+(\d+)\s+R`)
...

우리는 xfdf.go, merge.go, 그리고 helpers.go 전반에 걸쳐 약 20곳에서 이 패턴을 발견했습니다. 일부는 프로세스 수명 동안 정확히 한 번만 컴파일되도록 패키지 수준 변수(package-level vars)로 이동되었습니다.

fmt.Sprintf를 strconv.AppendInt로 교체 (50개 이상의 수정 사항)

이 부분은 우리를 놀라게 했습니다. fmt.Sprintf가 공짜가 아니라는 점은 알고 있었지만, 얼마나 많은 핫 패스(hot paths)가 그 비용을 지불하고 있는지는 깨닫지 못했습니다. fmt.Sprintf를 호출할 때마다 인자들을 interface{}로 박싱(boxing)하고, 힙(heap)에 새로운 문자열을 할당하며, 리플렉션(reflection)을 사용하여 포매터(formatter)를 실행합니다.

해결 방법은 스택에 할당된 스크래치 버퍼(scratch buffer)와 strconv.AppendInt를 사용하여 fmt.Sprintf의 리플렉션 오버헤드를 피하는 것입니다.

이전. 루프 내의 폰트 참조 문자열:

font.CachedRef = fmt.Sprintf("/CF%d", font.ObjectID)

이후. AppendInt를 사용하는 12바이트 스택 버퍼가 직접 작성함:

var refBuf [12]byte
font.CachedRef = "/CF" + string(strconv.AppendInt(refBuf[:0], int64(font.ObjectID), 10))

이 방식도 여전히 할당을 발생시킵니다. Go의 []byte에서 string()으로의 변환은 불변성(immutability)을 보장하기 위해 데이터를 복사하며, + 연결 연산이 두 번째 문자열을 생성하기 때문입니다. 하지만 이는 fmt.Sprintf의 리플렉션 기반 박싱 및 포매팅을 빠른 스택 버퍼 쓰기 및 복사로 교체하는 것입니다. 핫 패스에서는 감소된 CPU 비용이 할당 비용보다 더 크며, 이 패턴은 컴파일러가 인라인(inline)화하고 최적화할 수 있을 만큼 충분히 일관적입니다.

우리는 핸들러(handlers), 제너레이터(generators), 아웃라인(outlines), secure.go, 그리고 sampledata 전반에 걸쳐 이 패턴을 약 50번 적용했습니다. 성능 영향은 누적됩니다. 각 수정 사항은 미미하지만, 핫 패스에서 50개의 fmt.Sprintf 호출을 제거하면 그 결과는 나중에 큰 차이로 나타납니다.

strconv.Itoa에서 strconv.AppendInt로 전환 (30개 이상의 수정 사항)

이것은 이전 수정 사항의 형제 격인 방법입니다. strconv.Itoa는 정수로부터 문자열 값을 생성합니다. 성능이 중요한 빌더(builders) 내에서는 문자열을 빌더의 버퍼로 복사해야 하므로 할당 압박(allocation pressure)을 가중시킵니다. 반면 strconv.AppendInt는 기존 바이트 슬라이스(byte slice)에 직접 작성하므로, 스택 버퍼를 재사용하고 중간 문자열 생성을 완전히 피할 수 있습니다.

이전. 폰트 메트릭(font metrics)을 위한 widths 배열 생성:

var widthsArray strings.Builder
for i, w := range metrics.Widths {
    if i > 0 {
...

이후. 재사용 가능한 [16]byte 스크래치 버퍼(scratch buffer)와 AppendInt 사용:

var widthsArray strings.Builder
var widthBuf [16]byte
for i, w := range metrics.Widths {
...

차이점은 미묘합니다. 첫 번째 버전은 매 반복(iteration)마다 중간 문자열(intermediate string)을 생성하며, 이는 탈출 분석(escape behavior)에 따라 할당 압박(allocation pressure)을 가중시킬 수 있습니다. 두 번째 버전은 스택에 할당된 스크래치 버퍼를 통해 builder에 직접 작성합니다. 변환 자체로 인한 반복당 할당은 발생하지 않습니다. builder는 여전히 필요에 따라 내부 버퍼를 확장하지만, 해당 확장은 루프 전체에 걸쳐 분할 amortized 됩니다.

폰트 레지스트리 핫 패스(Hot Path)에서 defer 제거 (13개 수정 사항)

이 부분은 팀 내부에서도 논쟁이 있었습니다. defer는 우아합니다. 인접한 줄에서 잠금(lock)과 잠금 해제(unlock)를 쌍으로 묶어주기 때문입니다. 잠금 해제를 잊어버릴 일이 없습니다. 하지만 우리가 사용하던 조건부 defer 패턴에는 숨겨진 비용이 있었습니다. defer가 if 블록 내부에 배치되면, Go 컴파일러가 (Go 1.14에서 도입된) 오픈 코디드 defer 최적화(open-coded defer optimization)를 적용할 수 없습니다. 대신 매 호출마다 더 느린 런타임 힙 할당 defer 프레임(defer frame)으로 회귀하게 됩니다. 시간당 수백만 번 호출되는 함수에서 이러한 할당 비용(allocation tax)은 빠르게 누적됩니다.

폰트 레지스트리는 모든 문서의 모든 테이블 내 모든 셀에서 호출됩니다. registry.go의 13개 함수가 뮤텍스(mutex) 잠금 해제를 위해 defer를 사용하고 있었습니다. 이전 패턴은 조건부 defer를 사용했는데, 이는 알려진 위험 요소입니다. 동일한 파일 내에서 조건부 잠금과 수동 잠금 해제를 혼용하는 것은 취약하며, 누군가 새로운 반환 경로(return path)를 추가할 경우 데드락(deadlock)을 유발할 수 있습니다.

이전:

func (r *CustomFontRegistry) HasFont(name string) bool {
    if !r.noLock {
        r.mu.RLock()
...

이후:

func (r *CustomFontRegistry) HasFont(name string) bool {
    if !r.noLock {
        r.mu.RLock()
...

GenerateSubsets 함수는 훨씬 더 까다로운 사례를 가지고 있었습니다. 루프 내부의 모든 조기 반환(early return) 경로에서 잠금을 해제해야 했습니다:

func (r *CustomFontRegistry) GenerateSubsets() error {
    r.mu.Lock()
    for name, font := range r.fonts {
...

트레이드오프(tradeoff)는 실재합니다. 조건부 defer를 제거하면 컴파일러가 런타임에 할당된 defer 프레임(defer frames)으로 폴백(fallback)하는 것을 방지할 수 있지만, 코드는 이제 더 취약해졌습니다. 새로운 반환 경로에서 잠금 해제(unlock)를 하나라도 누락하면 데드락(deadlock)이 발생합니다. 우리는 이 코드 경로가 시간당 수백만 번 실행되기 때문에 처리량(throughput) 이득이 그만한 가치가 있다고 판단하여 이 위험을 수용했습니다.

불필요한 string/[]byte 변환 제거 (40개 이상의 수정 사항)

Go는 string과 []byte 사이의 변환을 매우 쉽게 만들어 줍니다. 너무 쉬워서 할당(allocation)이 일어난다는 사실조차 인지하지 못하게 될 정도입니다. 모든 []byte(myString)은 문자열 데이터를 힙(heap)에 할당된 새로운 바이트 슬라이스(byte slice)로 복사합니다.

우리는 핫 패스(hot paths)에서 이러한 사례를 약 40개 정도 발견했습니다. 가장 창의적인 해결책은 unsafe.Slice를 사용하여 제로 카피(zero-copy) 변환을 구현하는 것이었습니다.

이전. 비밀번호 패딩(padding) 시 복사본을 할당합니다:

func padPassword(password string) []byte {
    pwd := []byte(password)
    if len(pwd) >= 32 {
...

이후. unsafe.Slice를 사용하여 복사를 완전히 피합니다 (문자열 인자가 항상 안정적인 메모리에 의해 뒷받침되므로 여기서는 안전합니다):

func padPassword(password string) []byte {
    if len(password) >= 32 {
        return unsafe.Slice(unsafe.StringData(password), 32)
...

경고: unsafe.Slice(unsafe.StringData(s), n)은 원본 문자열과 메모리를 공유하는 []byte를 생성합니다. 이는 문자열이 반환된 슬라이스보다 오래 유지되고, 슬라이스가 절대 변이(mutate)되지 않을 때만 안전합니다. padPassword에서는 반환된 바이트 슬라이스가 암호화를 위해 일시적으로 사용된 후 폐기되므로, 여기서는 이러한 트레이드오프가 안전합니다. 반환된 슬라이스보다 수명이 짧은 문자열에는 이 패턴을 사용하지 마십시오. 또한 메모리 모델(memory model)의 영향을 완전히 이해하지 못했다면 결과로 생성된 바이트 슬라이스에 값을 쓰지 마십시오.

또한 하위 바이트(underlying bytes)에 대한 제로 카피(zero-copy) 액세스가 필요한 곳에서는 strings.Builder 대신 bytes.Buffer로 전환하였으며, 정규식 ReplaceAllFunc 콜백 내부의 fmt.Sprintf를 직접적인 바이트 슬라이스 생성(direct byte slice construction)으로 교체했습니다.

논블로킹 로깅 (Non-Blocking Logging)

Go의 표준 log 패키지는 내부적으로 뮤텍스(mutex)를 보유하고 있습니다. 모든 log.Printf 호출은 이 뮤텍스를 획득합니다. 초당 수천 개의 요청을 처리하는 요청 경로(request path)에서는 해당 뮤텍스가 경합 지점(contention point)이 됩니다.

이전. 서버 고루틴(goroutine)에서의 log.Fatalf:

go func() {
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatalf("listen: %s\n", err)
...

이후. stderr로 직접 쓰기:

go func() {
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        fmt.Fprintf(os.Stderr, "listen: %s\n", err)
...

마찬가지로, gin.Recovery 래퍼(wrapper)를 gin.CustomRecovery로 교체하여 패닉 처리(panic handling)를 중앙 집중화하고, 요청마다 별도로 적용하던 defer 래퍼를 제거했습니다.

비용이 큰 작업 전의 저렴한 가드 (Cheap Guards Before Expensive Operations)

strings.TrimSpace는 트리밍(trimming)이 필요하지 않을 때 원본의 서브 슬라이스(sub-slice)를 반환하지만, 핫 루프(hot loop) 내에서 반복적으로 호출되면 여전히 스캐닝 오버헤드(scanning overhead)가 발생합니다. bytes.Equal은 내부적으로 길이를 먼저 확인하지만, 길이 가드(length guard)를 사용하면 의도가 명확해지며 길이가 다를 경우 호출 자체를 완전히 건너뛸 수 있습니다. 대부분의 입력값이 트리밍을 필요로 하지 않거나 크기가 눈에 띄게 다를 경우, 두 방식 모두 가드를 적용할 가치가 있습니다.

이전:

if !ok || !bytes.Equal(origBody, body) {

이후:

if !ok || len(origBody) != len(body) || !bytes.Equal(origBody, body) {

길이 확인은 $O(1)$입니다. bytes.Equal은 $O(n)$입니다. 가드는 길이가 다를 때 비용이 큰 호출을 단락 평가(short-circuit)합니다.

TrimSpace에 대해서도 동일한 아이디어를 적용했습니다. 무작정 트리밍하는 대신, 먼저 첫 번째와 마지막 바이트를 확인합니다:

mode := strings.ToLower(opts.Mode)
if len(mode) > 0 && (mode[0] == ' ' || mode[len(mode)-1] == ' ') {
    mode = strings.TrimSpace(mode)
...

그리고 렌더러(renderer)에서는 TrimSpace를 바이트를 수동으로 스캔하는 제로 할당(zero-allocation) isSpace 헬퍼 함수로 교체했습니다:

func isSpace(s string) bool {
    for i := 0; i < len(s); i++ {
        if s[i] != ' ' && s[i] != '\t' && s[i] != '\n' && s[i] != '\r' {
...

마이크로 최적화(Micro-Optimizations)보다 우선하는 알고리즘 호이스팅(Algorithmic Hoisting)

모든 SlopGuard 수정 사항이 한 줄짜리 코드는 아니었습니다. internal/pdf/redact/ocr_adapter.go에서 P6-26을 찾아냈을 때는, 단어별 OCR 검색의 매 반복마다 strings.ToLower와 strings.TrimSpace를 호출하는 중첩 루프(nested loop)가 탐지되었습니다. 해결 방법은 두 정규화(normalization) 작업을 루프 외부로 완전히 호이스팅(hoisting)하는 것이었습니다.

수정 전. 매 비교마다 각 쿼리(query)와 각 OCR 단어가 소문자로 변환되고 공백이 제거되었습니다:

for _, query := range queries {
    query = strings.ToLower(strings.TrimSpace(query))
    for _, word := range ocrWords {
...

수정 후. 루프가 시작되기 전에 모든 정규화가 한 번 수행됩니다:

for i, query := range queries {
    queries[i] = strings.ToLower(strings.TrimSpace(query))
}
...

이를 통해 핫 패스(hot path)의 할당량이 $O(N \times M)$에서 $O(N + M)$으로 변경되었습니다. 중첩 루프 밖으로 작업을 꺼내는 이러한 구조적 변경은, 이 코드 경로에서 단일 AppendInt 교체보다 더 큰 이득을 가져다주었습니다.

맵 사전 크기 지정 (Map Pre-Sizing)

Go의 맵(map)은 부하 계수(load factor)에 도달하면 크기를 두 배로 늘리며 확장됩니다. 확장이 일어날 때마다 모든 엔트리를 재해싱(rehash)하고 새로운 백킹 어레이(backing array)를 할당합니다. 대략적인 크기를 알고 있다면 용량 힌트(capacity hint)를 추가하여 이를 방지할 수 있습니다.

수정 전:

font.UsedChars = make(map[rune]bool)

수정 후:

font.UsedChars = make(map[rune]bool, 256)

수정 전:

objMap := make(map[int][]byte)

수정 후:

objMap := make(map[int][]byte, len(objMatches))

이것들은 아주 작은 변화입니다. 하지만 맵이 핫 루프(hot loop) 내부에 존재하고 안정화되기 전까지 10배로 확장된다면, 절약되는 비용은 상당해집니다.

정적 fmt.Errorf를 errors.New로 교체

fmt.Errorf는 포맷팅 동사(format verbs)가 없을 때도 문자열을 포맷팅합니다. 반면 errors.New는 정적 문자열을 단순히 감싸기만 합니다. 호출당 차이는 미미하지만, 이러한 호출은 종종 루프(loop) 내부에 있는 에러 경로(error paths)에서 발생합니다.

이전:

return fmt.Errorf("no successful runs")

이후:

return errors.New("no successful runs")

strings.Split을 strings.Cut 또는 bytes.Split으로 교체

strings.Split은 문자열 슬라이스(slice of strings)를 할당합니다. strings.Cut은 할당(allocation) 없이 두 개의 문자열을 반환합니다. 미리 할당된 버퍼(preallocated buffers)로 bytes.Split을 사용하면 문자열 할당을 완전히 피할 수 있습니다.

SVG 스타일 파싱의 경우:

이전:

styleParts := strings.Split(style, ";")
for _, part := range styleParts {
    kv := strings.SplitN(part, ":", 2)
...

이후:

styleParts := strings.SplitSeq(style, ";")
for part := range styleParts {
    part = strings.TrimSpace(part)
...