<?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/ja/tags/performance/</link>
    <description>ソフトウェアエンジニアリングと開発組織のリーダーシップについて。評価、採用とチームの拡大、CI/CD、DevOps モニタリング、エージェンティック AI。ソウルより。</description>
    <generator>Hugo</generator>
    <language>ja</language>
    <copyright>© 2026 仁才徳</copyright>
    <lastBuildDate>Sat, 21 Nov 2026 17:52:23 +0900</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/ja/tags/performance/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>閉じられたプルリクエスト、フォーク、そしてPyPIパッケージ：Python向けの高速なHTML→Markdown変換</title>
      <link>https://jared.lynskey.co.nz/ja/posts/2026/2026-10-18-pyhtml2text/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ja/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に変換するとき、相対リンクを解決する必要がありました。上流のRustクレートは、LLMで書かれたという理由で私のプルリクエストを受け入れられなかったので、フォークしてpyhtml2textとして公開しました。base_url付きのPythonバインディング、新しいhtml2markdown、プロファイルガイド最適化をかけたwheel、そして深くネストしたHTMLを線形時間で処理できるようにパッチを当てたパーサーです。なぜ作ったのか、中に何が入っているのか、そして出力をどう検証したかを紹介します。</description>
      <content:encoded><![CDATA[<p>10月15日、<a href="https://pypi.org/project/pyhtml2text/"  target="_blank" rel="noreferrer">pyhtml2text</a>をPyPIで公開しました。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="#%e3%81%aa%e3%81%9c%e5%bf%85%e8%a6%81%e3%81%a0%e3%81%a3%e3%81%9f%e3%81%ae%e3%81%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>私が作っているマーケットプレイス兼コミュニティアプリは、<code>Accept: text/markdown</code> のリクエストに、HTMLの代わりにMarkdownを返します。ナビゲーションバーやフッターをかき分けて読みたくないAIエージェントやLLMクライアントのためです。エッジ側の話は<a href="https://jared.lynskey.co.nz/ja/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="#%e3%81%be%e3%81%9a%e3%81%af%e4%b8%8a%e6%b5%81%e3%81%ab%e7%9b%b8%e8%ab%87" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>8月29日に<a href="https://github.com/jugglerchris/rust-html2text/issues/287"  target="_blank" rel="noreferrer">issue #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> というオプションを追加する変更で、issueには「たたき台のつもりなので、メンテナーが別のアプローチを取りたければそれでも構わない」と書き添えました。</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>issueにも返信がありました。</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="#%e3%83%95%e3%82%a9%e3%83%bc%e3%82%af%e3%81%ae%e4%b8%ad%e8%ba%ab" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>フォークは私のrust-html2textフォークの<code>pyhtml2text-perf</code> ブランチです。上流にきれいにリベースできるよう、小さなコミット3つだけにとどめています。中心は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%e3%83%91%e3%83%83%e3%82%b1%e3%83%bc%e3%82%b8" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p><a href="https://github.com/jaredlynskey/pyhtml2text"  target="_blank" rel="noreferrer">pyhtml2text</a>はPyO3とmaturinで作っていて、関数は2つです。</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を必要としないことも宣言しているので、フリースレッド版のPython 3.14tでも、インポート時にGILが再び有効になることはありません。</li>
<li><strong>パニックは <code>ValueError</code> として返ります。</strong> PyO3はデフォルトで <code>PanicException</code> を送出しますが、これは <code>except Exception</code> では捕まえられません。変換エラーは処理済みのつもりのWebワーカーがそれで落ちてしまうので、バインディング側で捕まえて <code>ValueError</code> として送出し直しています。</li>
<li><strong>wheelは30個あります。</strong> CPython 3.10以降向けのabi3 wheelと、フリースレッド版3.14t向けのwheelを、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="#%e9%ab%98%e9%80%9f%e5%8c%96" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>バージョン0.2.0は、実際のページで0.1.0の1.5〜1.7倍、短いスニペットでは2倍速くなり、出力はバイト単位で同じでした。大半はプロファイルガイド最適化（PGO）によるものです。CIで計測用のwheelをビルドし、ドキュメントのページとRFCからなる学習用セットで動かして、そのプロファイルを使って本番のwheelをビルドします。学習用セットに含まれないページで約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="#%e6%b7%b1%e3%81%8f%e3%83%8d%e3%82%b9%e3%83%88%e3%81%97%e3%81%9fhtml%e3%81%a8html5ever%e3%81%b8%e3%81%ae%e3%83%91%e3%83%83%e3%83%81" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>40,000階層のリストを手で書く人はいません。でも、自分が書いていないページを変換していれば、いずれ悪意のあるものや壊れたものが送られてきます。標準のパーサーでは、40,000階層にネストした <code>&lt;ul&gt;&lt;li&gt;</code> のパースに<strong>6秒</strong>かかりました。たった1つのリクエストでワーカーが止まってしまうということです。</p>
<p>原因は、rust-html2textが使っているHTML5パーサーの<a href="https://github.com/servo/html5ever"  target="_blank" rel="noreferrer">html5ever</a>にありました。ほとんどのブロックレベルの開始タグは、開いている <code>&lt;p&gt;</code> 要素が「button scope内」にあるかを確認する必要があり、html5everはそのたびに開いている要素のスタック全体をたどっていました。ネストが深くなるほどタグ1つあたりの時間が延び、全体の時間は深さの2乗で増えていったわけです。</p>
<p>パッケージには、パッチを1つ当てたhtml5ever 0.39.0を同梱しています。要素が開いたり閉じたりするたびにその答えを更新しておくので、確認にかかる時間がネストの深さに左右されなくなりました。同じ文書のパースは<strong>0.14秒</strong>になりました。パッチがほかに何も変えていないことを確かめるため、html5libのツリー構築テストすべて、実際のページ約20件、ランダムなタグスープ文書300,000件で、元のパーサーとパッチ版のDOMを比較し、すべて一致しました。</p>
<p>Markdownコンバーターにも、同じ理由で上限を設けています。どんな入力でもスレッドのスタックをあふれさせることはなく、引用やリストは32階層を超えるとそれ以上インデントしないので、出力が2乗で膨らむこともありません。展開したグリッドが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>~~strikethrough~~</code> を加えた形で書き出します。</p>
<ul>
<li><code>#</code> の見出し、<code>-</code> の箇条書き、<code>_emphasis_</code> と <code>**strong**</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="#%e5%bf%85%e8%a6%81%e3%81%aa%e3%81%a8%e3%81%93%e3%82%8d%e3%81%a0%e3%81%91%e3%82%a8%e3%82%b9%e3%82%b1%e3%83%bc%e3%83%97%e3%81%99%e3%82%8b" 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="#%e9%9f%93%e5%9b%bd%e8%aa%9e%e3%81%ae%e5%8a%a9%e8%a9%9e%e3%81%ae%e5%89%8d%e3%81%ae%e5%a4%aa%e5%ad%97" aria-label="アンカー">#</a>
    </span>
    
</h3>
<p>これは私のアプリ自身のページで見つかった問題です。韓国語では、文法上の助詞がスペースなしで名詞の直後に付きます。そのため、括弧を含む語を太字にするとこうなります。</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>
<p>日本語でも同じことが起きます。日本語の助詞（の、を、は）も、韓国語と同じく前の語にスペースなしで付きます。全角の括弧もCommonMarkでは句読点として扱われるので、<code>**タイタニック（Titanic）**の</code> のような書き方では太字になりません。中国語をはじめ、後ろに続く語の前にスペースを置かない言語ならどれも同じです。</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="#%e8%aa%ad%e3%81%bf%e6%88%bb%e3%81%97%e3%81%a6%e5%87%ba%e5%8a%9b%e3%82%92%e7%a2%ba%e3%81%8b%e3%82%81%e3%82%8b" 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="#%e6%9c%ac%e7%95%aa%e7%92%b0%e5%a2%83%e3%81%a7" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>私のアプリのMarkdownネゴシエーションは、0.3.0が出たその日に、純粋なPythonのhtml2textからpyhtml2textに切り替えました。ガイドページのひとつでは、変換が4.2 msから0.36 msになり、約12倍高速になりました。リンクは絶対URLになり、表は本物のパイプテーブルになり、韓国語の太字は助詞がくっついたままです。abi3 wheelが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="#%e3%82%af%e3%83%ac%e3%82%b8%e3%83%83%e3%83%88%e3%81%a8%e3%83%90%e3%82%b0%e5%a0%b1%e5%91%8a%e5%85%88" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>プレーンテキストのレンダリングは、Chris EmersonさんによるMITライセンスのrust-html2textです。pyhtml2textは、そのフォーク、パッチを当てたhtml5ever（MIT/Apache-2.0）、そしてMarkdownコンバーターを加えたものです。このパッケージはどちらのプロジェクトとも提携しておらず、承認も受けていません。なので、<strong>問題は上流ではなく<a href="https://github.com/jaredlynskey/pyhtml2text/issues"  target="_blank" rel="noreferrer">pyhtml2textのissueトラッカー</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/ja/posts/2026/2026-09-09-scale-to-zero-504s/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ja/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）を使うと、停止中のマシンへのリクエストは起動を待たされます。25〜33秒かかっていたコールドスタートを約3秒まで縮めた記録です。</description>
      <content:encoded><![CDATA[<p><strong>追記（2026年10月22日）</strong>：この記事の一番大事な数字は間違っています。公開したその日に、ゾーンの504をユーザーエージェントごとに集計したところ、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率を障害と判断する前に、どのユーザーエージェントがそのエラーを受けているかを確認してください。</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/ja/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秒かかっていました。この作業をイメージごとに1回だけ（<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 のダッシュボードでトラフィックの急増を調べに行ったら、その下にもっとひどいものが埋まっていました。1日のうちにアプリが処理したリクエストの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="#%e6%80%a5%e5%a2%97%e3%81%af%e5%9b%ae%e3%81%a0%e3%81%a3%e3%81%9f" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>もともと調べたかったのは、中央値が毎時121件のところに約4,900件が集中した1時間です。ユニークな訪問者は42人。1人あたり110リクエストで、人間のブラウジングではありません。</p>
<p>スキャナーでした。ボットが1体、存在しないサブドメインをでっち上げながら、それぞれにシークレットを要求して回っていました。</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>30ほどのホスト名、思いつく限りの <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秒ごとにポーリングしているエンドポイントです。つまりこれは抽象的なエラー率の数字ではありませんでした。ユーザーの端末が1日中、おそらく何週間も、未読バッジを静かに読み込めずにいたということです。</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="#%e3%83%ad%e3%82%b0%e3%81%8c%e5%81%a5%e5%85%a8%e3%81%ab%e8%a6%8b%e3%81%88%e3%81%9f%e7%90%86%e7%94%b1" 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">ゼロスケールはコストの約束であって、レイテンシの約束ではない
    <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="#%e3%82%bc%e3%83%ad%e3%82%b9%e3%82%b1%e3%83%bc%e3%83%ab%e3%81%af%e3%82%b3%e3%82%b9%e3%83%88%e3%81%ae%e7%b4%84%e6%9d%9f%e3%81%a7%e3%81%82%e3%81%a3%e3%81%a6%e3%83%ac%e3%82%a4%e3%83%86%e3%83%b3%e3%82%b7%e3%81%ae%e7%b4%84%e6%9d%9f%e3%81%a7%e3%81%af%e3%81%aa%e3%81%84" 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>アイドルのマシンは停止し、トラフィックが来れば再び起動する。使った分だけ払う。トラフィックにムラのある小さなアプリならまさに望む挙動で、だからこそマシンを10台定義していても普段は1台しか動いていませんでした。</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>1日にコールドスタートが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="#%e5%8e%9f%e5%9b%a0%e3%81%af%e8%87%aa%e5%88%86%e3%81%ae-entrypoint-%e3%81%ae%e4%b8%ad%e3%81%ab%e3%81%82%e3%81%a3%e3%81%9f" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>すべてのマシンが、リクエストを1件処理する前に実行していたものです。</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>「1日に92回」を思い浮かべながらもう一度読んでみてください。</p>
<p><code>migrate</code> は完全な Django の起動です。全モデルをインポートし、Postgres に接続し、マイグレーションテーブルを問い合わせ、やることがないと判断する。共有CPUでは、何も達成しないために10秒かかります。<code>collectstatic</code> は2回目の完全な Django 起動で、そのうえ静的ファイルをオブジェクトストレージにアップロードし、Web サーバーが立ち上がろうとしているまさに同じ単一コアを奪い合います。アプリサーバーが3回目の起動です。</p>
<p>Python インタプリタが3つ、うち2つはすでに済んだ作業を繰り返しながら、マシンが目覚めるたびに毎回。</p>
<p>そう書いた理由はまっとうで、同じような形になっているコードは多いはずです。マイグレーションはどこかで走らせる必要があり、Fly の <code>release_command</code> は以前ハングしたことがあり、entrypoint はデプロイ時に必ず実行される唯一の場所だからです。デプロイ作業を置く場所としては正しい。ただ<strong>マシン起動ごと</strong>に置く場所としては正しくない。そしてマシンが自分で止まったり起きたりし始めた瞬間、その2つはもう同じ出来事ではありません。</p>
<p>バグの全体はこれで、よくある種類だと思います。</p>
<blockquote><p><strong>リリース</strong>に属する作業が、<strong>マシン起動</strong>ごとに実行されていました。ゼロスケールが1つの出来事を92個に変えたのです。</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="#%e8%a7%a3%e6%b3%95-%e3%83%aa%e3%83%aa%e3%83%bc%e3%82%b9%e3%82%92%e4%b8%80%e5%ba%a6%e3%81%a0%e3%81%91%e7%a2%ba%e4%bf%9d%e3%81%99%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>あるイメージで起動する8台目のマシンでマイグレーションが走る必要はありません。そのイメージについて一度走ればよく、残りはそれが済んだと知ればよいだけです。</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">すべての失敗は「とにかく準備する」で終わらせる
    <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="#%e3%81%99%e3%81%b9%e3%81%a6%e3%81%ae%e5%a4%b1%e6%95%97%e3%81%af%e3%81%a8%e3%81%ab%e3%81%8b%e3%81%8f%e6%ba%96%e5%82%99%e3%81%99%e3%82%8b%e3%81%a7%e7%b5%82%e3%82%8f%e3%82%89%e3%81%9b%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>コードよりも、この部分こそ真似する価値があります。</p>
<p>このゲートはユーザーとスキーマのマイグレーションの間に立ちます。<strong>スキップする</strong>方向に間違えれば、マイグレーションされていないデータベースにリクエストを受けることになり、これは本物の障害です。<strong>準備する</strong>方向に間違えれば、冪等な no-op のマイグレーションを2回走らせて10秒を無駄にするだけです。</p>
<p>この2つの結果は対称ではないので、コードも対称に扱ってはいけません。不確かな経路はすべて <code>PREPARE</code> を返します。</p>
<ul>
<li><strong>Redis がない、または到達不能。</strong> 準備します。これは以前の挙動そのものなので、キャッシュ障害は「壊れる」ではなく「遅くなる」に落ちます。</li>
<li><strong>環境にイメージ参照がない。</strong> 準備します。どのリリースか分からない以上、準備済みかどうかも分かりません。</li>
<li><strong>ロックの持ち主がマイグレーション中に落ちた。</strong> ロックが期限切れになり、次の待機者が引き継いで準備します。</li>
<li><strong>タイムアウトより長く待った。</strong> それでも準備します。永遠にサービスできないマシンのほうが、重複マイグレーションより悪いからです。</li>
</ul>
<p>逆方向の非対称を1つだけ意図的に入れてあります。他のマシンが実際にロックを保持していると分かったマシンは、サービスを始めずに<strong>待ちます</strong>。デプロイ中に起動が遅いのは構いません。半分だけ適用されたスキーマに問い合わせを受けるのは困ります。</p>
<p>接続エラーを握りつぶすキャッシュラッパーの上にこれを組む場合、罠が1つあります（私も最初はそうしていました）。そういうラッパーは Redis に到達できないとき <code>add()</code> が <code>False</code> を返し、それは「他の誰かがロックを持っている」とまったく同じに読めます。そのままなら全マシンがマイグレーションをスキップしていました。まさに危険な方向です。ロックを読み返して区別してください。誰も保持していないロックは、競争に負けたのではなく、キャッシュが壊れているという意味です。</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-%e3%81%aa%e3%81%97%e3%81%a7%e3%83%86%e3%82%b9%e3%83%88%e3%81%99%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>このロジックはユニットテストの価値があります。面白い経路ほど手作業では再現できないからです。メソッド2つのフェイクで足ります。</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> の別名を使っているのはこのためです。こうしておけば、同じプロセスの他のスレッドに影響する <code>time</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="#%e5%8a%b9%e6%9e%9c%e3%81%af%e3%81%82%e3%81%a3%e3%81%9f%e3%81%8b%e5%8d%8a%e5%88%86%e3%81%af" 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秒、2台目は11秒でした。以前の25〜33秒に対して、窓の3分の2が消えたことになります。ゲート自体は Django を一切インポートしないので2秒で済みます。</p>
<p>しかし10秒はやはり10秒です。その最初の1秒に届いたリクエストは相変わらず失敗します。そこで残りを探しに行きました。</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="#%e8%aa%b0%e3%82%82%e3%82%ad%e3%83%a3%e3%83%83%e3%82%b7%e3%83%a5%e3%81%97%e3%81%a6%e3%81%84%e3%81%aa%e3%81%8b%e3%81%a3%e3%81%9f%e3%83%90%e3%82%a4%e3%83%88%e3%82%b3%e3%83%bc%e3%83%89" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>このイメージには、世の中のほぼすべての Python 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 フレームワークもすべてのライブラリも、1日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> はすべてイメージに載っていました。ノートパソコンの Python 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="#%e3%82%b5%e3%82%b9%e3%83%9a%e3%83%b3%e3%83%89%e3%81%a8%e3%81%9d%e3%82%8c%e3%82%92%e5%a1%9e%e3%81%84%e3%81%a7%e3%81%84%e3%81%9f%e4%b8%80%e8%a1%8c" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>9秒まで来て、取り除ける作業が尽きました。残っていたのは避けられない起動1回分です。Python が立ち上がり、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>1ページたりともスワップされたことがありません。その日のログにも OOM kill はなく、&ldquo;oom&rdquo; に一致した11行は、コンテンツハッシュにたまたまその3文字を含む JavaScript バンドルへのリクエストでした。そして本当のメモリガードはまったく別の場所、アプリサーバー自身の設定にありました。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>3回試して、ばらつきは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="#%e3%83%9e%e3%82%b7%e3%83%b3%e3%81%8c%e7%9c%a0%e3%81%a3%e3%81%a6%e3%81%84%e3%82%8b%e9%96%93%e3%82%bd%e3%82%b1%e3%83%83%e3%83%88%e3%81%af%e3%81%a9%e3%81%86%e3%81%aa%e3%82%8b%e3%81%ae%e3%81%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>ろくなことになりませんし、直すためのフックもありません。Fly は VM を凍結します。プロセスにシグナルは届かず、降りていく途中で何も閉じられません。握っていた接続は目覚めたときもメモリに残り、数分前に相手が捨てたソケットを指しています。</p>
<p>これは降りるときに解く問題ではありません。上がってくるときに解く問題で、その大半は、すでに正しい判断をしてあったかどうかで決まります。</p>
<ul>
<li><strong>データベース接続はリクエストごとに開く</strong>（<code>conn_max_age = 0</code>）。古びるほど長生きする接続がありません。</li>
<li><strong>Redis キャッシュは例外を投げずに縮退する。</strong> ラッパーが接続エラーを捕まえてミスとして返します。</li>
</ul>
<p>2つ目が働く瞬間を実際に見られました。ある復帰で、予想どおりの失敗がログに出ました。</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="#%e7%a7%81%e3%81%ab%e5%98%98%e3%82%92%e3%81%a4%e3%81%84%e3%81%9f%e3%83%86%e3%82%b9%e3%83%88" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>最初のサスペンド計測は、この機能が大失敗だと告げました。502、30秒後、しかも2回続けて。</p>
<p>私は <code>fly-force-instance-id</code> でリクエストを特定のマシンに固定していました。インスタンス1台を負荷試験するには素晴らしいヘッダーですが、この用途には最悪です。インスタンスを強制すると、そのマシンを起こしてくれるはずのプロキシのロジックを迂回してしまうからです。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>教訓は2つ、そして高くつくのは2つ目です。計測しやすい経路ではなく、ユーザーが通る経路を測ること。そして、ツールが何かを拒否したら、その拒否文を読むこと。「Machines with swap cannot be suspended」という一文が、この午後の作業すべての突破口になりました。</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="#%e3%81%82%e3%81%aa%e3%81%9f%e3%81%ae%e3%82%a2%e3%83%97%e3%83%aa%e3%81%a7%e7%a2%ba%e8%aa%8d%e3%81%99%e3%81%b9%e3%81%8d%e3%81%93%e3%81%a8" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>アイドルのインスタンスを停止するプラットフォームを使っているなら、次の問いに答えるのに私は半日かかりましたが、もっと早く確かめていれば、何週間も続いた静かな失敗を防げたはずです。</p>
<ol>
<li><strong>コールドスタートは何秒かかりますか。</strong> コンテナが走る時間ではなく、実際のリクエストに応答するまでの時間です。秒数で即答できないなら、必要になる前に測ってください。</li>
<li><strong>entrypoint が起動ごとに行っている処理のうち、デプロイに属するものは何ですか。</strong> マイグレーション、静的ファイル収集、キャッシュのウォームアップ、インデックス構築。1回ならどれも問題ありません。92回ならどれも高くつきます。</li>
<li><strong>バイトコードをキャッシュしているものはありますか。</strong> ビルドに <code>compileall</code> のない <code>PYTHONDONTWRITEBYTECODE</code> は、答えが「ノー」だという意味です。</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をオートスケール：負荷テストで小さなマシン1台の限界を測る</title>
      <link>https://jared.lynskey.co.nz/ja/posts/2026/2026-07-22-my-current-stack/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ja/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で動かしています。1台を速くし、負荷テストでレイテンシが崩れる同時実行数を測り、その手前にオートスケールの閾値を置く方法です。</description>
      <content:encoded><![CDATA[<p>Fly.ioでDjangoを安く動かすために、私はshared-cpu-1xの小さなマシン1台をできるだけ速くし、レイテンシが崩れるまで負荷テストをして、その少し手前でFlyのオートスケーラーが2台目を起動するように設定しています。負荷テストはステップ状に負荷を上げるLocust（もう一方のアプリでは同時実行数を順に変える小さなPythonスクリプト）で行い、p95とエラー率を見ます。トラフィックが落ちればアイドルのマシンは自動で止まるので、普段のコストはアプリごとに小さなVM 1台です。</p>
<p>私は現在、個人開発者として2つのプロダクトを運用しています。ひとつは現場で見積もりを出す職人向けの<strong>現場見積もりアプリ</strong>、もうひとつは出品とリアルタイムメッセージングを備えた<strong>マーケットプレイス兼コミュニティアプリ</strong>です。</p>
<p>プロダクトもユーザーも全く違いますが、技術スタックはほぼ同一です。そしてどちらも、Fly.ioの最安ティアである<strong>shared-cpu-1xマシン</strong>だけで動いています。この制約は意図的なものです。ピーク負荷に合わせてサーバーを大きくするのではなく、小さなマシン1台から絞り出せる性能を最大化し、どこで崩壊するかを正確に測定し、その実測された限界を軸にFlyのオートスケーラーにマシンの追加と削除を任せます。この記事では、それを可能にしている最適化、閾値の根拠となった負荷テストの数値、そしてFly.ioでスケールアップ/ダウンが実際にどう動くのかを紹介します。</p>

<h2 class="relative group">哲学：1台を測定し、それを掛け算する
    <div id="哲学1台を測定しそれを掛け算する" 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="#%e5%93%b2%e5%ad%a61%e5%8f%b0%e3%82%92%e6%b8%ac%e5%ae%9a%e3%81%97%e3%81%9d%e3%82%8c%e3%82%92%e6%8e%9b%e3%81%91%e7%ae%97%e3%81%99%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>両アプリともスケーリング戦略は同じ3ステップです。</p>
<ol>
<li>小さなマシン1台を、合理的な範囲で可能な限り速くする。</li>
<li>壊れるまで負荷テストを行い、レイテンシが崩壊する同時実行数を記録する。</li>
<li>その直前で2台目のマシンが起動するようFlyのオートスケーラーを設定し、トラフィックが減ったらアイドルマシンを停止させる。</li>
</ol>
<p>こうすればキャパシティはマシン数にほぼ線形に比例し、ベースラインコストはアプリごとに小さなVM 1台です。以下の内容はすべて、この3ステップのいずれかのためにあります。</p>

<h2 class="relative group">小さなマシン1台を速くする
    <div id="小さなマシン1台を速くする" 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="#%e5%b0%8f%e3%81%95%e3%81%aa%e3%83%9e%e3%82%b7%e3%83%b31%e5%8f%b0%e3%82%92%e9%80%9f%e3%81%8f%e3%81%99%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>

<h3 class="relative group">Granian：APIはWSGI、WebSocketはuvloop ASGI
    <div id="granianapiはwsgiwebsocketは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="#granianapi%e3%81%afwsgiwebsocket%e3%81%afuvloop-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>で—ワーカーあたり一度に1つずつ—実行します。つまりASGIは、ワーカーあたりの同時リクエストを実質1つに絞りながら、asyncio/uvloop/Channelsのスタック一式をただメモリに載せていただけでした。<code>--blocking-threads</code>を使うWSGIは、同じ同期ビューを本物のスレッドプールで走らせます。ワーカー1つ × スレッド16 = I/Oバウンドなリクエスト（DB読み取り、S3のプリサイン）16件を同時に、非同期スタックより低い常駐メモリでさばきます。</p>
<p>なぜワーカーが1つなのか？VMが<code>shared-cpu-1x</code>—1コアだからです。2つ目のワーカーは1コアではPythonを並列に走らせられない（GIL + 1コア）くせに、常駐するDjangoプロセスをまるごと1つ余分に食います。Granianはまさにこの点を警告します。ワーカー1つにスレッド16が、I/Oバウンドな処理における1 vCPUマシンの正直な上限です。<code>--workers-max-rss 1400</code>はワーカーがメモリ上限を超えると再生成するので、暴走したPDFや画像処理がマシンをOOMへ引きずっていく代わりにリサイクルされます。</p>
<p>WebSocketは自前のGranianプロセスに切り出しました。uvloopと<code>--ws</code>を使う<strong>ASGI</strong>アプリで、長寿命コネクションのためにワーカー1つで動かします。同期APIにはASGIの経路はまったく不要です。ビューがソケットへプッシュしたいときはRedis経由で<code>async_to_sync(channel_layer.group_send)</code>を呼ぶので、メッセージは変わらずWebSocketプロセスへ渡ります。2つのサーバーが、それぞれ本当に得意なインターフェースを走らせているわけです。ローカルのDockerも同じWSGIスレッドプールで動かしているため、テスト時は私のラップトップがプロダクションマシン1台の近似になります。</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="#%e3%83%9b%e3%83%83%e3%83%88%e3%83%91%e3%82%b9%e3%81%ab%e3%81%afrust" 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>これらはアーキテクチャを変えません。2台目のマシンが必要になる前に、1 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="#%e9%9a%a0%e3%82%8c%e3%81%9f%e3%83%ac%e3%82%a4%e3%83%86%e3%83%b3%e3%82%b7%e7%a8%8e%e3%82%92%e6%bd%b0%e3%81%99" 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="#%e6%9c%ac%e5%bd%93%e3%81%ae%e3%83%9c%e3%83%88%e3%83%ab%e3%83%8d%e3%83%83%e3%82%af%e3%81%ae%e5%89%8d%e3%81%ab%e3%82%ad%e3%83%a3%e3%83%83%e3%82%b7%e3%83%a5%e3%82%92%e7%bd%ae%e3%81%8f" 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="#%e3%83%96%e3%83%ad%e3%83%bc%e3%82%ab%e3%83%bc%e3%81%aa%e3%81%97%e3%81%ae%e3%83%90%e3%83%83%e3%82%af%e3%82%b0%e3%83%a9%e3%82%a6%e3%83%b3%e3%83%89%e5%87%a6%e7%90%86" 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="#%e3%83%a1%e3%83%a2%e3%83%aajemalloc%e3%81%a8%e3%82%b9%e3%83%af%e3%83%83%e3%83%97%e3%81%ae%e3%82%af%e3%83%83%e3%82%b7%e3%83%a7%e3%83%b3" aria-label="アンカー">#</a>
    </span>
    
</h3>
<p>画像とPDFの処理は、定常状態ベースの見積もりでは予測できないメモリスパイクを起こします。安上がりな緩和策が2つ。Dockerイメージに<strong>jemalloc</strong>をプリロードして断片化を抑えること、そして<strong>全マシンにスワップ</strong>を持たせることです（APIマシンに2GB、WebSocketマシンに1GB）。スパイクが来てもプロセスがOOMで殺される代わりにディスクへスワップされます。スワップは性能のための機能ではなく、メモリ割り当てを小さく保つための保険です。</p>

<h2 class="relative group">Djangoの負荷テスト：膝（knee）を見つける
    <div id="djangoの負荷テスト膝kneeを見つける" 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%e3%81%ae%e8%b2%a0%e8%8d%b7%e3%83%86%e3%82%b9%e3%83%88%e8%86%9dknee%e3%82%92%e8%a6%8b%e3%81%a4%e3%81%91%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>閾値の根拠として通用するのは、実測した値だけです。プロジェクトごとに専用のハーネスがあります。</p>
<ul>
<li>見積もりアプリには、同時実行数を掃引してRPS、p50/p95/p99、エラー率を報告する小さなPythonのストレステストスクリプトがあります。生成した数百件のサンプルデータに対して実行するので、リスト系エンドポイントは現実的なデータ量でクエリされます。</li>
<li>マーケットプレイスは<strong>Locust</strong>で30秒刻みのステップ負荷により50 → 500ユーザーまでランプして飽和点を探し、実際の閲覧中心トラフィックに合わせたエンドポイント重み付けを使っています。さらに別建ての小さなテストスイートが、仮想ユーザー5 → 50をp95 &lt; 2秒の閾値付きでプロダクションに対してランプします。</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マシン1台</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%e3%81%a7%e3%81%ae%e3%82%b9%e3%82%b1%e3%83%bc%e3%83%aa%e3%83%b3%e3%82%b0%e3%81%ae%e4%bb%95%e7%b5%84%e3%81%bf" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>Flyのモデルはシンプルです。アプリはプロキシの背後にある同一マシンの集合で、プロキシがマシンごとの負荷を数えます。宣言するのは2つの数字だけです。</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は12—プールの約75%で、ユーザーが数秒のレイテンシを体験した後ではなく、スレッドにまだ余裕があるうちに2台目が起動します。hard limitの24（プールの1.5倍）はサーキットブレーカーです。短いバーストはスレッド上でキューイングされ、それを超えたら、1台のマシンが溶け落ちるのを許すのではなく、プロキシが負荷を遮断します。（旧来のASGIビルドは実質スロットが約3で8/20でした。プールを広げたことで両方の数字を引き上げられたのです。）</p>
<p><strong>スケールダウン：</strong> トラフィックが減ると、Flyはアイドルマシンを自動的に停止し、<code>min_machines_running = 1</code>まで縮小します。停止中のマシンはコンピューティング費用がかからず rootfs のストレージ分だけなので、各アプリのベースラインコストは文字通り小さなVM 1台で、バースト用のキャパシティは常に待機しています。</p>
<p>私はここに、停止中のマシンは「1秒未満でコールドスタートする」と書いていました。それは間違いで、しかも高くつく間違いでした。想定ではなく実際に計測したところ、コールドスタートには<strong>25〜33秒</strong>かかっていて、まだ起動中のマシンに振られたリクエストはその時間をまるごと待たされます。当初は、ヘルスチェックがずっと緑のままCDNのダッシュボードに出ていた22パーセントの失敗率を、このコールドスタートのせいだと考えていました。ところがその数字は、CDN自身のEarly Hintsのプローブがオリジンで失敗していたもので、実際のクライアントが受け取った504はひとつもありませんでした。それでも、コールドスタートそのものは本物でした。</p>
<p>対処は上のスケーリングの数値にはありません。あの数値は問題ないのです。マシンが立ち上がる途中で何をしているか、そして Fly にマシンを停止ではなくサスペンドさせるかどうかにあります。そうすれば復帰は約3秒のメモリ復元になります。別記事にまとめました。<a href="https://jared.lynskey.co.nz/ja/posts/2026/2026-09-09-scale-to-zero-504s/" >ゼロスケールと、再起動のたびに起きる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%e3%81%af%e5%88%a5%e3%81%ae%e8%bb%b8%e3%81%a7%e3%82%b9%e3%82%b1%e3%83%bc%e3%83%ab%e3%81%99%e3%82%8b" aria-label="アンカー">#</a>
    </span>
    
</h3>
<p>マーケットプレイスはWebSocketサーバーを、同じDockerイメージを共有する<strong>2つ目の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="#%e3%82%b3%e3%83%b3%e3%83%94%e3%83%a5%e3%83%bc%e3%83%86%e3%82%a3%e3%83%b3%e3%82%b0%e3%82%92%e3%82%a8%e3%83%83%e3%82%b8%e3%81%a8%e3%82%af%e3%83%a9%e3%82%a4%e3%82%a2%e3%83%b3%e3%83%88%e3%81%b8%e3%82%aa%e3%83%95%e3%83%ad%e3%83%bc%e3%83%89%e3%81%99%e3%82%8b" 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）を組み込み、端末上で動かしています。サーバー側の推論コストはゼロで、オフラインでも動作します。</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="#%e6%ae%8b%e3%82%8a%e3%81%ae%e3%82%b9%e3%82%bf%e3%83%83%e3%82%af%e3%82%92%e6%89%8b%e7%9f%ad%e3%81%ab" 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="#%e6%8c%81%e3%81%a1%e5%b8%b0%e3%81%a3%e3%81%a6%e3%81%bb%e3%81%97%e3%81%84%e3%82%82%e3%81%ae" aria-label="アンカー">#</a>
    </span>
    
</h2>
<p>移植できるアイデアは特定のライブラリではなく、ループそのものです。安いマシン1台を本当に速くする（Rustのホットパス、コネクション再利用、本当のボトルネックの前のキャッシュ、CDNとクライアントへのオフロード）。どの同時実行数で壊れるかを特定できるまで負荷テストする。オートスケーラーのsoft limitをその膝に置き、アイドルマシンは停止させ、最小フリートは1に保つ。プロダクションアプリ2つ、リアルタイム機能、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>
