<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Performance · 인재덕</title>
    <link>https://jared.lynskey.co.nz/ko/tags/performance/</link>
    <description>소프트웨어 엔지니어링과 개발 조직 리더십에 대한 이야기. 성과 리뷰, 채용과 팀 확장, CI/CD, 데브옵스 모니터링, 에이전틱 AI. 서울에서 씁니다.</description>
    <generator>Hugo</generator>
    <language>ko</language>
    <copyright>© 2026 인재덕</copyright>
    <lastBuildDate>Sat, 21 Nov 2026 17:52:23 +0900</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/ko/tags/performance/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>닫힌 풀 리퀘스트, 포크, 그리고 PyPI 패키지: Python을 위한 빠른 HTML→Markdown 변환</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/2026-10-18-pyhtml2text/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/2026-10-18-pyhtml2text/</guid>
      <pubDate>Sun, 18 Oct 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Python</category>
      <category>Rust</category>
      <category>PyPI</category>
      <category>Open Source</category>
      <category>Markdown</category>
      <category>LLM</category>
      <category>PyO3</category>
      <category>Performance</category>
      <description>AI 에이전트용으로 HTML을 Markdown으로 변환하면서 상대 링크를 절대 URL로 풀어야 했습니다. 원본 Rust 크레이트는 제 풀 리퀘스트가 LLM으로 작성됐다는 이유로 받아 줄 수 없었고, 그래서 포크를 만들어 pyhtml2text를 공개했습니다. base_url을 지원하는 Python 바인딩, 새로 만든 html2markdown, 프로파일 기반 최적화(PGO) 휠, 깊이 중첩된 HTML을 선형 시간에 처리하도록 패치한 파서까지. 왜 만들었는지, 무엇이 들어 있는지, 출력을 어떻게 검증했는지 정리했습니다.</description>
      <content:encoded><![CDATA[<p>10월 15일, PyPI에 <a href="https://pypi.org/project/pyhtml2text/"  target="_blank" rel="noreferrer">pyhtml2text</a>를 공개했습니다. HTML을 일반 텍스트나 Markdown으로 바꿔 주는 패키지이고, Chris Emerson의 Rust 크레이트인 <a href="https://github.com/jugglerchris/rust-html2text"  target="_blank" rel="noreferrer">rust-html2text</a>를 기반으로 합니다. Markdown 변환은 제가 측정한 페이지에서 흔히 쓰는 Python 변환기들보다 3배에서 21배 빨랐습니다. 상대 링크를 페이지 URL 기준으로 풀어 주는 기능도 있어서, 출력물이 원래 페이지를 떠나도 링크가 그대로 작동합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pip install pyhtml2text</span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">pyhtml2text</span> <span class="kn">import</span> <span class="n">html2markdown</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">html</span> <span class="o">=</span> <span class="s2">&#34;&#34;&#34;&lt;h2&gt;Before you start&lt;/h2&gt;
</span></span></span><span class="line"><span class="cl"><span class="s2">&lt;p&gt;Read the &lt;a href=&#34;setup.html&#34;&gt;setup guide&lt;/a&gt; and &lt;b&gt;back up&lt;/b&gt; your data.&lt;/p&gt;
</span></span></span><span class="line"><span class="cl"><span class="s2">&lt;img src=&#34;https://jared.lynskey.co.nz/img/diagram.png&#34; alt=&#34;How it fits together&#34;&gt;
</span></span></span><span class="line"><span class="cl"><span class="s2">&lt;table&gt;&lt;tr&gt;&lt;th&gt;Plan&lt;/th&gt;&lt;th&gt;Price&lt;/th&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Basic&lt;/td&gt;&lt;td&gt;Free&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">html2markdown</span><span class="p">(</span><span class="n">html</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="s2">&#34;https://example.com/docs/intro.html&#34;</span><span class="p">))</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="gu">## Before you start
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">Read the [<span class="nt">setup guide</span>](<span class="na">https://example.com/docs/setup.html</span>) and <span class="gs">**back up**</span> your data.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">![<span class="nt">How it fits together</span>](<span class="na">https://example.com/img/diagram.png</span>)
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">| Plan | Price |
</span></span><span class="line"><span class="cl">| --- | --- |
</span></span><span class="line"><span class="cl">| Basic | Free |</span></span></code></pre></div></div>
<p>시작은 rust-html2text에 보낸 풀 리퀘스트였습니다. 메인테이너는 LLM으로 작성된 코드라는 이유로 이를 닫았고, 그래서 pyhtml2text는 포크 위에서 돌아갑니다. 이 글은 그 과정과 포크·패키지에 들어 있는 것, 그리고 Markdown 출력이 맞는지 어떻게 확인했는지에 대한 이야기입니다.</p>

<h2 class="relative group">왜 필요했나
    <div id="왜-필요했나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%99%9c-%ed%95%84%ec%9a%94%ed%96%88%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>제가 만드는 마켓플레이스 겸 커뮤니티 앱은 <code>Accept: text/markdown</code> 요청에 HTML 대신 Markdown으로 답합니다. 내비게이션 바와 푸터를 헤치고 다니고 싶지 않은 AI 에이전트와 LLM 클라이언트를 위해서입니다. 엣지 쪽 이야기는 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-09-cloudflare-crawlers-cache/" >크롤러와 캐시에 관한 글</a>에서 다뤘습니다. 앱 데이터에서 나오는 페이지는 HTML이 텅 빈 JavaScript 셸이라 Markdown을 바로 만듭니다. 나머지는 정적 HTML(마케팅, 약관, 블로그 페이지)이고, 이건 변환을 거칩니다.</p>
<p>변환할 때 문제는 링크입니다. 정적 사이트의 페이지에는 <code>/en/posts/...</code>나 <code>../setup/</code> 같은 링크가 가득합니다. 브라우저에서는 문제없습니다. 어느 페이지에서 온 링크인지 브라우저가 알고 있으니까요. 하지만 Markdown을 읽는 에이전트에게는 그런 맥락이 없어서 <code>/login</code>을 따라갈 수 없습니다. 필요한 건 <code>https://example.com/login</code>입니다.</p>
<p>순수 Python으로 작성된 <a href="https://pypi.org/project/html2text/"  target="_blank" rel="noreferrer">html2text</a>에는 이를 위한 <code>baseurl</code> 옵션이 있어서 처음에는 그걸 썼습니다. 하지만 느리고, 아래에서 다룰 Markdown 문제도 있었습니다. rust-html2text는 빠르고 테스트도 잘 돼 있었지만, 링크를 풀어 주는 기능이 없었습니다.</p>

<h2 class="relative group">먼저 업스트림에 요청하기
    <div id="먼저-업스트림에-요청하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%a8%bc%ec%a0%80-%ec%97%85%ec%8a%a4%ed%8a%b8%eb%a6%bc%ec%97%90-%ec%9a%94%ec%b2%ad%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>8월 29일, 사용 사례와 원하는 동작을 적어 <a href="https://github.com/jugglerchris/rust-html2text/issues/287"  target="_blank" rel="noreferrer">이슈 #287</a>을 열었습니다. RFC 3986 방식으로 풀되, 절대 URL과 <code>mailto:</code>, <code>data:</code>, <code>#fragment</code> 링크는 건드리지 않는 동작이었습니다. 몇 분 뒤 <a href="https://github.com/jugglerchris/rust-html2text/pull/288"  target="_blank" rel="noreferrer">풀 리퀘스트 #288</a>을 열었습니다. <code>Config::base_url(...)</code> 옵션을 추가하는 PR이었고, 이슈에는 이게 출발점일 뿐이며 메인테이너가 다른 방식을 원한다면 충분히 이해한다고 적었습니다.</p>
<p>10월 11일, 메인테이너가 PR을 닫았습니다.</p>
<blockquote><p>Thanks for the contribution, but I&rsquo;m unable to accept this as it appears to be LLM generated. (I have now added a brief policy to the README.md - it wasn&rsquo;t previously stated)</p>
</blockquote><p>(기여해 줘서 고맙지만 LLM으로 생성된 것으로 보여 받을 수 없다, 이전에는 명시돼 있지 않던 간단한 정책을 이제 README.md에 추가했다는 내용입니다.)</p>
<p>그리고 이슈에는 이렇게 답했습니다.</p>
<blockquote><p>Hi - this is a reasonable feature request, thanks! I have closed the PR as it appears to be LLM-written which I can&rsquo;t accept, but thanks for the attempt.</p>
<p>A short HTML sample and expected output would definitely help get the feature implemented!</p>
</blockquote><p>(합리적인 기능 요청이라 고맙다, PR은 LLM으로 작성된 것으로 보여 받을 수 없어 닫았지만 시도해 줘서 고맙다, 짧은 HTML 예시와 기대하는 출력이 있으면 기능 구현에 분명 도움이 될 거라는 내용입니다.)</p>
<p>README에는 이제 이런 정책이 있습니다.</p>
<blockquote><p>At this time, this project is not able to accept code contributions produced with generative AI/LLMs due to the uncertain copyright status.</p>
</blockquote><p>(현재 이 프로젝트는 저작권 지위가 불확실하기 때문에 생성형 AI나 LLM으로 만든 코드 기여를 받을 수 없다는 내용입니다.)</p>
<p>판단은 정확했습니다. 그 코드는 제가 AI 코딩 도구로 작성했습니다. 저는 이 정책이 무리하다고 생각하지도 않습니다. LLM 출력물의 저작권 문제는 아직 정리되지 않았고, 다른 프로젝트들이 의존하는 MIT 크레이트에 그런 코드를 병합했을 때의 위험은 메인테이너가 떠안게 됩니다. 그분의 프로젝트이고, 답변도 정중했습니다. 기능 요청 이슈는 지금도 열려 있습니다.</p>
<p>그래도 저는 그 기능이 필요했고, 메인테이너와 그 프로젝트의 기여 정책을 두고 논쟁하는 건 기능을 얻는 좋은 방법이 아닙니다. 그래서 변경 사항은 포크에 두고 그 위에 Python 패키지를 만들었으며, 둘 다 업스트림이 아니라는 점을 분명히 밝혀 두었습니다.</p>

<h2 class="relative group">포크에 들어 있는 것
    <div id="포크에-들어-있는-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%8f%ac%ed%81%ac%ec%97%90-%eb%93%a4%ec%96%b4-%ec%9e%88%eb%8a%94-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>포크는 제 rust-html2text 포크의 <code>pyhtml2text-perf</code> 브랜치입니다. 업스트림 위로 깔끔하게 리베이스할 수 있도록 작은 커밋 세 개로만 유지하고 있습니다. 핵심은 PR에 있던 <code>Config::base_url</code> 옵션입니다. 상대 링크를 <a href="https://www.rfc-editor.org/rfc/rfc3986#section-5.3"  target="_blank" rel="noreferrer">RFC 3986 §5.3</a>에 따라 풀고, base URL을 주지 않으면 출력은 그대로입니다. 또 하나는 크레이트가 호출될 때마다 스타일 규칙을 새로 만들지 않게 한 변경인데, 짧은 스니펫 기준 7.3 µs가 5.6 µs가 됐습니다. 큰 페이지에서는 아무것도 아니지만, 몇천 번 호출하면 쌓입니다. 마지막 하나는 아래의 Markdown 변환기가 크레이트에서 필요로 하는 부분을 공개할 뿐입니다.</p>

<h2 class="relative group">Python 패키지
    <div id="python-패키지" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#python-%ed%8c%a8%ed%82%a4%ec%a7%80" aria-label="앵커">#</a>
    </span>
    
</h2>
<p><a href="https://github.com/jaredlynskey/pyhtml2text"  target="_blank" rel="noreferrer">pyhtml2text</a>는 PyO3와 maturin으로 만들었고, 함수는 두 개입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">pyhtml2text</span> <span class="kn">import</span> <span class="n">html2text</span><span class="p">,</span> <span class="n">html2markdown</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">html2text</span><span class="p">(</span><span class="n">html</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">80</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">decorate</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">link_footnotes</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">          <span class="n">table_borders</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">wrap_links</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">max_wrap_width</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">raw</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">html2markdown</span><span class="p">(</span><span class="n">html</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">base_url</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span></span></span></code></pre></div></div>
<p><code>html2text</code>는 rust-html2text의 일반 텍스트 렌더러로, 터미널과 이메일의 <code>text/plain</code> 파트를 위해 만들어진 것입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">html2text</span><span class="p">(</span><span class="s1">&#39;&lt;p&gt;Please &lt;a href=&#34;https://jared.lynskey.co.nz/login&#34;&gt;sign in&lt;/a&gt; first.&lt;/p&gt;&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">                <span class="n">base_url</span><span class="o">=</span><span class="s2">&#34;https://example.com/docs/page.html&#34;</span><span class="p">))</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Please [sign in][1] first.
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">[1]: https://example.com/login</span></span></code></pre></div></div>
<p>바인딩에서 잘 드러나지 않는 점 몇 가지:</p>
<ul>
<li><strong>두 함수 모두 <code>str</code>이나 UTF-8 <code>bytes</code>를 받습니다.</strong> 그래서 <code>response.content</code>를 디코딩하지 않고 바로 넘길 수 있습니다. 입력은 복사하지 않고 빌려 씁니다.</li>
<li><strong>변환하는 동안 GIL을 풉니다.</strong> 처음부터 끝까지 순수 Rust라서 스레드가 여러 코어로 확장됩니다. 모듈이 GIL이 필요 없다고 선언하기 때문에, free-threaded Python 3.14t에서 모듈을 임포트해도 GIL이 다시 켜지지 않습니다.</li>
<li><strong>패닉은 <code>ValueError</code>로 돌아옵니다.</strong> PyO3는 기본적으로 <code>PanicException</code>을 던지는데, 이건 <code>except Exception</code>으로 잡히지 않습니다. 변환 오류를 처리했다고 생각하는 웹 워커가 여기서 죽어 버리니, 바인딩에서 잡아서 <code>ValueError</code>로 다시 던집니다.</li>
<li><strong>휠은 30개입니다.</strong> CPython 3.10 이상용 abi3 휠과 free-threaded 3.14t 휠을, Linux(glibc와 musl), macOS, Windows에서 maturin CI가 빌드할 수 있는 모든 아키텍처에 대해 제공합니다. 그래서 설치할 때 Rust 툴체인이 필요 없습니다.</li>
</ul>

<h2 class="relative group">빠르게 만들기
    <div id="빠르게-만들기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%b9%a0%eb%a5%b4%ea%b2%8c-%eb%a7%8c%eb%93%a4%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>0.2.0은 실제 페이지에서 0.1.0보다 1.5~1.7배, 짧은 스니펫에서는 두 배 빨랐고, 출력은 바이트 단위까지 똑같았습니다. 대부분은 프로파일 기반 최적화(PGO) 덕분입니다. CI가 계측용 휠을 빌드해서 문서 페이지와 RFC로 이뤄진 학습 세트를 돌리고, 그 프로파일로 실제 휠을 빌드합니다. 학습 세트에 없는 페이지에서 약 25% 빨라지며, CI가 계측 빌드를 네이티브로 돌릴 수 있는 플랫폼에만 적용됩니다. 나머지는 작은 할당이 아주 많을 때 훨씬 잘 버티는 mimalloc 할당자로 바꾼 것, 그리고 포크의 스타일 규칙 변경에서 나왔습니다.</p>
<p>속도를 올리면서 아무것도 바뀌지 않았는지 확인하려고, 실제 페이지 코퍼스를 모든 옵션 조합으로 변환한 출력의 해시를 기록했습니다. 빈 입력이나 아주 깊은 중첩 같은 엣지 케이스도 넣었고요. 모든 변경은 해시를 하나도 바꾸지 않아야 했습니다.</p>
<p>Apple Silicon Mac에서 Markdown으로 변환한 중앙값 시간입니다.</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>백과사전 문서 (1 MB)</th>
					<th>뉴스 사이트 첫 페이지 (370 KB)</th>
					<th>Python 문서 페이지 (245 KB)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><a href="https://pypi.org/project/markdownify/"  target="_blank" rel="noreferrer">markdownify</a></td>
					<td>184 ms</td>
					<td>28 ms</td>
					<td>97 ms</td>
			</tr>
			<tr>
					<td><a href="https://pypi.org/project/html2text/"  target="_blank" rel="noreferrer">html2text</a> (순수 Python)</td>
					<td>73 ms</td>
					<td>13 ms</td>
					<td>37 ms</td>
			</tr>
			<tr>
					<td><a href="https://pypi.org/project/html-to-markdown/"  target="_blank" rel="noreferrer">html-to-markdown</a></td>
					<td>44 ms</td>
					<td>5.6 ms</td>
					<td>15 ms</td>
			</tr>
			<tr>
					<td><strong>pyhtml2text</strong></td>
					<td><strong>14 ms</strong></td>
					<td><strong>1.7 ms</strong></td>
					<td><strong>4.5 ms</strong></td>
			</tr>
	</tbody>
</table>
<p>일반 텍스트로 변환한 경우입니다.</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>백과사전 문서 (780 KB)</th>
					<th>뉴스 사이트 첫 페이지 (370 KB)</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><a href="https://pypi.org/project/html2text/"  target="_blank" rel="noreferrer">html2text</a> (순수 Python)</td>
					<td>71.5 ms</td>
					<td>14.9 ms</td>
			</tr>
			<tr>
					<td><a href="https://pypi.org/project/html2text-rs/"  target="_blank" rel="noreferrer">html2text-rs</a></td>
					<td>15.2 ms</td>
					<td>2.5 ms</td>
			</tr>
			<tr>
					<td><strong>pyhtml2text</strong></td>
					<td><strong>10.9 ms</strong></td>
					<td><strong>1.6 ms</strong></td>
			</tr>
	</tbody>
</table>

<h2 class="relative group">깊이 중첩된 HTML, 그리고 html5ever 패치
    <div id="깊이-중첩된-html-그리고-html5ever-패치" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ea%b9%8a%ec%9d%b4-%ec%a4%91%ec%b2%a9%eb%90%9c-html-%ea%b7%b8%eb%a6%ac%ea%b3%a0-html5ever-%ed%8c%a8%ec%b9%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>40,000단계로 중첩된 목록을 손으로 쓰는 사람은 없습니다. 하지만 남이 쓴 페이지를 변환하다 보면 언젠가는 악의적이거나 망가진 무언가가 그런 걸 보내옵니다. 기본 파서로는 40,000단계 중첩된 <code>&lt;ul&gt;&lt;li&gt;</code>를 파싱하는 데 <strong>6초</strong>가 걸렸습니다. 요청 하나에 워커 하나가 그만큼 묶이는 겁니다.</p>
<p>원인은 rust-html2text가 쓰는 HTML5 파서인 <a href="https://github.com/servo/html5ever"  target="_blank" rel="noreferrer">html5ever</a>에 있었습니다. 대부분의 블록 레벨 시작 태그는 열린 <code>&lt;p&gt;</code> 요소가 &ldquo;button scope 안에&rdquo; 있는지 확인해야 하는데, html5ever는 이 질문에 답하려고 열린 요소 스택 전체를 훑었습니다. 중첩이 깊어질수록 태그 하나당 시간이 늘었고, 그래서 전체 시간은 깊이의 제곱에 비례해 커졌습니다.</p>
<p>패키지에는 패치 하나를 적용한 html5ever 0.39.0이 들어 있습니다. 요소가 열리고 닫힐 때마다 그 답을 갱신해 두기 때문에, 확인하는 데 드는 시간이 더 이상 깊이에 좌우되지 않습니다. 같은 문서가 이제 <strong>0.14초</strong>에 파싱됩니다. 패치가 다른 것은 아무것도 바꾸지 않았는지 확인하려고, html5lib의 트리 구성 테스트 전체, 실제 페이지 약 20개, 무작위 태그 수프 문서 300,000개에서 기본 파서와 패치한 파서의 DOM을 비교했고, 전부 동일했습니다.</p>
<p>Markdown 변환기에도 같은 이유로 한계를 두었습니다. 어떤 입력도 스레드 스택을 넘치게 할 수 없고, 인용문과 목록은 32단계를 넘으면 더 들여쓰지 않아서 출력이 제곱으로 불어나지 않습니다. 그리고 행·열 병합을 펼친 격자가 100,000칸을 넘는 표는 셀 내용만 씁니다.</p>

<h2 class="relative group">html2markdown
    <div id="html2markdown" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#html2markdown" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>0.3.0에서 <code>html2markdown</code>이 추가됐고, 패키지 작업의 대부분이 여기에 들어갔습니다. rust-html2text의 렌더러는 Markdown처럼 보이는 텍스트를 만들지만, 터미널 폭에 맞춰 줄바꿈되고 파싱할 용도로 만든 게 아닙니다. 그래서 <code>html2markdown</code>은 파서만 빌려 쓰고, 출력은 직접 <a href="https://commonmark.org/"  target="_blank" rel="noreferrer">CommonMark</a>에 GitHub 스타일 파이프 표와 <code>~~취소선~~</code>을 더한 형식으로 씁니다.</p>
<ul>
<li><code>#</code> 제목, <code>-</code> 글머리표, <code>_기울임_</code>과 <code>**굵게**</code>.</li>
<li>인라인 링크와 이미지. <code>base_url</code>을 주면 절대 URL로 바꿉니다. 아이콘만 들어 있는 링크는 <code>aria-label</code>이나 <code>title</code>을 링크 텍스트로 씁니다.</li>
<li>펜스 코드 블록. 페이지가 언어를 지정했으면(<code>class=&quot;language-python&quot;</code>) 언어 태그를 붙입니다.</li>
<li>파이프 표. 여러 행이나 열에 걸친 셀은 빈 셀이 되고, 헤더 행이 없는 표에는 빈 헤더를 붙이며, 레이아웃용 표는 문단으로 씁니다.</li>
<li>줄바꿈은 하지 않습니다. 숨겨진 콘텐츠(<code>hidden</code>, <code>aria-hidden</code>, <code>display: none</code>), 스크립트, 스타일, 폼 컨트롤은 뺍니다.</li>
</ul>

<h3 class="relative group">필요한 것만 이스케이프하기
    <div id="필요한-것만-이스케이프하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%95%84%ec%9a%94%ed%95%9c-%ea%b2%83%eb%a7%8c-%ec%9d%b4%ec%8a%a4%ec%bc%80%ec%9d%b4%ed%94%84%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>어떤 HTML→Markdown 변환기는 Markdown 문법이 될 수 있는 문자를 전부 이스케이프합니다. 예를 들어 markdownify는 기본적으로 모든 <code>_</code>와 <code>*</code>를 이스케이프합니다. 결과는 정확하지만 <code>snake\_case</code>, <code>5 \* 3</code> 같은 표기로 가득해서, 사람이 읽기 어렵고 모델에게는 토큰 낭비입니다. pyhtml2text는 CommonMark 파서가 문법으로 읽을 자리에서만 문자를 이스케이프합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="n">html2markdown</span><span class="p">(</span><span class="s1">&#39;&lt;p&gt;Use &lt;code&gt;snake_case&lt;/code&gt;, 5 * 3, $5 and &#39;</span>
</span></span><span class="line"><span class="cl">              <span class="s1">&#39;&lt;a href=&#34;../setup.html&#34;&gt;setup&lt;/a&gt;&lt;/p&gt;&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">              <span class="n">base_url</span><span class="o">=</span><span class="s2">&#34;https://example.com/docs/intro.html&#34;</span><span class="p">)</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">Use <span class="sb">`snake_case`</span>, 5 * 3, $5 and [<span class="nt">setup</span>](<span class="na">https://example.com/setup.html</span>)</span></span></code></pre></div></div>

<h3 class="relative group">한국어 조사 앞의 굵은 글씨
    <div id="한국어-조사-앞의-굵은-글씨" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%95%9c%ea%b5%ad%ec%96%b4-%ec%a1%b0%ec%82%ac-%ec%95%9e%ec%9d%98-%ea%b5%b5%ec%9d%80-%ea%b8%80%ec%94%a8" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>이건 제 앱의 페이지에서 직접 겪은 문제입니다. 한국어에서는 조사가 띄어쓰기 없이 명사에 바로 붙으니, 괄호가 들어간 단어를 굵게 하면 이런 HTML이 나옵니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="cl"><span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;&lt;</span><span class="nt">b</span><span class="p">&gt;</span>타이타닉(Titanic)<span class="p">&lt;/</span><span class="nt">b</span><span class="p">&gt;</span>의 감독<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span></span></span></code></pre></div></div>
<p>가장 자연스러운 Markdown은 <code>**타이타닉(Titanic)**의</code>이고, markdownify도 이렇게 씁니다. 그런데 이건 작동하지 않습니다. CommonMark의 flanking 규칙에 따르면 <code>**</code>가 문장 부호 뒤에서 닫히려면 그 뒤에 공백이나 또 다른 문장 부호가 와야 합니다. <code>의</code>는 글자이므로 별표가 그대로 글자로 남습니다. 순수 Python html2text는 공백을 넣어서 이 문제를 피합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">**타이타닉(Titanic)** 의 감독</span></span></code></pre></div></div>
<p>굵게는 표시되지만 한국어가 달라집니다. 조사를 띄어 쓴 셈이니 맞춤법이 틀린 문장이 됩니다. pyhtml2text는 대신 문장 부호를 마커 바깥으로 옮깁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl">**타이타닉(Titanic**)의 감독</span></span></code></pre></div></div>
<p>닫는 괄호는 더 이상 굵지 않지만, 강조는 제대로 파싱되고 원문의 글자는 하나도 빠지지 않습니다. 일본어와 중국어, 그리고 뒤에 오는 말 앞에 공백을 두지 않는 모든 언어에 똑같이 적용됩니다.</p>

<h3 class="relative group">다시 읽어서 출력 검증하기
    <div id="다시-읽어서-출력-검증하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%8b%a4%ec%8b%9c-%ec%9d%bd%ec%96%b4%ec%84%9c-%ec%b6%9c%eb%a0%a5-%ea%b2%80%ec%a6%9d%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>단위 테스트를 통과했다고 변환기를 믿지는 않습니다. Markdown 출력의 버그는 아무도 테스트를 써 볼 생각을 못 한 조합에서 나오니까요. 그래서 출력을 다시 읽어 보는 방식으로 확인합니다.</p>
<p>변환하는 동안 문단마다 CommonMark로 다시 파싱해서 강조가 의도한 대로 읽히는지 확인합니다. 그렇지 않으면 다른 강조 스타일(<code>_</code> 대신 <code>*</code>, 또는 그 반대)로 다시 쓰고, 둘 다 안 되면 텍스트, 링크, 코드는 남기고 서식만 버려서 단어가 하나도 사라지지 않게 합니다. 테스트 스위트는 다른 Markdown 파서로 왕복 검사를 해서, 보이는 모든 단어, 링크 대상, 이미지 소스를 원본 HTML과 비교합니다. 이스케이프되지 않은 문법에 먹힌 텍스트, 파싱되지 않은 링크, 엉뚱한 <code>*</code>가 모두 차이로 드러납니다. 실제 페이지와 수만 개의 무작위 문서에 대해 돌리고, 실패하면 최소 사례로 줄여 줍니다.</p>

<h2 class="relative group">프로덕션 적용
    <div id="프로덕션-적용" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%94%84%eb%a1%9c%eb%8d%95%ec%85%98-%ec%a0%81%ec%9a%a9" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>제 앱의 Markdown 협상(negotiation)은 0.3.0이 나온 날 순수 Python html2text에서 pyhtml2text로 바뀌었습니다. 가이드 페이지 하나 기준으로 변환 시간이 4.2 ms에서 0.36 ms로, 약 12배 빨라졌습니다. 링크는 절대 URL이 됐고, 표는 진짜 파이프 표가 됐으며, 한국어 굵은 글씨 뒤의 조사도 붙은 그대로입니다. abi3 휠이 이미 x86_64와 arm64의 Python 3.14를 지원하기 때문에, 컨테이너 이미지에는 설치를 위해 새로 추가할 게 없었습니다.</p>

<h2 class="relative group">크레딧, 그리고 버그 제보처
    <div id="크레딧-그리고-버그-제보처" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%81%ac%eb%a0%88%eb%94%a7-%ea%b7%b8%eb%a6%ac%ea%b3%a0-%eb%b2%84%ea%b7%b8-%ec%a0%9c%eb%b3%b4%ec%b2%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>일반 텍스트 렌더링은 Chris Emerson의 rust-html2text이고, MIT 라이선스입니다. pyhtml2text는 여기에 그 포크와 패치한 html5ever 사본(MIT/Apache-2.0), 그리고 Markdown 변환기를 더한 것입니다. 이 패키지는 두 프로젝트 어디와도 제휴하거나 보증받은 관계가 아니니, <strong>문제는 업스트림이 아니라 <a href="https://github.com/jaredlynskey/pyhtml2text/issues"  target="_blank" rel="noreferrer">pyhtml2text 이슈 트래커</a>에 제보해 주세요.</strong> 이 코드의 버그는 제가 고칠 몫이고, 업스트림 메인테이너가 받지 않기로 한 코드에 대한 제보를 받게 해서는 안 되니까요.</p>
<p>Python에서 HTML을 변환하고 있다면, 특히 모델이 읽을 용도라면 한번 써 보세요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl">pip install pyhtml2text</span></span></code></pre></div></div>
<p>소스는 <a href="https://github.com/jaredlynskey/pyhtml2text"  target="_blank" rel="noreferrer">GitHub</a>에 있고, 0.1.0부터 0.3.0까지의 변경 사항은 changelog에 정리돼 있습니다.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-10-18-pyhtml2text/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Fly.io 콜드 스타트, 33초를 3초로 줄인 방법</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/2026-09-09-scale-to-zero-504s/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/2026-09-09-scale-to-zero-504s/</guid>
      <pubDate>Wed, 09 Sep 2026 00:00:00 +1200</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Fly.io</category>
      <category>Django</category>
      <category>DevOps</category>
      <category>Cloudflare</category>
      <category>Performance</category>
      <category>Cold Starts</category>
      <category>Redis</category>
      <category>Debugging</category>
      <description>Fly.io에서 auto_stop_machines로 0까지 스케일 다운하면, 멈춘 머신에 온 요청은 부팅을 기다려야 합니다. 25~33초 걸리던 콜드 스타트를 약 3초로 줄인 과정입니다.</description>
      <content:encoded><![CDATA[<p><strong>업데이트 (2026년 10월 22일):</strong> 이 글의 핵심 숫자는 틀렸습니다. 글을 올린 그날 존의 504를 user agent별로 묶어 봤더니, 9월 5일부터 9일까지의 7,344건이 전부 Cloudflare 자체의 Early Hints 프로브(<code>bastion early hints</code>, <code>nginx-ssl early hints</code>)였습니다. 이 프로브는 Fly 오리진에서 응답을 받지 못해 504로 기록되고, 실제 요청 경로를 그대로 따라 하기 때문에 사용자 장애와 똑같아 보입니다. 같은 기간 실제 클라이언트(앱, 브라우저, curl, 검색 크롤러)가 받은 504는 하나도 없었습니다. 오리진이 preload 헤더를 보내지 않아 Early Hints가 하는 일이 없었기 때문에 그날 바로 껐습니다. 아래의 콜드 스타트는 진짜였고 해결책도 유효하지만, 22%는 사용자가 겪은 숫자가 아니었습니다. Cloudflare의 5xx 비율을 장애로 판단하기 전에, 어떤 user agent가 그 에러를 받고 있는지부터 확인하세요.</p>
<p><strong>업데이트 (2026년 11월 4일):</strong> 정정이 하나 더 있습니다. 이 504는 오리진이 응답하지 못한 프로브가 아닙니다. Cloudflare 자체의 Early Hints 캐시 조회로, 오리진에는 아예 가지 않으며, 여기서 504는 그 URL에 캐시된 것이 없었다는 뜻일 뿐입니다. Early Hints를 끈 것도 최선의 해결책은 아니었습니다. <code>Link</code> 응답 헤더를 보내자 기능이 동작하기 시작했고 이 미스는 히트로 바뀌었습니다. 자세한 내용은 <a href="https://jared.lynskey.co.nz/ko/posts/2026/cloudflare-504-early-hints/" >Cloudflare 504 에러, 사실은 장애가 아니었다: Early Hints와 HTTP 103</a>에 정리했습니다.</p>
<p>결론부터 말하면, <code>auto_stop_machines</code>를 켜 두면 멈춰 있는 Fly.io 머신에 들어온 요청은 부팅이 끝날 때까지 기다립니다. 제 앱은 머신이 시작될 때마다 entrypoint가 Django 마이그레이션과 <code>collectstatic</code>을 돌리고, 바이트코드도 전혀 캐시되지 않아서 콜드 스타트에 25~33초가 걸렸습니다. 이 작업을 이미지당 한 번만(<code>FLY_IMAGE_REF</code>를 키로 쓰는 Redis 락으로) 실행하고 빌드에 <code>compileall</code>을 넣자 콜드 부팅이 약 9초로 줄었습니다. 그리고 <code>auto_stop_machines</code>를 <code>'stop'</code>에서 <code>'suspend'</code>로 바꾸자(그러려면 swap을 빼야 했습니다) 깨어나는 데 약 3초면 충분해졌습니다.</p>
<p>Cloudflare 대시보드에서 트래픽이 튄 구간을 확인하러 들어갔다가, 그 아래에 훨씬 심각한 문제가 깔려 있는 걸 발견했습니다. 하루 동안 앱이 처리한 요청의 22%가 실패하고 있었습니다. 알림은 하나도 울리지 않았고, 헬스 체크는 전부 정상이었으며, 로그도 멀쩡해 보였습니다. 실패한 요청이 애초에 애플리케이션까지 도달하지 못했기 때문입니다.</p>
<p>원인은 제가 직접 작성한 컨테이너 시작 스크립트였습니다. 합리적인 작업을, 완전히 잘못된 타이밍에 하고 있었습니다.</p>

<h2 class="relative group">트래픽 급증은 미끼였다
    <div id="트래픽-급증은-미끼였다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%8a%b8%eb%9e%98%ed%94%bd-%ea%b8%89%ec%a6%9d%ec%9d%80-%eb%af%b8%eb%81%bc%ec%98%80%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>원래 확인하려던 건 한 시간 동안 약 4,900건이 몰린 구간이었습니다. 중앙값은 시간당 121건이고요. 순 방문자는 42명. 방문자 한 명당 110건인데, 사람이 이렇게 브라우징하지는 않습니다.</p>
<p>스캐너였습니다. 봇 하나가 존재하지도 않는 서브도메인을 지어내며 시크릿 파일을 찾아다니고 있었습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">api-stage-asia.example.com/.env.local
</span></span><span class="line"><span class="cl">api-us-east-1-demo.example.com/.env
</span></span><span class="line"><span class="cl">api-eu-uat.example.com/wp-config.php~
</span></span><span class="line"><span class="cl">app-test-us-east-1.example.com/actuator/configprops
</span></span><span class="line"><span class="cl">prod-api-use2.example.com/.env.local
</span></span><span class="line"><span class="cl">relay.example.com/.env.production</span></span></code></pre></div></div>
<p>서른 개쯤 되는 호스트명, 생각할 수 있는 모든 <code>.env</code> 변형, 그리고 Django 앱에 대고 요청한 어느 Java 프레임워크의 actuator 엔드포인트까지. 전부 정규 호스트로 301 리다이렉트됐고 아무것도 노출되지 않았습니다. 지루하고, 실제로 무해한 트래픽이었습니다.</p>
<p>그런데 분석 화면을 열어둔 김에 같은 날짜를 상태 코드로 묶어봤습니다. 진짜 문제는 거기 있었습니다.</p>
<table>
	<thead>
			<tr>
					<th>상태 코드</th>
					<th>24시간 요청 수</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>전체</td>
					<td>11,350</td>
			</tr>
			<tr>
					<td>504 Gateway Timeout</td>
					<td>2,474</td>
			</tr>
	</tbody>
</table>
<p>22%입니다. 게다가 사이트 전체에 고르게 퍼진 게 아니라, 가장 아픈 곳에 정확히 몰려 있었습니다.</p>
<table>
	<thead>
			<tr>
					<th>엔드포인트</th>
					<th>504</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>알림 안 읽음 개수</td>
					<td>621</td>
			</tr>
			<tr>
					<td>알림 목록</td>
					<td>614</td>
			</tr>
			<tr>
					<td>메시지 안 읽음 개수</td>
					<td>469</td>
			</tr>
			<tr>
					<td>피드 커서</td>
					<td>210</td>
			</tr>
	</tbody>
</table>
<p>전부 모바일 앱이 30초마다 폴링하는 엔드포인트입니다. 그러니까 이건 추상적인 에러율 숫자가 아니었습니다. 사용자들의 폰이 하루 종일, 아마 몇 주 동안, 안 읽은 알림 배지를 조용히 못 불러오고 있었던 겁니다.</p>

<h2 class="relative group">로그가 멀쩡해 보였던 이유
    <div id="로그가-멀쩡해-보였던-이유" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%a1%9c%ea%b7%b8%ea%b0%80-%eb%a9%80%ec%a9%a1%ed%95%b4-%eb%b3%b4%ec%98%80%eb%8d%98-%ec%9d%b4%ec%9c%a0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>처음엔 앱이 느려졌겠거니 했습니다. 아니었습니다. 가장 나빴던 시간대의 애플리케이션 요청 로그를 아카이브에서 꺼내봤습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">[2026-09-08 01:00:29] &#34;GET /api/notifications/unread/&#34; 304 61.615
</span></span><span class="line"><span class="cl">[2026-09-08 01:00:29] &#34;GET /api/notifications/&#34;        304 63.568
</span></span><span class="line"><span class="cl">[2026-09-08 01:00:59] &#34;GET /api/notifications/unread/&#34; 304 58.742
</span></span><span class="line"><span class="cl">[2026-09-08 01:00:59] &#34;GET /api/notifications/&#34;        304 105.438</span></span></code></pre></div></div>
<p>44~105밀리초, 전부 304. 오리진은 빨랐습니다.</p>
<p>이게 중요한 단서이고, 규칙으로 적어둘 만합니다. <strong>엣지가 오리진은 들어본 적도 없는 에러를 보고한다면, 요청은 도착하기 전에 죽고 있는 것입니다.</strong> 애플리케이션 로그를 그만 읽고, 그 앞에 있는 것을 보세요.</p>
<p>제 경우엔 Fly.io의 프록시였고, 답은 머신 스케줄링 방식에 있었습니다.</p>

<h2 class="relative group">0으로 스케일 다운은 비용에 대한 약속이지, 지연 시간에 대한 약속이 아니다
    <div id="0으로-스케일-다운은-비용에-대한-약속이지-지연-시간에-대한-약속이-아니다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#0%ec%9c%bc%eb%a1%9c-%ec%8a%a4%ec%bc%80%ec%9d%bc-%eb%8b%a4%ec%9a%b4%ec%9d%80-%eb%b9%84%ec%9a%a9%ec%97%90-%eb%8c%80%ed%95%9c-%ec%95%bd%ec%86%8d%ec%9d%b4%ec%a7%80-%ec%a7%80%ec%97%b0-%ec%8b%9c%ea%b0%84%ec%97%90-%eb%8c%80%ed%95%9c-%ec%95%bd%ec%86%8d%ec%9d%b4-%ec%95%84%eb%8b%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>제 설정은 이렇습니다. 언뜻 보면 합리적이죠.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">auto_stop_machines</span> <span class="p">=</span> <span class="s1">&#39;stop&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">auto_start_machines</span> <span class="p">=</span> <span class="kc">true</span>
</span></span><span class="line"><span class="cl">  <span class="nx">min_machines_running</span> <span class="p">=</span> <span class="mi">1</span></span></span></code></pre></div></div>
<p>유휴 머신은 정지하고, 트래픽이 오면 다시 시작합니다. 쓴 만큼만 냅니다. 트래픽이 들쭉날쭉한 작은 앱이라면 정확히 원하는 동작이고, 그래서 머신을 열 대 정의해두고도 평소엔 한 대만 돌고 있었습니다.</p>
<p>이 방식이 숨기는 청구서는 지연 시간입니다. 정지된 머신으로 요청이 들어오면, 누군가는 그 머신이 부팅될 때까지 기다려야 합니다. 부팅이 프록시의 인내심보다 오래 걸리면, 그 누군가는 504를 받습니다.</p>
<p>그래서 제 머신은 부팅에 얼마나 걸렸을까요? 한 번도 측정한 적이 없었습니다. 로그 아카이브는 알고 있습니다. 시작 스크립트가 각 단계를 출력하고, 모든 줄에 머신 ID가 붙어 있으니까요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">WITH</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="p">(</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">SELECT</span><span class="w"> </span><span class="n">instance</span><span class="p">,</span><span class="w"> </span><span class="k">timestamp</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">         </span><span class="k">CASE</span><span class="w"> </span><span class="k">WHEN</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">ILIKE</span><span class="w"> </span><span class="s1">&#39;%Starting app server%&#39;</span><span class="w"> </span><span class="k">THEN</span><span class="w"> </span><span class="s1">&#39;begin&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="k">WHEN</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">ILIKE</span><span class="w"> </span><span class="s1">&#39;%Migrations complete%&#39;</span><span class="w"> </span><span class="k">THEN</span><span class="w"> </span><span class="s1">&#39;migrated&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="k">WHEN</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">LIKE</span><span class="w">  </span><span class="s1">&#39;%&#34;GET /healthz%&#39;</span><span class="w">       </span><span class="k">THEN</span><span class="w"> </span><span class="s1">&#39;serving&#39;</span><span class="w"> </span><span class="k">END</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">phase</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">FROM</span><span class="w"> </span><span class="n">logs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">WHERE</span><span class="w"> </span><span class="n">app</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;myapp&#39;</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="k">timestamp</span><span class="p">::</span><span class="nb">date</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;2026-09-08&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="p">)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="n">instance</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">min</span><span class="p">(</span><span class="k">timestamp</span><span class="p">)</span><span class="w"> </span><span class="n">FILTER</span><span class="w"> </span><span class="p">(</span><span class="k">WHERE</span><span class="w"> </span><span class="n">phase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;begin&#39;</span><span class="p">)</span><span class="w">    </span><span class="k">AS</span><span class="w"> </span><span class="n">started</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">min</span><span class="p">(</span><span class="k">timestamp</span><span class="p">)</span><span class="w"> </span><span class="n">FILTER</span><span class="w"> </span><span class="p">(</span><span class="k">WHERE</span><span class="w"> </span><span class="n">phase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;migrated&#39;</span><span class="p">)</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">migrated</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">       </span><span class="k">min</span><span class="p">(</span><span class="k">timestamp</span><span class="p">)</span><span class="w"> </span><span class="n">FILTER</span><span class="w"> </span><span class="p">(</span><span class="k">WHERE</span><span class="w"> </span><span class="n">phase</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;serving&#39;</span><span class="p">)</span><span class="w">  </span><span class="k">AS</span><span class="w"> </span><span class="n">first_serve</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="k">GROUP</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="n">instance</span></span></span></code></pre></div></div>
<p>모든 머신에서 일관되게 나온 답입니다.</p>
<table>
	<thead>
			<tr>
					<th>단계</th>
					<th>소요 시간</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>부팅부터 마이그레이션 완료까지</td>
					<td>10~13초</td>
			</tr>
			<tr>
					<td>마이그레이션부터 첫 요청 처리까지</td>
					<td>8~19초</td>
			</tr>
			<tr>
					<td><strong>합계</strong></td>
					<td><strong>25~33초</strong></td>
			</tr>
	</tbody>
</table>
<p>그리고 이게 얼마나 자주 일어나는지 세어봤습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="k">count</span><span class="p">(</span><span class="o">*</span><span class="p">)</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">starts</span><span class="p">,</span><span class="w"> </span><span class="k">count</span><span class="p">(</span><span class="k">DISTINCT</span><span class="w"> </span><span class="n">instance</span><span class="p">)</span><span class="w"> </span><span class="k">AS</span><span class="w"> </span><span class="n">machines</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">logs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">WHERE</span><span class="w"> </span><span class="n">app</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;myapp&#39;</span><span class="w"> </span><span class="k">AND</span><span class="w"> </span><span class="k">timestamp</span><span class="p">::</span><span class="nb">date</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;2026-09-08&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="k">AND</span><span class="w"> </span><span class="n">message</span><span class="w"> </span><span class="k">ILIKE</span><span class="w"> </span><span class="s1">&#39;%Starting app server%&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c1">-- starts: 92, machines: 10</span></span></span></code></pre></div></div>
<p>하루에 콜드 스타트 92번. 매번 그 머신으로 라우팅된 요청이 타임아웃되는 30초짜리 창이 열린 겁니다. 22%가 더는 미스터리가 아니었습니다.</p>

<h2 class="relative group">원인은 제 entrypoint 안에 있었다
    <div id="원인은-제-entrypoint-안에-있었다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%9b%90%ec%9d%b8%ec%9d%80-%ec%a0%9c-entrypoint-%ec%95%88%ec%97%90-%ec%9e%88%ec%97%88%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>모든 머신이 요청 하나를 처리하기 전에 실행하던 코드입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="c1"># entrypoint.sh, run on every machine start</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Running migrations...&#34;</span>
</span></span><span class="line"><span class="cl">python manage.py migrate --noinput
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Running collectstatic in background...&#34;</span>
</span></span><span class="line"><span class="cl">python manage.py collectstatic --noinput <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">exec</span> <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span>    <span class="c1"># then start the app server</span></span></span></code></pre></div></div>
<p>&ldquo;하루에 92번&quot;을 떠올리면서 다시 읽어보세요.</p>
<p><code>migrate</code>는 완전한 Django 부팅입니다. 모든 모델을 임포트하고, Postgres에 연결하고, 마이그레이션 테이블을 조회한 뒤, 할 일이 없다고 판단합니다. 공유 CPU에서 아무것도 하지 않기 위해 10초를 씁니다. <code>collectstatic</code>은 두 번째 완전한 Django 부팅이고, 그다음 정적 파일을 오브젝트 스토리지에 업로드하면서 웹 서버가 기동하려는 바로 그 단일 코어를 두고 경쟁합니다. 앱 서버가 세 번째 부팅이고요.</p>
<p>파이썬 인터프리터 세 개, 그중 둘은 이미 끝난 일을 반복하면서, 머신이 깨어날 때마다 매번.</p>
<p>이렇게 짠 이유는 나름 타당했고, 아마 여러분 코드도 비슷할 겁니다. 마이그레이션은 어딘가에서는 돌아야 하고, Fly의 <code>release_command</code>는 예전에 멈춘 적이 있었으며, entrypoint는 배포 시 반드시 실행되는 유일한 지점이니까요. 배포 작업을 넣기에 맞는 자리입니다. 다만 <strong>머신 시작마다</strong> 넣기에 맞는 자리가 아닐 뿐입니다. 그리고 머신이 알아서 멈추고 시작하기 시작한 순간, 이 둘은 더 이상 같은 사건이 아닙니다.</p>
<p>버그의 전부는 이것이고, 흔한 실수라고 생각합니다.</p>
<blockquote><p><strong>릴리스</strong>에 속한 작업이 <strong>머신 시작</strong>마다 실행되고 있었습니다. 0으로 스케일 다운이 사건 하나를 아흔두 개로 바꿔놓았습니다.</p>
</blockquote>
<h2 class="relative group">해법: 릴리스를 한 번만 선점하기
    <div id="해법-릴리스를-한-번만-선점하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%95%b4%eb%b2%95-%eb%a6%b4%eb%a6%ac%ec%8a%a4%eb%a5%bc-%ed%95%9c-%eb%b2%88%eb%a7%8c-%ec%84%a0%ec%a0%90%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>특정 이미지로 부팅하는 여덟 번째 머신에서 마이그레이션이 돌 필요는 없습니다. 그 이미지에 대해 한 번만 돌면 되고, 나머지는 그게 끝났다는 사실만 알면 됩니다.</p>
<p>즉, 배포할 때마다 이름이 바뀌는 락입니다. Fly가 <code>FLY_IMAGE_REF</code>로 그 이름을 공짜로 주고, Redis는 이미 있었습니다. 전체가 Django보다 먼저 실행되는 작은 스크립트라서, 흔한 경우의 답이 프레임워크 부팅이 아니라 밀리초로 끝납니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># release_gate.py: runs before Django exists. Exit code 0 means &#34;prepare this release&#34;.</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">time</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">PREPARE</span><span class="p">,</span> <span class="n">SKIP</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>
</span></span><span class="line"><span class="cl"><span class="n">LOCK_TTL</span><span class="p">,</span> <span class="n">WAIT</span><span class="p">,</span> <span class="n">POLL</span> <span class="o">=</span> <span class="mi">300</span><span class="p">,</span> <span class="mi">240</span><span class="p">,</span> <span class="mi">2</span>
</span></span><span class="line"><span class="cl"><span class="n">_sleep</span><span class="p">,</span> <span class="n">_monotonic</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">,</span> <span class="n">time</span><span class="o">.</span><span class="n">monotonic</span>    <span class="c1"># aliases, so tests can replace them</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">release_id</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;&#34;&#34;Something that changes exactly when the deployed image does.&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;FLY_IMAGE_REF&#34;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;FLY_MACHINE_VERSION&#34;</span><span class="p">)</span> <span class="ow">or</span> <span class="s2">&#34;&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">claim</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="n">release</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">client</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">release</span><span class="p">:</span>   <span class="c1"># no Redis, or no idea which release: behave as before</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">PREPARE</span>
</span></span><span class="line"><span class="cl">    <span class="n">done_key</span><span class="p">,</span> <span class="n">lock_key</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&#34;release:</span><span class="si">{</span><span class="n">release</span><span class="si">}</span><span class="s2">:done&#34;</span><span class="p">,</span> <span class="sa">f</span><span class="s2">&#34;release:</span><span class="si">{</span><span class="n">release</span><span class="si">}</span><span class="s2">:lock&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">done_key</span><span class="p">):</span>            <span class="c1"># somebody already did it for this image</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">SKIP</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="n">owner</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&#34;FLY_MACHINE_ID&#34;</span><span class="p">,</span> <span class="s2">&#34;unknown&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">lock_key</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">nx</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">ex</span><span class="o">=</span><span class="n">LOCK_TTL</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">PREPARE</span>                  <span class="c1"># we won the race; we do the work</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="c1"># Someone else is preparing. Wait for them, because serving requests</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># against a half-migrated schema is worse than starting slowly.</span>
</span></span><span class="line"><span class="cl">    <span class="n">deadline</span> <span class="o">=</span> <span class="n">_monotonic</span><span class="p">()</span> <span class="o">+</span> <span class="n">WAIT</span>
</span></span><span class="line"><span class="cl">    <span class="k">while</span> <span class="n">_monotonic</span><span class="p">()</span> <span class="o">&lt;</span> <span class="n">deadline</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="n">_sleep</span><span class="p">(</span><span class="n">POLL</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">done_key</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="n">SKIP</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">client</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="n">lock_key</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">nx</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">ex</span><span class="o">=</span><span class="n">LOCK_TTL</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="n">PREPARE</span>              <span class="c1"># the owner died and its lock expired; take over</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">PREPARE</span>                      <span class="c1"># waited long enough; do it ourselves</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE</span></span></span></code></pre></div></div>
<p>entrypoint는 <code>if</code> 하나가 됩니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="k">if</span> python3 release_gate.py claim<span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    python manage.py migrate --noinput
</span></span><span class="line"><span class="cl">    python manage.py collectstatic --noinput <span class="p">&amp;</span>
</span></span><span class="line"><span class="cl">    python3 release_gate.py <span class="k">done</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">exec</span> <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span></span></span></code></pre></div></div>

<h2 class="relative group">모든 실패는 &ldquo;그냥 준비한다&quot;로 끝나야 한다
    <div id="모든-실패는-그냥-준비한다로-끝나야-한다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%aa%a8%eb%93%a0-%ec%8b%a4%ed%8c%a8%eb%8a%94-%ea%b7%b8%eb%83%a5-%ec%a4%80%eb%b9%84%ed%95%9c%eb%8b%a4%eb%a1%9c-%eb%81%9d%eb%82%98%ec%95%bc-%ed%95%9c%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>코드보다 이 부분을 베껴 가시는 걸 권합니다.</p>
<p>이런 게이트는 사용자와 스키마 마이그레이션 사이에 놓입니다. <strong>건너뛰는</strong> 쪽으로 틀리면 마이그레이션되지 않은 데이터베이스에 요청을 받게 되고, 이건 진짜 장애입니다. <strong>준비하는</strong> 쪽으로 틀리면 멱등한 no-op 마이그레이션을 두 번 돌리고 10초를 낭비합니다.</p>
<p>두 결과는 대칭이 아니므로, 코드도 대칭으로 다루면 안 됩니다. 불확실한 경로는 전부 <code>PREPARE</code>를 반환합니다.</p>
<ul>
<li><strong>Redis가 없거나 접근 불가.</strong> 준비합니다. 예전 동작 그대로라서, 캐시 장애가 &ldquo;고장&quot;이 아니라 &ldquo;느림&rdquo; 정도로 그칩니다.</li>
<li><strong>환경에 이미지 참조가 없음.</strong> 준비합니다. 어떤 릴리스인지 모르니 준비됐는지도 알 수 없습니다.</li>
<li><strong>락 주인이 마이그레이션 도중 사망.</strong> 락이 만료되고, 다음 대기자가 넘겨받아 준비합니다.</li>
<li><strong>타임아웃보다 오래 기다림.</strong> 그래도 준비합니다. 영영 서비스하지 못하는 머신이 중복 마이그레이션보다 나쁩니다.</li>
</ul>
<p>반대 방향으로 의도한 비대칭이 하나 있습니다. 다른 머신이 락을 실제로 쥐고 있는 걸 확인한 머신은 서비스를 시작하지 않고 <strong>기다립니다</strong>. 배포 중에 느리게 시작하는 건 괜찮습니다. 절반만 적용된 스키마에 질의를 받는 건 괜찮지 않습니다.</p>
<p>연결 에러를 삼켜 버리는 캐시 래퍼 위에 이걸 만든다면 함정이 하나 있습니다. 제가 처음에 그랬거든요. 그런 래퍼는 Redis에 닿지 못하면 <code>add()</code>가 <code>False</code>를 반환하는데, 이게 &ldquo;다른 누가 락을 쥐고 있다&quot;와 완전히 똑같이 읽힙니다. 그대로 뒀다면 모든 머신이 마이그레이션을 건너뛰었을 겁니다. 정확히 위험한 방향이죠. 락을 되읽어서 구분하세요. 아무도 쥐고 있지 않은 락은 경쟁에서 진 게 아니라 캐시가 고장 났다는 뜻입니다.</p>

<h2 class="relative group">Redis 없이 테스트하기
    <div id="redis-없이-테스트하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#redis-%ec%97%86%ec%9d%b4-%ed%85%8c%ec%8a%a4%ed%8a%b8%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이 로직은 단위 테스트할 가치가 있습니다. 정작 흥미로운 경로들은 손으로 재현할 수 없기 때문입니다. 메서드 두 개짜리 페이크면 충분합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">FakeRedis</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;&#34;&#34;Enough of a Redis client for the gate: get, and set with nx/ex.&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">):</span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">set</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">nx</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">ex</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">nx</span> <span class="ow">and</span> <span class="n">key</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">None</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">store</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="kc">True</span></span></span></code></pre></div></div>
<p>그다음 시간을 내 마음대로 흘려보내며 까다로운 경우를 몰아봅니다. 게이트가 <code>time.sleep</code>을 직접 부르지 않고 모듈 수준의 <code>_sleep</code>, <code>_monotonic</code> 별칭을 쓰는 이유가 이겁니다. 덕분에 같은 프로세스의 다른 스레드까지 건드리지 않고 테스트에서 교체할 수 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">test_a_waiter_takes_over_when_the_owner_disappears</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">redis</span> <span class="o">=</span> <span class="n">FakeRedis</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">release_gate</span><span class="o">.</span><span class="n">claim</span><span class="p">(</span><span class="n">redis</span><span class="p">,</span> <span class="s2">&#34;img-1&#34;</span><span class="p">),</span> <span class="n">release_gate</span><span class="o">.</span><span class="n">PREPARE</span><span class="p">)</span>   <span class="c1"># the owner takes the lock</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">owner_dies</span><span class="p">(</span><span class="n">_seconds</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="n">redis</span><span class="o">.</span><span class="n">store</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="s2">&#34;release:img-1:lock&#34;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>                              <span class="c1"># its lock expired</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">    <span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">release_gate</span><span class="p">,</span> <span class="s2">&#34;_sleep&#34;</span><span class="p">,</span> <span class="n">owner_dies</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">release_gate</span><span class="o">.</span><span class="n">claim</span><span class="p">(</span><span class="n">redis</span><span class="p">,</span> <span class="s2">&#34;img-1&#34;</span><span class="p">),</span> <span class="n">release_gate</span><span class="o">.</span><span class="n">PREPARE</span><span class="p">)</span></span></span></code></pre></div></div>

<h2 class="relative group">효과가 있었나? 절반은
    <div id="효과가-있었나-절반은" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%9a%a8%ea%b3%bc%ea%b0%80-%ec%9e%88%ec%97%88%eb%82%98-%ec%a0%88%eb%b0%98%ec%9d%80" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>배포한 뒤 머신을 정지시켰다가 다시 시작하면서 시계를 봤습니다. 이제 시작 과정은 자기 판단을 출력하고 곧바로 비켜섭니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">15:23:34  Starting app server...
</span></span><span class="line"><span class="cl">15:23:36  release gate: this release is already prepared, starting straight away
</span></span><span class="line"><span class="cl">15:23:44  &#34;GET /healthz HTTP/1.1&#34; 200</span></span></code></pre></div></div>
<p>10초, 두 번째 머신은 11초였습니다. 이전의 25~33초와 비교하면 창의 3분의 2가 사라졌고, 게이트 자체는 Django를 전혀 임포트하지 않아서 2초면 끝납니다.</p>
<p>하지만 10초는 여전히 10초입니다. 그 첫 순간에 도착한 요청은 여전히 실패합니다. 그래서 나머지를 찾아 나섰습니다.</p>

<h2 class="relative group">아무도 캐싱하지 않던 바이트코드
    <div id="아무도-캐싱하지-않던-바이트코드" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%95%84%eb%ac%b4%eb%8f%84-%ec%ba%90%ec%8b%b1%ed%95%98%ec%a7%80-%ec%95%8a%eb%8d%98-%eb%b0%94%ec%9d%b4%ed%8a%b8%ec%bd%94%eb%93%9c" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이미지에는 세상 거의 모든 파이썬 Dockerfile에 들어 있는 그 한 줄이 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dockerfile" data-lang="dockerfile"><span class="line"><span class="cl"><span class="k">ENV</span> <span class="nv">PYTHONDONTWRITEBYTECODE</span><span class="o">=</span><span class="m">1</span></span></span></code></pre></div></div>
<p>좋은 조언입니다. 컨테이너가 런타임에 레이어 안으로 <code>.pyc</code>를 갈겨쓰면 안 되죠. 제가 끝까지 생각해보지 않았던 건 이 거래의 나머지 절반입니다. 런타임이 바이트코드를 절대 쓰지 않고, 빌드도 쓰지 않는다면, 아무것도 캐싱되지 않고, 모든 프로세스 시작마다 의존성 트리 전체를 소스에서 컴파일합니다.</p>
<p>세어봤습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">site-packages .py  files : 5,707
</span></span><span class="line"><span class="cl">site-packages .pyc files : 0</span></span></code></pre></div></div>
<p>Django, REST 프레임워크, 모든 라이브러리가 하루 92번의 시작마다 매번 다시 컴파일되고 있었습니다. 프로덕션 머신에서 측정한 값입니다.</p>
<table>
	<thead>
			<tr>
					<th><code>django.setup()</code></th>
					<th>시간</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>배포된 그대로</td>
					<td>5.15초</td>
			</tr>
			<tr>
					<td><code>compileall</code> 이후</td>
					<td>3.17초</td>
			</tr>
	</tbody>
</table>
<p>해결은 한 줄이고, <code>compileall</code>은 명시적으로 쓰기 때문에 저 환경 변수가 있어도 동작합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dockerfile" data-lang="dockerfile"><span class="line"><span class="cl"><span class="k">RUN</span> python -m compileall -q /app/.venv/lib /app/myapp <span class="o">||</span> true</span></span></code></pre></div></div>
<p>빌드 시간 16초, 딱 한 번, 캐시되는 레이어에서.</p>
<p>작업하는 김에 더 조용한 문제도 하나 찾았습니다. <code>.dockerignore</code>에는 이렇게 적혀 있었습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">__pycache__/
</span></span><span class="line"><span class="cl">*.pyc</span></span></code></pre></div></div>
<p>Docker는 이 패턴을 경로의 각 구성요소가 아니라 상대 경로 <strong>전체</strong>에 대해 매칭합니다. 그래서 앵커되지 않은 패턴은 빌드 컨텍스트의 최상위에서만 매칭됩니다. 중첩된 <code>__pycache__</code>는 전부 이미지로 실려 가고 있었습니다. 노트북의 파이썬 3.15가 컴파일한 <code>.pyc</code> 218개가, 인터프리터가 3.14인 이미지 안에 실려 들어가서 전부 조용히 무시되고 있었죠. 패턴은 <code>**/__pycache__/</code>와 <code>**/*.pyc</code>여야 합니다.</p>
<p>솔직한 결과: 전체적으로는 2초가 아니라 1초 정도를 벌었습니다. 10초가 9초가 됐습니다. 격리된 벤치마크가 늘 그렇듯 과대평가였습니다.</p>

<h2 class="relative group">서스펜드, 그리고 그걸 막고 있던 한 줄
    <div id="서스펜드-그리고-그걸-막고-있던-한-줄" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%84%9c%ec%8a%a4%ed%8e%9c%eb%93%9c-%ea%b7%b8%eb%a6%ac%ea%b3%a0-%ea%b7%b8%ea%b1%b8-%eb%a7%89%ea%b3%a0-%ec%9e%88%eb%8d%98-%ed%95%9c-%ec%a4%84" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>9초에서 더 걷어낼 작업이 없어졌습니다. 남은 건 피할 수 없는 부팅 한 번이었습니다. 파이썬이 뜨고, Django가 임포트되고, WSGI 앱이 공유 코어에서 올라오는 시간.</p>
<p>그러면 부팅을 안 하면 됩니다. Fly는 머신을 종료하는 대신 메모리를 스냅샷할 수 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">auto_stop_machines</span> <span class="p">=</span> <span class="s1">&#39;suspend&#39;</span>   <span class="c"># was &#39;stop&#39;</span></span></span></code></pre></div></div>
<p>테스트하러 갔더니 Fly가 거절했고, 이번 작업 전체에서 가장 유용한 에러 메시지를 돌려줬습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">failed to suspend VM: failed_precondition:
</span></span><span class="line"><span class="cl">Machines with swap cannot be suspended</span></span></code></pre></div></div>
<p>제 설정 상단에는 제가 직접 쓰고 스스로 믿고 있던 주석과 함께 이게 있었습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="c"># Swap cushion so a memory spike swaps to disk instead of getting OOM-killed.</span>
</span></span><span class="line"><span class="cl"><span class="nx">swap_size_mb</span> <span class="p">=</span> <span class="mi">2048</span></span></span></code></pre></div></div>
<p>합리적인 예방책입니다. 그런데 실제로 일을 하고 있었을까요? 모든 머신이 이렇게 답했습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">MemTotal:   985220 kB
</span></span><span class="line"><span class="cl">SwapTotal: 2097148 kB
</span></span><span class="line"><span class="cl">SwapFree:  2097148 kB</span></span></code></pre></div></div>
<p>단 한 페이지도 스왑된 적이 없었습니다. 그날의 로그에도 OOM 킬은 없었고요. &ldquo;oom&quot;에 매칭된 11줄은 알고 보니 콘텐츠 해시에 우연히 그 세 글자가 들어간 자바스크립트 번들 요청이었습니다. 그리고 진짜 메모리 가드는 완전히 다른 곳, 앱 서버 자체 설정에 있었습니다. 800MB를 넘긴 워커는 1GB 천장에 닿기 한참 전에 재시작되고 있었죠.</p>
<p>즉 이 완충 장치는 한 번도 일어난 적 없는 사건에 대한 보험이었고, 이미 다른 메커니즘이 커버하고 있었으며, 그 보험료가 서스펜드 기능이었습니다. 제거했습니다.</p>
<table>
	<thead>
			<tr>
					<th>깨어나는 경로</th>
					<th>응답까지</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>오늘 아침의 콜드 부팅</td>
					<td>25~33초</td>
			</tr>
			<tr>
					<td>게이트와 바이트코드 이후의 콜드 부팅</td>
					<td>9~10초</td>
			</tr>
			<tr>
					<td><strong>서스펜드에서 재개</strong></td>
					<td><strong>2.5~3.1초</strong></td>
			</tr>
	</tbody>
</table>
<p>세 번 측정했고 편차는 0.5초 이내였습니다. 깨어난 직후 모든 엔드포인트가 250~435밀리초 만에 200을 반환했습니다.</p>

<h2 class="relative group">머신이 자는 동안 소켓은 어떻게 되나
    <div id="머신이-자는-동안-소켓은-어떻게-되나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%a8%b8%ec%8b%a0%ec%9d%b4-%ec%9e%90%eb%8a%94-%eb%8f%99%ec%95%88-%ec%86%8c%ec%bc%93%ec%9d%80-%ec%96%b4%eb%96%bb%ea%b2%8c-%eb%90%98%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>좋을 게 없고, 고칠 훅도 없습니다. Fly는 VM을 얼립니다. 프로세스에는 시그널이 가지 않고, 내려가는 길에 아무것도 닫을 수 없습니다. 쥐고 있던 커넥션은 깨어날 때도 그대로 메모리에 남아, 몇 분 전에 상대가 버린 소켓을 가리키고 있습니다.</p>
<p>이건 내려갈 때 푸는 문제가 아닙니다. 올라올 때 푸는 문제이고, 대부분은 이미 올바른 선택을 해둔 덕분에 풀립니다.</p>
<ul>
<li><strong>DB 커넥션은 요청마다 새로 엽니다</strong>(<code>conn_max_age = 0</code>). 오래 살아서 상할 것이 없습니다.</li>
<li><strong>Redis 캐시는 장애가 나도 예외를 던지지 않습니다.</strong> 래퍼가 커넥션 에러를 잡아 미스로 돌려줍니다.</li>
</ul>
<p>두 번째 것이 값을 하는 장면을 직접 봤습니다. 어느 재개에서 정확히 예상했던 실패가 로그에 찍혔습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">redis.exceptions.ConnectionError: Error while reading from fly-...</span></span></code></pre></div></div>
<p>그리고 그게 발생한 요청은 3.6초 만에 200을 반환했습니다. 죽은 캐시는 느린 페이지이지 에러 페이지가 아니니까요. 이후의 재개에서는 아무것도 찍히지 않았습니다.</p>
<p>여러분의 캐시 클라이언트가 죽은 커넥션에서 예외를 던진다면, 서스펜드는 모든 깨어남을 500 폭죽으로 바꿔놓을 겁니다. 설정을 켜기 <strong>전에</strong> 확인하세요.</p>

<h2 class="relative group">저에게 거짓말을 한 테스트
    <div id="저에게-거짓말을-한-테스트" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%a0%80%ec%97%90%ea%b2%8c-%ea%b1%b0%ec%a7%93%eb%a7%90%ec%9d%84-%ed%95%9c-%ed%85%8c%ec%8a%a4%ed%8a%b8" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>첫 서스펜드 측정은 이 기능이 재앙이라고 말했습니다. 502, 30초 만에, 두 번 연속으로.</p>
<p>저는 <code>fly-force-instance-id</code>로 요청을 특정 머신에 고정했습니다. 인스턴스 하나를 부하 테스트할 때는 훌륭한 헤더지만, 이 용도에는 최악입니다. 인스턴스를 강제하면 그 머신을 깨워줬을 프록시 로직을 건너뛰기 때문입니다. Fly는 이미 말해주고 있었습니다. 제가 그걸 에러가 아니라 답으로 읽었다면요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">machine was recently stopped and is unavailable to service request</span></span></code></pre></div></div>
<p>의미 있는 숫자는 실제 트래픽이 지나는 경로에서 나옵니다. 엣지를 통해 동시 요청 40개, 소프트 리밋 12를 훌쩍 넘겨서 프록시가 서스펜드된 머신으로 확장할 수밖에 없게 만들었습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">status codes:  40 × 200
</span></span><span class="line"><span class="cl">slowest:       2.1s</span></span></code></pre></div></div>
<p>교훈은 두 가지이고, 두 번째가 값비쌉니다. 계측하기 편한 경로가 아니라 사용자가 지나는 경로를 측정하세요. 그리고 도구가 뭔가를 거절하면, 그 거절문을 읽으세요. &ldquo;Machines with swap cannot be suspended&quot;라는 한 문장이 이 오후 전체를 열어젖혔습니다.</p>

<h2 class="relative group">여러분 앱에서 확인해볼 것
    <div id="여러분-앱에서-확인해볼-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%97%ac%eb%9f%ac%eb%b6%84-%ec%95%b1%ec%97%90%ec%84%9c-%ed%99%95%ec%9d%b8%ed%95%b4%eb%b3%bc-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>유휴 인스턴스를 정지시키는 플랫폼을 쓰고 있다면, 아래 질문들에 저는 반나절을 썼고 몇 주치의 조용한 실패를 아낄 수 있었을 겁니다.</p>
<ol>
<li><strong>콜드 스타트는 얼마나 걸리나요?</strong> 컨테이너가 실행되는 시간이 아니라, 실제 요청에 응답하기까지의 시간입니다. 몇 초인지 바로 답할 수 없다면, 필요해지기 전에 측정해두세요.</li>
<li><strong>entrypoint가 시작마다 하는 일 중 배포에 속한 건 무엇인가요?</strong> 마이그레이션, 정적 파일 수집, 캐시 워밍, 인덱스 빌드. 한 번이면 다 괜찮습니다. 아흔두 번이면 다 비쌉니다.</li>
<li><strong>바이트코드를 캐싱하고 있긴 한가요?</strong> 빌드에 <code>compileall</code>이 없는 <code>PYTHONDONTWRITEBYTECODE</code>는 &ldquo;아니요&quot;라는 뜻입니다.</li>
<li><strong>정지 대신 서스펜드를 쓸 수 있나요?</strong> 못 쓴다면, 무엇이 막고 있나요? 제 경우엔 한 번도 건드려지지 않은 스왑 파일이었습니다.</li>
<li><strong>엣지는 보는데 오리진은 모르는 에러가 있나요?</strong> 둘을 비교하세요. 그 격차는 리포팅 오차가 아니라 사이에서 죽고 있는 요청이고, 애플리케이션 로그는 절대 보여주지 않습니다.</li>
</ol>
<p>덧붙이자면, 그동안 헬스 체크는 내내 초록불이었습니다. 늘 그렇습니다. 헬스 체크는 이미 떠 있는 머신을 상대로 돌기 때문에, 그 머신이 존재하기 전의 30초에 대해서는 아무것도 보고할 수 없습니다.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-09-09-scale-to-zero-504s/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Fly.io에서 Django 오토스케일링: 부하 테스트로 작은 머신 한 대의 한계 찾기</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/2026-07-22-my-current-stack/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/2026-07-22-my-current-stack/</guid>
      <pubDate>Wed, 22 Jul 2026 00:00:00 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Django</category>
      <category>Python</category>
      <category>React Native</category>
      <category>Expo</category>
      <category>Fly.io</category>
      <category>PostgreSQL</category>
      <category>WebSockets</category>
      <category>Scaling</category>
      <category>Load Testing</category>
      <category>Performance</category>
      <category>Tech Stack</category>
      <description>Django 앱 두 개를 Fly.io의 shared-cpu-1x 머신에서 돌립니다. 머신 한 대를 빠르게 만들고, 부하 테스트로 무너지는 지점을 찾고, 그 앞에 오토스케일 임계값을 두는 방법입니다.</description>
      <content:encoded><![CDATA[<p>Fly.io에서 Django를 싸게 돌리려고, 저는 shared-cpu-1x 작은 머신 한 대를 최대한 빠르게 만들고, 지연 시간이 무너질 때까지 부하 테스트를 한 뒤, 그 직전에 Fly 오토스케일러가 두 번째 머신을 띄우도록 설정합니다. 부하 테스트는 단계적으로 부하를 올리는 Locust(다른 앱에서는 동시성을 바꿔 가며 돌리는 작은 Python 스크립트)로 하고, p95 지연 시간과 에러율을 봅니다. 트래픽이 줄면 Fly가 유휴 머신을 다시 멈추기 때문에, 평소 비용은 앱당 작은 VM 한 대입니다.</p>
<p>저는 현재 1인 개발자로 두 개의 프로덕트를 운영하고 있습니다. 하나는 현장에서 견적을 내는 기술자들을 위한 <strong>현장 견적 앱</strong>이고, 다른 하나는 게시글 등록과 실시간 메시징을 갖춘 <strong>마켓플레이스 겸 커뮤니티 앱</strong>입니다.</p>
<p>프로덕트도 다르고 사용자도 다르지만, 기술 스택은 거의 동일합니다. 그리고 둘 다 Fly.io에서 가장 저렴한 티어인 <strong>shared-cpu-1x 머신</strong>에서만 돌아갑니다. 이 제약은 의도적인 것입니다. 피크 부하에 맞춰 서버를 크게 잡는 대신, 작은 머신 한 대에서 뽑아낼 수 있는 성능을 최대한 끌어올리고, 정확히 어디서 무너지는지 측정한 다음, 그 측정된 한계를 기준으로 Fly의 오토스케일러가 머신을 추가하고 제거하도록 맡깁니다. 이 글에서는 이를 가능하게 하는 최적화들, 임계값의 근거가 된 부하 테스트 수치, 그리고 Fly.io에서 스케일 업/다운이 실제로 어떻게 동작하는지 다룹니다.</p>

<h2 class="relative group">철학: 머신 한 대를 측정하고, 그다음 곱하기
    <div id="철학-머신-한-대를-측정하고-그다음-곱하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%b2%a0%ed%95%99-%eb%a8%b8%ec%8b%a0-%ed%95%9c-%eb%8c%80%eb%a5%bc-%ec%b8%a1%ec%a0%95%ed%95%98%ea%b3%a0-%ea%b7%b8%eb%8b%a4%ec%9d%8c-%ea%b3%b1%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>두 앱 모두 스케일링 전략은 같은 세 단계입니다.</p>
<ol>
<li>작은 머신 한 대를 합리적인 수준에서 최대한 빠르게 만든다.</li>
<li>무너질 때까지 부하 테스트를 하고, 지연 시간이 급격히 나빠지는 동시성 지점을 기록한다.</li>
<li>그 지점 직전에 두 번째 머신이 시작되도록 Fly 오토스케일러를 설정하고, 트래픽이 줄면 유휴 머신을 정지시킨다.</li>
</ol>
<p>그러면 용량은 머신 수에 거의 선형으로 비례해서 늘어나고, 기본 비용은 앱당 작은 VM 한 대입니다. 아래의 모든 내용은 이 세 단계 중 하나를 위한 것입니다.</p>

<h2 class="relative group">작은 머신 한 대를 빠르게 만들기
    <div id="작은-머신-한-대를-빠르게-만들기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%9e%91%ec%9d%80-%eb%a8%b8%ec%8b%a0-%ed%95%9c-%eb%8c%80%eb%a5%bc-%eb%b9%a0%eb%a5%b4%ea%b2%8c-%eb%a7%8c%eb%93%a4%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>

<h3 class="relative group">Granian: API는 WSGI, WebSocket은 uvloop ASGI
    <div id="granian-api는-wsgi-websocket은-uvloop-asgi" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#granian-api%eb%8a%94-wsgi-websocket%ec%9d%80-uvloop-asgi" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>두 백엔드 모두 Django 6 + Django REST Framework입니다. API는 Rust 기반 서버인 <strong>Granian</strong>이 서빙하지만, ASGI가 아니라 <strong>블로킹 스레드 풀을 쓰는 WSGI</strong>로 돌립니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">granian --interface wsgi myapp.wsgi:application <span class="se">\
</span></span></span><span class="line"><span class="cl">    --workers <span class="m">1</span> --blocking-threads <span class="m">16</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    --workers-max-rss <span class="m">1400</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    --workers-kill-timeout <span class="m">15</span> --respawn-failed-workers</span></span></code></pre></div></div>
<p>처음에는 <code>--interface asgi --loop uvloop</code>로 시작했는데, 잘못된 선택이었습니다. 이 앱들의 모든 HTTP 뷰는 동기(sync)이고, Django의 ASGI 핸들러는 동기 뷰를 <code>thread_sensitive</code>로, 즉 워커당 한 번에 하나씩 실행합니다. 그래서 ASGI는 워커당 동시 요청을 사실상 하나로 묶어놓으면서도, asyncio/uvloop/Channels 스택 전체를 그냥 메모리에 올려두기만 했습니다. <code>--blocking-threads</code>를 쓰는 WSGI는 같은 동기 뷰를 진짜 스레드 풀에서 돌립니다. 워커 1개 × 스레드 16개 = I/O 바운드 요청(DB 읽기, S3 프리사인) 16개 동시 처리를, 비동기 스택보다 낮은 상주 메모리로 해냅니다.</p>
<p>왜 워커 하나일까요? VM이 코어 하나짜리 <code>shared-cpu-1x</code>이기 때문입니다. 두 번째 워커는 코어 하나에서 파이썬을 병렬로 돌릴 수 없지만(GIL + 코어 1개), 상주하는 Django 프로세스 하나를 통째로 더 잡아먹습니다. Granian이 바로 이 점을 경고합니다. 워커 하나에 스레드 16개가 I/O 바운드 작업에서 1 vCPU 머신의 현실적인 한계치입니다. <code>--workers-max-rss 1400</code>은 워커가 메모리 상한을 넘기면 재생성하므로, 폭주하는 PDF나 이미지 작업이 머신을 OOM으로 끌고 가는 대신 재활용됩니다.</p>
<p>WebSocket은 자체 Granian 프로세스로 빠졌습니다. uvloop와 <code>--ws</code>를 쓰는 <strong>ASGI</strong> 앱이고, 장수명 커넥션을 위해 워커 하나로 돌립니다. 동기 API에는 ASGI 경로가 전혀 필요 없습니다. 뷰가 소켓으로 푸시하려 할 때는 Redis를 통해 <code>async_to_sync(channel_layer.group_send)</code>를 호출하므로, 메시지는 여전히 WebSocket 프로세스로 건너갑니다. 서버 두 개가 각자 진짜 잘하는 인터페이스를 돌리는 셈입니다. 로컬 Docker도 같은 WSGI 스레드 풀로 돌리기 때문에, 테스트할 때 제 노트북이 프로덕션 머신 한 대와 거의 같은 조건이 됩니다.</p>

<h3 class="relative group">핫 패스에는 Rust
    <div id="핫-패스에는-rust" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ed%95%ab-%ed%8c%a8%ec%8a%a4%ec%97%90%eb%8a%94-rust" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>Python 핫 패스에 Rust 기반 대체재가 있으면 무조건 씁니다.</p>
<ul>
<li><strong>orjson</strong> (<code>drf-orjson-renderer</code> 경유) — 모든 API 응답이 표준 라이브러리 JSON 인코더 대신 Rust로 직렬화됩니다.</li>
<li><strong>blurhash-rs</strong> — 업로드 시점에 이미지 플레이스홀더를 계산합니다.</li>
<li><strong>uuid-utils</strong> — Rust 기반 UUID 생성.</li>
<li><strong>psycopg 3 (binary)</strong> — C로 가속된 Postgres 드라이버.</li>
</ul>
<p>이것들은 아키텍처를 바꾸지 않습니다. 두 번째 머신이 필요해지기 전까지 vCPU 하나가 해낼 수 있는 한계치를 끌어올릴 뿐입니다.</p>

<h3 class="relative group">숨어 있는 지연 비용 없애기
    <div id="숨어-있는-지연-비용-없애기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%88%a8%ec%96%b4-%ec%9e%88%eb%8a%94-%ec%a7%80%ec%97%b0-%eb%b9%84%ec%9a%a9-%ec%97%86%ec%95%a0%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>두 코드베이스를 통틀어 가장 큰 성능 개선은 알고리즘이 아니라 커넥션 재사용이었습니다. Granian의 스레드 풀에서는 새 스레드마다 boto3 S3 클라이언트를 새로 만들고 있었고, 사진이나 PDF를 반환하는 모든 엔드포인트가 그 비용을 지불하고 있었습니다. 작은 커스텀 스토리지 클래스로 클라이언트를 프로세스 단위로 캐싱하도록 바꾸자:</p>
<blockquote><p>새 스레드에서의 서명된 URL 생성이 <strong>~150ms에서 ~1ms</strong>로 줄었습니다.</p>
</blockquote><p>데이터베이스에도 같은 교훈이 적용됩니다. Fly의 Postgres는 PgBouncer 뒤에 있으므로 앱은 <code>conn_max_age=0</code>으로 두고 커넥션 재사용을 풀러에 맡기며, 오래된 SSL 커넥션에 워커가 매달리지 않도록 <code>connect_timeout</code>을 5초로 잡아 빠르게 실패시킵니다.</p>

<h3 class="relative group">진짜 병목이 있는 곳에 캐싱하기
    <div id="진짜-병목이-있는-곳에-캐싱하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%a7%84%ec%a7%9c-%eb%b3%91%eb%aa%a9%ec%9d%b4-%ec%9e%88%eb%8a%94-%ea%b3%b3%ec%97%90-%ec%ba%90%ec%8b%b1%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>마켓플레이스를 부하 테스트하면서 새겨둘 만한 사실을 발견했습니다. <strong>한계는 CPU가 아니라 Postgres 커넥션이었습니다.</strong> 둘러보기 트래픽은 압도적으로 익명이고 사용자 간에 동일한데, 부하가 걸리면 그 동일한 목록 쿼리들이 CPU는 놀고 있는 동안 커넥션 풀을 포화시킵니다.</p>
<p>해결책은 익명 목록 페이지를 위한 Redis 캐시입니다. 무효화는 네임스페이스별 버전 카운터로 처리합니다. 쓰기가 발생하면 카운터 하나만 올리면 되고(O(1), 키 관리 불필요), 해당 리소스의 캐시된 페이지 전체가 즉시 무효화됩니다. 짧은 TTL이 놓친 것들을 보완합니다. 둘러보기 페이지를 Redis에서 바로 서빙하면 진짜 병목이 제거되고, 작은 머신은 커넥션을 로그인 트래픽에 쓸 수 있게 됩니다.</p>

<h3 class="relative group">브로커 없는 백그라운드 작업
    <div id="브로커-없는-백그라운드-작업" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%b8%8c%eb%a1%9c%ec%bb%a4-%ec%97%86%eb%8a%94-%eb%b0%b1%ea%b7%b8%eb%9d%bc%ec%9a%b4%eb%93%9c-%ec%9e%91%ec%97%85" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>두 앱 모두 Celery 대신 Django의 데이터베이스 기반 태스크 프레임워크인 <strong>django-tasks-db</strong>를 씁니다. 별도의 <code>db_worker</code> 프로세스가 데이터베이스를 폴링하며 이미지 처리, PDF 생성, 기계 번역, 리마인더 같은 작업을 처리합니다. 브로커도 없고, 크기를 정하고 모니터링해야 할 추가 서비스도 없으며, API 프로세스는 무거운 작업에 절대 블로킹되지 않습니다. 심지어 워커는 PgBouncer를 우회해 Postgres에 직접 연결하는데, 오래 걸리는 작업은 트랜잭션 풀링과 잘 맞지 않기 때문입니다.</p>

<h3 class="relative group">메모리: jemalloc과 스왑 쿠션
    <div id="메모리-jemalloc과-스왑-쿠션" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%a9%94%eb%aa%a8%eb%a6%ac-jemalloc%ea%b3%bc-%ec%8a%a4%ec%99%91-%ec%bf%a0%ec%85%98" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>이미지와 PDF 처리는 정상 상태 기준의 메모리 산정으로는 예측할 수 없는 스파이크를 만듭니다. 저렴한 완화책 두 가지: Docker 이미지에 <strong>jemalloc</strong>을 프리로드해 단편화를 줄이고, <strong>모든 머신에 스왑</strong>을 둡니다(API 머신 2GB, WebSocket 머신 1GB). 스파이크가 나면 프로세스가 OOM으로 죽는 대신 디스크로 스왑됩니다. 스왑은 성능 기능이 아니라, 메모리 할당을 작게 유지할 수 있게 해주는 보험입니다.</p>

<h2 class="relative group">Django 부하 테스트: 변곡점 찾기
    <div id="django-부하-테스트-변곡점-찾기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#django-%eb%b6%80%ed%95%98-%ed%85%8c%ec%8a%a4%ed%8a%b8-%eb%b3%80%ea%b3%a1%ec%a0%90-%ec%b0%be%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>임계값은 직접 측정한 값이어야 설득력이 있습니다. 프로젝트마다 자체 하네스가 있습니다.</p>
<ul>
<li>견적 앱에는 동시성 레벨을 훑으며 RPS, p50/p95/p99, 에러율을 보고하는 작은 Python 스트레스 테스트 스크립트가 있습니다. 미리 생성해 둔 수백 건의 샘플 데이터를 상대로 돌리기 때문에 목록 엔드포인트가 현실적인 데이터 양에서 쿼리됩니다.</li>
<li>마켓플레이스는 <strong>Locust</strong>로 30초 단위 스텝을 밟아 50 → 500 사용자까지 올리며 포화 지점을 찾고, 실제 둘러보기 위주 트래픽에 맞춘 엔드포인트 가중치를 씁니다. 여기에 더 작은 별도 테스트 스위트가 p95 &lt; 2초 임계값으로 프로덕션을 상대로 가상 사용자 5 → 50을 램프합니다.</li>
</ul>
<p>견적 앱 스윕의 대표적인 수치입니다(Granian 워커 1개 × 블로킹 스레드 16개, 개발 머신의 Docker):</p>
<table>
	<thead>
			<tr>
					<th>엔드포인트</th>
					<th>동시성</th>
					<th>RPS</th>
					<th>p95</th>
					<th>에러</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>health</td>
					<td>25</td>
					<td>602</td>
					<td>52ms</td>
					<td>0%</td>
			</tr>
			<tr>
					<td>무거운 목록</td>
					<td>25</td>
					<td>309</td>
					<td>260ms</td>
					<td>0%</td>
			</tr>
			<tr>
					<td>가벼운 목록</td>
					<td>25</td>
					<td>357</td>
					<td>61ms</td>
					<td>0%</td>
			</tr>
			<tr>
					<td>무거운 목록</td>
					<td>50</td>
					<td>309</td>
					<td>347ms</td>
					<td>0%</td>
			</tr>
	</tbody>
</table>
<p>그리고 다른 모든 것을 결정하는 숫자는 <strong>shared-cpu-1x 머신 한 대</strong>에서 마켓플레이스를 부하 테스트한 결과에서 나옵니다. 기존 ASGI 빌드에서는 이게 단단한 벽이었습니다. 동기 뷰가 사실상 <strong>슬롯 3개</strong> 정도로 직렬화되는 바람에, p95가 동시 요청 ~5개까지 300ms 미만을 유지하다가 모든 게 thread_sensitive 락 뒤에 줄 서면서 ~8–10개를 지나면 붕괴했습니다. 이 변곡점을 바깥으로 밀어낸 것이 바로 API를 WSGI 스레드 풀로 옮긴 일입니다. 머신당 실질 동시 슬롯이 ~3개가 아니라 <strong>16개</strong>가 됐고, 이 새 천장이 오토스케일링 설정 전체의 근거입니다.</p>

<h2 class="relative group">Fly.io에서 스케일링이 동작하는 방식
    <div id="flyio에서-스케일링이-동작하는-방식" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#flyio%ec%97%90%ec%84%9c-%ec%8a%a4%ec%bc%80%ec%9d%bc%eb%a7%81%ec%9d%b4-%eb%8f%99%ec%9e%91%ed%95%98%eb%8a%94-%eb%b0%a9%ec%8b%9d" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Fly의 모델은 단순합니다. 앱은 프록시 뒤에 있는 동일한 머신들의 집합이고, 프록시가 머신별 부하를 셉니다. 선언하는 것은 숫자 두 개입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">.</span><span class="nx">concurrency</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">type</span> <span class="p">=</span> <span class="s1">&#39;requests&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">soft_limit</span> <span class="p">=</span> <span class="mi">12</span>   <span class="c"># 이를 넘으면 다른 머신을 시작</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hard_limit</span> <span class="p">=</span> <span class="mi">24</span>   <span class="c"># 이를 넘으면 큐잉 대신 부하를 차단</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nx">auto_stop_machines</span> <span class="p">=</span> <span class="s1">&#39;stop&#39;</span>
</span></span><span class="line"><span class="cl"><span class="nx">auto_start_machines</span> <span class="p">=</span> <span class="kc">true</span>
</span></span><span class="line"><span class="cl"><span class="nx">min_machines_running</span> <span class="p">=</span> <span class="mi">1</span></span></span></code></pre></div></div>
<p><strong>스케일 업:</strong> 한 머신의 진행 중(in-flight) 요청이 soft limit을 넘으면 프록시가 정지된 머신을 시작하고 새 트래픽을 그쪽으로 보냅니다. WSGI 스레드 풀 덕에 머신마다 실질 동시 슬롯이 16개이므로 soft limit은 풀의 약 75%인 12로 잡았습니다. 이렇게 하면 사용자가 수 초짜리 지연을 겪은 뒤가 아니라 스레드에 아직 여유가 있을 때 두 번째 머신이 시작됩니다. hard limit 24(풀의 1.5배)는 서킷 브레이커입니다. 짧은 버스트는 스레드에서 큐잉되고, 그 너머에서는 머신 하나가 녹아내리게 두는 대신 프록시가 부하를 차단합니다. (기존 ASGI 빌드는 실질 슬롯이 ~3개여서 8/20이었습니다. 풀을 넓힌 덕에 두 숫자 모두 올릴 수 있었습니다.)</p>
<p><strong>스케일 다운:</strong> 트래픽이 줄면 Fly가 유휴 머신을 자동으로 정지시키고, <code>min_machines_running = 1</code>까지 내려갑니다. 정지된 머신은 컴퓨팅 비용이 들지 않고 루트 파일시스템 스토리지만 청구되므로, 각 앱의 기본 비용은 말 그대로 작은 VM 한 대이고 버스트 용량은 항상 대기 중입니다.</p>
<p>원래 저는 여기에 정지된 머신이 &ldquo;1초도 안 되어 콜드 스타트한다&quot;고 썼습니다. 틀렸고, 비싸게 틀렸습니다. 가정하는 대신 실제로 측정해보니 콜드 스타트는 <strong>25~33초</strong>가 걸렸고, 아직 부팅 중인 머신에 떨어진 요청은 그 시간을 고스란히 기다려야 합니다. 처음에는 헬스 체크가 전부 초록불인 와중에 CDN 대시보드에 찍힌 22퍼센트 실패율을 이 콜드 스타트 탓으로 돌렸습니다. 알고 보니 그 숫자는 CDN 자체의 Early Hints 프로브가 오리진에서 실패한 것이었고, 실제 클라이언트가 받은 504는 하나도 없었습니다. 그래도 콜드 스타트 자체는 진짜였습니다.</p>
<p>해결책은 위의 스케일링 숫자에 있지 않습니다. 그 숫자들은 멀쩡합니다. 머신이 올라오는 동안 무엇을 하느냐에 있고, Fly에게 머신을 정지 대신 서스펜드하도록 요청하는 데 있습니다. 그러면 깨어나는 일이 약 3초짜리 메모리 복원이 됩니다. 따로 정리해두었습니다. <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-09-scale-to-zero-504s/" >0으로 스케일 다운, 그리고 재시작마다 30초짜리 장애</a>에서 진단 과정과 무엇을 바꿔야 하는지를 다룹니다. <code>auto_stop_machines</code>를 쓰면서 Fly에서 뭔가를 돌리고 있다면, 이 문단을 믿기 전에 그 글을 먼저 읽으세요.</p>
<p>한 가지 미묘한 포인트: 동시성 타입이 <code>connections</code>가 아니라 <code>requests</code>입니다. 현대 클라이언트는 keep-alive 커넥션을 계속 열어 두기 때문에, 커넥션을 세면 실제 부하에서도 수치가 거의 움직이지 않아 오토스케일러가 트리거되지 않습니다. 진행 중 요청을 세야 실제 작업량이 추적됩니다.</p>

<h3 class="relative group">WebSocket은 다른 축으로 스케일된다
    <div id="websocket은-다른-축으로-스케일된다" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#websocket%ec%9d%80-%eb%8b%a4%eb%a5%b8-%ec%b6%95%ec%9c%bc%eb%a1%9c-%ec%8a%a4%ec%bc%80%ec%9d%bc%eb%90%9c%eb%8b%a4" aria-label="앵커">#</a>
    </span>
    
</h3>
<p>마켓플레이스는 WebSocket 서버를 같은 Docker 이미지를 공유하는 <strong>두 번째 Fly 앱</strong>으로 분리합니다. API 앱은 WSGI로 워커 1개 × 블로킹 스레드 16개를 돌리며 <em>요청</em>을 셉니다(soft limit 12). WebSocket 앱은 <strong>512MB</strong> 머신에서 ASGI로 uvloop와 함께 워커 1개를 돌리며 <em>커넥션</em>을 셉니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">http_service</span><span class="p">.</span><span class="nx">concurrency</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">  <span class="nx">type</span> <span class="p">=</span> <span class="s1">&#39;connections&#39;</span>
</span></span><span class="line"><span class="cl">  <span class="nx">soft_limit</span> <span class="p">=</span> <span class="mi">1500</span>
</span></span><span class="line"><span class="cl">  <span class="nx">hard_limit</span> <span class="p">=</span> <span class="mi">2000</span></span></span></code></pre></div></div>
<p>오래 유지되는 소켓은 열어 두는 비용은 거의 없지만 슬롯을 몇 시간씩 차지하고, HTTP 요청은 슬롯을 밀리초 단위로 차지합니다. 같은 오토스케일링 신호로 둘 다 감당할 수는 없습니다. 분리하면 각 플릿이 자기 부하를 제대로 반영하는 지표로 스케일되고, 유휴 WebSocket 용량은 2GB가 아니라 512MB만 차지합니다. Channels 쪽에서는 Redis 레이어가 <code>capacity: 1500</code>과 60초 메시지 만료로 돌아가고, 30초마다 소켓 keepalive를 보냅니다. Fly의 Redis 프록시가 Channels가 의존하는 장수명 BRPOP 소켓을 유휴 상태로 간주해 끊어버리기 때문입니다.</p>

<h2 class="relative group">컴퓨팅을 엣지와 클라이언트로 오프로드하기
    <div id="컴퓨팅을-엣지와-클라이언트로-오프로드하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%bb%b4%ed%93%a8%ed%8c%85%ec%9d%84-%ec%97%a3%ec%a7%80%ec%99%80-%ed%81%b4%eb%9d%bc%ec%9d%b4%ec%96%b8%ed%8a%b8%eb%a1%9c-%ec%98%a4%ed%94%84%eb%a1%9c%eb%93%9c%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>가장 저렴한 서버 작업은 서버가 아예 하지 않는 작업입니다.</p>
<ul>
<li><strong>정적 파일과 미디어</strong>는 Fly의 S3 호환 오브젝트 스토리지에 두고, 비공개 미디어는 서명된 URL로 CDN을 통해 서빙합니다. 이미지 바이트는 Django 머신을 전혀 거치지 않습니다.</li>
<li><strong>AI 추론은 사용자의 폰에서 돌아갑니다.</strong> 두 앱 모두 작은 로컬 LLM(양자화된 4B 모델, 약 2.7GB)을 내장해 기기에서 직접 돌립니다. 서버 측 추론 비용은 0이고, 오프라인에서도 동작합니다.</li>
<li><strong>오프라인 우선 모바일</strong>(기기의 SQLite와 재시도가 있는 동기화 큐) 덕분에 앱은 키 입력마다 수다스러운 요청으로 API를 두들기는 대신, 쓰기를 배치로 모으고 통신 음영 지역을 견딥니다.</li>
</ul>

<h2 class="relative group">나머지 스택, 간단히
    <div id="나머지-스택-간단히" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%82%98%eb%a8%b8%ec%a7%80-%ec%8a%a4%ed%83%9d-%ea%b0%84%eb%8b%a8%ed%9e%88" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>인증은 호스팅형 ID 공급자와 WebAuthn 패스키를 쓰고, WebSocket 커넥션은 업그레이드 완료 전에 인증합니다. 프로덕션은 Postgres, 개발은 SQLite. 관리자 화면과 감사 이력에는 기성 Django 패키지 몇 개를 씁니다. 모바일은 Expo 위의 React Native와 TypeScript에 Expo Router와 Tailwind를 쓰고, OTA 업데이트는 자체 호스팅 Expo Updates 서버에서 내보내며, 인앱 구독은 구독 관리 서비스에 맡깁니다. 품질 게이트는 백엔드에 pytest와 mypy, 클라이언트에 단위 테스트와 E2E 테스트입니다.</p>

<h2 class="relative group">가져가서 쓸 만한 것
    <div id="가져가서-쓸-만한-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ea%b0%80%ec%a0%b8%ea%b0%80%ec%84%9c-%ec%93%b8-%eb%a7%8c%ed%95%9c-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이식 가능한 아이디어는 특정 라이브러리가 아니라 루프 자체입니다. 저렴한 머신 한 대를 진짜로 빠르게 만들고(Rust 핫 패스, 커넥션 재사용, 진짜 병목 앞의 캐시, CDN과 클라이언트로 오프로드), 정확히 어느 동시성에서 무너지는지 찾을 때까지 부하 테스트를 하고, 오토스케일러의 soft limit을 그 변곡점에 놓고, 유휴 머신은 정지시키고, 최소 플릿은 1로 유지합니다. 프로덕션 앱 두 개, 실시간 기능, AI 어시스턴트 — 그런데 평상시 청구서는 플랫폼에서 가장 저렴한 VM 두어 대 값입니다.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-07-22-my-current-stack/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
