예를 들어 100KB 를 저장하는 페이지에 위와 같이 데이터를 저장한 상태이다. 여기서 데이터 40KB 짜리를 하나 더 넣으면 어떻게 될까? 물리적인 한계로 이 페이지에는 아마 저장할 수 없을 것이다. 그렇다면 어떻게 동작해야 할까?

Page Split

일단 페이지를 분할(Page Split) 하는 방법이 있다. 물리적인 페이지가 가득차게 되면 HDD 나 SDD 로부터 새로운 페이지를 할당 받아 데이터의 절반을 이주 시킵니다.

여기서 넘치는 것만 이주시키는 것이 아니라 반반해서 이주시키는 이유는 만약 Page 1 에 데이터가 또다시 들어오게 되는 경우 빈번하게 Page Split 이 일어날 확률이 높기 때문입니다.

예를 들어 40KB 를 또 삽입시켰다고 해봅시다. 이제 새로운 Page2 가 생기고 기존 Page 1 에서 5:5 로 나눠진 #2 가 Page 2 로 오게 됩니다. 즉 Page 1 에서 다음 데이터를 받기 위한 여유 공간들이 생기게 됩니다. 그리고 삭제/업데이트 등등이 되면서 더더욱 단편화가 많이 일어날 수도 있겠죠?

그렇기 때문에 인덱스를 리빌드 하는 과정이 필요합니다. 리빌드를 하게되면 어느정도 단편화가 해소됩니다. 만약에 너무 큰 데이터가 오면 어떻게 될까요? 예를 들면 95KB 같은 데이터가 들어오게 되는 경우 입니다. 그 경우에는 페이지에 하나의 원소밖에 저장되지 않게 되고, 이는 B-Tree 내부 페이지의 성능을 악화시키게 됩니다.

그래서 대부분의 데이터 베이스에서는 max_payload_size 이하인 것들을 페이지 내부에 저장하고 max_payload_size 를 초과하는 데이터의 경우에는 Overflow Page 에 저장하게 됩니다.

오버 플로우 페이지(Overflow Page)

너무 큰 데이터가 들어오면 위와 같이 페이지를 망가트리는 경우가 있게 될 수 있으므로 Linked List 를 통해서 원본 Page(Primary Page) 에서 link 를 통해 Overflow Page 로 갈수 있도록 연결시켜 둡니다. 이렇게 함으로써 페이지에는 최대한 정렬된 순서로 많은 원소가 들어갈 수 있게 됩니다.

마치며

결과적으로 메인 페이지(Primary Page)를 가볍게 유지하면, 하나의 페이지에 들어갈 수 있는 인덱스 키(Key)의 개수(Fanout)를 최대로 확보할 수 있습니다. 이는 거대한 데이터가 들어오더라도 B-Tree의 전체 트리 깊이(Tree Depth)가 깊어지는 것을 방지하며, 데이터베이스 검색 성능의 핵심인 '디스크 I/O 횟수'를 최소화하는 결정적인 역할을 합니다.

결론적으로 B-Tree는 데이터가 점진적으로 늘어나는 일반적인 상황은 **'페이지 분할(Page Split)'**을 통해 트리의 균형을 맞추며 확장하고, 트리의 구조 자체를 위협하는 비정상적으로 큰 데이터는 '오버플로우 페이지(Overflow Page)'로 격리하는 투트랙(Two-track) 전략을 통해 빠르고 안정적인 검색 성능을 유지한다고 볼 수 있습니다

이 글에서 corpus 라는 용어를 많이 쓰게 될텐데 이글 내부에서는 우리가 가지고 있는 문서의 콜렉션으로 해석하면 된다.

* 이 글에서 용어(Term) 의 단위는 공백(뛰어쓰기) 기준으로 나눈다. 실제로는 사용하는 Tokenizer 에 따라 계산이 다르게 될 수 있다.

TF(Term Frequency)

TF 는 용어 그대로 문서(Document) 에 나타나는 단어의 빈도수를 의미한다. 기호로는 TF(t, d) 로 표기한다. 간단하게 t(Term) 이 얼마나 d(Document) 에 많이 등장하는가를 나타내는 함수이다.

TF(t, d) = t 가 d 에서 나타나는 빈도수 / d 의 모든 용어 수

아주 간단하게 위와 같이 계산된다. TF 의 분자값은 t 의 빈도수에 영향을 받고, 분모값은 용어의 총 개수의 영향을 받는다. 즉, 단어가 document 에서 많이 등장할수록 점수가 비례하여 높아지는 것이다.

파이썬 코드로 작성하면 아마 아래와 같이 작성해볼수 있을 것이다.

def tf(t: str, d: Document) -> float:
    tokens = d.text.split()
    frequency = tokens.count(t)
    return frequency / len(tokens)

아주 심플하다. 그런데 코드를 작성하다보니 아래와 같은 의문이 든다.

왜 분모에 d 의 모든 용어 수 라는 부분이 있을까? 그냥 단순하게 빈도수만 보면 안되나?

이렇게 분모에 단어수와 같은 제약을 두는 이유는 아래와 같다. 만약에 아래와 같은 문서 두개가 있다고 해보자.

• 문서 A : 사과 농장에서 자라는 사과는 정말 맛있어요.

• 문서 B : 사과하고 싶지만 영수는 사과를 할수 없었고, .... (1000 단어 가량의 문서 길이)

두 문서를 봤을때 "사과" 라고 검색한다고 하면 문서 A 는 TF(2, 6) 으로 나오고 문서 B 는 생략된 부분에 사과가 한개 더 등장해서 TF(3, 1000) 이 되었다고 해보자. 만약 빈도수만 본다면 문서 B 가 나오는 것이 정상이다.

하지만 빈도수가 높기만 한걸로 측정한다면 해당 용어가 그 문서내에서 얼마나 중요한 단어인지는 판단할수가 없다. A 문서에서는 6개의 단어중 2개인 1/3 이 "사과" 이므로 1000개 중에 3번 나오는 문서 B 에 비해 더 "사과" 가 중요한 비중을 차지하고 있다고 해석해볼 수 있다. 이것이 TF 의 분모에 문서 내에서 용어의 총 개수가 존재하는 이유이다.

IDF(Inverse Document Frequency)

IDF 는 흔한 단어는 가중치를 낮추고, corpus 내부에서 빈도수가 낮은 단어의 가중치를 올려주는 역할이다. 영어 문서를 예로 들자면 "the", "a" 와 같은 관사들은 주로 등장하므로 가중치가 낮아지고, "API" 와 같은 단어들은 개발문서에만 등장하므로 상대적으로 가중치가 높아진다. 가중치를 낮춰야 하므로 역함수의 형태를 뛰어 이번엔 아래와 같이 빈도수가 분모로 가게 된다.

IDF(t, D) = log (corpus 내부의 문서 개수 / t 를 포함하는 문서의 개수)

log 를 씌우는 이유는 스케일을 완만하게 만들기 때문이다. 직관적으로 와닿지 않을 수 있으니 아래와 같은 예시가 있다고 해보자.

• the => 1000개의 문서 집합에서 1000번 등장 N / DF = 1

• quantum => 1000개의 문서 집합에서 1번 등장 N / df = 1000

위의 문서 셋에서 quantum 은 1000배나 중요하다고 판단된다. 즉, 과대평가가 되어 검색어의 결과의 하한(threshold) 를 설정하는데 문제가 될수도 있다. 그래서 log 를 씌우게 되면 quantum 의 중요도는 6.9가 되어 스케일이 줄어들게 된다.

AI 와 대화해보니 정보이론적 근거가 있다고 하긴 하는데.. 그 부분은 내 분야가 아니므로 한번 궁금하면 공부해보길 바란다. 아마 엔트로피 개념과 연관되어 있지 않을까 싶다.

IDF 는 파이썬으로 코드를 작성해보면 아래와 같이 작성해볼 수 있을 것이다.

def idf(t: str, corpus: list[Document]) -> float:
    n = len(corpus)
    df = sum(1 for doc in corpus if t in doc.text.split())
    return math.log(n / df)

아직까지는 이해하기 쉽다. 이제 이 둘을 섞은 TF-IDF 에 대해서 알아보자.

TF-IDF

TF-IDF 는 더 단순하다 TF * IDF 를 한것이다. 실제로 아래 수식처럼 그냥 곱하기를 하면 된다.

TF-IDF(t, d, D) = TF(t, d) * IDF(t, D)

일단 이 수식이 뭔지 이해하기 전에 TF 와 IDF 를 한번만 더 짚고 넘어가보자.

• TF: 이 용어(Term) 이 문서(d) 내부에서 얼마나 자주 등장하는가?

• IDF: 이 용어가 corpus 내부에서 얼마나 희귀한가?

이 둘을 곱한 것이므로 빈도수가 높지만 흔한 단어(the 와 같은) 들은 IDF 점수가 낮으므로 상대적으로 낮은 점수를 받게 될 수 있고, 빈도수가 낮지만 희귀한 단어들은 IDF 점수가 높으므로 상대적으로 높은 점수를 받을 수 있게 된다.

즉, corpus 내부에서 내가 검색하려는 용어(t) 에 대해 중요도와 빈도수를 어느정도 조합하여 검색하는 것이라 보면 된다. 하지만 위의 수식을 보면 알듯이 TF(t, d) 가 압도적으로 높다면 아무리 희귀하지 않다고 해도 점수가 높게 측정될 수도 있다.

이렇게 되면 상관없는 문서들이 나오게 될 수 있으므로 별도의 가중치를 두어야 하나? 아니면 상한(maximum threshold) 를 두어서 막아야 하나? 등의 고민을 해볼만 하다. 하지만 이런 방법론을 연구하고 실험하는 것 또한 어렵다. 이를 해결하기 위한 유명한 솔루션은 BM25 라는 방식을 이용하는 거라고 한다.

BM25

BM25 의 수식은 위와 같다. 엄청 복잡해 보이지만 복잡하게 적은 것일 뿐 하나하나 뜯어보면 그렇게 어렵지는 않다.

여기서 대부분은 우리가 이해할 수 있지만 k_1 은 새롭게 보는 개념이다. 이는 포화를 위한 계수인데 보통 1.2 ~ 2.0 사이의 값을 채택한다고 한다.

K1 (term frequency saturation)

score = (k_1 + 1) * tf / (k_1 + tf)

위와 같은 수식일때 tf 가 커지면 커질수록 분자/분모가 모두 커지므로 일정값에 수렴하게 된다. 예를 들어, k_1 이 1 이라고 해보면 아래와 같은 tf 값을 대입해가며 나오는 값을 확인해볼 수 있다.

  tf = 1  →  2·1/(1+1) = 1.00
  tf = 2  →  2·2/(2+1) = 1.33  (+0.33)
  tf = 3  →  2·3/(3+1) = 1.50  (+0.17)
  tf = 5  →  2·5/(5+1) = 1.67  (+0.17 for 2 steps)
  tf = 100 → 2·100/101 = 1.98  (+0.31 for 95 steps)

위의 결과를 보면 1 -> 2 로 갈때는 0.33 이나 늘었지만 5 -> 100 일때는 0.31 밖에 오르지 않았다. 즉, 분자가 아무리 커져도 분모도 커지므로 점점 영향력이 약해지는 것이다. 즉, k_1 의 값이 높아지면 높아질수록 느리게 포화되고 상한선 또한 높아진다.

그래프로 동일한 corpus 에서 k_1 = 1.0 일때와 k_1 = 3.0 일때를 그래프로 비교해보자.

위 그래프를 보면 k_1 이 3.0 일때 점수자체가 좀 더 높은것을 알수 있고 일정스코어 이상에 수렴하기 까지 걸리는 시간도 오래걸림을 알 수 있다. 조금 더 해석을 해보자면 TF 점수를 얼마나 믿을 것 인가? 로도 해석해 볼 수 있다.

b (length normalization parameter)

b 또한 가중치인데요. 여기서는 (1 - b + b * |d|/avgdl) 에만 집중하면 조금 더 쉽게 이해할 수 있습니다. 일단 |D| * avgdl 을 먼져 해석해보면 이 문서가 평균적으로 얼마나 긴가? 를 나타내는 값으로 볼 수 있습니다. 이 값이 분모에 있으므로 문서가 길면 길수록 점수가 낮아지는 구조가 됩니다. 즉, 문서가 길면 어떤 단어가 나올 확률도 높다고 생각해서 정규화를 해준다고 생각하면 됩니다.

그러면 수식을 쉽게 이해하기 위해 b 가 0 일때를 가정해보겠습니다. b 가 0 이면 1 - 0 + 0 * |d|/avgdl 이 되므로 사실상 문서 문서길이에 대한 패널티를 안보겠다는 것과 같습니다. 반대로 1일때는 어떨까요? 1 - 1 + 1 * |d|/avgdl 이 되므로 "문서 길이에 대한 패널티만 적용하겠다" 와 같습니다. 즉, 1 에 가까우면 가까울수록 문서 길이에 비례한 점수 페널티가 커집니다.

이것도 그래프로 한번 살펴보도록 하겠습니다.

b 가 0 일때는 |d|/avgdl 에 대한 패널티가 없는 상태입니다. 따라서 x 축의 값인 |d| / avgdl 이 올라가도 그래프가 변하지 않습니다.

b 가 1 일때는 |d| / avgdl 이 커지면 커질수록 우하향 하는 모습을 확인할 수 있습니다. 즉, 분모의 값이 커지므로 점수가 빠르게 내려가는 것을 확인할 수 있습니다.

정리

BM25 수식쪽에와서 살짝 복잡해진 부분은 있지만 하나하나 뜯어봤을때 아래와 같은 부분들을 커버한다고 이해하면 될 것 같습니다.

• TF saturation 은 TF 일정 단어가 반복되는 스팸문서에 대한 페널티를 적용합니다.

• Length Normalization 은 긴 문서일수록 분모가 커져서 점수를 깎아 긴 문서에 대한 보정을 적용합니다.

• IDF 희귀한 단어일수록 가중치를 줍니다

Openclaw 나 LLM 메모리에도 적용해 볼수 있을까? 근데 대화내에서 문서를 어떤 단위로 잡아야 할지.. 뭐 이런것들이 고민이라 쉽지 않을것 같다.

최근에 LinkedIn 이나 여러 소셜 플랫폼들의 글을 보면 AI native 회사 라는 워딩들이 많이 보입니다. IBM 의 정의에 따르면 AI native 를 아래와 같이 정의한다고 하는데요.

“AI를 사고와 업무 방식에 끊임없이 내재화하는 상태”

그렇다면 팀원들이 계속해서 AI 를 사고와 업무 방식에 끊임 없이 내재화 하려면 어떻게 해야할까요? 개발자들은 이미 Claude code 나 Codex 등 여러 AI Tool 들을 사용하는데 익숙하지만 대부분의 비개발자 직군의 사람들은 별도로 공부를 하지 않는다면 사용하는 사람들을 찾기 어렵습니다. 또한 금전적인 문제 또한 이 분야에 가장 큰 이슈이기도 하기 때문입니다.

이러한 생각을 하다 사내에서 비개발자 직군분들이 Claude code 를 알려주면 잘 쓸수 있을까? 라는 고민을 하기 시작했고, 이를 기반으로 Claude code 를 어떻게 사용해야 하는지에 대한 아래처럼 장표를 만들고 이를 공유하는 자리를 가지게 되었습니다.

Workflow 로서의 Claude code

세션 진행간 Terminal 보다는 GUI 기반의 Google Antigravity 를 통해 Claude code 를 이용하도록 했고, Context 와 SKILL 의 개념 그리고 워크플로우에 어떻게 적용해야 하는지 등등을 공유했습니다.

세션에서 가장 중요하게 공유했던 부분은 SKILL 에 관한 부분인데요. 이 SKILL 을 가장 중요하게 생각하는 이유는 개인이 특정한 Task 를 수행할 때 수행하는 일련의 작업이나 지식들을 담는 곳 이기 때문입니다. claude code 와 같은 도구들은 이미 많이 SOTA 모델을 잘 오케스트레이션하여 사용하여 이미 똑똑하지만 학습되지 않은 연속적인 작업들을 수행하는데는 어려움을 겪으므로 SKILL 을 통해 지식을 전수해줘야 하기 때문입니다.

그래서 SKILL 의 예시로 세션에서 playwright 를 통해 브라우저 자동화를 하는 방법에 대해 공유하였는데 이후에 어드민의 일부 작업들을 playwright 를 통해 자동화 하기 시작했다고 말씀해주셨습니다. 자동화 해준 이야기들을 듣다보니 계속해서 아래와 같은 고민이 들기 시작했습니다.

우리가 기존에 운영하던 내부 어드민은 정말 HTML 로 계속해서 유지되어야 하나?

사실 특정 작업들을 AI 도구들이 쉽게 작업하도록 도와주기 위해서는 “기존의 사람 친화적인 interface 보다는 LLM Model 에 친화적인 Interface 가 낫지않을까?” 라는 생각이 들었습니다. 기존 HTML 형식의 GUI 는 사람에게 정보를 정리해서 가독성이 좋게 전달하기 위한 수단인데, 사실 LLM 에게는 그것보단 구조화된 JSON, YAML 등의 형태가 더 이해하기 쉬울수도 있겠다 라는 생각이 들었습니다.

그래서 AI 가 필요한 정보나 액션만 취할 수 있는 도구를 쥐어준다는 느낌으로 mcp 로 제공해주면 어떨까? 라는 생각이 들었습니다. 그래서 mcp 로 어드민에서 사람에게 보여주던 정보들을 기존의 API 를 통해 이용할 수 있도록 내부에 배포하여 이용할수 있도록 하였더니 꽤나 이것들을 이용해서 이것저것 많이 시도해보시는 느낌을 받았습니다.

이러한 현상을 보면서 AI native 로 변해간다는건 조직원들이 AI Tool 에 대해 익숙해지고 더 많이 사용하게 되고, 원래 사람위주의 Interface 들이 점차 AI native 하게 정말 구조적인 정보 또는 액션만 제공하는 구조로 워크플로우 자체가 변해가는 것이구나 라는 생각이 들었습니다. 위 작업을 하면서 기존에는 크게 잘 사용하지 않던 mcp 에 대한 시각도 많이 바뀌게 된거 같습니다.

마치며

아직은 AI 초기라 잘 모르겠지만 이후에는 모두가 Claude code 와 같은 에이전트 형태의 커스터마이징이 가능한 Tool 을 이용하게 될 것이고 이제 항상 반복되던 Admin 작업들은 LLM 성능이 좋아지면 좋아질수록, 잘 관리된 도메인 지식인 SKILL 과 내부 데이터 및 액션에 대한 도구를 제공해주는 mcp 로 자동화 하는 방식으로 발전해나갈 것이라는 생각이 들었습니다.

개인적으로 비개발자 분들이 여러 업무에 자동화를 하는 것을 보면서 제 개인적으로도 인싸이트를 많이 얻었던 것 같습니다. Mixpanel 의 로그를 분석한다거나, 동영상 편집에 이용한다거나 등등. 이 글을 읽으시는 개발자 분들도 일상생활을 자동화 하기위해 클로드 코드를 많이 이용해보시길 바랍니다.

프로그래밍을 공부하다보면 위 두 단어를 반드시 마주하게 된다. 가끔 헷갈려하는 경우가 많은데 오늘은 python 에서 기본 모듈인 ast 모듈을 공부하며 이를 알아보도록 하자.

식(Expression)

기본적으로 식(Expression) 이란 평가되면 값이 나오는 코드 조각을 뜻한다. 파이썬에서는 어떠한 부분들이 있을까?

바로 위와 같은 코드 조각들이 존재한다. 특징 들을 보면 1 + 2 를 실행시키면 바로 3 이라는 값이 나오듯. 코드 조각들이 평가되는 순간에 바로 **값(valude)**이 나오게 된다. 이를 한번 ast 모듈을 통하여 파싱해보자.

ast 모듈의 parse 함수에는 mode 라는 값이 존재하는데, eval 로 하게 되면 단일 표현식만 파싱이 가능하다

expressions = {
    'BinOp': '1 + 2',
    'UnaryOp': '-x',
    'BoolOp': 'a and b',
    'Compare': 'x > 0',
    'Call': 'print("hello")',
    'Name': 'x',
    'Constant': '42',
    'Attribute': 'obj.method',
    'Subscript': 'lst[0]',
}

for expr_type, code in expressions.items():
    print(f"\n{'='*40}")
    print(f"{expr_type}: {code}")
    print(f"{'='*40}")
    tree = ast.parse(code, mode='eval')  # 표현식 모드로 파싱
    print(ast.dump(tree, indent=2))

이를 파싱하면 아래와 같은 출력값이 나온다.

========================================
BinOp: 1 + 2
========================================
Expression(
  body=BinOp(
    left=Constant(value=1),
    op=Add(),
    right=Constant(value=2)))

========================================
UnaryOp: -x
========================================
Expression(
  body=UnaryOp(
    op=USub(),
    operand=Name(id='x', ctx=Load())))

(생략...)

보면 전부 Expression 이라는 큰 그룹으로 묶여 있음을 알 수 있다. 즉, AST 가 이 코드 조각들을 식으로 인식하고 있음을 알 수 있다. 이제 대략적으로 식(Expression) 에 대한 감은 왔을 것이다. 그렇다면 문장은 또 어떤 것이 있을까? 한번 알아보도록 하자.

문장(Statement)

문장(Statement) 는 위와 같이 “무언가를 한다/흐름을 만든다” 에 가까운 하나의 실행 단위이다. 뭐 분기 흐름을 만든다, 클래스를 정의한다 등등과 같은 무언가 특정 행위를 만들거나 정의하는 코드 조각의 모음이다. 이 코드 조각들 또한 ast 를 이용해서 parsing 하는 것이 가능하다.

statements = {
    'FunctionDef': '''
def greet(name):
    return f"Hello, {name}!"
''',
    'If': '''
if x > 0:
    print("positive")
else:
    print("non-positive")
''',
    'For': '''
for i in range(5):
    print(i)
''',
    'Return': '''
return x + y
''',
}

for stmt_type, code in statements.items():
    print(f"\n{'='*50}")
    print(f"{stmt_type} 예제:")
    print(f"{'='*50}")
    tree = ast.parse(code)
    # 첫 번째 문장의 타입 확인
    first_stmt = tree.body[0]
    print(f"첫 번째 문장 타입: {type(first_stmt).__name__}")
    print(f"\nAST 구조:")
    print(ast.dump(first_stmt, indent=2))

==================================================
FunctionDef 예제:
==================================================
첫 번째 문장 타입: FunctionDef

AST 구조:
FunctionDef(
  name='greet',
  args=arguments(
    args=[
      arg(arg='name')]),
  body=[
    Return(
      value=JoinedStr(
        values=[
          Constant(value='Hello, '),
          FormattedValue(
            value=Name(id='name', ctx=Load()),
            conversion=-1),
          Constant(value='!')]))])

==================================================
If 예제:
==================================================
첫 번째 문장 타입: If

AST 구조:
If(
  test=Compare(
    left=Name(id='x', ctx=Load()),
    ops=[
      Gt()],
    comparators=[
      Constant(value=0)]),
  body=[
    Expr(
      value=Call(
        func=Name(id='print', ctx=Load()),
        args=[
          Constant(value='positive')]))],
  orelse=[
    Expr(
      value=Call(
        func=Name(id='print', ctx=Load()),
        args=[
          Constant(value='non-positive')]))])

(생략 ...)

도중에 생략하긴 했는데 위와 같이 나오게 된다. If 와 같은 문장들은 식(Expression) 과 다르게 Statement로 감싸져 있지 않음을 확인할 수 있다. 이는 자리가 중요하기 때문이다. 문장 자리(stmt position) 에서는 Expression 이 들어갈 수 없기 때문에 ast.Expr 로 감싸게 된다.

def f():
    return 1 + 2  # ← Return(value=BinOp(...)) (BinOp를 Expr로 감싸지 않음)

하지만, 만약 문장 자리가 아닌 표현식 자리(expr position) 이라면 위와 같이 Expr 로 감싼 상태로 나오지 않게 된다.

바이트코드

이렇게 AST 로 해석되고 나면 어떻게 될까? 바로 컴파일 되게 된다. 파이썬도 Java 처럼 플랫폼 독립적이기 위해 이를 파이썬 가상 머신(PVM) 이 해석할 수 있는 구조인 바이트코드로 해석한다. 이를 코드로 확인해보기 위해서는 dis 모듈을 사용해보면 된다.

def add(a, b):
    return a + b

print("=== dis.dis() 출력 ===")
dis.dis(add)

=== dis.dis() 출력 ===
  2           RESUME                   0

  3           LOAD_FAST_LOAD_FAST      1 (a, b)
              BINARY_OP                0 (+)
              RETURN_VALUE

위와 같이 첫번째로 2 와 3 같은 소스코드의 줄 번호가 나오고, RESUME, LOAD_FAST, BINARY_OP, RETURN_VALUE 와 같은 opcode(명령어) 그리고 0,1,0 과 같은 피연산자 인덱스가 나오게 된다. 위와 같이 dis 모듈을 통해 코드의 바이트 코드를 출력할 수 있다는 사실을 알 수 있다.

바이트 코드 예시

몇가지 바이트 코드를 한번 알아보도록 하자.

• LOAD_CONST : 상수를 스택에 푸시

• BINARY_OP : 이항 연산 수행

• STORE_FAST: 스택에서 값을 꺼내 지역변수에 저장

def simple_math():
    x = 1 + 2
    return x

print("=== x = 1 + 2 의 바이트코드 ===")
dis.dis(simple_math)

print("\n=== 상수 테이블 ===")
print(f"co_consts: {simple_math.__code__.co_consts}")

이 코드를 실행하면 어떻게 될까? 일단 결과를 보기보다 예측해보자.

• LOAD_CONST 1 (1) → 스택 = [1]

• LOAD_CONST 2 (2) → 스택 = [1, 2]

• BINARY_OP 0 (+) → 스택 = [3] (1과 2를 팝하고 3을 푸시)

• STORE_FAST 0 (x) → 스택 = [] (3을 팝하여 x에 저장)

• LOAD_FAST 0 (x) → 스택 = [3] (x의 값을 푸시)

• RETURN_VALUE → 스택 = [] (3을 반환)

위와 같이 생각해 볼수 있다. 가장 첫번째로 1 과 2 를 스택에 넣어두고 BINARY_OP 를 통해 Pop 해서 3을 밀어넣고 이 값을 지역변수에 저장하는 것들을 생각해볼 수 있다. 실제로 실행하면 어떨까?

=== x = 1 + 2 의 바이트코드 ===
  2           RESUME                   0

  3           LOAD_CONST               1 (3)
              STORE_FAST               0 (x)

  4           LOAD_FAST                0 (x)
              RETURN_VALUE

=== 상수 테이블 ===
co_consts: (None, 3)

실제로 실행하게 되면 위와 같은 결과를 얻게 된다. 그 이유는 Cpython 의 상수 폴딩(constant folding) 때문인데 1+2 같이 사실상 컴파일시점에 값을 알 수 있는 식(Expression) 들은 3 하나만 상수테이블에 넣고 바이트 코드는 LOAD_CONST 3 만 남기게 된다.

Bytecode tracer

위와 같이 다른 바이트코드들도 많지만 굳이 다뤄야 할 정도로 유익하진 않다고 생각해서 bytecode_tracer 라는 tool 을 소개하고 이글을 마치려고 한다. 만약 스택 상태를 추적하고 싶다거나, 강의 목적으로 스택이 변화하는걸 보여주고 싶다면 아래와 같이 bytecode_tracer 를 이용하면 쉽게 시각화 할 수 있다.

import sys
sys.path.insert(0, '/home/roach/python-debug')

from tools.bytecode_tracer import trace_execution

# 간단한 함수 추적
def add(a, b):
    return a + b

print("=== 스택 상태 추적: add(1, 2) ===")
trace_execution(add, (1, 2))

┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Offset ┃ Opcode                ┃ Arg            ┃ Stack Before                  ┃ Stack After                   ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│      0 │ RESUME                │                │ []                            │ []                            │
│      2 │ LOAD_FAST_LOAD_FAST   │ a, b           │ []                            │ [1, 2]                        │
│      4 │ BINARY_OP             │ +              │ [1, 2]                        │ [3]                           │
│      8 │ RETURN_VALUE          │                │ [3]                           │ []                            │
└────────┴───────────────────────┴────────────────┴───────────────────────────────┴───────────────────────────────┘

CFG

from tools.cfg_visualizer import visualize_cfg

def test_loop(n):
    total = 0
    for i in range(n):
        total += i
    return total

print("=== for 루프의 CFG 생성 ===")
output_path = visualize_cfg(test_loop, 'outputs/cfg/test_loop.png')
print(f"CFG 저장됨: {output_path}")

cfg 라는 tool 을 설치하면 위와 같이 바이트 코드의 흐름도 또한 확인해볼 수 있다.

연습 문제

def loop_with_range(n):
    total = 0
    for i in range(n):
        total += i
    return total

def loop_with_while(n):
    total = 0
    i = 0
    while i < n:
        total += i
        i += 1
    return total

n 회 기준으로 for-loop 와 while 루프가 위 처럼 코드가 존재할때 과연 바이트 코드가 같을까? 아니면 누가 더 빠를까? 한번 바이트 코드를 보면 아래와 같이 컴파일된다 (python 3.13 기준이다)

=== for + range ===
  2           RESUME                   0

  3           LOAD_CONST               1 (0)
              STORE_FAST               1 (total)

  4           LOAD_GLOBAL              1 (range + NULL)
              LOAD_FAST                0 (n)
              CALL                     1
              GET_ITER
      L1:     FOR_ITER                 7 (to L2)
              STORE_FAST               2 (i)

  5           LOAD_FAST_LOAD_FAST     18 (total, i)
              BINARY_OP               13 (+=)
              STORE_FAST               1 (total)
              JUMP_BACKWARD            9 (to L1)

  4   L2:     END_FOR
              POP_TOP

  6           LOAD_FAST                1 (total)
              RETURN_VALUE

=== while ===
  8           RESUME                   0

  9           LOAD_CONST               1 (0)
              STORE_FAST               1 (total)

 10           LOAD_CONST               1 (0)
              STORE_FAST               2 (i)

 11           LOAD_FAST_LOAD_FAST     32 (i, n)
              COMPARE_OP              18 (bool(<))
              POP_JUMP_IF_FALSE       16 (to L2)

 12   L1:     LOAD_FAST_LOAD_FAST     18 (total, i)
              BINARY_OP               13 (+=)
              STORE_FAST               1 (total)

 13           LOAD_FAST                2 (i)
              LOAD_CONST               2 (1)
              BINARY_OP               13 (+=)
              STORE_FAST               2 (i)

 11           LOAD_FAST_LOAD_FAST     32 (i, n)
              COMPARE_OP              18 (bool(<))
              POP_JUMP_IF_FALSE        2 (to L2)
              JUMP_BACKWARD           16 (to L1)

 14   L2:     LOAD_FAST                1 (total)
              RETURN_VALUE

바이트 코드의 양만 봐도 알 수 있듯이 while 문에 조금 더 많은 바이트 코드가 존재한다. 그 이유는 아래 연산이 매 반복의 분기마다 이뤄지기 때문이다.

• 비교(COMPARE_OP) + 분기(POP_JUMP_IF_FALSE)

• 증가를 위한(LOAD_CONST/BINARY_OP/STORE_FAST)

실제 어느정도 크지 않다면 비슷하겠지만 바이트 코드를 보게 된다면 위와 같이 미세한 차이들도 발견해볼 수 있다. 이러한 지식은 언젠가 알아두면 도움이 되니 파이썬을 사용하고 있다면 한번정도는 공부해보면 좋은 것 같다.

import tokenize
import io

# 토큰 타입 이름 확인
print("주요 토큰 타입:")
print(f"  NAME: {tokenize.NAME} - 변수명, 함수명 등")
print(f"  NUMBER: {tokenize.NUMBER} - 숫자 리터럴")
print(f"  STRING: {tokenize.STRING} - 문자열 리터럴")
print(f"  OP: {tokenize.OP} - 연산자")
print(f"  NEWLINE: {tokenize.NEWLINE} - 줄바꿈")
print(f"  INDENT: {tokenize.INDENT} - 들여쓰기 시작")
print(f"  DEDENT: {tokenize.DEDENT} - 들여쓰기 종료")
print(f"  ENDMARKER: {tokenize.ENDMARKER} - 파일 끝")

이건 python 에서 주로 쓰이는 토큰 타입들이다. 이를 출력해보면 아래와 같이 출력된다.

주요 토큰 타입:
  NAME: 1 - 변수명, 함수명 등
  NUMBER: 2 - 숫자 리터럴
  STRING: 3 - 문자열 리터럴
  OP: 55 - 연산자
  NEWLINE: 4 - 줄바꿈
  INDENT: 5 - 들여쓰기 시작
  DEDENT: 6 - 들여쓰기 종료
  ENDMARKER: 0 - 파일 끝

토큰화 함수

기본적으로 tokenize.generate_tokens(readline) 함수를 사용합니다.

• readline: 한 줄씩 읽어오는 함수

• 반환: 토큰 네임드튜플 (type, string, start, end, line)

# 간단한 코드 토큰화 예시
code = "x = 1 + 2"
print(f"코드: {code!r}")
print("\n토큰 목록:")
print("-" * 60)

tokens = tokenize.generate_tokens(io.StringIO(code).readline)
for tok in tokens:
    tok_name = tokenize.tok_name[tok.type]
    print(f"{tok.type:3} {tok_name:12} {tok.string!r:15} 위치: {tok.start}-{tok.end}")

코드: 'x = 1 + 2'

토큰 목록:
------------------------------------------------------------
  1 NAME         'x'             위치: (1, 0)-(1, 1)
 55 OP           '='             위치: (1, 2)-(1, 3)
  2 NUMBER       '1'             위치: (1, 4)-(1, 5)
 55 OP           '+'             위치: (1, 6)-(1, 7)
  2 NUMBER       '2'             위치: (1, 8)-(1, 9)
  4 NEWLINE      ''              위치: (1, 9)-(1, 10)
  0 ENDMARKER    ''              위치: (2, 0)-(2, 0)

실제로 실행시켜보면 해당 토큰의 타입과 이름과 위치정보 등등이 표기 된다. 이를 통해 토큰이 파일내에서 어떤 위치에 있는지 등등을 판단할 수 있다.

INDENT, DEDENT

code2 = '''def greet(name):
    print(f"Hello, {name}!")
    return True
'''

print("=== 실습 2: 함수 정의 토큰화 ===")
print(f"\n원본 코드:")
print(code2)
print("=" * 70)
print(f"{'타입':<15} {'값':<20} {'줄':<5} {'열':<5}")
print("=" * 70)

tokens = list(tokenize.generate_tokens(io.StringIO(code2).readline))
for tok in tokens:
    tok_name = tokenize.tok_name[tok.type]
    line, col = tok.start
    value = tok.string[:18] + '...' if len(tok.string) > 20 else tok.string
    print(f"{tok_name:<15} {value!r:<20} {line:<5} {col:<5}")

print("\n주목할 점:")
print("- INDENT: 함수 본문의 들여쓰기가 시작됨을 표시")
print("- DEDENT: 들여쓰기가 종료됨을 표시 (return 문 이후)")
print("- f-string의 경우 FSTRING_START, FSTRING_MIDDLE, FSTRING_END로 분리됨")

=== 실습 2: 함수 정의 토큰화 ===

원본 코드:
def greet(name):
    print(f"Hello, {name}!")
    return True

======================================================================
타입              값                    줄     열    
======================================================================
NAME            'def'                1     0    
NAME            'greet'              1     4    
OP              '('                  1     9    
NAME            'name'               1     10   
OP              ')'                  1     14   
OP              ':'                  1     15   
NEWLINE         '\n'                 1     16   
INDENT          '    '               2     0    
NAME            'print'              2     4    
OP              '('                  2     9    
FSTRING_START   'f"'                 2     10   
FSTRING_MIDDLE  'Hello, '            2     12   
OP              '{'                  2     19   
NAME            'name'               2     20   
OP              '}'                  2     24   
FSTRING_MIDDLE  '!'                  2     25   
FSTRING_END     '"'                  2     26   
OP              ')'                  2     27   
NEWLINE         '\n'                 2     28   
NAME            'return'             3     4    
NAME            'True'               3     11   
NEWLINE         '\n'                 3     15   
DEDENT          ''                   4     0    
ENDMARKER       ''                   4     0    

주목할 점:
- INDENT: 함수 본문의 들여쓰기가 시작됨을 표시
- DEDENT: 들여쓰기가 종료됨을 표시 (return 문 이후)
- f-string의 경우 FSTRING_START, FSTRING_MIDDLE, FSTRING_END로 분리됨

실제로 실행시켜보면 “INDENT” 와 “DEDENT” 등이 표기되는 것을 알 수 있다. FSTRING_START 등 신기한 토큰들도 많이보인다. Python 은 들여쓰기 수준이 증가하거나 감소할때 잘 알고 있듯이 INDENT 와 DEDENT 가 아래 처럼 발생한다.

=== 중첩 함수의 INDENT/DEDENT ===
def outer():
    x = 1
    def inner():
        y = 2
        return y
    return x

============================================================
NAME: 'def'
NAME: 'outer'
OP: '('
OP: ')'
OP: ':'
INDENT → 레벨 1
  NAME: 'x'
  OP: '='
  NUMBER: '1'
  NAME: 'def'
  NAME: 'inner'
  OP: '('
  OP: ')'
  OP: ':'
  INDENT → 레벨 2
    NAME: 'y'
    OP: '='
    NUMBER: '2'
    NAME: 'return'
    NAME: 'y'
  DEDENT ← 레벨 2
  NAME: 'return'
  NAME: 'x'
DEDENT ← 레벨 1

List comprehension 토큰화

=== 연습 2: 리스트 컴프리헨션 토큰화 ===
코드: squares = [x**2 for x in range(10) if x % 2 == 0]

토큰 목록:
--------------------------------------------------
  NAME            'squares'
  OP              '='
  OP              '['
  NAME            'x'
  OP              '**'
  NUMBER          '2'
  NAME            'for'
  NAME            'x'
  NAME            'in'
  NAME            'range'
  OP              '('
  NUMBER          '10'
  OP              ')'
  NAME            'if'
  NAME            'x'
  OP              '%'
  NUMBER          '2'
  OP              '=='
  NUMBER          '0'
  OP              ']'

모든 코드가 토큰화 된다.

마치며

양질의 글은 아니지만 복리 효과를 믿으며 적어보는 글. 토큰화에 대한 개념을 알고 있으면 나중에 재밌는 것들을 해볼 수 있을 것 같다.

크롤러를 운영하다보면 규모 및 속도에 따라서 크게 두가지 부류로 크롤러를 운영하게 된다.

• html 만을 http request 로 가져와서 Parsing 하는 경우

• javascript 들이 로딩되고 실행되고 나서 데이터를 가져오기 위해 selenium 같은 헤비한 크롤러를 돌리는 경우

이 외에도 여러 방식이 더 있을 수 있지만 보통은 이 두가지 부류로 크롤링을 하게 된다고 생각한다. 첫번째 http request 의 경우 별도의 프로세스를 뛰어도 되지 않기 때문에 헤비하지 않고, 상대적으로 가벼운 http call 로 진행된다. 대부분의 경우 timeout 이 났을때의 재처리 혹은 에러 처리방안 등등만 잘 고려하면 크게 문제가 되지않는다.

두번째 방식이 selenium 과 같이 별도의 브라우저 프로세스를 뛰어야 하는 경우인데, 이 같은 경우는 프로세스를 하나 더 뛰우기 때문에 프로세스를 처리하는 정책, 몇 개의 worker 를 뛰우는게 좋은지 등등 리소스 측면에서 여러가지로 대응해야 할점이 많다. 오늘은 두번째 방식인 브라우저 프로세스로 인한 크롤러를 운영하며 겪었던 문제를 적어보려고 한다.

현상

크롤러가 초기에는 잘 돌다가 한 3시간 정도의 시간이 지나고나면 갑자기 shutdown signal 를 받고 종료 되 버렸다. 이는 크롤러의 SIGTERM 에 달려있는 핸들러의 로그로 운영체제가 이를 종료하기를 원했다는 것이다. 그래서 로그창을 확인해보니 꺼지기 5분전 마지막 CDP 에 캡쳐된 request 외에는 별다른 로그가 존재하지 않았다.

그래서 메트릭 창을 확인해보니 CPU 도 정상적이고, 메모리도 정상적이였기 때문에 문제를 찾기 어려웠다. 그러던 중 로그를 유심히 살펴보다가 [Errno 11] Resource temporarily unavailable 라는 로그를 발견했다. 보통 운영체제 수준에서 소켓 관련이나 프로세스/스레드의 제한이 Limit 을 넘게 되면 발생하는 문제로 알고 있다.

예를 들면, fork 를 통해서 새로운 프로세스를 만들때 이때 PID 테이블이 고갈되면 이러한 에러를 리턴하는 것으로 기억하고 있었다. 따라서 무언가 프로세스의 Pool 과 관련있겠구나 싶어서 이 부분과 관련된 코드를 찾아보았다.

추측

크로미움을 spawn 할때 현재 PID 에서 자식 프로세스로 spawn 하게 된다. 그때 Chromium 하위에 자식 프로세스들이 spawn 됬는데 이를 정리하지 못하는건가? 라는 생각이 들었다. 운영 환경이 Docker 로 돌아가고 있었기 때문에 Init 프로세스가 내 어플리케이션이라 프로세스를 잘 정리하지 못할 수 있겠다는 생각이 들었다.

이렇게 생각한 이유는 Go 에서 spawn 한 Chromium 은 자식프로세스로 관리하지만 해당 Chromium 이 생성한 자식들은 추적할 방안이 없기 때문이다.

우리가 실행중인 어플리케이션이 PID 가 1 인 이유는 도커 환경에서 실행되었기 때문이다. 운영또한 도커 환경에서 실행되므로 앞으로 아래 코드들은 모두 도커 환경에서 실행되었다고 생각해주면 된다.

일단 추측이 맞는지 테스트 해보기 위해서 간단하게 sh 와 sleep 을 이용해서 테스트를 진행하기로 했다.

┌─────────────────────────────────────────────────────────────────┐
│ 1. Go spawns 'sh' process                                       │
│    zombie-check (PID 1)                                         │
│     └─ sh (PID 10)                                              │
│                                                                 │
│ 2. sh launches 'sleep' in background (&) and exits immediately │
│    zombie-check (PID 1)                                         │
│     └─ sh (PID 10)                                              │
│         └─ sleep (PID 20) ← running in background              │
│                                                                 │
│ 3. sh exits, Go reaps it via cmd.Run() ✅                       │
│    zombie-check (PID 1)                                         │
│     └─ sleep (PID 20) ← ORPHAN! Kernel reparents to PID 1      │
│                                                                 │
│ 4. After 100ms, sleep exits                                    │
│    zombie-check (PID 1)                                         │
│     └─ sleep (PID 20) [defunct] ← ZOMBIE! 🧟                   │
│                                                                 │
│ 5. Go doesn't track reparented processes                       │
│    → Receives SIGCHLD but ignores it                           │
│    → Zombie remains forever (or until dumb-init reaps it)      │
└─────────────────────────────────────────────────────────────────┘

테스트 하고자 하는 방법론은 간단하다. Go 의 exec.Command 로 sh 를 spawn 하고, sh 가 sleep 을 spawn 한다. sleep 은 background 에서 진행되므로 sh 는 바로 종료되고, sleep 은 좀비 프로세스로 남게 되는지를 테스트 해보는 것이다.

func main() {
    // Create 10 zombie processes
    for i := 0; i < 10; i++ {
        cmd := exec.Command("sh", "-c", "sleep 0.1 &")
        cmd.Run()
        time.Sleep(200 * time.Millisecond)

        fmt.Printf("Generated zombie %d/10\n", i+1)
    }
    for {
        time.Sleep(2 * time.Second)
    }
}

이를 docker 로 실행시키고 docker exec $ID_FIXED ps -o pid,ppid,stat,comm,args 커맨드를 통해 확인하면 생성된 sh 의 자식 프로세스인 sleep 이 어떻게 처리되는지 알 수 있다.

Checking process table inside container:
PID   PPID  STAT COMMAND          COMMAND
    1     0 S    zombie-check     ./zombie-check
   12     1 Z    sleep            [sleep]
   14     1 Z    sleep            [sleep]
   16     1 Z    sleep            [sleep]
   18     1 Z    sleep            [sleep]
   20     1 Z    sleep            [sleep]
   22     1 Z    sleep            [sleep]
   24     1 Z    sleep            [sleep]
   26     1 Z    sleep            [sleep]
   28     1 Z    sleep            [sleep]
   30     1 Z    sleep            [sleep]
   31     0 R    ps               ps -o pid,ppid,stat,comm,args

확인해보면 sleep 상태의 좀비 프로세스들이 무수히 생겨났다는걸 알 수 있습니다. 이제 도커에서 PID 1 인 제 Go application 이 자식프로세스가 죽었을때 adopt 하지 않는것을 알았으니 실제 크롤러를 로컬 환경에서 장시간 돌려 확인해보도록 하겠습니다.

재현

일단 예전 크롤러 파일을 뛰우고 크롤러를 뛰운 다음에 Zombie Process 가 계속해서 증가하는지 모니터링 해보도록 하겠습니다. (해당 스크립트는 Claude code 와 함께 작성하였습니다)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🧟 Zombie processes: 45 ⚠️  Warning
  📦 Total processes:  75
  🆔 PID usage:        78 / 99999 (0.1%)

실제로 확인해보니 계속해서 Zombie Process 가 종료되지 않고 늘지 않는 것을 확인할 수 있습니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Zombie Processes (showing up to 10)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PID   PPID  STAT COMMAND
  ────  ────  ──── ───────
  55     1 Z    chromium
  56     1 Z    chromium
  57     1 Z    chromium
  58     1 Z    chromium
  60     1 Z    chromium
  61     1 Z    chromium
  67     1 Z    chromium
  70     1 Z    chromium
  169     1 Z    chromium
  295     1 Z    chromium

실제로 확인해보면 크로미움 커맨드로 실행된 Process 들이며 PPID 는 1로 가지고 있습니다. 여기서 어 진짜 자식프로세스인가 의문이 들어 실제로 프로세스를 한번 커맨드로 확인해보았습니다.

1685  1679 S    /usr/lib/chromium/chromium --type=zygote --no-zygote-sandbox --no-sandbox --headless --headless
 1686  1679 S    /usr/lib/chromium/chromium --type=zygote --no-sandbox --headless --headless
 1701  1679 S    /usr/lib/chromium/chromium --type=utility --utility-sub-type=network.mojom.NetworkService
 1718  1686 S    /usr/lib/chromium/chromium --type=renderer --headless --no-sandbox --disable-dev-shm-usage
 1738  1685 S    /usr/lib/chromium/chromium --type=gpu-process --no-sandbox --disable-dev-shm-usage

확인해보니 renderer 나 gpu-process 등 chromium 의 하위 프로세스로 생성된 자식들임을 확인 할 수 있습니다. 이러한 프로세스 들이 부모 chromium 이 죽어서 PID 1 로 입양 되었지만, 실제로 Go 에서는 이를 정리하지 않기 때문에 정리가 되고 있지 않던 것이 였습니다.

수정

  sigChan := make(chan os.Signal, 10)
  signal.Notify(sigChan, syscall.SIGCHLD)

  go func() {
      for range sigChan {
          // 모든 종료된 자식 reap
          for {
              var status syscall.WaitStatus
              pid, err := syscall.Wait4(-1, &status, syscall.WNOHANG, nil)
              if pid <= 0 || err != nil {
                  break
              }
              log.Debug().Int("pid", pid).Msg("Reaped zombie")
          }
      }
  }()

이러한 에러를 수정하기 위해서는 어떠한 방법이 있을지 고민해보다가 1차원적으로는 위와 같은 Go 코드를 짤 방법을 생각해보았습니다. 하지만, 뭔가 Dockerfile 이 아닐때 실행해도 잘 될까? 무언가 좀 보장하기 어렵게 만드는거 같다는 생각이 들었고, 동시성 이슈는 없을까..? 등등 조금 부족한 OS 지식으로 이러한 코드를 작성하고 안전하다고 하기에는 무리가 있다는 생각이 들었습니다.

그래서 검색을 해보니 이미 유명한 이슈였고, 해결하는 방법으로 dumb-init 이라는 프로세스가 존재했습니다. dumb-init 은 아주 간단하게 커맨드의 앞에 작성해주고 뒤에 실행하고 싶은 executable 한 커맨드를 넘겨주면 됩니다.

테스트

이제 dumb-init 으로 실행된 도커파일을 monitoring 툴을 통해서 감지해보자.

📍 Stage 1/4: Initial crawling (0-10min)
   Expected: 0-10 zombies

💡 Tip: Open another terminal and run:
   docker logs -f crawler-fixed-test

Press Ctrl+C to stop monitoring...
╔════════════════════════════════════════════════════════════════╗
║  🧟 Zombie Process Monitor - Bug Reproduction Test     ║
╚════════════════════════════════════════════════════════════════╝

📅 Time: 2026-01-19 15:46:32
⏱️  Elapsed: 0h 0m 10s

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🧟 Zombie processes: 0 ✅ Normal
  📦 Total processes:  32
  🆔 PID usage:        35 / 99999 (0.0%)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Zombie Processes (showing up to 10)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  None yet - system is clean ✨

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 Stage 1/4: Initial crawling (0-10min)
   Expected: 0-10 zombies

💡 Tip: Open another terminal and run:
   docker logs -f crawler-fixed-test

오래 켜놓아도 프로세스가 32에서 증가하거나 줄어들지 않는 것을 확인할 수 있다. 이제 함께 실행한 기존에 버그가 있던 코드로 실행된 도커를 확인해보자.

📊 Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🧟 Zombie processes: 43 ⚠️  Warning
  📦 Total processes:  73
  🆔 PID usage:        76 / 99999 (0.1%)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Zombie Processes (showing up to 10)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PID   PPID  STAT COMMAND
  ────  ────  ──── ───────
  46     1 Z    chromium
  47     1 Z    chromium
  49     1 Z    chromium
  50     1 Z    chromium
  60     1 Z    chromium
  62     1 Z    chromium
  103     1 Z    chromium
  106     1 Z    chromium
  156     1 Z    chromium
  375     1 Z    chromium

위와 같이 기존 코드는 좀비 프로세스가 잘 정리되지 않는 것을 확인해볼 수 있다.

마치며

이번 트러블 슈팅은 OS 적 지식이 도움이 좀 많이 되었던거 같다. OS 지식 기반으로 Claude 와 함께 추론하여 버그를 찾았는데 시각화 하는 과정에서 꽤 많은 도움을 많이 받았다. 이제 일단 fix 는 해두었으니 이를 모니터링 수단과 함께 연동할 방법을 찾아봐야겠다.

Index 란 무엇이고 왜 중요할까? Index 는 데이터베이스에서 File System 에 일어나는 Random I/O 를 줄이기 위해 존재한다. 랜덤 I/O 란, 해당 데이터가 저장된 Array 에 우리가 특정 주소값 i 를 넣어 조회하듯 일어나는 이벤트를 뜻한다.

그럼 느리지 않을거 같은데 왜 랜덤 I/O 를 줄여야 하지? 라는 고민이 충분히 들수도 있다. 이러한 이유는 File System 까지 가는 계층에서 드는 비용과 전통적인 HDD 의 경우 디스크헤드 비용, Kernel 에서 블락단위로 읽어오는 비용 등등 여러가지 부가적인 요소들이 들어가게 된다. 이는 B-Tree 같은 것들이 왜 leaf node에서 range 로 한번의 I/O 로 많은 것들을 읽을 수 있도록 설계해놨는지를 알 수 있게 해준다.

B-Tree

                [Internal Node]
                /      |      \
               /       |       \
    [Internal Node] [Internal] [Internal]
        /    \         |  \        /  \
       /      \        |   \      /    \
   [Leaf]  [Leaf]  [Leaf] [Leaf] [Leaf] [Leaf]

B-Tree 의 자료구조이다. 정렬된 형태로 존재하며 빠르게 원하는 key 값으로 데이터를 찾을 수 있게 Internal Node 들은 키값만을 저장한다. Leaf Node 는 실제로 찾아야 하는 데이터 혹은 그 데이터를 가르키는 어떠한 값을 가르키도록 보통 설계되어 있다. (MySQL InnoDB 엔진의 경우 이 값이 클러스터링 인덱스또는 실제 값을 가르키게끔 되어 있거나, Postgresql 의 경우 TID 값을 통해 Heap 을 가르키도록 되어 있다)

CREATE TABLE logs (
    id BIGSERIAL PRIMARY KEY,
    timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    level VARCHAR(10) NOT NULL,
    service VARCHAR(50) NOT NULL,
    message TEXT NOT NULL,
    metadata JSONB
); 

CREATE UNIQUE INDEX logs_pkey ON public.logs USING btree (id)
CREATE INDEX idx_test ON public.logs USING btree (level, service)

만약 위와 같은 테이블이 있다고 해보자. 해당 테이블이 있을때 아래와 같은 쿼리를 날리면 어떻게 될까?

SELECT level, service, message FROM logs WHERE level='ERROR'

인덱스가 있어 빠를것 같지만 아래와 같은 실행 계획을 가지게 되며 실행시간도 11021.287 ms 로 꽤나 긴것을 확인할 수 있습니다.

이 실행계획을 간단히 설명해보면 첫번째로 Bitmap Index Scan 을 통해 해당 행들이 페이지내의 어느 블록에 있는지를 알아냅니다. 이렇게 하는 이유는 그냥 Index Scan 을 통해서 Random I/O 를 발생시키면 너무 오래걸리기 때문에 Bitmap 에서 정렬시켜 순차적으로 한번에 많이 긁어오기 위함입니다.

그리고 해당 Bitmap 을 이용하여 Heap Scan 을 실시합니다. 이때 정렬된 순서로 긁기 때문에 그냥 Random I/O 보다는 더 효율적으로 데이터를 가져오게 됩니다.

Buffers: shared hit=6599 read=656800 dirtied=56788 written=18

그래서 결과를 보면 실제로 Memory 에서 가져온것은 6599 건, 그리고 파일시스템을 통해서 656800 건 만큼 블록단위로 데이터를 읽어 가져오게 됩니다. 즉, 대부분을 파일 시스템을 통해 가져오는 것을 확인할 수 있습니다. 여기서 최적화를 해야 한다면 어떻게 해야할까요?

커버링 인덱스

여기서 커버링 Index 를 이용해 볼 수 있습니다. 커버링 Index 는 세컨더리 인덱스에도 값을 저장하게끔 하여 실제 Heap page 까지는 도달되는 I/O 를 줄이는 방법입니다. 인덱스에서 대부분의 질의가 해결되기 때문에 커버링 인덱스라고 불립니다.

만드는 가장 간단한 방법은 복합 인덱스를 아래와 같이 만들어보는 것입니다.

CREATE INDEX idx_composite ON logs(level, service, message);

VACUUM ANALYZE logs;

위와 같이 인덱스를 생성하고 쿼리를 날리게 되면 아래와 같은 결과를 얻을 수 있습니다.

일단 실행계획을 분석해보면 Heap Fetches 가 0 인것을 확인할 수 있습니다. 즉, 인덱스에서 모든 조회가 이루어졌음을 확인할 수 있습니다. read 또한 6889 로 급격히 감소했음을 확인할 수 있습니다. 다만, 이 부분은 실제 데이터가 최신인지 확인할 수 없을때는 증가할 수 있습니다. (실험을 위해 VACUUM ANALYZE 를 미리 실행시킨 이유가 그 이유입니다)

즉, Index Scan 만을 통해 데이터를 모두 가져오고 Heap 을 하나도 Fetch 하지 않았음을 확인할 수 있습니다. 이전에 비해 비약적으로 빨라진 것을 확인할 수 있습니다. 이것이 인덱스에서 데이터를 Fetch 해오는 것이 커버가 되는 커버링 인덱스라고 할 수 있습니다.

다만, 여기서 의문은 방금의 인덱스는 과연 좋은 인덱스 였을까요? 보통 Tree 자료구조에서 key 로 무언갈 선정한다는건 이 데이터를 정렬의 축으로 잡겠다는 의미와 같습니다. 즉, level 과 service 는 ENUM 과 같은 제약된 다양성을 가지는 곳에는 괜찮을 수 있지만, message 와 같이 정렬이 필요없는 부분또한 key 에 속하게 되어 종단 노드의 크기가 커지게 됩니다.

      [Internal Node (level, service, message)]
                /      |      \
               /       |       \
    [Internal Node] [Internal] [Internal] => level, service, message
        /    \         |  \        /  \
       /      \        |   \      /    \
   [Leaf]  [Leaf]  [Leaf] [Leaf] [Leaf] [Leaf]

사실 message 를 빠르게 가져오기 위해 key 에 넣게 된다면 그 만큼의 INSERT 와 UPDATE 시에 오버헤드가 걸리게 되므로 trade-off 를 계산해야 되는 상황에 빠지게 됩니다. 그렇다면 message 를 탐색 key 로 잡지 않고 종단 노드에만 위치하게 하는 방법은 없을까요? Postgresql 에서는 이를 INCLUDE 라는 키워드를 통해 해결하게 해줍니다.

Include

CREATE INDEX idx_include ON logs(level, service) INCLUDE (message);

위와 같이 INCLUDE 를 통해 message 를 추가하게 되면 종단 노드에만 잡혀서 아주 컴팩트한 인덱스가 되고, INSERT 와 UPDATE 시 비용이 덜 들게 된다고 생각할 수 있습니다. 실제 테스트를 위해 한번 추가하고 난 뒤에 Index 사이즈를 보도록 합시다.

SELECT
    indexrelname,
    pg_size_pretty(pg_relation_size(indexrelid)) AS index_size
FROM pg_stat_user_indexes
WHERE relname = 'logs';

실제로 사이즈를 보니 예상 한 것보다 너무 비대한 것을 확인할 수 있습니다 . 이유는 무엇일까요? 이를 알아보기 위해서는 일단 데이터를 확인해보도록 하겠습니다.

SELECT COUNT(*) / COUNT(DISTINCT (level, service, message)) as duplication_ratio
  FROM logs;

로그 테이블에서 (level, service, message) 가 유니크한 수를 전체 개수로 나누어 얼마나 유니크한지를 보도록 하겠습니다. 1.0 에 근사한 수치가 나올수록 카디널리티가 높아 인덱싱에 유리한 구조임을 알수 있겠죠.

실제로 해보면 약 3048 이 나오게 됩니다. 즉, 동일한 조합이 평균적으로 약 3048 개가 중복되어 있음을 알 수 있습니다. 그런데 왜 inx_composite 은 217MB 뿐인데, idx_include 는 1822MB 나 될까요? 이는 Postgresql 이 인덱스를 생성하는 방식이 대략적으로 아래와 같기 때문입니다. (이는 설명하기 위한 수도코드로 살짝 동작이 다릅니다!!)

btree_insert(index, key=(level, service, message), tid) {
    existing_entry = search_btree(key);

    if (existing_entry != NULL) {
        add_tid_to_posting_list(existing_entry, tid);
    } else {
        create_new_entry_with_posting_list(key, tid);
    }
}

btree_insert_with_include(index, key=(level, service), tid, include=message) {
    create_new_index_tuple(key=(level, service), tid, include_data=message);
}

의사 코드를 보면 복합 인덱스는 중복 제거를 하지만, include 의 경우 중복제거를 하지 않습니다. 즉, 복합 인덱스에서는 (level, service, message) 가 합쳐저 하나의 posting_list 로 관리되지만, include 에서는 (level, service) 가 같더라도 message 가 다르면 별도의 엔트리가 생성되게 됩니다. (저도 궁금해서 공식 문서를 읽어봤는데 “INCLUDE indexes can never use deduplication“ 라고 적혀있더군요)

실제로 페이지에 저장된 튜플의 밀도도 훨씬 복합인덱스가 높은 것을 확인할 수 있습니다.

마치며

INCLUDE 관련 부하 테스트를 하게 되다가 알게 된 사실이라 적어봅니다. 언제 사용해야 할지 지금 까지 감은 카디널리티가 엄청나게 높고, key 로 잡아야 하는 컬럼의 데이터가 크다면 써볼 수 있을것 같습니다. 다만 이렇게 까다로운 경우 대부분 성능향상을 하기 위해서는 많은 테스팅이 필요하므로 테스트를 많이 해보고 도입해볼 것 같습니다.

이 개념을 적용하기 위해서는 Postgresql 에서는 xmin 과 xmax 를 활용한다. Postgresql 에서 테이블안에 있는 데이터는 튜플(Tuple) 형태로 저장된다. 예를 들면, 아래와 같이 테이블이 있다고 해보자.

테이블 구조

위 테이블에는 id,name,balance,created_at 등의 column 이 존재한다. 여기서 튜플은 (1,Alice,1000,2026-01-14)를 의미한다. 즉, 하나의 레코드가 튜플로 저장된다.

튜플

튜플은 아래와 같은 정보를 가지고 있다.

• ctid: 페이지에서 저장된 위치를 나타내는 값

• xmin: 이 튜플을 INSERT 한 트랜잭션의 ID

• xmax: 이 튜플을 DELETE 한 트랜잭션의 ID

각 처리된 트랜잭션의 ID 정보를 가지고 있는 이유는 해당 Tuple 의 가시성(Visibility) 를 계산하기 위함이다. 쿼리를 날려보고 결과를 확인해보며 이해해 보자.

--- 세션 A 시작
BEGIN;

SELECT txid_current(); -- 810

SELECT xmin, xmax, ctid, id, name, balance
FROM accounts
ORDER BY id;

세션 A 는 ximn txid(트랜잭션 ID) 를 810 로 가지고 있고, xmax 는 0 으로 가지고 있다. xmax 는 삭제될때만 txid 를 남기므로 0 이라는 것은 아직 지워지지 않았음을 의미한다.

즉, 이 세개의 데이터는 현재 Transaction 전에 생긴 데이터임을 알 수 있다. 이 트랜잭션을 닫지 않고, 다른 트랜잭션(세션 B) 를 열어보자.

BEGIN;

SELECT pg_current_snapshot();
SELECT txid_current(); -- 811

INSERT INTO accounts (name, balance)
VALUES ('New User (uncommitted)', 9999)
RETURNING xmin, xmax, ctid, id, name, balance;

여기서는 811 로 나온다. 여기서 INSERT 한게 세션 A 에 보일까? xmin 의 문제는 아니지만 세션 A 에는 보이지 않는다. 그 이유는 기본 격리수준인 READ COMMITED 를 이용하기 때문이다. B 세션을 커밋해보자. 그리고 A 세션은 아직 커밋하지 않았지만 다시 SELECT 를 해보자.

세션 B 에서 저장된 값의 xmin 을 보니 세션 B 의 트랜잭션 ID 가 남아있는 것을 확인할 수 있다. 이제 세션 C 를 열고 삭제해보자.

BEGIN;

SELECT pg_current_snapshot();
SELECT txid_current(); -- 813

DELETE FROM accounts where name = 'New User (uncommitted)';

세션 C(813) 에서 해당 튜플을 삭제했다. 이 튜플은 xmax 값이 아마 813 으로 남아있을 것이다. Postgresql 은 이처럼 트랜잭션이 열린동안에도 읽기와 쓰기에 대한 Lock 을 하지 최소화 하거나 하지 않기 위해 Tuple 을 계속해서 생성해내고, xmin, xmax 값을 바꾼다. 이제 후에 Vacuum 으로 정리될 죽은 튜플에서 xmax 값을 확인해보자.

상태가 죽음(DEAD) 로 표시한걸 확인할 수 있다. 이는 다음에 AUTO VACUUM 이 돌때 제거된다. 수동으로 호출도 가능하다.

VACUUM accounts;

이제 대략적으로 쓰기/삭제(업데이트는 삭제와 쓰기가 일어남) 일어날 때 마다 튜플이 생성되는 걸 확인할 수 있었다. 그리고 이를 후에 주기적으로 정리하는 VACUUM 이라는 것도 있다는 것을 알게 되었다. 이제 스냅샷에 대해 알아보자. 스냅샷은 직관적으로 내 트랜잭션에 무엇이 보여야 하는지를 관리해준다.

스냅샷

스냅샷이 중요한 개념인데 트랜잭션 격리 레벨에 따라 다르다. 기본 격리 수준인 READ COMMITED 에서는 각 쿼리가 실행될때마다 스냅샷이 기록됩니다. 예시와 함께 보시죠

BEGIN;

SELECT pg_current_snapshot(); --- 815:815

SELECT xmin, xmax, ctid, id, name, balance
FROM accounts
ORDER BY id;

SELECT pg_current_snapshot(); --- ???:???

위와 같은 쿼리가 있을때 두번째로 snapshot() 을 찍으면 어떻게 될까요? 만약 아무런 변경이 없어 xmin 값이 올라가지 않았다면 동일하게 815:815 가 나왔을 것입니다. 하지만 만약, 다른 세션에서 새로운 컬럼을 아래와 같이 추가한다면 어떻게될까요?

BEGIN;

SELECT pg_current_snapshot();
SELECT txid_current(); --- 816

INSERT INTO accounts (name, balance)
VALUES ('New User (uncommitted)', 9999)
RETURNING xmin, xmax, ctid, id, name, balance;

COMMIT;

위와 같이 추가하게 되면 이제 xmin 의 경계가 816까지 올라가게 됩니다. 이 상태에서 닫지않은 815 세션에서 동일하게 쿼리를 수행하면 어떻게 될까요?

BEGIN;

SELECT pg_current_snapshot(); --- 815:815

SELECT xmin, xmax, ctid, id, name, balance
FROM accounts
ORDER BY id;

SELECT pg_current_snapshot(); --- 816:816

816으로 나오게 됩니다. 그리고 저 SELECT 에서는 새롭게 추가한 New User (uncommitted) 가 보이게 됩니다. 당연한 READ COMMITED 의 동작이지만 여기에는 스냅샷 기반으로 가시성을 통제하는 뒷단의 마법같은 로직이 숨겨져있습니다.

스냅샷

snapshot 은 기본적으로 xmin:xmax:[진행중인 txid] 로 구성됩니다. 각 값은 아래와 같은 정의를 가집니다.

• Snapshot xmin: 아직 완료되지 않은(Active) 트랜잭션 중 가장 낮은 ID. (이보다 작은 ID는 모두 커밋됨이 보장됨)

• Snapshot xmax: 현재까지 할당된 TXID 중 가장 큰 값 + 1. (이보다 크거나 같은 ID는 스냅샷 생성 시점에 아직 시작도 안 한 "미래" 트랜잭션)

• xip_list (진행 중인 txid): xmin과 xmax 사이에서 아직 진행 중인 트랜잭션들의 목록

그래서 특정한 xmin 을 높이는 작업이나 xmax 를 높이는 작업이 끝나면, 각 xmin과 xmax 의 값이 올라갔던 것입니다. 위에서는 아직 진행중인 transaction 을 제가 로깅하진 않았지만 아마 816 에서 세션을 열고, 815 에서 한번더 확인했다면 815 에서 816이 진행중인 세션으로 보였을 것입니다. 이 스냅샷의 범위와 튜플을 이용해 가시성을 통제합니다.

이해를 하기 위해 그림과 함께 보면 현재 snapshot 이 807:814:[807] 이라고 가정해봅시다. 각 튜플마다 지금 보여야 하는지 안보여야 하는지를 한번 설명해보도록 하겠습니다.

• A 튜플은 이미 734 에서 처리되었으므로 우리 세션에 보여야 합니다.

• B 튜플은 806 에서 커밋되었으나 xmax 가 커밋된 결과에 있으므로 삭제되었으므로 보이지 않습니다.

• C 튜플은 현재 트랜잭션이 커밋되지 않은 상태로 진행중이므로 현재에서 보이지 않습니다.

• D 튜플은 810 에서 커밋되었으니 snapshot_xmax(814) 보다 tuple_xmin(810) 이 작으므로 현재 트랜잭션에 보입니다.

• E 튜플 또한 삭제 되었으니 보이지 않습니다.

• F 튜플은 커밋되었으나 snapshot_xmax(814) 보다 tuple_xmin(820) 이 더 크므로 미래에 일어난 일이므로 보이지 않습니다.

즉 이런식으로 현재 snapshot 이 가지고 있는 범위에 따라 보이는 튜플들을 통제합니다. 만약 기본 격리수준인 READ COMMITED 의경우 쿼리를 실행한번 더 하게되면 xmax 가 820 까지 늘어나게 되면서 F 튜플이 보였을 수 있습니다.

REPEATABLE READ 는?

그렇다면 REPEATBALE READ 는 어떨까요? 본질적으로 REPEATABLE READ 는 PHANTOM READ 를 방지하므로 820 은 제 트랜잭션에서 노출되서는 안됩니다. Postgresql 은 여기서 쉽게 REPETABLE READ 는 트랜잭션이 시작되고 첫번째 쿼리가 만든 스냅샷만 해당 트랜잭션에서 이용하게 합니다.

BEGIN;

SELECT * FROM TABLE; --- 815:819

SELECT * FROM TABLE; --- 815:819

COMMIT;

즉, 같은 트랜잭션에서 스냅샷이 바뀌지 않으므로 여러번 SELECT 해도 결과가 바뀌지 않습니다. 다만, MySQL 과 다르게 동시에 해당 튜플에 값을 쓸때 처리하는 방식이 다르므로 Postgresql 에서는 REPEATABLE READ 를 쓸때 조심하셔야 됩니다.

마치며

Postgresql 에 Tuple 과 스냅샷에 대해 알아보았는데요. 다음시간에는 격리수준에 대한 조금 더 자세한 내용을 알아보려고 합니다

리뷰

최근 회사에서도 AI Agent 를 정말 많이 사용하고 있고, 우리 파이프라인 자체는 이미 LLM call 의 chaining 을 이용해서 사진이나 제품을 분류하는 일들을 많이 진행하고 있었음. 예전에 langchain 이 나올 무렵에는 대부분 langchain 도 단순히 OpenAPI 의 wrapper 수준이여서 API 콜 정도 밖에 지원하지 않았었는데, 그때 수동으로 chaining 이나 routing 같은 패턴을 순수 파이썬 코드로 작업했었었다.

이 책을 읽으면 그때 경험을 간접적으로 해볼 수 있다. 순수 파이썬 코드로 짜보면서 내부에서 대략적으로 어느 방식으로 돌아가는지 이해하고, 나중에 직접적으로 제어해야 할때 알맞은 디자인 패턴을 골라서 적용할 수 있도록 경험치를 쌓아주는 책.

장점

• 하루만에 충분히 읽을 수 있음

• 순수 파이썬 코드로 간단하게 현재 LLM Agent 를 여러 디자인 패턴과 함께 맛보기 좋음

• 파이썬을 알고만 있다면 아주쉽게 따라하기 좋음

• 쉬움

단점

• UI 구현은 솔직히 왜 있는지 잘 모르겠음

• 밑바닥부터 무언갈 만들긴 하나 거의 가드레일 하나 없는 Tutorial 수준의 예시들임

추천하는 독자

• Agent 로 파이프라인을 한번도 구성해보지 않은 사람들 (구성해봤다면 굳이 안읽어도 될거 같음. 추상화된 개념 정도의 수준의 구현만 있음)

난이도

• Easy

정리

Agent 파이프라인을 이미 구성해본 사람들에게는 그다지 도움이 안되지만, 처음 시작해보는 사람들에게는 이렇게 구성할 수 있구나 하고 깨달음을 줄 수도 있는 책. 근데 이미 langchain 이나 이런걸 쓴다해도, 이정도의 개념을 모르고 쓰기는 어렵다고 생각함.

책링크: https://product.kyobobook.co.kr/detail/S000218729898

시스템 프로그래밍을 공부하거나 비동기 프로그래밍 아키텍쳐 부분을 공부하다보면 심심치 않게 selector, epoll, kqueue 등의 키워드를 마주하게 된다. 이를 개념적으로 이해하는 것도 좋으나 항상 코드와 함께 무엇이 문제여서 발전했는지 보다보면 조금 더 이해가 잘간다. 함께 C로 작성된 코드로 함께 알아보자. (대부분이 pseudo 느낌이라 사실 C 를 몰라도 이해하기 쉬울 것이다)

이 포스트에서는 sleep 상태로의 전환 그리고 읽기가 가능할때 다시 깨어나서 값을 출력하는 등을 보여주는데 집중할 것이므로 기타 부수적인 지식이나 사항은 따로 설명하지 않을 예정이다.

Busy waiting

    while (len != 0 && (ret = read(fd, ptr, len)) != 0) {
        if (ret == -1) {
            if (errno == EINTR) {
                continue;
            }
            if (errno == EAGAIN || errno == EWOULDBLOCK) {
                fprintf(stderr, "File is not ready for reading\n");
                sleep(1);
                break;
            }
        }
        if (ret == -1) {
            perror("read");
            break;
        }
        len -= ret;
        ptr += ret;
    }

일단 Blocking 은 대부분 알고 있으니 NonBlocking 부터 시작해보겠다. 기존 Blocking 시스템에서는 file 이 사용가능 할때까지 blocking 이 걸렸으나, nonblocking 은 특수한 에러(EAGAIN or EWOULDBLOCK) 과 같은 에러를 리턴해서 현재 파일 읽기 또는 쓰기가 불가능함을 알려준다. (또는 블락킹을 당할 상황)

따라서 Busy waiting 방식으로 while 문 안에서 계속해서 파일이 사용가능한지를 체크하게 되면 한가지 문제점이 발생한다. 바로 프로세스가 계속해서 Sleep 상태로 들어가지 못하고 일해야 한다는 사실이다. 즉, CPU 를 계속해서 사용하게 된다. (signal 로 구현도 가능하나 복잡하여 이 본문에서는 다루지 않겠다)

이 부분을 해결하기 위해서는 현실적으로 많이 사용하는 “Blocking” 으로 전환하고, 멀티 스레드 혹은 멀티 프로세스 모드로 전환하여 하나의 스레드(또는 프로세스)가 blocking 되더라도 다른 일을 처리 가능하므로 하나의 스레드의 블락킹이 전체 프로그램에 크게 영향을 미치지 않아 보이게 할 수 있다. 다만 이러한 방식은 그 유명한 C10K 문제를 유발하게 된다.

select

그렇다면 프로세스는 원하는 fd 들이 준비될때까지 sleep 상태에 들어가고, fd 들이 쓸수 있는 상태가 되었을때 알림을 받고 일할 수 있다면 어떨까? select 는 이러한 문제를 해결하기 위해 개발되었다.

int  select(int n, fd_set *read_fds, fd_set *write_fds, fd_set *except_fds,
         struct timeval *timeout);

공식문서를 보면 대략적으로 위와 같이 정의되어 있다. (가독성을 위해 인자 이름을 변경하였다)

간단하게 설명하면 우리가 확인하고 싶은 fd 들의 집합(e.g. 1,2,3,4,..) 를 넘기면 커널이 준비된 fd 들의 집합을 리턴해준다. 즉, 읽기가 가능한지 확인하고 싶은 집합, 쓰기가 가능한지 확인하고 싶은 집합 등을 보내면 된다.

read_fds = [1,2,3,4] ======Send======> readable: [1] ======return========> [1]

대략적으로 위와 같이 읽기 가능한 목록을 리턴해준다고 생각하면 된다. 근데 이렇게 배열로 관리하지 않고 fd_set 이라는 특별한 자료구조로 관리하기 때문에 매크로를 이용해서 내가 원하는 fd 가 읽기 가능한지 파악해야 된다. select 에서는 FD_ISSET 이라는 매크로를 지원하는데 이를 통해서 내가 원하는 fd 가 읽기 가능한지 확인 가능하다.

이런식으로 계속해서 읽기 가능한 set 을 알려주므로 select 는 레벨 트리거 라고 불린다.

커널은 이를 어떻게 확인할까? kernel 은 우리가 제공한 fd_set 을 N 번 순회하면서 이를 확인한다. 그래서 select 의 첫번째 인자는 n 을 받고 있는데 이는 우리가 제공한 fd 들 중 가장 높은 fd 에 +1 을 해준 값이다. 즉, kernel 이 내부적으로 0~n 까지 순회하며 이를 확인한다는 것이다. 따라서 기존 방식보다는 효율적이나 계속해서 커널이 N 번 확인이 반복된다는 단점이 존재한다.

실습

이정도만 알면 대략적으로 코드를 작성해볼수 있다. 코드에서 우리 프로세스의 STDIN 이 읽기 가능할때 해당 부분에서 1024 바이트만큼 읽어오는 코드를 작성해보겠다.

#include <stdio.h>
#include <sys/select.h>
#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h>

#define TIMEOUT 5
#define BUF_LEN 1024

int main(void) {
    struct timeval tv;
    fd_set readfds;
    int ret;

    FD_ZERO(&readfds);
    FD_SET(STDIN_FILENO, &readfds);

    tv.tv_sec = TIMEOUT;
    tv.tv_usec = 0;

    ret = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &tv); // (0 ~ nfds - 1)

    if (ret == -1) {
        perror("select");
        return 1;
    } else if (!ret) {
        printf("%d seconds elapsed.\n", TIMEOUT);
        return 0;
    }

    /**
     * File descriptor 에서 즉시 읽기가 가능함.
     */
    if (FD_ISSET(STDIN_FILENO, &readfds)) {
        char buf[BUF_LEN + 1];
        int len;

        len = read(STDIN_FILENO, buf, BUF_LEN);
        if (len == -1) {
            perror("read");
            return 1;
        }

        if (len) {
            buf[len] = '\0'; // null character
            printf("Read %d bytes: %s\n", len, buf);
        }

        return 0;
    }

    fprintf(stderr, "No input available.\n");
    return 1;
}

코드자체는 간단하다. 부분적으로 나눠서 보면 select 부분에서 STDIN_FILENO 가 읽기 가능할때까지 프로세스는 sleep 상태가 될것이고, 커널에서 읽기 가능하다 (FD_ISSET(STDIN_FILENO, &readfds)) 라고 알려주면 byte 를 읽고 정상적으로 종료할 것이다.

바이너리 파일로 만들어서 한번 테스트 해보자.

gcc -o ./bin/test_select 10.c
./bin/test_select < test_pipe

이제 실행했으니 한번 프로세스의 상태를 알아보자. (pipe 는 go 의 channel 같은 느낌으로 이해하면 된다)

ps aux | grep test_select

상태를 출력해보면 아래와 같이 S+ 상태로 나온다.

roach      35347  0.0  0.0   2784  1436 pts/1    S+   14:50   0:00 ./bin/test_select

즉, fore ground 에서 sleep 상태로 있다는 뜻이다. 이제 해당 프로세스에 “hello” 를 입력해서 깨워보자.

echo "hello" > my_input_pipe

이렇게 입력하고 나면 아래와 같이 sleep 상태에서 일어나서 들어온 값을 출력시키고 정상적으로 종료한다.

readable!!
Read 6 bytes: hello

마치며

오늘은 간단하게 리눅스 커맨드들과 함께 프로세스의 상태를 확인하며 select 를 알아보았다. 다음시간에는 poll 과 epoll 등을 알아보려고 한다.

레벨 트리거(level trigger): LLM 의 설명으로는 전압이 1로 올라가게되면 그 상태를 유지하는 구간이 생기게 되는데 높은 레벨의 상태를 유지하는 동안에는 계속 1 을 리턴한다고 해서 특정 상태에 머무르면 트리거 된다고 해서 레벨방식이라고 한다.

• 나는 바이브 코딩이 개발자를 근시일내에 대체할 것이라는 말엔 동감하지 않음

• 현재의 AI Tool 은 단순히 개인 역량을 더 증폭시켜주는 도구라고 생각함

• AI 코딩 에이전트의 성능을 작업 시간으로 재는 것이 유효한가?

• LLM 은 일종의 OS 의 철학적 역할과 비슷하게 구현 상세를 추상화시키는 도구가 될것이라고 생각

들어가며

요새 vibe coding 이라는 말이 되게 평범해졌고, 이제 누구나 노력한다면 간단한 프로토타입은 AI 로 개발할 수 있는 시대가 도래했다. 이런 기술력은 표면적으로는 AI 로 사람을 근시일내에 쉽게 대체할수 있어 보이지만 나는 사실 이러한 AI 신봉자들에 의견에는 크게 동의하지 않는다. 그래서 이런 부분때문에 뭐 공부를 하지 않아야된다 라고 조언하는 사람들 또한 좋아하지 않는다. 이 이야기를 하기 위해서는 내가 AI 를 사용했던 경험들에 대해 이야기 해야 한다.

2022년 인가 2023년 쯤 인가 언젠지는 잘 기억안나지만 Github Copilot 이 나오고 그때 신청해서 엄청나게 썼던 기억이 난다. 개인적으로 계속 쓰다가, 회사 코드에서도 사용을 권장해서 신청하여 회사코드에서도 적용할 방법들을 계속해서 고민했었다. 그래서 배민 내부에서도 Github Copilot 을 잘 쓰는 방법에 대해 3번 정도 사내에서 작거나 크게 공유하는 자리를 가졌었다.

그 당시 코파일럿을 보면서 느꼈던 점은 참 구조화된 일은 잘한다는 것이였다. 예를 들면, given-when-then 으로 테스트 코드를 구조화 시켰을때 Copilot 이 새롭게 테스트 코드를 작성해도 이 given-when-then 을 맞춰서 잘 작성해준다는 것이였다. 즉, 파일 내에서의 일정한 패턴을 인식하고, 이 패턴에 맞게 코드를 작성해주는 것처럼 보였다.

그래서 이 당시에는 코파일럿에게 위와 같이 패턴이 파일내에서 한눈에 보이는 작업들을 많이 시켰다. 이러한 작업은 내가 작성하나 코파일럿이 작성하나 실상 큰 차이가 나지 않았기 때문이다. 이때도 일부 내가 패턴이 보이되 쉽게 반복해서 해야 하는 작업들은 코파일럿에게 넘기는 방법을 많이 연구했었다.

Agent 시대의 도래

그러다가 LLM 기술이 발전하고 컨텍스트 사이즈가 늘어나고 점차 Agent 향으로 발달하면서 확연하게 code assistance 들의 성능이 좋아진게 느껴졌다. 특히 Antropic 의 Claude Code 가 나오고 바로 써봤을때 정말 놀라운 수준의 지능을 가졌다고 느껴지기도 했다.

이정도면 사람들이 많이 쓰겠지? 라는 생각을 가지고 주변 개발자들과 만나는 시간을 가질때 이야기를 자주 했었지만 쓰는 사람이 생각보다 많지 않았다. (쓰는 사람이 나밖에 없을때가 더 많았던거 같다)

그 당시 집에서 혼자 웹 Trading 게임을 바이브코딩만으로 완성시켜보겠다고 클로드 코드랑 놀았던 기억이 있다. 여하튼, 이 당시 사용하지 않는 개발자들과 많이 이야기 해보며 느꼈던 점은 보통 아래와 같았다.

1. AI 기술에 대해 너무 큰 기대를 가지고 있음.

2. Copilot 시절의 auto-completion 기능때문에 Context 를 헤쳤던 안좋은 기억이 많음

3. 그냥 필요가 있다고 느껴지지 않아 안써봄.

AI 로 근시일내 사람이 대체 불가하다고 믿는 이유

AI 기술에 대해 너무 큰 기대를 가지고 있는 그룹에 대해 이야기해보자. 이 경우는 프롬프트를 입력하면 Coding agent 가 뚝딱하고 완벽한 결과를 내놓기를 원한다. 하지만 그건 거의 불가능하다. 이건 나는 지금도 불가능하다고 생각하는데 이 이유는 아래와 같다.

예를 들어, 10억에서 100억건 사이의 문서를 크롤링 해야한다고 해보자. 이걸 AI Agent 에게 시킬때 단순히 아래와 같이 프롬프팅 했다고 해보자.

"내가 특정 페이지들에서 문서를 하루동안 크롤링 할건데, 최대한 이 시간동안에는 중복처리가 안되게 해줘."

그렇다면 중복처리는 어떻게 해야할까? AI agent 가 UUID 를 Unique 키로 이용해 Redis 를 통해 분산 시스템에서도 보장되는 중복처리를 하겠다고 플랜을 작성했다.

{"uuid" : "1"}

위와 같이 하면 충분히 중복처리가 가능할거 같고, 사용자 또한 크게 생각하지 않고 accept 를 누른다. 몇 번의 바이브 코드로 수정하고 동작하자 운영에 배포한다. 운영에 나가면 어떻게 될까? 높은 확률로 Redis 가 정상적으로 동작하지 않게 된다. 일단 저 구조로 10억개가 올라가면 어림잡아 계산 때려도 메모리가 몇십에서 몇백GB 이상이 필요하게 된다. 점점 쌓이다가 결국 죽고 말것이다.

여기서 문제가 이제 발생한다. Vibe coding 으로 저 코드를 accept 한 유저가 이 문제를 발견할 수 있을까? 내 생각에는 높은 확률로 발견하지 못한다. 왜냐면 이걸 accept 한 사람의 코드를 작성하는 판단에는 Memory 에 대한 경험 또는 학습이 부족하기 때문이다.

그리고 어찌어찌 알아내서 개선을 한다해도 이 이후에 개선은 Chat-GPT 또는 또다른 LLM 에 맞겨 진행한다. 이게 정말 Production 에 배포되도 되는 코드인가? 상황에 따라 다르겠지만 대부분의 상황에서 개인적으로는 아니라고 생각한다.

이 이야기를 들으면 반대로 모든 걸 다 디테일하게 챙겨주면 가능하지 않냐는 말을 하는 사람도 있다. 나도 이 부분에는 동의한다. 다만 여기서의 모순은 이 모든걸 다 챙길 사람이라는 리소스가 필요하다는 것이다. 즉, 이 말이 능력이 좋은 한 사람이 여러 Agent 를 활용해 생산성을 높일 수는 있지만, 그 사람을 대체하는 것은 아직은 불가능하다는 뜻이기도 하다.

그러므로 나는 현재의 AI 도구들은 증폭기라고 생각한다. 즉, 결국 LLM 이라는 것도 내가 입력한 토큰 기반으로 답변을 생성해내는 것이기 때문에, Garbage-in Garbage-out 이라는 말과 같이 쓰레기를 넣으면 쓰레기가 나올수 밖에 없다.

AI Agent 를 활용하는 방법

위와 같이 AI Agent 는 LLM 모델의 성능 그리고 내가 입력한 토큰들에 의해 결과가 좌지우지된다. 즉, 비결정적이다. 그래서 AI 와 TDD 를 함께 섞어 테스트로 결정적인 함수[^1]를 만들어서 이 비결정적인 Output 을 테스트하여 최대한 비결정성을 줄이려는 시도들을 하는 것 같다.

이러한 구조적인 방향성에는 크게 동의하며 나 또한 AI 에게 TDD 는 아니지만 Test 는 대부분 수행시키며, 코드 규칙을 따르게 하기 위한 lint 도 시킨다. 어떠한 더 좋은 방향성이 나올지는 모르지만, 사람의 개입으로 비결정적인 방향을 결정성을 지닌 함수에 넣어 빠르게 피드백을 받고 고치게 하는 이러한 방향으로 구조화 되어야 한다고 본다.

구조화 하는 방향과 함께 나의 작업 방향성과 AI 의 방향성이 틀어질 확률 또한 낮춰야 한다고 생각한다. 나 또한 최대한 Planning 과정에서 AI Agent 와 이야기를 많이 하여 대부분의 Planning 과정에서 구현 방향 또한 공유하고, 그걸 토대로 구현을 AI 에게 맡긴다.

이러한 방향에서 계속해서 인간이 개입해야 한다고 보며 개인의 능력에 따라서 AI 가 동일한 토큰을 입력했을때 원하는 답변을 얻을 확률을 줄이는 것이 개인의 역량이라고 본다.

OS 의 철학적 역할을 하게될 AI

위와 같이 AI 가 기초적인 구현을 잘 하게 되다보면 OS 의 철학적 역할과 비슷해질것이라고 본다. 우리는 하드웨어가 어떻게 동작하는지 기초적인 구현체는 잘 모르지만, 아래단계에서 추상화를 통해 구현의 복잡함을 숨겨주기 때문에 우리가 프로그래밍을 할때는 논리에만 집중하여 프로그래밍을 할 수 있게 된다.

나는 AI 들이 발전하면 점차 구체적인 구현작업들은 AI 들이 대부분 해주고, 사람은 오히려 더 추상적인 일들을 많이 하게 될것이라고 믿고 있다. 다만 현재에도 하드웨어를 만들고 더 효율 좋은 좋은 아키텍쳐로 발전하려고 힘쓰는 사람들이 있듯이 이 시간대에도 더 효율성이 좋은 미래의 보편적인 추상화 아래의 부분에서 힘쓰는 사람들이 있을거라고 생각한다.

코딩에이전트를 시간으로 효율을 측정하는게 정말 유효한가?

이렇게 하다보면 특정 작업에서는 내가 코드를 작성할때보다 AI 가 작성할때 시간이 더 걸리는 경우가 있다. 그래서 가끔 AI 코딩 에이전트의 시간 효율성이 인간 작업자에 비해 별로다 라고 이야기하는 리포트들이 나오는데, 나는 시간으로 측정하는게 맞나 싶다.

애초에 이 일을 맡겨 놓으면 나는 이 일에 뇌를 소비하지 않고, 또 다른 작업을 플래닝하는데 뇌를 쓸수 있는 가용시간이 생기는 것이기 때문에, 하나의 Task 를 같이 했을때 시간으로 측정하는건 크게 의미가 없다고 본다. 오히려 AI 도구를 쓰는 사람들이 위와 같이 작업을 하려는 노력을 해야한다고 본다.

마치며

나는 AI 가 앞으로 세상을 많이 바꿀거라고 생각한다. 지금은 극 초기라고 생각하고 앞으로 더 빠르게 바뀔것 같다. 이러한 시기에 내가 장점이라고 생각하는 부분은 기존에는 좋은 기관에 가야만 배울수 있던 부분들을 AI 를 통해 학습하고 실제로 구현해서 실험까지 해보는 것들이다.

실제로 AI 와 대화하면서 많이 생각하고, 실제로 몰랐던 부분들을 직접 구현해보고 테스트해보면서 다른 문제들을 해결할 방법들에 대한 실마리를 얻곤 한다. 평상시 잘 몰랐던 부분들을 AI 와 함께 학습하면서 최근에 실력이 더 빠르게 늘고 있다고 생각한다.

다만, 이러한 과정속에서도 대부분의 구현을 AI 에 맡기기 보다 자신이 원하는 케이스를 반환하도록 AI 를 함수처럼 이용해보거나 반대로 AI 에게 추상적인 부분을 맡기고 자신이 최대한 구현해 보며 구현력을 높이는 방향도 좋다.

아니라면 알고리즘을 풀어보는 연습을 하는 것도 좋다. 알고리즘 문제 풀이가 자신의 논리를 코드로 정확하게 옮기는 힘을 기른다고 생각하기에 이런 부분에서 큰 도움이 된다고 생각한다. 여하튼 AI 세상이 와도 뭐 노동은 가치가 없어진다는 등 나는 이러한 시대가 온다고 말하기에는 현재의 기술수준은 그정도는 아니라고 생각한다. 각자 자기가 할수있는 방향에서 AI 를 쓸수 있다면 써보도 개인의 능력을 키우는데 많이 써보는게 좋다고 생각한다.

그리고 과도한 AI hype 은 경계해야 한다. 그렇게 실제로 일자리를 없앨 기술이라면 이미 개발자는 아예 없어졌어야 한다. 재미있던 부분을 빠르게 공부해보고 잘 가르쳐주는 똑똑한 친구를 얻었다고 생각하면 좋을 것 같다.

[^1]: 테스트는 입력과 기대 출력이 고정되어 있으므로 결정적(deterministic)인 함수처럼 다룬다. 즉, F(Input) = Output 형태로 동일한 입력에 대해 동일한 출력이 나오는지를 검증하는 과정이다.

오늘은 이 LinkedList 를 일정 Block 단위로 묶어 한번에 읽어오고, 이에 대한 순회연산은 메모리 내부에서 진행하는 방식으로 최적화를 진행해보려고 한다.

기본구조

지난시간까지는 노드가 어디에 저장됬는지 offset 을 쫓아 이동했다면, 이제는 Page 를 연속적으로 쫓아 Page 가 어디에 저장됬는지를 찾게 될 것이다. 하나의 페이지사이즈가 4096 일때 이 페이지에 저장될 수 있는 16바이트 크기의 노드 개수는 256개이다. 그렇다면 우리가 페이징 시스템을 적용함으로써 얻을 수 있는 File I/O 의 이상적인 축소치는 아래와 같은 식이 될 것이다. 조금 더 수식적으로 정리해보자.

1. 기본 가정

• 페이지 크기 ($P_{size}$): 4096 bytes

• 노드 크기 ($N_{size}$): 16 bytes

• 기존 I/O 횟수 ($IO_{old}$): 10,000 번

2. 페이지 당 노드 수용량 ($C$) 한 페이지에 저장될 수 있는 노드의 개수는 아래와 같이 계산된다.

$$C = \frac{P_{size}}{N_{size}} = \frac{4096}{16} = 256 \text{ (nodes/page)}$$

3. I/O 감소 효율 계산 페이징 시스템을 적용했을 때 기대할 수 있는 파일 I/O 횟수($IO_{new}$)는 기존 횟수에 페이지 밀집도의 역수를 곱한 것과 같다.

$$IO_{new} = IO_{old} \times \frac{1}{C}$$

$$IO_{new} = 10000 \times \frac{1}{256}$$

$$IO_{new} = 39.0625 \text{ (ops)}$$

결론: 기존에 10,000번 발생하던 디스크 I/O는 페이징 기법을 통해 이론적으로 약 39.06번으로 감소하게 된다.

기존의 File I/O 가 10000 이고, 노드 사이즈는 16, 페이지 사이즈는 4086 인 경우로 가정해보자. 이 경우 페이지당 노드에 256개가 저장되게 되므로 아래와 같이 File/IO 를 줄일 수 있다.

구현

이제 구현부로 들어가보자. 저번 시간에 LinkedList 로 이미 File I/O 에 익숙해졌으므로 개념만 잡는다면 아주 쉽게 구현할 수 있을 것이다. 기본적으로 Page 의 offset 도 알아야 하고, Page 안의 Node 의 offset 도 알아야 할것이다. Page 안의 Node 는 이제부터 Slot 이라고 칭하겠다.

Node 구현

일단 첫번째로 저번시간과 마찬가지로 데이터를 저장할 Node 의 구현체부터 구현해보자. Node 는 uint32 타입의 값을 가지고, 다음 Slot 을 나타내는 NextSlot 과 다음 페이지를 가지는 NextPage 값을 가진다.

여기서 NextPage 를 왜 Node 가 들고있지? Page 가 들고 있어야 할거 같은데? 라는 의문이 들수도 있는데 이 설계의 경우 Page 는 단순히 노드를 관리하고 예제 수준에서의 복잡성 및 I/O 를 줄이기 위해 도입된 것이므로 Node 의 연속적인 탐색을 이어주기 위해 Node 에 NextPage 의 정보도 담도록 하였다. (만약, NextPage 가 조금 더 나은 설계라고 생각되시면 한번 혼자서 구현해보는것도 추천한다.)

type Node struct {
    Value    uint32 // 4 byte
    NextPage uint32 // 4 byte
    NextSlot uint16 // 2 byte
    Tomb     uint8  // 1 byte
    _pad     uint32 // 4 byte
}

Page 구현

이제 Page 에 대해 고민해보자. Page 는 어떠한 정보를 담고 있어야 할까? 사실상 지금 예시에서는 별다른 정보가 필요하지 않으니 얼마나 많은 노드가 있는지를 Length 라고 저장해보자. 이 값은 메타데이터이므로 Page 의 Header 로서 저장된다.

type PageHeader struct {
    Length uint16
}

PageHeader 는 2byte 를 필요로 하므로 읽거나 쓸때 2byte 의 buffer 를 만들어주고 파일 시스템을 통해 쓰거나 읽어오면 된다. 이 부분은 이제 익숙하므로 바로 부가설명없이 코드로 적겠다.

func readPageHeader(f *os.File, pageID uint32) (PageHeader, error) {
    offset := pageOffset(pageID)
    if _, err := f.Seek(offset, io.SeekStart); err != nil {
        return PageHeader{}, err
    }

    buf := make([]byte, PAGE_HEADER_SIZE)
    if _, err := io.ReadFull(f, buf); err != nil {
        return PageHeader{}, err
    }

    var ph PageHeader
    ph.Length = Endian.Uint16(buf[0:2])
    return ph, nil
}

func writePageHeader(f *os.File, pageID uint32, ph PageHeader) error {
    offset := pageOffset(pageID)
    if _, err := f.Seek(offset, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, PAGE_HEADER_SIZE)
    Endian.PutUint16(buf[0:2], ph.Length)

    _, err := f.Write(buf)
    return err
}

다만 Page 의 경우 하나의 메소드가 하나 더 필요하다. Page 가 없을 경우 Used 를 0 으로 Page 를 하나 생성해주어야 한다. Used 를 0 으로 하고 페이지를 하나 생성해서 파일에 써주자.

// 새로운 빈 페이지를 파일에 생성
// - PageHeader(Used = 0) 으로 기록하고 나머지는 0 으로 채움
func initEmptyPage(f *os.File, pageID uint32) error {
    offset := pageOffset(pageID)
    if _, err := f.Seek(offset, io.SeekStart); err != nil {
        return err
    }

    // 페이지 전체를 0 으로 채운다.
    buf := make([]byte, PAGE_SIZE)

    _, err := f.Write(buf)
    return err
}

이제 Page 의 경우 기본적인 Interface 는 완성되었다. 그렇다면 저장소의 메타데이터인 Header 는 어떤 정보가 필요할까? Header 의 경우 이제는 읽어올때 Page 를 읽어오는 옵션이 생겼으므로HeadPage, TailPage 정보가 추가로 필요할 것이다.

Header 구현

type Header struct {
    Magic     [4]byte // Magic: 포맷 식별자 [4]byte{'L', 'L', 'S', 'T'}
    Version   uint16
    PageSize  uint16
    PageCount uint32
    HeadPage  uint32
    HeadSlot  uint16
    TailPage  uint32
    TailSlot  uint16
    Size      uint64
}

우리가 파일을 읽고 쓸때 항상 첫번째 부분은 Header 이므로 Header 에 수정된 부분을 계속해서 업데이트 해주면 된다. Header 를 읽고 쓰는 부분 또한 코드로 적어보자.

func writeHeader(f *os.File, h *Header) error {
    if _, err := f.Seek(0, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, 0, HEADER_SIZE)
    buf = append(buf, h.Magic[:]...)
    buf = Endian.AppendUint16(buf, h.Version)
    buf = Endian.AppendUint16(buf, h.PageSize)
    buf = Endian.AppendUint32(buf, h.PageCount)
    buf = Endian.AppendUint32(buf, h.HeadPage)
    buf = Endian.AppendUint16(buf, h.HeadSlot)
    buf = Endian.AppendUint32(buf, h.TailPage)
    buf = Endian.AppendUint16(buf, h.TailSlot)
    buf = Endian.AppendUint64(buf, h.Size)

    if _, err := f.Write(buf); err != nil {
        return err
    }

    return nil
}

func readHeader(f *os.File, h *Header) error {
    if _, err := f.Seek(0, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, HEADER_SIZE)
    if _, err := io.ReadFull(f, buf); err != nil {
        return err
    }

    copy(h.Magic[:], buf[0:4])

    // Magic 검증
    if h.Magic != Magic {
        return ErrInvalidMagic
    }

    h.Version = Endian.Uint16(buf[4:6])
    h.PageSize = Endian.Uint16(buf[6:8])
    h.PageCount = Endian.Uint32(buf[8:12])
    h.HeadPage = Endian.Uint32(buf[12:16])
    h.HeadSlot = Endian.Uint16(buf[16:18])
    h.TailPage = Endian.Uint32(buf[18:22])
    h.TailSlot = Endian.Uint16(buf[22:24])
    h.Size = Endian.Uint64(buf[24:32])

    return nil
}

딱히 어려운 부분은 없고, 계속해서 사이즈 만큼의 buffer 를 만들고 파일에 적거나 읽는다. 이 부분만 알아두면 된다. 그렇다면 PagedLinkedList 도 저번시간에 만든 LinkedList 와 같이 기본적인 Interface 를 한번 만들어보자.

저장소 Interface 구현

type LinkedListStore interface {
    Open(path string, truncate bool) (*Handle, error)
    AppendTail(h *Handle, value uint32) error
    DeleteFirstByValue(h *Handle, value uint32) (bool, error)
    TraverseValues(h *Handle) ([]uint32, error)
    TraverseValuesPhysical(h *Handle) ([]uint32, error)
    Where(h *Handle, target uint32) (*Location, error)
    Close(h *Handle) error
}

저번 챕터와 메소드는 거의 동일한데 TraverseValuesPhysical 가 추가되었다. TraverseValues 는 Page 를 메모리의 Buffer 로 읽어와 I/O 를 줄이는 버전이고, TraverseValuesPhysical 은 예전처럼 Node 의 Next 를 통해 전체 Node 를 I/O 로 순회하는 버전이다. 차이를 비교하기 위해 만들어 두었다.

읽는 것 보다 쓰는 것을 먼져 생각하면 조금 구조가 쉬우므로 쓸때 어떤 사항을 고려해서 구현해야 할지 생각해보자. 아마 아래와 같은 알고리즘으로 진행될 것이다.

1. 헤더를 읽어 파일에서 Page 위치를 찾는다.

2. 만약 해당 위치에 Page 가 없다면 Page 를 생성하고, 있다면 마지막 Page 정보를 리턴한다. (마지막인 이유는 여유가 있는 페이지는 마지막 페이지이기 때문이다.)

3. 해당 페이지에 노드를 쓸수 없는 경우 (PageHeader.Length >= SLOT_PER_PAGE) 에는 새롭게 페이지를 할당하여 리턴한다.

4. 쓸수 있다면 노드를 어느 위치에 써야하는지 알려주고 Page 정보를 수정한뒤 리턴한다.

5. 노드를 써야하는 위치로 Offset 을 이동시킨다.

6. 새롭게 노드를 생성한 뒤 파일의 해당 위치에 노드를 작성한다.

7. 기존 HeaderNode 가 없었다면 새 Node 로 갱신한다.

8. 기존 TailNode 를 읽어와 기존 TailNode 의 Next 를 현재 노드로 갱신한다.

9. 해더의 정보도 갱신한다.

사실 기존 메커니즘과 크게 다르지는 않다. 다만 새롭게 페이지를 할당하고, 노드에 이 정보를 갱신해야 하는 과정들이 추가되었다. 일단 큰 구현에 앞서 몇가지 먼져 짚고 넘어가야 할 부분이 있다. 우리가 Page 의 위치는 어떻게 추론할 수 있을까?

Page 가 연속적으로 쓰인다는 가정하에 Page 의 위치를 나타내는 ID 를 하나 0부터 시작하는 자연수의 sequence 로 부여 하고 페이지사이즈를 곱하면 해당 페이지의 offset 을 알수 있다.

$$PAGE\_OFFSET = HEADER\_SIZE + PAGE\_ID \times PAGE\_SIZE$$

코드로 구현해보면 아래와 같이 구현될 것이다.

// - 헤더 영역(HeaderSize) 이후에 페이지들이 연속적으로 저장된다고 가정
// - pageID=0 이면 header 바로 뒤에 오는 첫 페이지
func pageOffset(pageID uint32) int64 {
    return int64(HEADER_SIZE) + int64(pageID)*PAGE_SIZE
}

이제 Page 의 위치를 구현하는 부분은 알았으니 Page 안에서 노드의 위치를 구현하는 부분을 계산해보자. Node 또한 Page offset 부터 Page 의 Header 사이즈만큼 이동한 다음 노드의 ID(Slot ID) 에 Node 의 크기를 곱한 부분부터 써주면 된다.

$$NODE\_OFFSET = PAGE\_OFFSET + PAGE\_HEADER\_SIZE + SLOT\_ID \times NODE\_SIZE$$

func writeSlot(f *os.File, pageID uint32, slotID uint16, node Node) error {
    offset := pageOffset(pageID) + PAGE_HEADER_SIZE + SLOT_SIZE*int64(slotID)
    if _, err := f.Seek(offset, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, SLOT_SIZE)
    Endian.PutUint32(buf[0:4], node.Value)
    Endian.PutUint32(buf[4:8], node.NextPage)
    Endian.PutUint16(buf[8:10], node.NextSlot)
    buf[10] = node.Tomb
    Endian.PutUint32(buf[11:15], node._pad) // 의미없는 패딩값 (0 유지)

    _, err := f.Write(buf)
    return err
}

코드로 구현해보니 그다지 어렵지 않다. 그렇다면 이제 Node 를 쓰는 경우를 직접적으로 구현해보자.

// 새 슬롯을 할당하는 함수
// - 마지막 페이지가 존재하고 여유 슬롯이 있으면 그 페이지를 사용.
// - 마지막 페이지가 가득 찼으면 새 페이지를 생성하고 그 페이지의 0번 슬롯을 사용
// - Header 의 PageCount를 증가시킴
func allocateSlot(f *os.File, h *Header) (pageID uint32, slotIndex uint16, err error) {
    if h.PageCount == 0 {
        pageID = 0
        if err = initEmptyPage(f, pageID); err != nil {
            return
        }
        h.PageCount = 1
    } else {
        // 이미 페이지가 하나 이상 있으면, "마지막 페이지" 를 우선 사용
        pageID = h.PageCount - 1
    }

    ph, err := readPageHeader(f, pageID)

    if err != nil {
        return
    }

    if int(ph.Length) >= SLOTS_PER_PAGE {
        pageID = h.PageCount // 새 페이지 번호
        if err = initEmptyPage(f, pageID); err != nil {
            return
        }
        h.PageCount++
        ph.Length = 0
    }

    slotIndex = ph.Length
    ph.Length++
    if err = writePageHeader(f, pageID, ph); err != nil {
        return
    }
    return pageID, slotIndex, nil
}

func (s *PagedStore) AppendTail(handle *Handle, value uint32) error {
    h, err := ensurePagedHeader(handle)
    if err != nil {
        return err
    }
    f := handle.File

    pageID, slotIndex, err := allocateSlot(f, h)
    if err != nil {
        return err
    }

    slotOffset := pageOffset(pageID) + PAGE_HEADER_SIZE + SLOT_SIZE*int64(slotIndex)
    if _, err := f.Seek(slotOffset, io.SeekStart); err != nil {
        return err
    }

    newNode := &Node{
        Value:    value,
        NextPage: NullPage,
        NextSlot: NullSlot,
        Tomb:     0,
        _pad:     0,
    }

    if err := writeSlot(f, pageID, slotIndex, *newNode); err != nil {
        return err
    }

    if h.HeadPage == NullPage {
        h.HeadPage = pageID
        h.HeadSlot = slotIndex
        h.TailPage = pageID
        h.TailSlot = slotIndex
        h.Size++
        return writeHeader(f, h)
    }

    tailNode, err := readSlot(f, h.TailPage, h.TailSlot)

    if err != nil {
        return err
    }

    tailNode.NextPage = pageID
    tailNode.NextSlot = slotIndex
    if err := writeSlot(f, h.TailPage, h.TailSlot, tailNode); err != nil {
        return err
    }

    h.TailPage = pageID
    h.TailSlot = slotIndex
    h.Size++
    return writeHeader(f, h)
}

위에서 설명한대로 페이지의 유/무에 따라 페이지를 생성하고 노드의 위치를 계산하는 allocateSlot 함수와 해당 offset 에 따라 노드를 작성하고 Header 를 갱신하는 부분을 작성해주면 된다.

읽기

이제 쓰기 부분은 마무리 되었고 읽기 부분을 작성해보자. 읽기 부분은 기존과 조금 다른게 Page 단위로 읽어와 이걸 메모리에 올려 Slot 은 메모리에서 순회해야 한다. 따라서 Page 의 정보를 담을 Buffer 가 필요하므로 PageBuffer 라는 구조체를 통해 Page 의 내용을 담도록 하겠다.

type PageBuffer struct {
    pageID uint32 // 현재 버퍼가 담고 있는 페이지 ID
    data   []byte // len == PAGE_SIZE
    valid  bool   // 아직 안 채워졌는지 여부
}

읽을때는 Page 를 읽어와서 Buffer 에 담고 첫번째 노드를 읽어온 후에 첫번째 노드 값의 NextSlot 정보를 통해 순회를 진행해주면 된다. 따라서 첫번째 노드를 읽어오는 메소드가 하나 필요하다.

func readSlotWithBuffer(f *os.File, pb *PageBuffer, pageID uint32, slotID uint16) (Node, error) {
    // 1) 버퍼에 원하는 페이지가 없으면 페이지 전체를 한 번 읽어온다.
    if !pb.valid || pb.pageID != pageID {
        if err := pb.loadPage(f, pageID); err != nil {
            return Node{}, err
        }
    }

    // 2) 페이지 내에서 이 슬롯이 시작하는 오프셋 계산
    //    [PageHeader(2바이트)] [Slot0] [Slot1] ...
    start := PAGE_HEADER_SIZE + int64(SLOT_SIZE)*int64(slotID)

    // 3) buf[start : start+SLOT_SIZE] 부분만 잘라서 파싱
    slotBytes := pb.data[start : start+SLOT_SIZE]

    var node Node
    node.Value = Endian.Uint32(slotBytes[0:4])
    node.NextPage = Endian.Uint32(slotBytes[4:8])
    node.NextSlot = Endian.Uint16(slotBytes[8:10])
    node.Tomb = slotBytes[10]
    node._pad = Endian.Uint32(slotBytes[11:15])

    return node, nil
}

위와 같이 첫번째 노드를 읽어왔으면 그 정보를 통해 아래와 같이 순회해주면 Traverse 메소드가 손쉽게 완성된다.

func (s *PagedStore) Where(handle *Handle, target uint32) (*Location, error) {
    h, err := ensurePagedHeader(handle)
    if err != nil {
        return nil, err
    }
    f := handle.File

    page := h.HeadPage
    slot := h.HeadSlot

    var pb PageBuffer

    for page != NullPage && slot != NullSlot {
        node, err := readSlotWithBuffer(f, &pb, page, slot)
        if err != nil {
            return nil, err
        }

        if node.Tomb == 0 && node.Value == target {
            return &Location{Page: page, Slot: slot}, nil
        }
        page = node.NextPage
        slot = node.NextSlot
    }

    return nil, nil
}

Where 은 순회하는 부분에서 찾는 값이 있다면 위치를 리턴해주기만 하면된다.

비교

이제 기존 메소드와 함께 비교해보자. 약 10000 개의 노드를 순회했을때 발생되는 I/O 횟수를 계측한 것이다. Header 사이즈 등을 고려했을때 우리가 수식으로 계산했던 39와 비슷하게 나오는 것을 확인할 수 있다.

roach@User1:~/btree$ go run chapter02/compare/main.go
List built: Size=10000, PageCount=40
Naive traverse length: 10000
Naive I/O: Reads=10000, Writes=0, Seeks=10000
Buffered traverse length: 10000
Buffered I/O: Reads=40, Writes=0, Seeks=40
Buffered I/O Diff: Reads=-9960, Writes=0, Seeks=-9960

시간 차이는 얼마나 걸릴까? 조금 더 데이터를 늘려 1000000 건으로 테스트 해보자.

roach@User1:~/btree$ go run chapter02/compare/main.go
List built: Size=1000000, PageCount=3922
Naive traverse length: 1000000
Naive I/O: Reads=1000000, Writes=0, Seeks=1000000
Naive traverse time: 1.319998672s
Buffered traverse length: 1000000
Buffered I/O: Reads=3922, Writes=0, Seeks=3922
Buffered traverse time: 30.416243ms
Buffered I/O Diff: Reads=-996078, Writes=0, Seeks=-996078

Naive 의 경우 1.31 초 가량이 걸렸는데 Buffered 의 경우 0.03 초 가량밖에 안걸림을 확인할 수 있다. I/O 가 얼마나 비싼작업인지 내심 확인해 볼수 있는 지표이다.

마치며

이번 챕터에서는 Page 와 같은 블록단위로 관리하는 방법을 통해 메모리에 올려 빠르게 읽으며 I/O 를 줄이는 방법을 알아보았다. 다음시간에는 근본적으로 시간 복잡도를 줄이는 BinaryTree 를 이용해서 시간복잡도 까지 줄여보는 작업을 진행해보려고 한다.

인터페이스 정의

type Handle struct {
    File   *os.File
    Header HeaderRecord
}

type HeaderRecord interface {
    headerVersion() uint16
}

type LinkedListStore interface {
    Open(path string, truncate bool) (*Handle, error)
    AppendTail(h *Handle, value uint32) error
    DeleteFirstByValue(h *Handle, value uint32) (bool, error)
    TraverseValues(h *Handle) ([]uint32, error)
    Close(h *Handle) error
}

일단 작업하기에 앞서 필수적인 Interface 들 부터 정의하고 작업을 시작하자. 우리는 LinkedListStore 라는 아래와 같은 연산을 지원하는 저장소를 만들것이다.

• AppendTail: 제일 마지막에 value 를 저장하는 연산과

• DeleteFirstByValue: 첫번째 값을 삭제하는 연산(중복값 저장 가능시)

• TraverseValues: 그리고 값을 순회하는 연산을 지원한다.

Handle 구조체는 파일을 관리하는 역할을 하며 우리는 앞으로 이 저장소의 Header 를 버저닝하여 업그레이드 할 것이기 때문에 headerVersion() 이라는 함수도 하나 추가해준다.

참고로 지난 시간과 마찬가지로 Endian 은 BigEndian 을 의미한다.

Header 정의

type Header struct {
    Magic      [4]byte // Magic: 포맷 식별자 [4]byte{'L', 'L', 'S', 'T'}
    Version    uint16 // Version: 버전
    PageSize   uint16 // PageSize: 추후에 페이지네이션으로 업그레이드 할때 이용
    HeadOffset int64 // HeadOffset: 첫 노드의 파일 오프셋(없으면 -1)
    TailOffset int64 // TailOffset: 마지막 노드의 파일 오프셋(없으면 -1)
    Size       int64 // Size: 통계 / 검증 용도
}

Header 는 우리가 저장한 시스템이 어떻게 이루어져있는지 나타낸다. Version, PageSize 는 지금 챕터에서는 중요하지 않기 때문에 현재 Chapter 에서 중요한 HeadOffset, TailOffset 을 보자.

우리가 LinkedList 를 구현할때는 위와 같이 Head 에 대한 정보가 필요하다. 어디서 부터 우리가 순회를 시작해야 할지 알아야 하기 때문에 Head 정보를 알아야 한다. 마찬가지로 우리가 AppendTail 같은 함수를 구현할때는 Head 에서 부터 시작해서 Tail 을 찾는 것보다, Tail 을 항상 관리해서 AppendTail 이 O(1) 시간안에 이뤄지게 하는 것이 낫다.

Node 정의

const nodePadBytes = 3

type Node struct {
    Value uint32             // - Value: 실제 값(32비트 정수; 예제 단순화를 위해 uint32 이용)
    Next  int64              // - Next: 다음 노드의 파일 오프셋 (없으면 -1)
    Tomb  uint8              // - Tomb: 논리 삭제 마크 (0 == 유효, 1 == 삭제됨). 물리 삭제는 하지 않음
    _pad  [nodePadBytes]byte // - _pad: 16 바이트 정렬을 위해 3바이트 패딩 (읽기 쉬운 고정 길이 유지)
}

Node 정의는 간단하다. Value 는 우리가 저장할 값인 unit32 를 정의하고 Next 는 다음 노드의 파일 오프셋이 저장될 것이므로 int64 를, Tomb 는 논리 삭제 마크(is_deleted) 로 0 과 1 을 저장한다. _pad 는 Node 를 깔끔하게 16바이트로 저장하기 위해 3byte padding 을 일부러 주었다.

메소드 구현

Header 쓰기

이제 Header 를 쓰는 함수를 먼져 구현해보자. 저번 offset 시간에도 배웠듯이 무언가를 쓰는 경우 해당 값을 쓸만큼의 buffer 를 먼져 생성해주어야 한다. Header 의 경우 4byte+2byte+2byte+8byte+8byte+8byte 로 총 32 바이트가 필요하다.

buf := make([]byte, 0, 32)

이제 이 buffer 에 쓰는 작업은 아주 쉽다.

func writeHeader(f *os.File, hdr *Header) error {
    if _, err := f.Seek(0, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, 0, 32)
    buf = append(buf, hdr.Magic[:]...)
    buf = Endian.AppendUint16(buf, hdr.Version)
    buf = Endian.AppendUint16(buf, hdr.PageSize)
    buf = Endian.AppendUint64(buf, uint64(hdr.HeadOffset))
    buf = Endian.AppendUint64(buf, uint64(hdr.TailOffset))
    buf = Endian.AppendUint64(buf, uint64(hdr.Size))

    _, err := f.Write(buf)
    return err
}

buffer 를 생성하고 BigEndian 의 함수를 이용하여 각 byte 크기에 맞게 byte 배열의 마지막에 값을 추가한뒤에 buffer 의 값을 파일에 쓴다.

Header 읽기

func readHeader(f *os.File, h *Header) error {
    if _, err := f.Seek(0, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, 4+2+2+8+8+8)

    if _, err := io.ReadFull(f, buf); err != nil {
        return err
    }

    copy(h.Magic[:], buf[0:4])

    // Magic 검증
    if h.Magic != Magic {
        return ErrInvalidMagic
    }

    h.Version = Endian.Uint16(buf[4:6])
    h.PageSize = Endian.Uint16(buf[6:8])
    h.HeadOffset = int64(Endian.Uint64(buf[8:16]))
    h.TailOffset = int64(Endian.Uint64(buf[16:24]))
    h.Size = int64(Endian.Uint64(buf[24:32]))

    return nil
}

Header 를 읽는 과정 또한 쉽다. 우리는 항상 파일의 가장 앞부분에 Header 를 쓸것이기 때문에, Header 크기만큼(32) 읽어온다. 읽어온 뒤에 Uint16 과 같은 함수로 buffer 에서 각 값이 가진 크기에 맞게 byte 배열을 추출하여 원하는 type 으로 변환한다.

이 구현부에서 Header 를 내부에서 생성해서 Return 하는 과정도 좋았을것 같다라는 생각이 들었다.

저장소 열기

이제 Interface 의 함수 중 하나인 Open 을 구현해보자. 우리가 저장소를 열때 원하는 결과는 무엇일까? 바로 우리가 탐색 또는 저장을 위해 필요한 Header 정보를 얻어오는 것이다. 따라서 Handle 의 정보를 얻어와야 할것이므로 아래와 같은 함수일 것이다.

Open(path string, truncate bool) (*Handle, error) // truncate 는 테스트 용으로 시작시 파일을 지우는 용도이다.

그렇다면 이 Open 또한 어렵지 않게 구현해 볼 수 있다.

func (s *OffsetStore) Open(path string, truncate bool) (*Handle, error) {
    flags := os.O_RDWR | os.O_CREATE
    if truncate {
        flags |= os.O_TRUNC
    }
    f, err := os.OpenFile(path, flags, 0666)
    if err != nil {
        return nil, err
    }

    info, err := f.Stat()
    if err != nil {
        f.Close()
        return nil, err
    }

    if info.Size() == 0 || truncate {
        hdr := &Header{
            Magic:      Magic,
            Version:    1,
            PageSize:   DefaultPageSize,
            HeadOffset: NullOffset,
            TailOffset: NullOffset,
            Size:       0,
        }
        if err := writeHeader(f, hdr); err != nil {
            f.Close()
            return nil, err
        }
    }

    hrd := &Header{}

    if err := readHeader(f, hrd); err != nil {
        f.Close()
        return nil, err
    }

    return &Handle{
        File:   f,
        Header: hrd,
    }, nil
}

코드가 복잡해보일수 있는데 생각보다 간단하다. 첫번째 부분은 "파일을 열거나 생성 또는 Truncate" 시키는 부분이다. 그리고 두번째 부분은 만약 "파일을 열었는데 빈 파일이거나, truncate 플래그라면" 우리가 헤더 정보를 넣어야 하므로 Header 를 생성한다. Header 를 생성했다면 기존에 만든 writeHeader 를 통해 파일에 써주면 된다.

만약 이미 값이 있는 데이터베이스라면 위와 같은 행위를 하지 않아도 되므로 readHeader 함수를 통해 Header 를 읽어온다. 이 함수를 통해서 Header 가 없는 경우에는 써주고, 있는 경우에는 읽어와서 Handle 구조체에 Header 와 file 정보를 넣어 리턴해준다.

여기까지는 offset 에 익숙하다면 쉬울 것이다. 만약 익숙하지 않다면 offset 을 읽고 조금 더 이해해보길 바란다. 이제 Node 도 저장하고 읽어와 보자.

Node 쓰고 읽기

const nodeOnDiskSize = 4 + 8 + 1 + nodePadBytes

func writeNodeAt(f *os.File, off int64, n *Node) error {
    if _, err := f.Seek(off, io.SeekStart); err != nil {
        return err
    }

    buf := make([]byte, nodeOnDiskSize)

    Endian.PutUint32(buf[0:4], uint32(n.Value))
    Endian.PutUint64(buf[4:12], uint64(n.Next))
    buf[12] = byte(n.Tomb)

    if _, err := f.Write(buf); err != nil {
        return err
    }

    return nil
}

func readNodeAt(f *os.File, off int64) (*Node, error) {
    if _, err := f.Seek(off, io.SeekStart); err != nil {
        return nil, err
    }

    buf := make([]byte, nodeOnDiskSize)

    if _, err := io.ReadFull(f, buf); err != nil {
        return nil, err
    }

    n := &Node{
        Value: Endian.Uint32(buf[0:4]),
        Next:  int64(Endian.Uint64(buf[4:12])),
        Tomb:  buf[12],
    }

    return n, nil
}

이제 byte 로 읽고 쓰는 부분은 익숙할테니 한번에 적도록 하겠다. Node 도 마찬가지로 Node 의 크기만큼 buffer 를 생성하고 읽거나 쓴다. 간단하게 설명하면 writeNodeAt 함수는 원하는 위치(offset) 에 Node 를 기록한다. readNodeAt 은 해당 offset 만큼 이동한뒤에 해당 offset 에서부터 nodeSize 만큼 읽어서 buffer 에 저장한다.

아마 익숙할거라 이 부분에 대해서는 더 설명하지는 않겠다. 이제 Node 와 Header 를 읽고 쓰는 부분은 마무리 됬으니 어떻게 Node 를 LinkedList 끝에 옮기는 연산을 계속할지 생각해보자.

AppendTail

AppendTail 을 생각해보면 아래와 같은 알고리즘으로 구현될 것이다.

1. 일단 첫번째로 파일의 처음 부분에서 Header 를 읽어온다.

2. 새롭게 value 를 담은 Node 를 생성한다.

3. 파일의 끝 Offset(io.SeekEnd) 에 Node 를 기록한다.

4. 기존 Tail Node 를 읽기 위해 Header 에 기록된 TailOffset 으로 이동해서 Tail Node 를 읽어온다.

5. 기존 TailNode 의 Next 로 새롭게 생성된(newNode) 가리킨다.

6. 기존 Header 의 TailOffset 을 새롭게 생성된 노드의 오프셋으로 바꾼다.

• 만약 과정 도중 Header 가 없는 경우 새롭게 노드를쓴다!

이정도 알고리즘으로 진행이 될 것이다. 코드로 작성해보면 아주 쉽게 확인해 볼 수 있다.

func (s *OffsetStore) AppendTail(handle *Handle, value uint32) error {
    h, err := ensureOffsetHeader(handle)
    if err != nil {
        return err
    }
    f := handle.File

    newNode := &Node{
        Value: value,
        Next:  NullOffset,
        Tomb:  0,
    }

    newOff, err := f.Seek(0, io.SeekEnd)
    if err != nil {
        return err
    }

    if err := writeNodeAt(f, newOff, newNode); err != nil {
        return err
    }

    if h.HeadOffset == NullOffset {
        h.HeadOffset = newOff
        h.TailOffset = newOff
        h.Size++
        return writeHeader(f, h)
    }

    // 기존 tail 노드의 Next 를 새 노드의 Next 로 설정
    tailNode, err := readNodeAt(f, h.TailOffset)
    if err != nil {
        return err
    }

    tailNode.Next = newOff
    if err := writeNodeAt(f, h.TailOffset, tailNode); err != nil {
        return err
    }

    h.TailOffset = newOff
    h.Size++

    return writeHeader(f, h)
}

아마 알고리즘을 먼져익히고 코드를 보면 이해가 쉽게 갈 것이다. 그렇다면 탐색은 어떨까? 탐색도 동일하다.

func (s *OffsetStore) TraverseValues(handle *Handle) ([]uint32, error) {
    h, err := ensureOffsetHeader(handle)
    if err != nil {
        return nil, err
    }
    f := handle.File

    out := make([]uint32, 0, h.Size)
    off := h.HeadOffset

    for off != NullOffset {
        node, err := readNodeAt(f, off)
        if err != nil {
            return nil, err
        }
        if node.Tomb == 0 {
            out = append(out, node.Value)
        }
        off = node.Next
    }
    return out, nil
}

파일을 열고 Header 에서 HeadOffset 을 읽어온 뒤에 NullOffset 에 도달할때까지 순회를 계속하며 Next Offset 으로 이동하며 Node 들을 읽어온다. (단. Tomb == 1 죽은 노드들은 제외한다.)

여기서 값을 찾는다면?

만약이 LinkedListStore 에서 특정 값을 찾는다면 시간복잡도가 얼마나 소비될까? LinkedList 의 복잡도인 O(N) 만큼 소비될 것이다. 왜냐면, Header 로 부터 시작해서 Next 들을 순회하며 마지막 노드까지 도달할 수 있기 때문이다. 코드는 간단하게 아래와 같이 작성해 볼수 있을 것이다.

func (s *OffsetStore) Where(handle *Handle, target uint32) (int64, error) {
    h, err := ensureOffsetHeader(handle)
    if err != nil {
        return 0, err
    }
    f := handle.File

    off := h.HeadOffset

    for off != NullOffset {
        node, err := readNodeAt(f, off)
        if err != nil {
            return 0, err
        }
        if node.Tomb == 0 && node.Value == target {
            return off, nil
        }
        off = node.Next
    }
    return NullOffset, nil
}

여기서 또 하나의 문제가 생긴다. O(N) 의 시간복잡도가 드는것도 문제지만 사실 파일을 읽는 I/O 작업은 상당히 헤비한 작업이다. 이 파일을 읽는 작업또한 오래걸릴 수 있다는 것이다. 여기서 어떻게 조금 더 최적화 해볼수 있을까?

떠오르는 방법으로는 만약 정렬된 순서라면 1~5 까지 노드의 HeadOffset 과 TailOffset 을 저장하고, 5~10, 10~15까지를 메모리에 Key-Value 상태로 인덱싱하고, 해당 Value 는 Offset 이므로 해당 그룹에서만 순회를 진행하는 것이다. 그렇게 되면 전체 크기에서 격자로 나눈 만큼이 M 이라면 O(N/M) 의 평균 시간복잡도로 변할것이고, 파일 I/O 또한 줄게된다.

이러한 방식을 생각하다보면 결국 Node 를 묶어서 관리하고 해당 그룹의 Offset 을 관리해야겠다는 생각이 든다. 따라서 다음 글에서는 이를 Page 라는 단위로 묶고, Node 는 Page 하부의 Slot 으로 관리하여 File I/O 를 줄이고, 메모리에서 순회하여 I/O 자체를 줄여보는 최적화를 진행해보겠다.

Go를 쓰다 보면 “인터페이스가 뭔가 다른 언어와 다르게 신기하게 쓰이는 구나” 하는 순간이 종종 있다. 특히 제네릭이 없던 시절의 Go 코드를 보면 아래처럼 interface{}를 마치 만능 컨테이너처럼 쓰는 코드가 흔했다.

var values []interface{}
values = append(values, 10)
values = append(values, "hello")
values = append(values, []int{1, 2, 3})

그리고 나중에 이런 식으로 타입에 따라 분기한다.

func Print(v interface{}) {
    switch x := v.(type) {
    case int:
        fmt.Println("int:", x)
    case string:
        fmt.Println("string:", x)
    case []int:
        fmt.Println("slice:", x)
    default:
        fmt.Printf("unknown type: %T\n", x)
    }
}

정적 타입 언어에서 이렇게 “무한정 아무 타입이나 넣고 꺼내는" 구조가 되는 건 꽤 놀랍다. 이게 어떻게 가능할까? 이 질문의 진짜 핵심은 Go 인터페이스의 내부 구조에 있다.

eface / iface

Go 언어는 인터페이스를 두 가지 형태로 나누어 구현하고 있다.

• eface: 빈 인터페이스 (interface{})

• iface: 메서드가 있는 인터페이스

이 두 구조를 알면 Go 인터페이스를 이해하는데 큰 도움이 된다.

eface — 빈 인터페이스 (interface{})

Go 런타임에 정의된 eface 구조체는 정말 단순하다.

type eface struct {
    typ  *_type         // dynamic type metadata
    data unsafe.Pointer // pointer to actual data
}

interface 값은 정적 타입이 interface이지만, 내부에는 “구체 타입 + 값”이 살아 있다.

예를 들어:

var x interface{} = 10

런타임 구조는 다음과 같다:

x = (type=*int, data=&10)

이 사실 하나만 이해해도 왜 여러 타입을 한 slice에 넣을 수 있는지 왜 type assertion이 가능한지 왜 JSON 언마샬 결과가 map[string]interface{} 인지 왜 reflect가 interface 기반으로 동작하는지 전부 설명된다.

iface — 메서드가 있는 인터페이스

예를 들어:

type Reader interface {
    Read([]byte) (int, error)
}

이런 인터페이스는 메서드 테이블(itab)을 포함하는 iface 구조를 사용한다.

type iface struct {
    tab  *itab
    data unsafe.Pointer
}

itab 안에는 아래와 같은 정보들이 존재한다.

• 인터페이스 정보

• 구체 타입 정보

• 인터페이스가 요구하는 메서드들의 함수 포인터(jump table)

var r io.Reader = bytes.NewBuffer([]byte("hi"))
r.Read(buf)

그래서 위와 같은 코드를 실행시켜보면 런타임에서 실제로는

itab.funcs[0](data, buf)

이런 식으로 메서드가 호출된다.

nil interface trap

이제 구조를 봤으니 이 trap도 제대로 이해할 수 있다.

var x interface{} = (*User)(nil)

fmt.Println(x == nil) // false

왜 false일까? 인터페이스가 “진짜 nil”이 되려면 typ == nil && data == nil 이 되어야 한다. 그러나 위 코드는 x = (typ = *User, data = nil) 이다. 즉, type 포인터는 살아있고 data는 nil 이기 때문에 interface 전체는 nil이 아니다.

실제 메모리 구조를 직접 확인

package main

import (
    "fmt"
    "unsafe"
)

type eface struct {
    typ  uintptr
    data uintptr
}

func dump(label string, v interface{}) {
    p := (*eface)(unsafe.Pointer(&v))

    fmt.Printf("[%s]\n", label)
    fmt.Printf("  interface address : %p\n", &v)
    fmt.Printf("  type pointer      : 0x%x\n", p.typ)
    fmt.Printf("  data pointer      : 0x%x\n", p.data)

    // data를 실제 타입으로 역참조할 수 있는 경우 출력
    if p.data != 0 {
        fmt.Printf("  data as int?      : %d\n", *(*int)(unsafe.Pointer(p.data)))
    }
    fmt.Println()
}

func main() {
    dump("int", 10)
    dump("string", "hello")
    dump("slice", []int{1, 2, 3})

    var u *int = nil
    dump("nil pointer in interface", u)

    var x interface{}
    dump("true nil interface", x)
}

실행 결과

[int]
  interface address : 0x140000a4010
  type pointer      : 0x102a924c0
  data pointer      : 0x102a83538
  data as int?      : 10

[string]
  interface address : 0x140000a4030
  type pointer      : 0x102a92280
  data pointer      : 0x102aad068
  data as int?      : 4339381145

[slice]
  interface address : 0x140000a4050
  type pointer      : 0x102a912e0
  data pointer      : 0x140000aa000
  data as int?      : 1374390214680

[nil pointer in interface]
  interface address : 0x140000a4070
  type pointer      : 0x102a8f260
  data pointer      : 0x0

[true nil interface]
  interface address : 0x140000a4090
  type pointer      : 0x0
  data pointer      : 0x0

nil pointer in interface 의 경우 type pointer 값이 존재하므로 interface 자체는 nil이 아니다. true nil interface 의 경우 type/data 둘 다 nil일 때만 진짜 nil 이다.

자주보이는 interface pattern들

여러 타입을 한 컨테이너에 담기 ([]interface{})

eface 구조 덕분에 어떤 타입이든 담을 수 있다.

list := []interface{}{1, "hello", []int{1,2,3}}

dynamic type이 살아있으니 type switch로 잘 처리된다.

type switch로 다형성 처리

switch v := x.(type) {
case int, string:
    ...
}

interface 내부 type pointer 비교만 하므로 성능도 꽤 빠른 편이다.

JSON / YAML 동적 구조 (map[string]interface{})

Go의 정적 타입 구조상, JSON 같은 문서 기반 구조를 표현하려면 value를 interface로 받을 수밖에 없다. 그리고 자연스럽게 type switch로 핸들링한다.

error 인터페이스 기반 다형성

type error interface {
    Error() string
}

iface 구조 덕분에 다양한 에러 타입을 단일 인터페이스로 다루고, wrapping/unwrapping도 dynamic type 정보 기반으로 자연스럽게 구현된다.

그렇다면 문제는 없을까?

얼핏 보기에 정적 타입 내부에서 꽤나 자유롭게 Interface 를 이용할 수 있어 보인다. 하지만 escape analysis 에 의한 interface 타입의 heap allocation 이 발생할 수 있다. 아마 rust 를 공부했던 사람들은 익숙할 수 있는데 이 heap allocation 을 이해하기 위해 아래 예시를 함께 보자.

func f() interface{} {
    x := 10
    return x
}

위 함수를 보면 x 에 정수(int) 값 10을 할당하고 return type 으로 interface{} 타입을 반환한다. 우리의 상식으로는 int 는 정수값으로 원래 스택 변수이기 때문에 heap allocation 이 발생하지 않을 것 같지만, 실제로는 heap allocation 이 발생한다. 이는 escape analysis 에 의한 interface 타입의 heap allocation 이 발생하기 때문이다.

이유는 무엇일까? 예를 들어 a = f() 라는 부분이 외부에 있다고 해보자. 그런데 x 의 값이 사라지면 interface 의 data pointer 가 dangling pointer 가 되어버린다. 따라서 컴파일러는 이를 최대한 안전하게 처리하기 위해 heap 에 올려버린다.

x escapes to heap because it’s stored in interface

실제 예시와 go build 에서 flag 를 통해 확인해보자

package main

func aa() interface{} {
    x := 100
    return x
}

func main() {
    a := aa()
    _ = a
}

❯ go build -gcflags="-m" interface_prac/main.go
# command-line-arguments
interface_prac/main.go:3:6: can inline aa
interface_prac/main.go:8:6: can inline main
interface_prac/main.go:9:13: inlining call to aa
interface_prac/main.go:5:9: 100 escapes to heap
interface_prac/main.go:9:13: 100 does not escape

위와 같이 100 이 heap 으로 escape[^1] 되는 것을 확인할 수 있다. 만약 int 타입으로 리턴됬다면 어떨까?

package main

func aa() int {
    x := 100
    return x
}

func main() {
    a := aa()
    _ = a
}

❯ go build -gcflags="-m" interface_prac/main.go
# command-line-arguments
interface_prac/main.go:3:6: can inline aa
interface_prac/main.go:8:6: can inline main
interface_prac/main.go:9:9: inlining call to aa

int 를 리턴하는 경우에는 위 예시처럼 escape 가 일어나지 않음을 확인할 수 있다. inlining call to escape[^2] 는 escape analysis 와 무관하다.

[^1]: “100 escapes to heap”은 x 변수가 escape했다는 뜻이 아니다. literal 100 자체가 interface wrapping 과정에서 힙으로 복사된 것이다. 함수의 반환 타입이 interface이기 때문에 literal은 임시 메모리에 둘 수 없어서 힙으로 올라가는 것이다.

[^2]: 여기서 “inlining call to aa”는 escape analysis와 무관하다. 단순히 컴파일러가 aa() 함수를 main 함수 안으로 인라인 최적화 한 것뿐이다. escape 여부는 '100 escapes to heap' 같은 별도의 메시지에서 판별된다.

[1, 2, 3] => [0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x03]

각 정수를 4 Byte 로 이어 붙이는걸 생각해볼 수 있다. 다만 여기서 byte 로 변환한 것을 어떻게 적어야 할지 고민해볼 수 있다. 예를 들어 [1] => [0x00, 0x00, 0x00, 0x01] 으로 적는 사람도 있을 것이고, [1] => [0x01, 0x00, 0x00, 0x00] 으로 적는 사람도 있을 것이다.

실제로 이러한 사유때문에 매핑(mapping) 방식이 별도로 존재하게 된다. [0x00, 0x00, 0x00, 0x01] 에서 0x00 을 가장 상위 바이트(MSB) 라고 표현하고, 0x01 을 가장 하위 바이트(LSB) 라고 표현한다. 메모리는 일반적으로 0x00, 0x01, 0x02, … 와 같이 증가하므로 이 상위 바이트에서 하위 바이트의 흐름을 어떻게 메모리 주소상에 맵핑할지를 나타내는 방식을 엔디안(Endian) 이라고 한다.

BigEndian

네트워크나 포맷에서 자주 쓰는BigEndian 은 상위 바이트(MSB) 를 메모리에 낮은 주소(앞쪽)에 쓰는 방식이다. 즉, [0x00, 0x00, 0x00, 0x01] 이 된다.

LittleEndian

그와 반대로 LittleEndian 은 하위 바이트(LSB) 를 메모리의 낮은 주소(앞쪽)에 쓰는 방식이다. 따라서, [0x01, 0x00, 0x00, 0x00] 이 된다.

왜 이렇게 세분화 되어 있는걸까? 그 이유는 네트워크 프로토콜, CPU 아키텍쳐 마다 이와 같이 맵핑하는 방식이 다르기 때문이다. 따라서 이를 잘 인지하는 것이 중요하다. 다른 맵핑 방식으로 읽게 되면 아예 다른 값으로 해석될 수 있기 때문이다.

Go lang 에서는?

Golang 에서는 이를 어떻게 처리할까? binary.BigEndian.PutUint32 를 사용하면 쉽게 인코딩이 가능하다. 예시를 위해 정수값을 4 바이트로 변환하여 byte 로 변환한다고 해보자. 첫번째로 해야할 일은 무엇일까? 바로 len(nums) * 4 만큼의 byte 배열을 확보해주는 것이다.

buffer := make([]byte, 4*len(nums))

이후에는 binary.BigEndian.PutUint32 을 이용하면 쉽게 4byte 배열에 맞게 들어가도록 변환 가능하다.

// PutUint32 stores v into b[0:4].
func (bigEndian) PutUint32(b []byte, v uint32) {
    _ = b[3] // early bounds check to guarantee safety of writes below
    b[0] = byte(v >> 24)
    b[1] = byte(v >> 16)
    b[2] = byte(v >> 8)
    b[3] = byte(v)
}

여기서 “비트연산” 이 생소하면 이 부분이 잘 이해가 안갈 수 있는데, 이 연산(right shift) 은 간단하게 비트를 오른쪽으로 미는 역할을 한다. 이 부분을 잘 이해하지 못하면 앞으로 시리즈가 어려우므로 예시를 들고 넘어가 보겠다.

비트연산(부가 설명)

예를 들어 어떤 수를 이진수로 변환했는데 00010010 00110100 01010110 01111000 과 같이 나왔다고 해보자. 우리가 이걸 4byte 에 하나하나 담으려면 어떻게 해야할까? 이럴때 비트 연산을 사용하면 쉽다. 첫번째로 00010010 을 담으려면 총 24번 오른쪽으로 밀어야 00000000 00000000 00000000 00010010 형태가 된다. (정확히는 shift 연산이지만 이해를 위해 민다는 표현을 차용했다)

즉, 이 상태에서 1 byte = 8bit 이므로 byte (v >> 24) 를 하게 되면 byte 는 00010010 을 가지게 된다. 나머지도 똑같다. 즉 담고 싶은 부분을 마지막 8bit 로 만들기 위해 shift 연산을 하는 것이다. 이해가 갔다면 스스로 Little-endian 방식도 한번 구현해보길 바란다.

import "encoding/binary"

func IntSliceToBytes(nums []uint32) []byte {
    buffer := make([]byte, 4*len(nums))
    for i, n := range nums {
        binary.BigEndian.PutUint32(buffer[i*4:], n)
    }
    return buffer
}

본문으로 돌아와서 다시 코드를 보면 이제 이 코드가 어떤 동작을 하는지 명확하게 이해갔을 것이다. 그렇다면 이제 이 byte 들을 파일에 쓰는 작업을 진행해보자.

파일(os.File)

일단 운영체제는 우리가 적어놨던 파일 또는 데이터들을 어떻게 읽고 가져올까? 우리가 파일을 읽을때 파일 전체를 로드해서 가져올까? 아니면 부분만 읽어서 가져올까? OS 를 공부해봤다면 들어봤겠지만 운영체제는 블럭단위로 파일을 읽게 된다.

그렇다면 운영체제는 이를 어떻게 나눠서 읽는걸까? 예를 들어 우리가 10KB 짜리 파일을 읽는데 1KB 블럭단위로 이 페이지를 읽어온다고 해보자. 첫번째로 1KB 를 읽고, 다음 부터는 마지막으로 읽은(1024~2048) 까지를 읽어야 할 것이다.

오프셋(Offset)

이를 위해 파일에서 어디까지 읽었는지를 알려주는 오프셋(Offset) 을 필요로 하게 되었고, 이는 파일 포인터에 값으로 저장되어 있다. 코드로 보면 조금 더 수월하게 이해할 수 있으니 코드로 한번 작성해보면서 알아보자.

    f, err := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE, 0666) // 파일을 생성

    if err != nil {
        panic(err)
    }

    arr := make([]uint32, 12) // 정수형 배열(우리가 쓸값)
    buf := make([]byte, 12*4) // 정수형 배열을 byte 로 변환할때 사용할 buffer (len(nums) * 4)

    for i := 0; i < 12; i++ {
        arr[i] = i
    }

    n, err := f.Write(IntSliceToBytes(arr))

파일을 쓰기 위해 파일을 생성하고, 우리가 원하는 정수 배열을 byte 배열로 전환한 다음에 f.Write(b byte[]) 를 통하여 해당 파일에 값을 쓰게 된다. 값을 쓸때 우리는 0번째 부터 48번째까지 offset 을 옮겨가며 파일에 값을 기록하게 된다.

    _, err = f.Read(buf)

    if err != nil {
        panic(err)
    }

    fmt.Printf("%v\n", BytesToIntSlice(buf))

// error    
panic: EOF

goroutine 1 [running]:
main.main()
        /home/roach/btree/file/main.go:51 +0x246
exit status 2

만약에, 우리가 이를 생각하지 않고 여기서 바로 Read 메소드를 호출하게 되면 어떻게 될까? 우리는 당연하게도 0번부터 읽을 것 같지만 offset 부터 읽게 된다. 즉, 48번째 부터 읽게 되므로 우리는 EOF 라는 에러를 마주하게 된다.

Seek 메소드

// Seek sets the offset for the next Read or Write on file to offset, interpreted
// according to whence: 0 means relative to the origin of the file, 1 means
// relative to the current offset, and 2 means relative to the end.
// It returns the new offset and an error, if any.
// The behavior of Seek on a file opened with O_APPEND is not specified.
func (f *File) Seek(offset int64, whence int) (ret int64, err error) {
    if err := f.checkValid("seek"); err != nil {
        return 0, err
    }
    r, e := f.seek(offset, whence)
    if e == nil && f.dirinfo.Load() != nil && r != 0 {
        e = syscall.EISDIR
    }
    if e != nil {
        return 0, f.wrapErr("seek", e)
    }
    return r, nil
}

따라서 이러한 문제를 마주하지 않기 위해서는 offset 을 우리가 원하는 위치로 이동시켜야 한다. Seek 함수를 보면 offset 은 양수/음수 값에 따라 현재 기준점(whence) 에서 오프셋을 계산하게 된다.

주석의 설명을 보면 0 은 파일의 시작 지점을 의미하고, 1 은 현재 offset 의 위치에서, 2 는 마지막을 기준으로 계산된다. 그렇다면 현재 Offset 위치를 알아낼때는 f.Seek(0, 1) 을 이용하면 현재의 오프셋 위치를 알아낼 수 있을 것이다. 실제로 테스트를 한번 해보자.

pos, err := f.Seek(0, 1) // 48 출력

따라서 파일을 읽기전에 f.Seek(0, 0) 으로 옮겨주자. 쓰기 이후 실행해보면 48이 잘 출력되는 걸 확인할 수 있다. 그렇다면 우리가 읽기 작업전에 해줘야 할 것은 무엇일까? 바로 파일의 offset 을 시작지점으로 옮겨줘야 한다.

    f.Seek(0, 0) // 0 이점 시작지 이므로

    _, err = f.Read(buf)

    if err != nil {
        panic(err)
    }

    fmt.Printf("%v\n", BytesToIntSlice(buf)) // [0 1 2 3 4 5 6 7 8 9 10 11]

위와 같이 파일을 시작지점으로 옮기고 이후 읽기를 실행하면 값을 잘 읽어오는 것을 확인할 수 있다. 그렇다면 여기서 아까의 질문인 운영 체제는 어떻게 파일을 나눠서 읽을 수 있을까? 에 대답할 수 있게 된다. 즉, Offset 으로 일정 단위로 읽는다면 충분히 나눠 읽을 수 있다는 것이다.

왜 나눠 읽지?

그렇다면 왜 나눠 읽는 것일까? 바이트를 하나하나 가져오면 안되는 걸까? 우리가 일반적으로 특정 데이터를 어디서 부터 가져오는 행위는 항상 가벼운 행위는 아니다. 따라서, 배치로 묶어서 처리하는 이유는 보통 I/O 와 같은 무거운 행위를 덜 하기 위해서이다.

즉, 운영체제가 나눠 읽는 이유도 이러한 성능적인 부분에서 최적화의 목적에 있다. 따라서 나눠 읽는 부분을 구현해보고 생각해보면서 어떤 최적화가 되는지 생각해보자.

Page

예를 들어 우리가 16 byte 씩 데이터를 읽고, 이를 특정 구조체에 저장한다고 해보자. 우리는 이러한 블럭단위를 Page 라고 부를 것이고, 이를 아래와 같이 구조체로 정의할 것이다.

const PAGE_SIZE = 16 // Byte

type Page struct {
    Id   int32
    Data []byte
}

만약 24개의 정수(96byte) 를 Page 로 읽게 되면 몇개의 Page 가 생성되게 될까? 96 / PAGE_SIZE = 96 / 16 = 6 개가 필요하게 될 것이다. 즉, 우리는 6 개의 Page 를 가지게 된다. 하지만 Page 마다 순서가 있으므로 이를 구분하기 위해 Id 라는 값을 둔다.

첫번째 페이지를 읽고, 두번째 페이지를 읽을 때 [f.Seek](http://f.Seek)`(첫번째](http://f.Seek\)\(첫번째)페이지 이후, 0)으로 만들어야 하기 때문에 Id 를 두는 것이다. 그렇다면 [f.Seek](http://f.Seek) 의 첫번째 인자로 들어갈 인자는PAGE_SIZE * Id` 가 됨을 알 수 있다.

Page 로 읽기

그렇다면 위의 예시(총 크기 96Byte) 에서 Page 단위로 우리가 읽는 부분의 프로세스는 어떻게 될까? 이미 예측하고 있을 수 있겠지만 아래와 같이 진행된다.

읽기 알고리즘

1. 총 크기 / PageSize 만큼의 루프를 생성한다.

2. 루프 내부에서 PageSize 만큼의 Buffer(byte 배열) 을 생성한다.

3. 루프 내부에서 현재 루프의 I(반복 횟수) * PAGE_SIZE 로 offset 을 설정한다. (i=0 일때 0 * 16, i = 1 일때 1 * 16, …)

4. 파일 포인터의 offset 을 계산된 값으로 이동시킨다. f.seek(I(반복 횟수) * PAGE_SIZE, 0)

5. 제공된 버퍼를 넣어 값을 읽는다.

여기서 고민이 한가지 생긴다. 어떻게 파일 단위로 이 페이지를 관리하지? 🤔 이를 위해 PageManager 라는 객체를 하나 만들어 볼수 있다.

type PageManager struct {
    f     *os.File
    pages []*Page
}

이렇게 되면 우리가 읽은 페이지를 Id 를 인덱스 삼아 Page 를 관리할 수 있게 되고, 필요한 전체 읽기(ReadAll) 이라는 함수 또한 이 객체에서 관리하게 할 수 있다.

func (p *PageManager) ReadAll() error {
    for i := 0; i < BYTE_LENGTH/PAGE_SIZE; i++ {
        buf := make([]byte, PAGE_SIZE)
        p.f.Seek(int64(i*PAGE_SIZE), 0) // 이건 사실 옮겨지기 때문에 불필요하나 명확한 예시를 위해 적음
        p.f.Read(buf)
        p.pages[i] = &Page{
            Id:   int32(i),
            Data: buf,
        }
    }
    return nil
}

이 ReadAll 이라는 함수를 이용하면 우리는 내부 SYSTEM_CALL 을 통해 디스크에서 파일을 읽어오게 된다. 근데 만약 정수 배열 0~4 번째 에 Read 가 유독 많다면 어떻게 될까? 이 SYSTEM_CALL 을 통해 계속 디스크로 부터 읽어오는 작업을 해야 할까?

이제는 그럴 필요가 없다. 우리가 이미 객체화 하여 메모리에 값을 올려뒀기 때문이다. ReadAt(id int32) 를 통해 메모리에서 값이 있다면 리턴하게 해보자.

func (p *PageManager) ReadAt(id int32) []byte {
    return p.pages[id].Data
}

이제는 SYSTEM_CALL 이 아닌 단순 Memory Random Access 로 해당 부분에 적혀있는 값을 가져올 수 있게 됬다. 즉, 이전의 Disk 에서 읽어오는 것보다는 가벼운 행위가 되었다.

전체 코드

package main

import (
    "encoding/binary"
    "fmt"
    "os"
)

const PAGE_SIZE = 16 // Byte
const INT_LENGTH = 24
const BYTE_LENGTH = INT_LENGTH * 4

type Page struct {
    Id   int32
    Data []byte
}

type PageManager struct {
    f     *os.File
    pages []*Page
}

func (p *PageManager) ReadAt(id int32) []byte {
    return p.pages[id].Data
}

func (p *PageManager) ReadAll() error {
    for i := 0; i < BYTE_LENGTH/PAGE_SIZE; i++ {
        buf := make([]byte, PAGE_SIZE)
        p.f.Seek(int64(i*PAGE_SIZE), 0)
        p.f.Read(buf)
        p.pages[i] = &Page{
            Id:   int32(i),
            Data: buf,
        }
    }
    return nil
}

func IntSliceToBytes(nums []uint32) []byte {
    buf := make([]byte, 4*len(nums))
    for i, n := range nums {
        binary.BigEndian.PutUint32(buf[i*4:], n)
    }
    return buf
}

func BytesToIntSlice(buf []byte) []int {
    n := len(buf) / 4
    out := make([]int, n)
    for i := 0; i < n; i++ {
        out[i] = int(binary.BigEndian.Uint32(buf[i*4:]))
    }
    return out
}

func main() {
    f, err := os.OpenFile("test.txt", os.O_RDWR|os.O_CREATE, 0666)
    if err != nil {
        panic(err)
    }

    pageManager := &PageManager{
        f:     f,
        pages: make([]*Page, BYTE_LENGTH/PAGE_SIZE),
    }

    arr := make([]uint32, INT_LENGTH)

    for i := 0; i < INT_LENGTH; i++ {
        arr[i] = uint32(i)
    }

    _, err = f.Write(IntSliceToBytes(arr))
    if err != nil {
        panic(err)
    }

    f.Seek(0, 0)

    pageManager.ReadAll()

    fmt.Printf("%v\n", BytesToIntSlice(pageManager.ReadAt(0)))
}

헷갈릴 만한 부분

• 우리가 Page 단위로 읽어야만 운영체제가 블럭 단위로 읽는 것은 아니다. 운영체제는 기본적으로 블럭단위로 읽고, 필요에 의해서는 더많은 데이터를 prefetch 하기도 한다.

최근 회사에서 이미지와 관련된 Cropping 문제로 운영 공수가 많이 들어간다는 요구사항을 받았다. 그래서 여러가지 방법을 고안했는데, 머릿속에 딱 든 생각은 두 가지 정도였다. 첫 번째로는 경계를 지니고 있는 사진들은 보통 일정 공백을 지니고 있는데 이를 수학적으로 계산해내는 방법, 두 번째로는 LLM을 통해 크롭핑할 영역을 분류하는 방법이다.

일단 운영상의 리소스나 결과물의 유지보수를 생각했을 때 후자인 LLM의 경우, 사실 완벽한 해법이라고 항상 생각하지는 않는다. 생성형 모델에게 완벽한 답변을 요구하게 되면 오히려 더 많은 공수가 들어가는 경우가 많고, 모델이나 프롬프트의 성능/퀄리티에 따라 결과가 쉽게 흔들릴 수 있다. 이건 결국 AI 전문가가 없는 팀에서는 유지보수 측면에서 리스크로 작용할 가능성이 크다. 따라서, 구분이 쉬운 사진에 대해서는 기존에 잘 연구되어 있는 알고리즘을 활용해 멱등성 있는 결과를 확보하는 것이 더 옳다고 판단했다.

수학적으로 계산?

그렇다면 이걸 어떻게 수학적으로 계산할 수 있을까? 예전에 배민 해커톤 때 cv2를 잠깐 건드렸던 기억 덕분에 떠올랐던 방법이 바로 경계선(Contours) 알고리즘이다.

컨투어 알고리즘은 Binary 또는 흑백화된 이미지를 기반으로 동작한다. 즉, 경계선을 찾을 때 색깔 정보는 필요 없고, 밝기의 변화(값의 차이)만 있으면 된다. 그래서 경계선을 찾는 데 필요하지 않은 채널을 줄이는(차원 축소하는) 과정이 먼저 필요했다.

또한 대부분의 사진들이 배경이 밝은 편이라, 특정 임계값 기준으로 이진화를 시켜주면 경계값을 쉽게 추출할 수 있다고 생각했다.

흑백화(Grayscale)

Grayscale은 쉽게 말하면 흑백화인데, 사진은 R,G,B의 3채널로 이루어져 있다. 하지만 실제로 경계선을 구분하는 과정에서는 색깔 정보가 크게 필요 없다. 즉, 불필요한 정보는 버리고, 밝기(intensity) 정보만 남기는 게 더 이득이다.

이렇게 Grayscale을 통해 3채널 → 1채널로 차원축소를 해주면, 컨투어·이진화·모폴로지 같은 후처리 단계가 더 안정적으로 동작하게 된다.

코드는 아주 간단하다.

gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

또한 상황에 따라 RGB → Gray로 변환할 때 사용하는 계수를 커스터마이징해볼 수도 있다. 작업 목적에 따라 밝기 가중치를 더 주거나 덜 줄 수도 있으니, 다양한 계수를 실험해보는 것도 좋은 방법이다.

이진화

이후에는 이진화 과정이 필요하다. 이진화는 특정 임계값(Threshold)을 기준으로 픽셀을 흑/백 두 값으로만 나누는 과정이다.

수도 코드로는 아래와 같다.

if gray[y][x] > threshold:
    thresh[y][x] = 0 # 흑백
else:
    thresh[y][x] = 255 # 백

cv2 가 제공하는 함수를 사용하면 아래와 같이 쉽게 이 과정을 진행할 수 있다.

_, thresh = cv2.threshold(gray, 240, 255, cv2.THRESH_BINARY_INV)

여기서 THRESH_BINARY_INV를 쓴 이유는, 밝은 배경은 0(검정), 내용물은 255(백색) 으로 만들기 위해서다. 이렇게 해야 이후 단계에서 “내용이 있는 덩어리(blob)” 를 쉽게 묶을 수 있다.

Dilation

이진화의 결과를 보면 알겠지만 작은 노이즈나 끊어진 영역들이 보통 존재한다. 예를 들면, 옷 사진이나 인물 사진 같은 경우 내부에 작은 빈 공간이나 패턴들이 있어서 하나의 큰 영역으로 인식되지 않는 경우가 많다.

이때 사용하는 것이 Morphology - Dilation(팽창) 이다.

팽창은 255(흰색) 픽셀을 주변으로 퍼뜨려 조각난 부분들을 하나의 덩어리로 묶어주는 역할을 한다.

특히 세로로 긴 이미지들은 위아래 이미지 사이에 약간의 흰 여백이 존재하고, 그 여백만 잘 검출하면 자연스럽게 한 장씩 분리되는 형태가 만들어진다. 따라서 Dilate를 적절한 커널 크기로 적용하면 구간 단위로 깔끔하게 묶여, 이후 컨투어 탐지 시 이미지 단위의 블록을 찾기 쉬워진다. (CNN 의 kernel 을 공부해봤다면 아마 이 개념이 익숙할 것이다.)

코드로는 아래와 같이 작성해볼수있다.

kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (100, 4)) 
dilated = cv2.dilate(thresh, kernel, iterations=2)

팽창(Dilate) 연산은 커널이 겹치는 영역 중 1개라도 흰색(255)이 있으면 그 커널의 중심 픽셀도 255로 바뀌는 방식이다. 즉, 커널 영역 내 흰색 픽셀의 존재 여부를 기준으로 주변을 흰색으로 확장한다.

이 Kernel 도 결국에 튜닝을 해서 찾아야 한다. 이 값을 잡을때 기본적으로 세로형 이미지이기 때문에 가로픽셀에서 합칠게 더 많아도 생각해서 가로를 100, 세로를 4를 주었다. 여러 이미지를 통해 디버깅을 진행하다보면 적당한 값을 찾을 수 있다.

경계선(Contours) 찾기

이제 마지막 단계는 경계선(Contours)을 찾는 것이다. Dilate까지 끝난 결과물에서는 이미지 내부의 유효한 영역들이 하나의 큰 덩어리(blob) 형태로 묶여 있다. 따라서 우리는 내부의 윤곽선은 상관없고 가장 바깥쪽 윤곽선을 찾으면 되므로 RETR_EXTERNAL 그리고 직사각형의 점만 얻으며 되므로 윤곽선 점들을 우리 상황에 맞게 효율적으로 반환하는 CHAIN_APPROX_SIMPLE 옵션을 사용하면, 각 “콘텐츠 블록”의 사각형 영역을 쉽게 얻을 수 있다.

이렇게 얻은 bounding box는 (x, y, w, h) 형태로 반환되는데, 여기서 우리는 특히 y와 h, 즉 “세로 위치와 높이”만 활용해서 세로로 긴 이미지 내에서 “각각 분리되어야 할 이미지”들을 판단할 수 있다.

결과

최종적으로는 위와 같이, 하나의 세로로 긴 이미지 안에 여러 장의 독립적인 이미지가 붙어 있을 경우, 각 영역을 조건에만 맞는다면 정확하게 검출해 개별 이미지로 분리할 수 있는 구조가 완성된다.

중간 과정에서 Grayscale → 이진화 → Dilate → Contours 로 이어지는 처리과정이 “불필요한 정보 제거 → 유효한 영역 강조 → 덩어리 묶기 → 외곽선 검출” 이라는 논리적 흐름으로 이어지기 때문에, 단순한 이미지라면 LLM 기반 접근보다 훨씬 안정적이고 유지보수가 쉬운 방식으로 동작할 수 있게 되었다.

물론 배경이 복잡하거나 조명 편차가 심한 이미지에서는 Threshold나 커널 사이즈를 별도로 튜닝해야 한다. 하지만 단순한 형태의 세로형 이미지라면 이 파이프라인이 가장 안정적이고 재현성 있는 접근이라고 판단했다. 경계가 명확하지 않고 모호한 이미지 또한 이 알고리즘을 통한 분리가 불가능했다.

그 부분은 아마 인공지능을 이용하거나 다른 방법을 찾아야 할거 같다. 이제 이 부분을 파이프라인에 넣어 운영리소스의 공수를 효율적으로 줄이는 방법만 찾으면 될거 같다.

크롤링 기반 서비스를 만들다 보면 크롤링 결과를 그대로 운영에 넣을 수 있는 경우는 사실 거의 없다. 보통 실제 운영까지 가기 위해서는 아래와 같은 형태의 전처리 파이프라인을 무수히 많이 거치게 된다.

크롤링 → 데이터 정제(이미지 사이징, 중복 제거, ...) → 분류 → 기타 가공 → 검수 → 운영 배포

초기에는 이런 과정을 함수 호출로만 연결해도 큰 문제가 없었다. 하지만 서비스가 오래되고, 비즈니스 로직이 추가되고, 예외 케이스가 늘어나면서 어느 순간 코드가 점점 중간에서 끼어들고 비집고 들어오는 로직들이 생겨나다보면 읽기 힘들어지는 시점이 오게된다.

개선 동기

새롭게 작업하기 위해 코드를 보다보니 기존에 이 코드에 익숙한 사람이 아니라면, 코드 자체의 흐름을 파악하기 어렵다는 생각이 들었다. 그 이유는 코드에는 아래와 같은 몇가지 문제들이 존재했기 때문이다.

1. 코드의 실행 흐름을 함수를 하나하나 따라 읽어가며 파악해야 한다.

2. 수십가지의 함수들의 입력/출력값을 단 한번에 보기 어렵다.

위와 같은 문제는 익숙하지 않은 상태에서 코드를 이해할때 필요치 않은 코스트를 생성하고, 코드를 작성하는 시점에 실수가 일어나기 쉬운 상태라고 생각이 들었다.

그래서 유지보수를 위해 코드를 해체해서 구조적으로 작성하게 끔 만들지 않으면 유지보수 비용이 꾸준히 늘어날 것 이고, 최대한 작업자가 현재 비즈니스 로직에 집중하여 코드의 작성하게 끔 만드는 것이 중요했다.

따라서 모든 프로세스가 처리되는 구조와 실행 흐름을 한눈에 어떤 순서로 실행되는지 알 수 있게끔 만들수 있는 구조로 변경하기로 했다.

Pipeline 설계 방향

핵심은 아래와 같이 매우 단순하게 만드는 것이다. 각 Stage 는 한가지의 책임만을 가질수 있도록 구조화하여 해당 부분에만 집중할 수 있게끔 만들고, Pipeline 은 이 연결된 단계들을 순차적으로 실행할 수 있게끔 한다.

1. Stage는 하나의 입력을 받아 하나의 출력을 만든다.

2. StageResult로 성공/실패/부분성공을 일관되게 표현한다.

3. Pipeline은 Stage를 순차적으로 실행하면서 흐름을 제어한다.

그래야 단계가 늘어나도 “단순한 연결” 처럼 읽히게 되고 파이프라인 도중에 Stage(새로운 비즈니스 로직) 을 추가하더라도 해당 부분에만 집중하고, 파이프라인에만 연결하면 되어 쉽다.

TInput = TypeVar("TInput")
TOutput = TypeVar("TOutput")


# 모든 Stage가 공통으로 반환하는 표준 구조
class StageStatus(str, Enum):
    SUCCESS = "success"
    PARTIAL_SUCCESS = "partial"
    FAILURE = "failure"
    SKIPPED = "skipped"


# StageResult는 Stage가 반환하는 유일한 타입
@dataclass
class StageResult(Generic[TOutput]):
    status: StageStatus
    data: Optional[TOutput] = None
    errors: List[str] = field(default_factory=list)
    metrics: Dict[str, Any] = field(default_factory=dict)

    @property
    def is_successful(self) -> bool:
        return self.status in (StageStatus.SUCCESS, StageStatus.PARTIAL_SUCCESS)

    @property
    def should_continue(self) -> bool:
        return self.status in (
            StageStatus.SUCCESS,
            StageStatus.PARTIAL_SUCCESS,
            StageStatus.SKIPPED,
        )

StageResult 를 생성하고 각 함수에서 이를 반환하게끔 한 이유는 모든 Stage의 반환 형태가 같으니 예측 가능해지므로 Result 를 활용하여 Stage 의 결과를 통일된 구조로 확인해볼 수 있다. 또한 Stage 를 진행시키는 Pipeline은 should_continue 하나만 보면 되므로 쉽다.

metric 은 모니터링을 위한 편의성 기능으로 각 Stage는 필요한 데이터만 metrics로 추가하면 된다. DB 기록, 모니터링, Slack 알림 등 확장에 유연하게 가져가기 위함이다.

class PipelineStage(ABC, Generic[TInput, TOutput]):
    @property
    @abstractmethod
    def name(self) -> str:
        pass

    @abstractmethod
    async def execute(self, input_data: TInput) -> StageResult[TOutput]:
        pass

    async def on_success(self, result: StageResult[TOutput]) -> None:
        pass

    async def on_failure(self, result: StageResult[TOutput]) -> None:
        pass

Pipeline 에서 Stage 의 핵심은 다음 두 가지로 아래와 같다.

1. execute 는 입력을 받아서 출력만 만든다. side-effect는 최소화하고, 필요하면 metrics에 기록하는 방식이다. execute 를 작성하는 팀원은 이 Stage 에서 Input 으로 무엇을 할지에만 집중하면 된다.

2. on_success / on_failure(옵션) 와 같은 Hook 형태의 함수들로 각 Stage 가 성공하거나 실패했을때 알림을 발송하거나 특정 작업을 트리거하는 형태가 가능하다.

Pipeline

Pipeline은 정말로 “흐름만” 관리하도록 만들었다. Stage를 정의된 순서대로 하나하나씩 실행시킨다.

1. 실패 시 즉시 중단

2. 부분 성공 또는 성공이면 다음 Stage로 진행

3. 마지막 Stage의 결과를 그대로 반환

Production 에는 멀티 프로세스 환경을 대비하기 위한 Message Queue 를 놓아 Input 과 Output 을 여러 worker 에서 실행될 수 있게 하는 부분과 실행 metadata 를 저장하는 DB 연결부 부분도 존재한다. 예제에서는 복잡할 수 있어 코드를 최대한 간소화하였다

class Pipeline:
    def __init__(self, stages: List[PipelineStage]):
        if not stages:
            raise ValueError("Pipeline must have at least one stage")
        self.stages = stages

    async def run(self, initial_input: Any = None) -> StageResult:
        current_input = initial_input
        last_result: Optional[StageResult] = None

        for index, stage in enumerate(self.stages, 1):
            try:
                result = await stage.execute(current_input)

                # Stage Hook 호출
                if result.is_successful:
                    await stage.on_success(result)
                else:
                    await stage.on_failure(result)

                # 실패면 즉시 종료
                if not result.should_continue:
                    return result

                # 다음 Stage 에게 넘길 data
                current_input = result.data
                last_result = result

            except Exception as e:
                error_msg = f"Unexpected error in '{stage.name}': {e}"
                failure = StageResult(
                    status=StageStatus.FAILURE,
                    data=None,
                    errors=[error_msg],
                    metrics={"stage": stage.name},
                )
                await stage.on_failure(failure)
                return failure

        return last_result or StageResult(status=StageStatus.SUCCESS)

이 Pipeline은 매우 단순하게 정의된 Stage 를 처리할 수 있는 Orchestrator 이다. 단순하게 각 Stage 만을 순차적으로 처리해주는 역할을 진행한다.

간단한 실제 예제: 크롤링 → 이미지 정제 → 분류

이제 실제로 서비스에서 자주 쓰는 구조를 예제로 만들어보자.

1. 크롤링 Stage

class CrawlStage(PipelineStage[None, List[dict]]):
    @property
    def name(self) -> str:
        return "crawl"

    async def execute(self, _):
        items = await crawl_products()
        return StageResult(status=StageStatus.SUCCESS, data=items)

2. 이미지 중복 제거 Stage

class DeduplicateImageStage(PipelineStage[List[dict], List[dict]]):
    @property
    def name(self) -> str:
        return "dedupe_images"

    async def execute(self, items):
        cleaned, errors = [], []

        for item in items:
            try:
                item["images"] = remove_duplicates(item["images"])
                cleaned.append(item)
            except Exception as e:
                errors.append(str(e))

        status = StageStatus.PARTIAL_SUCCESS if errors else StageStatus.SUCCESS

        return StageResult(
            status=status,
            data=cleaned,
            errors=errors,
            metrics={"input": len(items), "output": len(cleaned)},
        )

3. 분류 Stage

class ClassifyStage(PipelineStage[List[dict], List[dict]]):
    @property
    def name(self) -> str:
        return "classify"

    async def execute(self, items):
        classified = []
        for item in items:
            item["category"] = await classify(item)
            classified.append(item)
        return StageResult(status=StageStatus.SUCCESS, data=classified)

pipeline = Pipeline(
    stages=[
        CrawlStage(),
        DeduplicateImageStage(),
        ClassifyStage(),
    ]
)

result = await pipeline.run()

이렇게 호출하면 읽는 사람으로 하여끔 전체 흐름이 아래처럼 읽힌다. 크롤링 → 중복제거 → 분류. 보는 순간 어떻게 절차적으로 실행됨을 빠르게 알수 있으며, 내가 구현할 비즈니스 로직의 코드가 어디쯤 위치해야 하는지도 알기 쉽다.

결론적으로는 Stage마다 단일 책임 원칙이 지켜지고, Pipeline은 흐름을 제어할 뿐이며, 각 Stage 실행 결과는 StageResult로 표준화돼 있기 때문에 코드가 길어져도 읽기가 편하다.

모니터링

구조를 바꾸며 얻게 된 결과 중 하나인데, 코드를 구조화 하여 결과물이 각 단계의 결과물을 저장하기 쉽게끔 변하여 각 단계에서 나오는 산출물을 통해 모니터링 대시보드를 구축하게 되었다. 각 단계에서의 결과를 확인하고, 해당 단계에서 추가적으로 모니터링 하고 싶은 부분들은 StageResult 에 넣기만 하면 자동으로 데이터베이스에 저장되고 모니터링 대시보드를 통해 출력되게 된다.

마치며

이번에 Pipeline 구조를 도입하면서 얻은 가장 큰 성과는 각 단계를 구조적으로 처리할 수 있게끔 만들었다는 점이다. 각 단계가 무엇을 책임지는지 명확해지고, 파이프라인 전체 흐름이 눈에 자연스럽게 들어오다 보니 새로운 비즈니스 로직을 추가하거나 기존 로직을 고치는 작업이 훨씬 편해졌다.

다만, 구현하며 살짝 아쉬운 포인트들도 있다. 개선하지 못한 부분을 정리해보면 아래와 같다.

1) FastAPI DI 구조(FastAPI Depends)에 더 자연스럽게 녹아들도록 개선

현재 구성은 우리 프로젝트 특성에 맞춰 살짝 바인딩되어 있어 DI 주입 방식이 Pipeline/Stage 바깥에 노출되는 경우가 몇 군데 있다. 이건 내부적으로는 큰 문제는 아니지만, Pipeline이 “독립적인 실행 단위"가 되려면 DI도 자연스럽게 숨겨져야 한다.

그래서 다음 단계에서는 Stage 내부에서 필요한 의존성들이 깔끔하게 캡슐화되는 구조로 리팩토링할 계획이다.

2) Message Queue 추상화 레이어 분리

프로덕션 환경에서 Pipeline은 여러 worker가 동시에 실행하므로 Message Queue 를 이용하게 되는데, 이 부분에서 자체 구현체인 QueueService 를 이용하다보니 DI 를 씀에도 쉽게 고치는것이 쉽지만은 않다. 따라서 이 부분을 Interface 로 사용하고, DI 를 통해 쉽게 끔 구현체를 갈아 낄 수 있게끔 구현해보려고 한다.

3) DB Tracking / Execution Metadata 구조 독립화

현재 Execution Metadata(DB에 저장되는 파이프라인 실행 기록)가 Pipeline 내부에서 직접 호출되는 형태로 되어 있다. 이건 편하긴 한데, 오픈소스 형태를 목표로 하면 “DB를 쓰지 않는 환경에서도 쓸 수 있는 구조” 로 만드는 게 맞을거 같다는 생각이 들었다.