Please Sleep

読書メモ: Prompt Engineering for LLMs

Kosei Moriyama — Mon, 21 Apr 2025 19:30:00 +0900

Prompt Engineering for LLMs: The Art and Science of Building Large Language Model–Based Applications (English Edition)

英語版 John Berryman (著), Albert Ziegler (著) 形式: Kindle版

Amazon.co.jpで詳細を見る

GitHub Copilot 開発者らによる、プロンプトエンジニアリングの本。プロンプトエンジニアリングと言うと、ChatGPT に投げる文言を工夫するテクニックのようなイメージだったが、そうではなく LLM をベースとしたアプリケーション開発全般を指している。LLM がどのような仕組みで動作しているのかをアプリケーション開発者の視点から概説したあとは、アプリケーションの実装方法について背景となる理論を踏まえて解説してくれる。

Cline や Cursor を始めコーディングエージェントが台頭し、実際の普段の業務で利用されるようになってきた。ただその内部構造がブラックボックスで、課題感を感じていた。LLM アプリケーションに対するメンタルモデルが出来上がっていないので、Cline のソースコードや各 LLM プラットフォームの API ドキュメントを見ても、いまいち掴みどころを持てていいなかった。

新しいツールや概念がどんどん出てくる中で、それらの情報に踊らされる、ただ表面を追うだけで時間を浪費させられてしまうことに危機感を持った。特に AI 関連は第一印象でどうしても「驚いて」しまうので、今までの新技術より「踊らされる」リスクが高い。

こうした背景の上で、いわゆる機械学習等のバックグラウンドがないソフトウェアエンジニアの立場から、こうした LLM アプリケーションの内部のメンタルモデルを構築するのに、この本はうってつけだった。現状ある製品をあくまでツールとして、あくまでブラックボックスとして使うだけなら不要だが、内部構造をある程度理解したい場合は非常に良い本だと思う。

なおもうすぐ和訳も出るようなので、そちらを待っても良いかもしれない。

LLMのプロンプトエンジニアリング —GitHub Copilotを生んだ開発者が教える生成AIアプリケーション開発

John Berryman (著), Albert Ziegler (著)

Amazon.co.jpで詳細を見る

以下読書メモ:

I. Foundations

1. Introduction to Prompt Engineering

プロンプトエンジニアリングというと、チャット型の LLM に投げる文言を工夫するテクニックという先入観があった。一方でこの本では、LLM をベースにしたアプリケーション全般を対象にしている。アプリケーションはプロンプトの構築や解釈をプログラマティックに行い、今まででは難しかった高度なタスクを遂行できるようになる。

> at the core, LLMs are simply models that predict the next word in a block of text—that’s it and nothing more!
- 本質的には、LLM は単にテキスト内の次の単語を予測するモデルで、それ以上でも以下でもない
- 抽象化すればスマホ IME の予測変換と変わらない
LLM に至る道のり
- 自然言語処理のマルコフモデル (1984) まで遡ることができる
- 2014 年: Google より seq2seq アーキテクチャの言語モデル
- 2015 年: Soft search
- 2017 年: Transformer アーキテクチャ
- 2018 年: GPT
- 2019 年: GPT-2
  - GPT と比較し、トレーニングセットのサイズを桁違いに増やすだけで性能が大幅に上昇。特定のタスク専用に fine-tuning したものよりも、トレーニングセットを大きくした汎用モデルのほうが性能で勝った
  - この時点で既に悪意のある利用が懸念されているのも興味深い。
    - > Due to our concerns about malicious applications of the technology, we are not releasing the trained model.
    - ref. https://openai.com/index/better-language-models/
- 2020 年: GPT-3
  - プロンプトによって出力を調整できることが発見され、prompt engineering という概念が生まれた
Prompt Engineering
- 前述のように LLM はあるテキストから残りを補完するモデルである。達成したい課題に対処するために入力テキストを工夫するのが、最もシンプルな形態のプロンプトエンジニアリング
- 一方で単一のプロンプトにとどまらず、プロンプトの構築と解釈をプログラムから行う、LLM ベースのアプリケーションの構築もプロンプトエンジニアリングの範疇
  - 最もシンプルなものは、入力に微細な変更を加えただけでほぼそのままモデルに渡すもの。一般的な Chat UI は ChatML のような形式への変換は行うがそれは薄いもので、Copilot の簡単な補完もほぼそのまま入力を受け渡している
  - 次のレベルでは、ユーザーの入力を変換・補強したうえでモデルに渡すもの。例えば Copilot で関連するコードを添えて LLM に渡し、補完の精度を上げるようなもの
  - 更に進むと、モデルとのやりとりがステートフルに、つまりこれまでのやりとりを保持しながら行うものになる。モデルが処理できるコンテキストにはサイズの限界があるので、コンテキストの管理が必要になる
  - 最終的には LLM アプリケーションがエージェントとして、外界とやりとりしながらタスクを実行するものを見ていく

2. Understanding LLMs

LLM の基本的な仕組み。LLM は学習セットにあるテキストを模倣する。一度に一つのトークンを処理している。以前のトークンを編集するような事はできない。 LLM の仕組みを概観し、LLM の利用時にどのような特性があるかを知る。

LLM とは何か。上段から見ていく
最もハイレベルでは、LLM はテキストをプロンプトとして受け取り、出力として入力を確率的に補完しテキストを完成させる
- 事前に大量のドキュメント (換言するとただのテキスト) で学習している。本、フォーラムの書き込み、論文、ソースコード、etc。そこから模倣した、新しいテキストを返すことができる
- トレーニングセットにあるテキストから確率的に補完をしているだけなので、事実ではない補完 (ハルシネーション) が起こる
LLM はテキストをトークンに分割して扱う
- トークンは 3, 4 文字程度のチャンク
  - 例: Tokenizer - OpenAI API
- 人間は単語単位で認識するが、LLM はトークン単位。この間にはいくつか違いがある
  - Tokenizer は決定的
  - トークンより細かい単位での操作が難しい。例えば one example を eno elpmaxe に変換してといってもうまくできない事が多い。あるいは Sw から始まるヨーロッパの国は? と聞いても、Sweden のトークンが Sw で切られていなければうまく答えられない。トークンを最小単位とした操作なら可能
  - 文字の表記を認識できない。例えばあるテキストを全て大文字にするタスクに失敗する。LLM にとって小文字のトークンと大文字のトークンは大きな違いで、人間のように a は A の別形式であると認識しているわけではない
- トークン数はモデルの利用にかかる金額や、扱えるトークン数上限などに関わるため、プロンプトエンジニアリングとしてはよく意識する必要がある
  - 多くのモデルは英語に最適化されているので、英語のほうがトークン長が効率的。反対にランダムな文字列などは効率が悪い
LLM は複数のトークンから、次の 1 トークンを補完している
- 最も可能性が高い 1 トークンを補完し、それを入力として次のトークンを補完する (自己回帰)
- 一度補完したトークンに遡って訂正したりはできない。一定の補完をしたあとに間違いに気づいた場合、それをリカバーするのはアプリケーション側の役割になる
- 補完は複数の候補から確からしいものを選択している
- 多くのモデルは logprobs と temperature というパラメータを持っている。logprobs は次のトークンの確率分布を返す。temperature は確率分布の平坦さを調整するパラメータで、0 は最も確からしいトークンを選択する。1 はトレーニングセットの確率分布と同じ選択をする。1 以上の場合、よりランダムな選択になる
  - 正確さを重視する場合は小さく、出力のバリエーションを増やしたい場合は大きくするなど、それぞれのユースケースがある
LLM はトランスフォーマーアーキテクチャをベースにしている
- 複数の 小さな脳 が集まって全体を構成している
- 各 小さな脳 はそれぞれ、テキストの中のひとつのトークンを処理する。またテキスト中の自分の位置も知っている。それぞれの 小さな脳 はレイヤーと呼ばれる複数のステップで計算をしている
- 小さな脳 は左 (ここまでのテキスト) の情報から予測し、それ (中間状態) を右 (これからのテキスト) に伝える
  - 計算は常に左から右へ行われており、これ以外の経路はない
- そのため、プロンプトエンジニアリングの観点では、プロンプトに記載する情報の順序が非常に重要になる。

3. Moving to Chat

ここまでは最もベースとなる、テキストの補完を行う LLM を見てきたが、ここではそれをチャット形式で利用する方法を見ていく。RLHF という方式でベースのモデルに fine tuning していき、ChatGPT などで見慣れたチャットができる能力を施していく。

RLHF (Reinforcement Learning from Human Feedback, 人間のフィードバックによる強化学習)
- ベースモデル (テキスト補完だけしかできない) に RLHF を適用し、チャット形式でのやりとりを可能にする
  - あわせて、役に立ち・正直で・無害 (Helpful, Honest, Harmless - HHH) という 3 つの基準を満たすようにする
- 順序
  - まずはベースモデルに fine-tuning を行い、SFT (supervised Fine-Tuning) model と呼ばれる中間モデルを作成する
    - ユーザーとアシスタント間のチャット形式の (HHH な) やりとりをトレーニングセットとして与える
      - GPT-3 の場合 13,000 件のやり取りを与えた
  - SFT を高い temperature で呼び出し、生成された複数パターンのテキストを人間が評価しランク付けする
  - SFT の生成とその評価結果を評価関数として、強化学習を行う
    - 報酬モデルを作成しそれで強化学習を繰り返すことで、人手で評価したものではカバーしきれない量の学習を行う
Instruction model
- RLHF が施されたこの時点のモデルは instruction modelと呼ばれる。ベースモデルが入力からの補完だけを行うのに対して、人間とアシスタントとのやりとりを学習した instruction modelは質問に対して回答を行うことができるようになった
  - 例えば What is a good indoor activity for a family of four? というプロンプトに対して、ベースモデルは続きの文章を生成する。instruction modelは質問とみなして回答を生成する
- ここで、ユーザーがこのプロンプトに対して補完を求めているのか、解答を求めているのか確実に判断できないという問題が残る
ChatML
- ここでは OpenAI が開発したフォーマットを扱う。後述例のように簡単なタグで明示できるようになっている
- トランスクリプトとしてプロンプトを定義できるようになる。またシステムプロンプトでロールを定義できる
- ChatML フォーマットを RLHF fine tuningしたものが chart model となる
- 実際にプロンプトエンジニアが直接 ChatML を記述することはない。例えば OpenAI API では、ロールでシステムやユーザーを明示して呼び出す。裏側で内部的に ChatML が利用されている <|im_start|>system You are a sarcastic software assistant. You provide humorous answers to software questions. You use lots of emojis.<|im_end|> <|im_start|>user I was told that my computer would show me a funny joke if I typed :(){ :|:&};: in the terminal. Why is everything so slow now?<|im_end|> <|im_start|>assistant I personally find the joke amusing. I tell you what, restart your computer and then come back in 20 minutes and ask me about fork bombs. |im_end|> <|im_start|>user Oh man.<|im_end|> <|im_start|>assistant Jokes on you, eh? <|im_end|>
Chat model であることで、ベースの補完モデルに劣後する部分もある
- HHH なレスポンスにチューニングされているので、その分解答の質が下がる可能性がある
- 丁寧なレスポンスのため前置きなどが入り、解答そのものを取り出す手間が増える
- オリジナルのトレーニングセットには、丁寧なものであれ無礼なものであれ、あらゆる文章が含まれている。HHH に従うようチューニングされたモデルでは、後者が出づらくなる
- ChatML であれ、あくまでも (このフォーマットに fine tuning された) モデルが、テキストを補完しているだけだ、という視点は改めて忘れないようにすると良い

4. Designing LLM Applications

LLM アプリケーションの全体像。LLM アプリケーションはユーザーのタスクを変換し、モデルからの解答を変換して返すループを繰り返す。特に前者には情報の収集や優先度付けも必要になる。

LLM Application はユーザーの問題領域と LLM のドメインとの変換レイヤー
ループ構造
- アプリケーションはユーザーの課題を変換し LLM に入力する。LLM からの出力を変換しユーザーに返す。このフローを問題解決まで繰り返す
- ループはまずユーザーの問題から始まり、次にアプリケーションはそれをモデルのドメインに変換する。このときアプリケーションは次の要件を満たすプロンプトを作成する必要がある
  - トレーニングセットのコンテンツによく似ている (赤ずきんの原理)
  - 問題解決に必要なすべての情報が含まれている (情報の収集、選別)
  - 問題を解決する補完をするようモデルを導く
  - 補完が自然なところで終了する
- 次は作成したプロンプトを LLM に渡し結果を受け取る。ここではモデルの選択 (品質、コスト、レイテンシ) や fine tuningの有無が検討事項になる
- 最後に受け取った結果を変換しユーザーに返す
ユーザーの課題をモデルのドメインに変換するステップ feed forward pass を詳しく見る
- - 必要な情報 (コンテキスト) を収集する
  - 収集したコンテキストをスニペットに分割する
  - スニペットにスコアを付け、選別する
  - 最終的なプロンプトを成形する
- 次のような難しさ、複雑さが発生する
  - 状態管理 (コンテキスト管理) 。”記憶” を引き継ぐ
  - 外部の情報の取得
  - 深い推論をさせる (chain of thoughtsを促すなど)
  - ツールの利用を通した外界とのインタラクション
性能の評価
- オフライン評価
  - 事前に性能を評価する。アプリケーションによっては簡単ではない。例えば Copilot のようなコード補完エージェントの場合は、生成されたコードをテストして評価できる
- オンライン評価
  - ユーザーからの評価 (自動収集されるテレメトリも含む)
  - ChatGPT のサムズアップ、ダウンボタンがわかりやすい例。Copilot の場合候補が選択されたかどうかなど、より暗黙的な指標の方が良い

II. Core Techniques

5. Prompt Content

Feed forward pass の第一段階である、プロンプトへの情報追加について。プロンプトのボイラープレートのような静的なコンテンツと、外部情報を取得するような動的なコンテンツに大別できる。

静的コンテンツ
- プロンプトの定型テンプレートに、モデルが従うべきルールなどを記載する。プロンプトの明確化のためのもの
  - 例えば Bing chat はこのようなものを使っていると解析された
  - 指示のコツは、否定形ではなく肯定形で、理由を付与する、絶対的な言い方を避ける
  - ただモデルが常にこれに従ってくれるとは限らない
- Few-shot prompting
  - いくつかの例を与えることで、モデルに期待する出力の形式を示す
  - 以下の欠点がある
    - 多くのコンテキストを含めるには、例の羅列という方法では長くなりすぎる。回答フォーマットの例示としての用途が良い
    - 例の内容によって補完内容にバイアスがかかる。
      - 例えば本のレビューをしたい場合、few shot として「本A: 1, 本B: 2, 本C: 1」と与えると、モデルは「本D: 1」(実際は 5 だったとしても) といったように、与えた例に従った補完をする
      - このようなケースでは、できるだけ実際の確率分布に従った例を与える必要がある (簡単ではないが)
      - 一方でエッジケースの明示には効果的
    - 意図しないパターンに LLM が従ってしまう。
      - 例えば「本A: 1, 本B: 2, 本C: 3」と与えた場合、モデルは単に昇順にしたスコアで「本D: 4」と補完してしまう可能性がある。また例の最初に典型例、後に例外や特殊例を与えると、モデルは直近の例を強く評価し、悲観的な補完をする傾向がある
      - バイアスを避けるために、例として何をどんな順で乗せるかは簡単ではない。DSPy という手法も考案されている
動的コンテンツ
- 関連のある情報を収集する。静的コンテツとは違い、レイテンシ、準備のしやすさ (preparability, その情報の取得が簡単か・困難か)、比較可能性 (情報は多く収集しあとからトリアージするが、その際に他の情報と比較できなければいけない)
- どのような情報を集めるべきかは、開発者による発想が求められる部分。考えの助けになるフレームワークは、マインドマップ、あるいは「ユーザーとの近さ」x「変化の多さ」の 2 次元にマッピングするなど
- RAG (Retrieval-Augmented Generation)
  - トレーニングセットには存在しない情報を付与するためのパターン
  - 無関係な情報を含めないように注意しないといけない (チェーホフの銃の誤謬)。コンテキストサイズが大きくても、無関係な情報を含めてしまうと、モデルはそれを考慮して補完を行い、精度が下がる
  - Lexical retrieval
    - チェーホフの銃の誤謬を避ける軽量な方法。検索クエリと取得結果に登場する単語の出現率に基づく類似度でスコアを付ける。スコアの低いものを除く
      - Stopword (一般的な単語) を除外し、Stemming (語幹を抽出) し、ジャッカード係数でスコアを付ける。TF-IDF や BM25 などを利用する発展系もある
    - NLP で昔から使われている手法なので、一般的な NLP のライブラリには実装されている
  - Neural retrieval
    - 単に単語の出現頻度による類似度ではなく、より意味を考慮した類似度の計算を行う。embedding model を用いてテキストをベクトルに変換し、その距離で類似度を計算する。距離の計算はユークリッド距離やコサイン類似度などでよい
    - 検索対象は事前に embedding model でベクトル化しておく必要がある (簡単には OpenAI のツールを用いても可能)。計算結果は一般的に Vector Storage と呼ばれる DB に格納される。検索クエリも同様にベクトル化し、Vector Storage に問い合わせる
  - Neural retrieval が必ずしも常にベストチョイスなわけではない。Lexcical retrieval は枯れた技術で、Elasticsearch などの成熟したツールがすでにあり、問題時のデバッグや手動でのチューニングはしやすい。一方で意味的なマッチをしたい場合 (別言語間の類似度や、画像の類似度など) は Neural retrieval でないと実現できない
- 要約
  - 長いコンテキストは要約する必要がある。テキストの要約は LLM が得意なタスク
  - 例えば本全体を要約する必要がある場合、段落 => 章 => 全体のように、段階的に要約していくと良い。ソースコードの場合は個別のファイル => ディレクトリ => プロジェクト全体、など

6. Assembling the Prompt

前章で集めたコンテンツをどのように構成し、どのようにトリアージし、最終的なプロンプトに仕上げるのかを見ていく。プロンプトの最終形は導入・本文・リフォーカス・移行からなる。ドキュメントには会話形式、分析レポート、構造化ドキュメントの 3 種類がある。本文にどう情報を組み込むかは、各構成要素の依存関係や重要性などを基にした最適化問題になる。

Anatomy of the Ideal Prompt (理想的なプロンプトの構成)
- 導入 (Introduction)
  - プロンプトの目的、文脈を明確化する
- 本文 (プロンプト要素の列)
  - 紹介文にプロンプトの各要素が続く。ここで LLM には以下の傾向があることに注意する
  - In-context learning
    - プロンプトの最後に近いほど、モデルへの影響が高くなる
  - The lost middle phenomenon
    - モデルはプロンプトの最初と最後を簡単に思い出せるが、真ん中の部分はそうではない
  - これらの特徴から、プロンプトの特に前半中間にある内容が効果的に使われないという、The Valley of Meh と呼ばれる現象が起こる。これを防ぐ方法はない
- リフォーカス (Refocusing)
  - LLM に本題を思い出させるためのもの。プロンプト全体が長いときほど効果的
- 移行 (Transition)
  - これまでのコンテキストの説明を終え、問題解決を行うよう促すもの。プロンプトの最後に加える
ドキュメントの形式
- 赤ずきんの原理に基づき、プロンプトはトレーニングセットにある文章に似ている方がよい。それを踏まえ、ここでは典型的なドキュメントの形式を見ていく
- 会話形式
  - 2 人の会話形式。1 人 (ユーザー) は何らかの助けを求め、もう 1 人 (モデル) はそれ助ける。
  - 自然で、複数回のやり取りも扱うことができ、実世界との統合もしやすい
- 分析レポート
  - 大学や企業で報告されるようなレポート形式。
  - 通常は Markdown 形式が推奨される。トレーニングセットに最も多く含まれており、必要な機能がシンプルに備わっている
  - 目次をつけるのも効果的。モデルの注意を適切に引き、Chain of Thoughts を促す
- 構造化ドキュメント (The Structured Document)
  - Python スクリプト、小さな React アプリ、マーメイド記法で作図された図式、SVG など、構造を持つもの
  - 特定の形式を強制し、モデルの出力を扱いやすくする
スニペットのフォーマッティング
- 動的に得られた情報をプロンプトに組み込む際、上記の形式に沿った自然なものにする
```
# 会話形式の場合の例
User: What's the weather like?
Assistant: It's going to be {{ weather["description"] }} with a temperature of {{ weather["temperature"] }} degrees.
```
- Elastic Snippets
  - ひとつの情報をスニペットにするとき、長さが違う複数のバージョンを用意しておく。コンテキストウィンドウのサイズにあわせて、その中のどれを使うかを決定する
プロンプト要素の関係
- 各プロンプト要素をどう配置するか。位置、重要性、依存関係をもとに決定する
- 位置
  - 時系列や因果関係などが壊れないように配置する
- 重要性
  - 重要な要素に多くのトークンを割り当てるのか、そうでないものを多く割り当てるのかのトレードオフ
  - 前提として、すべての要素が同じ尺度でスコアリングされている必要がある
- 依存関係
  - Requirement (必要条件。ある要素が他の要素に依存している) と Incompatibility (非互換性。ある要素が他の要素と同時に存在できない) の 2 つの関係がある
ここまで来ると、最終的なプロンプトの作成は、最適化問題になる
- 依存関係とプロンプトのの長さの制約の中で、価値を最大化するようなプロンプトを作成する
- 線形プログラミングや 0-1ナップサック問題などに似ているが、独自のソリューションが必要になることが多い
- 最初はナイーブな方法から始めて発展させていく

7. Taming the Model

ここまででプロンプトの作成ができるようになったので、次はモデル自体に関わるトピックを扱う。logprobs を用いてアプリケーションを工夫することができる。モデル選択の判断軸。Fine tuning をするかどうか、する場合でも、より軽量な手法もある。

理想的な補完の構造
- 前文 (preamble)
  - RLHF が丁寧なやりとりをする場合の前置きや免責事項など。結果をアプリケーションが解釈する際に邪魔にもなりやすい (システムプロンプトである程度は抑制できる)
  - 一方で Chain of thoughts で推論を行う場合、前文が長い方がより良い出力になることが多い
- 認識できる開始と終了
  - モデルのアウトプットをプログラムで解釈するためには、モデルの補完結果部分の開始と終了が認識できないといけない。例えばマークダウンの場合はセクション記法など、ドキュメントの形式によって異なる
- 追記 (postscript)
  - 前文同様にこちらも不要なのでなくしたいことが多い。プロンプトで抑制するのも良いが、モデルによっては stop sequence に対応しているものもある。streaming で接続している場合は、必要なアウトプットの終了を認識できた時点で生成をストップさせると良い
logprobs を活用する
- 出力の確信度に基づいたアクションを行う。例えば、一定の確度以上の場合にだけユーザーに提示する、一定の確度以下の場合リトライしたり、別のモデルに切り替えるなど
- モデルに何らかの分類、例えば「この文面はプロフェッショナルに書かれていますか」、をさせる場合、その度合いを logprobs を用いて定量的に判定する
- プロンプト (入力側) のエラー検知。モデルによっては echo という、プロンプトを含めてレスポンスしてくれるものもある。この場合プロンプトの logprobs も確認できる。例えばタイプミスがあった場合、そのトークンだけ logprobs が非常に低くなったりする
モデルの選択
- 以下の軸で検討すると良い
  - 性能 (intelligence)
  - レイテンシ
  - コスト
  - 使いやすさ
    - GPU 配置の可変性、モデルのデプロイ、クラッシュ時のリスタート、キャッシュ機能などの有無
  - 機能
    - ツール機能があるか、logprobs を返すかなど
  - その他
    - OSS でなければならない。特定のデータ所在地でなければならないといった、特殊な要件
- 小さく始めるには商用の LLM-as-a-service から始めるのが速い。発展に応じて OSS モデルに切り替えることもあり得る
- 十分な性能のモデルよりも、良いモデルで開発を進めると良い。新しいモデルが出ると、過去のものは値下げされる
Fine tuning
- fine tuning を行うべきかどうかは、まずはそのトレーニングセットがどれだけ入手しやすいかを考えるべき
- また fine timing の手法にも段階がある
  - Full fine tuning
    - モデルのすべてのパラメータを継続的にチューニングする
  - Parameter efficient fine-tuning (PeFT)
    - パラメータの一部をチューニングする。LoRA のような手法が例。Full よりも計算が短い。
    - Full はモデルに新しい知識を教えることができる。LoRA はそうではなく、モデルの前提を調整するイメージ。例えば日本を起点にした旅行アプリの場合、日本をベースにした旅行先を提案するように調整するといった使い方になる
  - Soft prompt
    - Fine tuning をするのではなく soft-prompt, つまりプロンプト側を学習し embedding (ベクトル) を入力として渡す
  - Fine tuning を施した場合でも、赤ずきんの原理に注意する。プロンプトが Fine tuning のデータセットに近いものにしないと、チューニング前の汎用な方のパスに入ることもある

III. An Expert of the Craft

8. Conversational Agency

エージェント型という、現実世界とインタラクションするものについて。

Tool usage

チャットモデルはナレッジカットオフ以降の情報は持っておらず、重要な情報を見逃したり、不得意なタスク (特に数学) がある。また実際に現実世界に作用 (メールを送る、など) をすることもできない。こうした限界を克服するために、ツールを利用する
2023 年 6 月に OpenAI はツール呼び出し用に fine tuning された新しいモデルを導入。その後、他の競合もそれに追随した

OpenAI を例にした実装例

function の定義をする

# get_room_temp, set_room_temp の実装は既にあるとする
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_room_temp",
            "description": "Get the ambient room temperature in Fahrenheit",
        },
    },
    {
        "type": "function",
        "function": {
            "name": "set_room_temp",
            "description": "Set the ambient room temperature in Fahrenheit",
            "parameters": {
                "type": "object",
                "properties": {
                "temp": {
                    "type": "integer",
                    "description": "The desired room temperature in ºF",
                    },
                },
                "required": ["temp"],
            },
        },
    }
]


available_functions = {
    "get_room_temp": get_room_temp,
    "set_room_temp": set_room_temp,
}

これを利用し処理する process_message 関数の例

def process_messages(client, messages):
# Step 1: send the messages to the model along with the tool definitions
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
)
response_message = response.choices[0].message
# Step 2: append the model's response to the conversation
# (it may be a function call or a normal message)
messages.append(response_message)
# Step 3: check if the model wanted to use a tool
if response_message.tool_calls:
    # Step 4: extract tool invocation and make evaluation
    for tool_call in response_message.tool_calls:
        function_name = tool_call.function.name
        function_to_call = available_functions[function_name]
        function_args = json.loads(tool_call.function.arguments)
        function_response = function_to_call(
            # note: in python the ** operator unpacks a
            # dictionary into keyword arguments
            **function_args
        )
        # Step 5: extend conversation with function response
        # so that the model can see it in future turns
        messages.append(
            {
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": function_name,
                "content": function_response,
            }
        )

呼び出しとその結果の例

# 呼び出し
messages = [
    {
        "role": "system",
        "content": "You are HomeBoy, a happy, helpful home assistant.",
    },
    {
        "role": "user",
        "content": "Can you make it a couple of degrees warmer in here?",
    }
]
client = OpenAI()
process_messages(client, messages)

# 結果1。モデルはツールを呼び出し、現在の温度を取得しようとしている。
[
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [{
            "id": "call_t7vNPjRlFJ3nKAhdGAz256cZ",
            "function": {
                "arguments": "{}",
                "name": "get_room_temp"
            },
            "type": "function",
        }],
    },
    {
        "tool_call_id": "call_t7vNPjRlFJ3nKAhdGAz256cZ",
        "role": "tool",
        "name": "get_room_temp",
        "content": "74",
    }
]

# process_message を再度呼んで 1 ステップ進める。
process_messages(client, messages)

# 現在温度に応じて温度を変更しようとしている。
[
    {
        "role": "assistant",
        "tool_calls": [{
            "function": {
                "name": "set_room_temp"
                "arguments": "{\"temp\":76}",
            },
            "type": "function"
            "id": "call_X2prAODMHGOmgt523Ob9BIij",
        }],
    },
    {
        "role": "tool",
        "name": "set_room_temp",
        "content": "DONE"
        "tool_call_id": "call_X2prAODMHGOmgt523Ob9BIij",
    }
]

モデルの内部ではツールは次のように、システムプロンプトでマークダウンと Typescript で定義されている。いずれもトレーニングセットで頻出の形式。また静的型付けもモデルへのよいヒントになる。(ただし OpenAI は内部表現を公開しておらず、著者らの独自調査による内容)。

<|im_start|>system
You are HomeBoy, a happy, helpful home assistant.
# Tools
## functions
namespace functions {
// Set the ambient room temperature in Fahrenheit
type set_room_temp = (_: {
// The desired room temperature in ºF
temp: number,
}) => any;
} // namespace functions
<|im_end|>
// 利用例
<|im_start|>user
I'm a bit cold. Can you make it a couple of degrees warmer in here?<|im_end|>
<|im_start|>assistant to=functions.get_room_temp
{}<|im_end|>
<|im_start|>tool
74<|im_end|>
<|im_start|>assistant to=functions.set_room_temp
{"temp": 76}<|im_end|>
<|im_start|>tool
DONE<|im_end|>
<|im_start|>assistant
The room temperature was 74ºF and has been increased to 76°F.<|im_end|>

ツール定義のガイドライン
- 適切なツールを選択できるよう、必要なものだけにする。複数のツールがあるとモデルは混乱する。
- 関数名・変数名などは、名前自体がドキュメントにもなっているような、適切な命名をする
- ツールの説明文は必要十分に
- 引数は極力シンプルにする。不要なものは省く。JSON Schema は利用できるが、高度な定義 (min Items, uniqueItems, minimum, maximum, pattern, format 等) に頼らないほうが良い
- ツールの返り値には不要なものは含まない。あったら便利かもしれないものを含めるとモデルが混乱する
- エラーはそのまま帰すのではなく、モデルの視点で活用できるように注意する。バリデーションエラーであれば、その理由と修正してリトライする旨を伝える。
- 危険な操作には人間の承認を必要とする

Reasoning
- モデルの推論能力は、一度に結果を出すのではなく、内部のモノローグを促すことによって強化することができる
- Chain of thought
  - 2022 年の論文 Chain-of-Thought Prompting Elicits Reasoning in Large Language Models では、モデルに先に理由を述べてから回答を出力するように促すと精度が上がることを実証した。一般的な質問では 69.4% から 75.6%、数学ドメインでは 20 から 60% の改善がみられた
    - 次のような few-shot プロンプトでそれを実現した Q: Do hamsters provide food for any animals? A: Hamsters are prey animals. Prey are food for predators. Thus, hamsters provide food for some animals. So the answer is yes. Q: Yes or no: would a pear sink in water? A: The density of a pear is about 0.6g/cm3, which is less than water. Objects less dense than water float. Thus, a pear would float. So the answer is no.
  - その後 Large Language Models are Zero-Shot Reasoners では単に Let’s think step-by-step, と付け加えるだけで同様の効果が得られることが示された
  - Think before you speak: Training Language Models With Pause Tokens では pause トークンを認識できるようモデルを fine tuning し、pause トークンを適当に挟むことで、モデルが立ち止まって考えられるようになり、精度が上がることを示した
  - いずれにしても、一度に答えを出すのではなく、内部で考えるように促すことで、推論の精度を上げることができる
- ReAct: Iterative Reasoning and Action
  - モデルに Think-Act-Observe のサイクルを繰り返させることで、より複雑なタスクをこなせるようにする
  - 例えば「雑誌 A と雑誌 B のどちらが古いか」というタスクを解かせる。ここで以下の Search, Lookup, Finish の 3 つのアクションを定義する
```
Solve a question-answering task with interleaving Thought, Action, and Observation steps.
Thought can reason about the current situation, and Action can be three types:
(1) Search[entity], which searches the exact entity on Wikipedia and returns the first paragraph if it exists. If not, it will return some similar entities to search
(2) Lookup[keyword], which returns the next sentence containing a keyword in the current passage
(3) Finish[answer], which returns the answer and finishes the task
Here are some examples.
```
  - そのうえで 3,000 程度のサンプルでモデルを fine tuningu すると精度が向上した
    - Search, Lookup ツールで検索するだけでも精度は良かったが、Reasoning を加えることでさらに向上した
    - 上記のプロンプトの下に few-shot を追加するだけではうまくいかず、fine tuning が必要だった
  - Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models では次のようなプロンプトを追加し、最初に計画をたててから実行するよう促すだけで、精度が向上することを示した。この手法はツール利用を伴わないシチュエーションでも有効
```
Let’s first understand the problem and devise a plan to solve the problem. Then, let’s carry out the plan and solve the problem step-by-step.
```
  - Reflexion: Language Agents with Verbal Reinforcement Learning は反対に実行後に結果を振り返るというアプローチをとっている
  - Branch-Solve-Merge Improves Large Language Model Evaluation and Generation は複数のソルバーに問題を解かせてからマージする
コンテキスト管理
- 前までの章の議論に加えて、エージェント型のアプリケーションでのコンテキスト管理について、さらに必要な要件がある
- コンテキストの収集元が追加される。これまでの会話の履歴、開いているファイルなどの (ユーザーがコピー&ペーストするのではなくエージェントがツールを通じて取得する)、その他ツールを利用して取得した外部の情報など
- コンテキストのトリアージには、万能な方法はない。
  - 不要なツールは候補から外す
  - 必要なアーティファクトだけを含める
  - アーティファクトのフォーマット (XML, JSON, Markdown など)
  - アーティファクトをどのように提供するか。単に全てを含めても収まるのか、Elastic snippet のような要約が必要か、RAG のような検索システムが必要か
  - 以前の会話をどこまで含めるか

9. LLM Workflows

現在の LLM の性能では、汎用性を維持しながら特定の複雑なタスクを確実にこなすことはできない。この章では LLM Workflows という、特定のドメインに特化させて複雑なタスクを遂行できるアプリケーションを見る。タスクをサブタスクに分解し、それをスーパーバイズする。スーパーバイザーは LLM でもそうでないパターンもある。なおここでは Lang‐ Chain, Semantic Kernel, AutoGen, DSPy といった特定のフレームワークの詳細には立ち入らず、概念的な説明を行う。

このような問題を考える。現在の LLM の性能ではこれを直接遂行するのは難しい
- 1.人気のあるShopifyストアフロントのリストを生成し、ウェブサイトのHTMLを取得。2.各ストアフロントについて、製品の提供、ブランディング、スタイル、価値などの詳細を抽出。3.各ストアフロントを確認し、そのビジネスに役立つプラグインを考案。4.各ストアフロントオーナーにプラグインコンセプトを宣伝するマーケティングメールを生成。5.メールを送る
- 必要な web 検索やメール送信といったツールを用意しても、例えば網羅的に 1 のリストアップタスクができる可能性は低い
- ツール側に要件を満たせるような特殊な実装を多く入れても、コンテキストが大きくなりすぎる、単一の LLM とのやり取りではうまくいかない
基本的なワークフロー
- 全体をサブタスクに分割する。各タスクの入出力を特定する
- タスクは LLM を使っても使わなくても良い。不必要なのであれば、従来の技術を使って実装した方が安定する。また人間による作業を伴うタスクがあっても良い
- LLM を使う場合のアプローチ
  - プロンプトのテンプレート。タスクの入力値で埋めてプロンプトが完成する。Lang-Chain はこのアプローチを採用している
  - ツールベースのアプローチ。例えば取得した html から店舗情報や商品情報を抽出するようなタスクは LLM が得意とする。特に入力として html をとるようなツールとして定義すると簡単
  - 複雑な推論では chain of thoughts を促してやる必要がある。OpenAI API であれば、ツール利用をオフにして試行させた上で、ツール利用をオンにして実施させる
  - 出力が正しくないと判定できる場合 (コードが出力ならテストを通すとか、LLM に出力を判断させるとか) 、それを入力にし再度修正を試みる実装もできる。ただし複雑さは大きくなる。
  - ワークフロー全体を構築する前に、個々のタスクの動作が適切か確認評価しておくと良い
- ここまででタスクの集合が定義できた。各タスクはDAG として表現できる。そしてDAG を管理するのは、従来からの Airflow や Luigi といったツールを利用することができる
  - LLM ベースのタスクの場合、失敗時の再試行が発生することがある。可能ならばこのリトライをタスク内で処理できると、DAG がシンプルになって良い
発展系では、タスクのスーパーバイザーを LLM に任せる構成
- 柔軟性が増える一方、開発の難しさが増える
- なかでも最もシンプルなものは、各タスクをツールとして、スーパーバイザーのモデルに依頼する形式
- これを発展させると、各タスクもそれぞれ会話型のエージェントとし、エージェント間のやり取りとしてワークフロー全体が構成される形式
- さらに進めると、スーパーバイザーのモデルが必要に応じてタスクを生成するという構成もありえる
- いずれにしてもこの分野はまだまだ安定しておらず、フロンティア

10. Evaluating LLM Applications

アプリケーションをどう評価するか。Copilot の開発では最初に評価システムを構築したことでうまくいった。評価方法にはオフライン評価とオンライン評価がある。

テスト対象
- 4章の LLM アプリケーションのループ全体のテスト、またはループの各要素の個別のテスト
- 例えばモデルを切り替えたい場合などは前者で、モデルのパラメータをチューニングしたい場合は後者で評価できると便利
- 最初に始める際にどちらかだけを選ぶのであれば前者のほうが良い
オフライン評価
- Example Suites
  - 実際に使われそうなプロンプトを5-20個ほど準備、それらを自動でアプリケーションに読み込ませ結果を保存、以前のバージョンとの diff をとる
  - いわゆるソフトウエアテストと異なり自動で結果が評価されるのではなく、人間がチェックしやすいだけの仕組み。ただ、全くアプリケーションがない状態でも始められる・結果を確認しながらアプリケーションを作り込めるという大きなメリットがある
  - 複雑なアプリケーションの場合、個別の LLM とのやり取り部分だけに適用しても良い
- サンプルの収集方法
  - そのタスクがすでに AI に頼らず実施されている (これからそれを AI アプリケーション化する) 場合、それを利用できる可能性がある。ただし現実のサンプルの分布とは離れている可能性はある
  - アプリケーションのリリース後の場合は実際の利用ログが使える場合がある。ただしリリース前には不可能、アプデ後には古いサンプルが無意味化、収集するためのプライバシーなどの整理が必要、生成結果が理想的とは限らないといった注意点がある
  - 自分で、あるいは LLM にサンプルの生成を依頼することもできる。LLM を使う場合は、まずサンプルのカテゴリを洗い出させ、それぞれのカテゴリごとに N 個のサンプルを生成するよう段階を踏むと良い。依然実際のサンプルの分布とはずれる可能性はあ？ことは留意する
- 生成結果の評価
  - Gold standard
    - Yes/No を回答するものや、複数の選択肢から選ぶようなものなど、理想の回答が確定的に定義できるケース
    - 自由に文章を生成するケースでは、重要な部分文字列を定義してその一致度を測るアプローチをとる
    - あるいはツール利用のエージェントの場合、適切な fiction call ができているかを測る方法もある
  - Functional testing
    - 生成結果が機能するかをテストする。コンパイルが通るか、単体テストをパスするかなど
  - LLM assessment
    - 上記のいずれもが難しい場合、LLM に判断を任せる方法もある
- SOMA assessment
  - 次の例のように、評価軸とそれぞれの度合いを定義し、LLM に評価させる方法 I need your help with evaluating a smart home assistant. I'm going to give you some interactions of that assistant, which you are to grade on a scale of 1 to 5. Grade each interaction for effectiveness: whether the assistant's attempted action would have remedied the user's problem. Please rate effectiveness on a scale of 1 to 5, where the values mean the following: 1. This action would do nothing to address the user's problem or might even make it worse. 2. This action might address a small part of the problem but leave the main part unaddressed. 3. This action has a good chance of addressing a substantial part of the problem. 4. This action is not guaranteed to work completely, but it should solve most of the problem. 5. This action will definitely solve the problem completely. The conversation was as follows: User: I'm a bit chilly. Assistant: to functions.set_room_temp {“temp”: 77} Please provide a thorough analysis and then conclude your answer with "Effectiveness: X," where X is your chosen effectiveness rating from 1 to 5.
オンライン評価
- A/B テスト
  - スタンダードな方法。評価指標をどのように選ぶかが肝になる
  - いずれにせよオンライン評価はオフライン評価に比べコストも時間がかかるので、オフライン評価も駆使しながらなにをオフライン評価にするかよく検討したほうが良い
  - スタンダード方法なので、既存のソリューションが多くある
- Metrics
  - 以下に大別できる
    - 直接フィードバック：ユーザーからの直接フィードバック
    - 機能的正確性：アウトプットは機能するか。コンパイルやテストが通るかなど
    - ユーザーの受け入れ：ユーザーは提案に従ったか
    - 達成された影響：ユーザーはどのくらい恩恵を受けるか
  - 例えば ChatGPT のサムズアップ・ダウンボタンは直接フィードバックにあたる。ただしこれはサムズアップされるのは特に優れた提案がされたときが多く、サムズダウンは不満があるときに多く押されるなど、バイアスはある
  - ユーザーの受け入れは、例えば旅行アプリの場合、提案した旅行プランを実際に予約したかどうかなど。可能ならこのような指標を開発できると良い

11. Looking Ahead

今後の発展。

Multimodality
- テキストだけでなく、画像や音声などのマルチモーダルな情報を扱うことができるようになる
- 方法の一つは、畳み込みネットワークを使い、画像等を embedding vector に変換。移行はテキストと同様に扱うことができる
- UIUX の幅が広がる他、LLM のトレーニングセットを大幅に増やせるというメリットもある。テキストだけではトレーニングセットが枯渇すると予想されている
User Experience and User Interface
- 現在は会話形式が一般的
- その発展形としては、例えばペアプログラミングの対象のコードのように、会話の対象物をステートフルなものとして提示しながらやり取りする形式がある
- Anthropic の Artifact などはこの例になる
Intelligence
- 現在のベンチマークでは主要なモデルはほぼ上位スコアに飽和しており、LLM コミュニティはベンチマークのアップデートも積極的に行っている
- 知識蒸留という、大きなモデルから迅速に小さなモデルの学習を進める手法も考えられている
- トレーニング方法の改善だけではなく、例えば量子化など、アーキテクチャレベルの改善も発展として存在する

Prompt Engineering for LLMs: The Art and Science of Building Large Language Model–Based Applications (English Edition)

英語版 John Berryman (著), Albert Ziegler (著) 形式: Kindle版

Amazon.co.jpで詳細を見る

LLMのプロンプトエンジニアリング —GitHub Copilotを生んだ開発者が教える生成AIアプリケーション開発

John Berryman (著), Albert Ziegler (著)

Amazon.co.jpで詳細を見る

証明書のピンニングをしている自アプリのデバッグ

Kosei Moriyama — Thu, 16 Jan 2025 20:00:00 +0900

モバイルアプリの HTTP 通信を見ながらデバッグしたい場合、mitmproxy や Wireshark といったプロキシを挟む (意図的に MITM を行い通信を見る) という定番の方法がある。

TLS 通信のパケットキャプチャ - Please Sleep

ただし証明書のピンニング (ピン留め, Certificate Pinning, SSL Pinning) をしている場合、中間で通信を覗こうと思っても単純にはできない。プロキシデフォルトの証明書をクライアントは信用しないため、通信に失敗する。

対象が自プロジェクトや自社のアプリで、管理している証明書にアクセスできる場合、これを回避できる。プロキシに正しい証明書を渡すことでクライアントはそれを信用し通信を行う。あとは通常通りプロキシから通信内容を参照できる。

ここでは Leaf certificate をピンニングしているケースを想定している。この状況で mitmproxy を使って iOS のネイティブアプリをデバッグする。ピンニングの方式やプロキシソフトによって手順の詳細は変わるので注意。

証明書の準備

PEM 形式の証明書を用意する。実際にピンニングしているものを使うので、取り扱いには十分注意する。

PEM 形式は概ね次のようなフォーマット。

秘密鍵と証明書のそれぞれのファイルがある場合は次のようにして結合する。

cat cert.key cert.crt > cert.pem

証明書を受け渡して Proxy を起動する

--certs オプションで任意の (Leaf) 証明書を使うよう mitmproxy に指定できる。

# <domain>=<cert file path> という記法。
mitmproxy --certs 'please-sleep-cou929.nu=/path/to/cert.pem'

https://docs.mitmproxy.org/stable/concepts-options/#certs

SSL certificates of the form “[domain=]path”. The domain may include a wildcard, and is equal to “*” if not specified. The file at path is a certificate in PEM format. If a private key is included in the PEM, it is used, else the default key in the conf dir is used. The PEM file should contain the full certificate chain, with the leaf certificate as the first entry.

動作確認

モバイルデバイスから試す前に、CLI での確認をしておくと効率的。

mitmproxy 認証局の証明書を使ってアクセスする状況を curl などで確認できる。デフォルトでは mitmproxy は ~/.mitmproxy に認証局のキーを作成する。こちらを引数として渡せば良い。

# mitmproxy がローカルホストの 8080 番ポートで待ち受けていると仮定。
curl --proxy 127.0.0.1:8080 --cacert ~/.mitmproxy/mitmproxy-ca-cert.pem https://please-sleep.cou929.nu

以上で通信が成功すれば OK。ここまででピンニング以外の部分は確認できる。

返される証明書の内容も確認しておくとよい。

# host, port に Proxy の接続先を指定する。
openssl s_client -servername please-sleep.cou929.nu -host 127.0.0.1 -port 8080 -showcerts </dev/null 2>/dev/null

# 例えばクライアントでは Leaf 証明書の base64 エンコードした文字列を比較していると行ったケースでは、次のようにしても確認しやすいかもしれない。
## 上記で取得した証明書部分を cert.crt に書き出しておく。
cat cert.crt | openssl x509 -pubkey -noout | openssl rsa -pubin -outform der 2>/dev/null |  openssl dgst -sha256 -binary | openssl enc -base64

これらの内容がピンニングしているクライアントが想定しているものと一致すれば OK。ここまででピンニングも含めた通信ができていることが確認できる。

端末からのアクセス

以降は通常のプロキシ利用と同じ手順で良い。

前述の手順で mitmproxy のプロセスが起動されている
iPhone 側でプロキシと証明書の設定
- Settings > Wifi > 詳細ページ > Configure Proxy にて、Manual をタップ
- mitmproxy を動かしているホストの ip と port 8080 (デフォルト) を入力し Save
- Safari で mitm.it にアクセスし証明書をダウンロード
- Settings > General > Profiles mitmproxy を選択しインストール
- Settings > General > About > Certificate Trust Settings より mitmproxy のトグルを有効化
該当のアプリで適当に通信を行う。mitmproxy でその内容が確認できれば成功

詳細は TLS 通信のパケットキャプチャ - Please Sleep に詳しい。

参考

PR

プロフェッショナルTLS＆PKI 改題第2版

Ivan Ristić (著), 齋藤孝道 (監修)

Amazon.co.jpで詳細を見る

読書メモ: Prometheus 実践ガイド

Kosei Moriyama — Mon, 17 Jun 2024 09:00:00 +0900

Prometheus実践ガイド: クラウドネイティブな監視システムの構築

仲亀拓馬 (著)

Amazon.co.jpで詳細を見る

会社でも利用している Prometheus だが、なんとなくでしか使えていなかったのでキャッチアップのために読んだ。その目的なのでハンズオンの部分は割愛し、全体は 400 ページほどあるがさっと読むことができた。

Prometheus のアーキテクチャや PromQL の基礎が把握できて満足。前者は、Grafana の存在で可視化部分が疎になっているのはわかっていたが、Alert 部分も分かれていることや、リモートストレージを介して別 Prometheus や外部サービスと連動させやすいのは新鮮だった。後者について、もともと時系列データへのクエリは苦手だったが、基礎的なプリミティブ (Guage/Counter/Histogram/Summary の区分、label の概念、Instant/Range Vector) を押さえることで理解しやすくなったと思う。また PromQL に限らず抽象化すれば Cloud Monitoring など他製品とも共通の考え方なので、その点も有用だった。さわりだけだが TSDB のファイル構成にも触れられていて、シンプルながらパワフルな印象を持ち、面白そうだった。

以下読書メモ。

Part1：Prometheusと監視の基本

Chapter 1：Prometheusで監視を始めるには

システム監視の基本
- 目的: サービスをユーザーに無事に届けるため = ダウンタイムの最小化
- 方式
  - メトリクス
    - システムの状態を数値化し時系列データとして扱う
    - Prometheus, Zabbix, CloudWatch など
  - ログ
    - システムの状態を文字列として記録する
    - 集計・比較しやすいメトリクスに対して、ログは詳細な情報が得られるがストレージ消費は多い
    - Elasticsearch, Cloud Logging など
  - トレーシング (分散トレーシング)
    - ユーザーのリクエストにスコープを置き、各処理経路の所要時間を記録する
    - 複数のコンポーネントをまたがるため、トレーシング ID という共通の ID で追跡する
    - OpenTelemetry はその標準
    - Jaeger, Zipkin, Datadog APM など
- 監視の導入フロー
  - サービスの正常・異常を定義
    - i.e. コーポレートサイトがブラウザからアクセスできる、商品をカートにいれることができる、アップロードしたファイルが正常に転送される
  - ユーザー側から導入する
    - コンポーネントの CPU やメモリ使用率からではなく、「そのサービスが使えているのか」から始める
    - ブラックボックス監視からホワイトボックス監視の順
  - アラートを設定する
    - 発報時にどんなアクションをするかを決め、通知レベルを分ける
    - 継続的に調整、不要なアラートの削除をする
  - 監視システム自体も監視する
- オブザーバビリティ
  - クラウドネイティブな環境では、多数のコンポーネントが協調するため、問題の発生パターンを事前に予測するのが従来よりも難しい
  - そのため各コンポーネントの状況が統一的な方法で記録され、それを事後に自由に取得できることが求められる
  - こうした概念は Obserbability と名付けられている

Chapter 2：Prometheusの概要と基本的な使い方

Prometheus とは
- CNCF Graduated Project
- すべてのデータを key-value のメトリクスとして扱う
  - key はメトリクス名 + ラベル (prometheus_build_info {instance="localhost:9090" })
- PromQL
  - メトリクスのクエリ言語
- エクスポーター
  - 監視システム側に従属する統一的なクライアント (エージェント) ではなく、ミドルウェアや OS といった各監視対象ごとに従属するクライアント (エクスポーター) という考え方
- Pull 型モデルとサービスディスカバリ
  - 監視サーバが各エクスポーターにメトリクスを問い合わせる Pull 型モデル
    - 監視対象を中央で一元管理できる。例えば監視対象がメトリクスを送れなくなったという検知や、スケールインでなくなったノードのデータ破棄などが容易になる
  - 伸縮するクラウドネイティブなインフラでは監視対象が動的に変わるため、サービスディスカバリが必要
アーキテクチャ
- 図2.5 Prometheus のアーキテクチャより引用
- Prometheus Server + TSDB
  - メトリクスの収集、保存、クエリを担当
- Exporter
- AlertManager
  - Prometheus Server がアラートルールに則った PromQL を定期実行し、マッチするものがあれば AlertManager に送信する
  - AlertManager はアラートのグルーピング、ラベル情報をもとにルーティングしたうえで通知を行う
- Grafana
  - ビジュアライズ
- Pushgateway
  - Push 型のメトリクス収集をカバーする。バッチ処理やイベントのような一時的な処理のメトリクス収集がユースケースになる
不得意なこと
- データの信頼性
  - Pull したデータが正常かどうかを検知する仕組みは無い。例えばネットワークの問題でデータが欠損しても再取得する機能はない
- エクスポーターの管理コスト
  - 種類が多く、コミュニティ、極端には個人がメンテナンスするものもある
構成ファイル
- prometheus.yml
  - global でグローバル設定
    - scrape_interval 監視間隔
    - scrape_timeout 監視タイムアウト
    - evaluation_interval アラートルールの評価間隔
      - 評価時にはクエリを実行するため大量のルールがある場合は負荷がかかる
    - external_labels 全体へのラベルを追加
      - env: production を全メトリクスにつけるといったユースケース
    - その他リモートストレージの設定など
  - scrape_configs で監視対象を定義
    - job_name 監視対象の名前。監視対象ごとに Job という単位で管理
    - metrics_path エクスポーターのエンドポイント。デフォルトは /metrics
    - scheme http か https
    - params クエリパラメータ
    - basic_auth ベーシック認証
    - interval, timeout はグローバルの設定を上書きできる
  - alerting でアラートルールを定義
    - alertmanagers AlertManager のエンドポイントを指定
      - 静的・動的に設定できる
    - alert_relabel_configs アラートルールのラベルを変更
  - rule_files で外部ファイルからアラートルールを読み込む
Topics: Prometheus のメトリクスフォーマットは Exposion Formats としてまとめられている
- これも参考にしつつオープンな標準として OpenMetrics がある

Chapter 3：監視ターゲットの検出とラベル操作

サービスディスカバリーはクラウドインフラの API や k8s などに既にある外部のサービスディスカバリー機能を呼び出すのが基本
- それがない場合はカスタマイズしたディスカバリーシステムが必要になる
Prometheus は監視対象の情報を label という形で保持している
- 監視対象のホストやパスなどもラベルとして表現されている
外部のサービスディスカバリーサービスから取得した対象の一覧に対して、さまざまな加工を行う必要がある。この操作を relabel (再ラベル) という
- 例えば gce のインスタンス情報を取得した場合、デフォルトでは ip としてプライベートアドレスが入っている。サブネット外の Prometheus から監視したい場合は別のフィールドにメタデータとして入っているパブリック ip を ip ラベルに置き換える
- そのほか、GCP など対象のサービス内のラベル表現を Prometheus 側の規則にそったラベルに置き換えたり、監視対象の絞り込みなども relabel の操作で実現する

Chapter 4：エクスポーターによるデータの収集

HTTP API のエンドポイントを公開し、Prometheus server からの Pull に応じて監視対象のメトリクスを取得、所定のフォーマットに変換して返す役割
二つの動作モデル
- デーモン
  - 監視対象とは別プロセスのデーモンとして動作する。Node exporter などはこのモデル
- プロキシ
  - 監視対象が HTTP でメトリクスを公開している場合、Exporter が Prometheus との間にプロキシとして立つ。Prometheus server からは監視対象の URL を添えて Exporter にリクエスト、Exporter はそこに問い合わせ、メトリクスを返す
    - 監視対象は Exporter 側には保持していない
メトリクスのフォーマット
- コメントとメトリクスデータから構成される
- メトリクスデータはメトリクスの key と value
- コメントには人間向けの純粋なコメントの他に、計算機向きのメトリクスの型情報も含まれている

# HELP go_goroutine Number of goroutines that currently exist.
# TYPE go_goroutine gauge
go_goroutine 38

Chapter 5：PromQLとメトリクス

メトリクスの種別

gauge: ある時点の値
counter: 累計値

histogram: 分布。各バケットの区切りが絶対値

le (less or equal) でバケットの区切りが表現される

prometheus_http_request_duration_seconds_bucket{handler="/",le="0.1"} 2
prometheus_http_request_duration_seconds_bucket{handler="/",le="0.2"} 3
prometheus_http_request_duration_seconds_bucket{handler="/",le="0.4"} 4
prometheus_http_request_duration_seconds_bucket{handler="/",le="1.0"} 5
prometheus_http_request_duration_seconds_bucket{handler="/",le="+Inf"} 5

summary: 分布。各バケットの区切りがパーセンタイル

prometheus_engine_query_duration_seconds{slice="inner_eval",quantile="0.5"} 0.001530686
prometheus_engine_query_duration_seconds{slice="inner_eval",quantile="0.9"} 0.001536674
prometheus_engine_query_duration_seconds{slice="inner_eval",quantile="0.99"} 0.001536674

被演算子のデータ型
- Instant vector:ある一時点のデータ
```
up{instance="localhost:9090",job="prometheus} 1
```
  - 時間の指定がなければ最新のメトリクスが選ばれる
- Range vector: ある期間のすべてのデータ
  - データに加えてタイムスタンプを持つ
```
node_memory_MemFree_bytes{instance="localhost:9100",job="node_exporter"}[5m]
28323840 @1596386196.235
28323848 @1596386201.235
28323932 @1596386206.235
28384833 @1596386211.235
28329991 @1596386216.235
```
  - Scala
  - 単純な数値
セレクタ
- {job="prometheus"} といった、メトリクスから条件に一致するものをフィルタするための指定
  - セレクタがない場合は全件取得になる
```
# 全サーバのリクエスト数が返される
prometheus_http_requests_total
```
  - matcher
  - =, !=, =~, !~
  - offset
  - offset 5m といった指定で、過去の時点データを取得する。範囲ではなく Instant vector を返す
  - range vector selector
  - [5m] といった指定で、過去の範囲データ Range vencor を取得する
演算子
- 算術演算子、比較二項演算子、論理演算子
- 集計演算
  - sum, min, max, avg, stddev, stdvar, count, count_values (count_if), bottomk, topk, quantile
  - grouping
    - by: 指定したラベルでグルーピングして集計する
    - without: 除外するラベルを指定し、残りのラベルすべてでグルーピングして集計する
```
# job ラベルごとの合計リクエスト数の集計例
sum(prometheus_http_requests_total) by (job)
```
関数
- rate, delta, sort など多くの種類がある rate(node_cpu_seconds_total[ 5m ])

Chapter 6：ルールとアラート

rule
- Prometheus server 側でクエリを定期実行する仕組み
- 定期実行のみを行う recording_rule
- アラートに対応する alert_rule
  - promql と条件式、インターバル、付与するラベルなどを定義する

groups:
  - name: example-alerts
    rules:
    - alert: HighMemoryUsage
      expr: node_memory_Active_bytes / node_memory_MemTotal_bytes * 100 > 80
      for: 5m
      labels:
        severity: critical
      annotations:
        summary: "High memory usage detected on instance {{ $labels.instance }}"
        description: "Memory usage is above 80% for more than 5 minutes.\n  VALUE = {{ $value }}\n  LABELS = {{ $labels }}"

    - alert: HighCPUUsage
      expr: sum(rate(node_cpu_seconds_total{mode="system"}[1m])) by (instance) / count(node_cpu_seconds_total{mode="system"}[1m]) by (instance) * 100 > 90
      for: 10m
      labels:
        severity: warning
      annotations:
        summary: "High CPU usage detected on instance {{ $labels.instance }}"
        description: "CPU usage is above 90% for more than 10 minutes.\n  VALUE = {{ $value }}\n  LABELS = {{ $labels }}"

    - alert: InstanceDown
      expr: up == 0
      for: 1m
      labels:
        severity: critical
      annotations:
        summary: "Instance down alert"
        description: "Instance {{ $labels.instance }} is down for more than 1 minute."

AlertManager
- 通知先を表現する receiver
  - チーム別、レベル別などに分けるユースケース
  - 指定したラベルにマッチすると送信する
- アラートをまとめる router
  - 待ち時間やインターバルと共にグループ化するラベルを指定する
  - 期間内のアラートを一つの通知にまとめられる

Chapter 7：メトリクスを可視化する

Grafana の使い方の解説。一般的なグラフツールやクラウドインフラのモニタリングツールと概念はそう変わらないので割愛。

Part2：Prometheusの実践

Chapter 8：Kubernetesの監視

Kubernetes クラスタの監視や Prometheus operator について。必要な時に最新のチュートリアルを参照した方が良いので割愛。

Chapter 9：Prometheusのストレージ

ローカルストレージとリモートストレージ
- Prometheus server 足下のストレージ TSDB の形式でファイルを保存するローカル形式と、リモートの外部ストレージに連携する形式
TSDB
- データ形式
  - 時系列データを保持
  - 一つのデータはサンプルデータと呼ばれる
  - 2時間分ごとにブロックが分かれている
    - チャンク内にはデータ本体と、そのブロックの期間等のメタデータ、インデックス
  - クエリの際は、メタデータからブロックを、インデックスから対象のファイルを探してスキャンする
  - 障害時の復旧のための WAL
    - ヘッドブロックのデータはメモリ上に保持しているので、障害時は WAL から復旧する
  - 一定以上古い期間のファイルはひとまとめにしていく
```
./data
    /01F01F5A3…  # 2時間分ごとのブロック
        /chunk
            00001
            …
        index
        meta.json
        tombstones
    /01F5AAB8V…
    /01F5AAB8X…
    /chunks_head  # 現在書き込み中のブロック（ヘッドブロック）
    /lock
    /queries.active
    /wal
```
  - データ量の見積もり
  - 1 メトリクスあたりのデータサイズ x 秒間の取得メトリクス数 x 保持期間 = TSDB のデータサイズという要領で見積もる
    - 1 メトリクスあたりのデータサイズは 1, 2 byte という経験則で良い。残り二つの項目は設定から算出できる
リモートストレージ
- さまざまな外部サービスと接続できる
- read/write または write only の接続方式がある
  - Prometheus はメトリクス収集に特化し、ストレージには書き込みのみ、可視化やアラートは外部システム側に任せる（あるいは別の Prometheus Server instance）という構成も可能になる
  - read もする場合、通常は外部ストレージから一定期間のデータを全権取得し、Prometheus 側で PromQL で集計するという構成になる。Prometheus 側のメモリ使用量には注意が必要
    - この意味でも可視化などを外部サービス側に任せる構成があり得てくる
- write にはバッファの大きさや並列数といったチューニングポイントがある。バッファが消費するメモリサイズや書き込みのレイテンシを鑑みながら調整する

Chapter 10：独自のメトリクスを公開する

方式
- Direct instrument
  - 監視対象に Prometheus のインタフェースに従ったメトリクス取得のエンドポイントを直接実装する
- Exporter
  - Exporter を実装する
実装時にはラベルのカーディナリティの低いメトリクスを作らないように注意する（本当に必要か検討する）
- 例えばメールアドレスごとのラベルなど

Chapter 11：実践的なPrometheusの活用

冗長化
- 複数の Prometheus server を起動するのがシンプル
  - それぞれでストレージを別で持つ
  - スクレイプ数やデータ量がサーバ数分増えてしまうが、シンプルなのがメリット
  - お互いを監視させると良い
  - Prometheus には冗長化のためのクラスタ化機能などはない
- AlertManager はクラスタ機能がある。複数起動し協調動作する
複数の Prometheus の連携
- 小型のサーバを複数展開するほうが運用しやすいことが多い
  - サービスごとや環境ごとに別のサーバをたてる
- 並列の連携
  - 複数の Prometheus が同一のリモートストレージに書き込む
  - リモートストレージを参照しに Garafana などで可視化する
- ツリー型の連携
  - 例えばデータセンター全体の監視で、フロアごとサーバのメトリクスを中央のサーバに集約する構成
  - これをサポートする機能は Prometheus が提供している
  - 中央（ツリーの上位）のサーバから Pull する federation と、下位のサーバから Push する Remote write receiver がある
- 別システムへの連携
  - Managed Prometheus や Cloud Monitoring などへ転送する
  - 一台であってもあり得る構成
配置場所
- 本番環境と同じ場所に構築する場合
  - コスト削減、経路上のネットワークの影響が少ない、k8s operator を使えるといったメリットがある
- 分けるのは障害時の影響を分離でき、一般的には良い
メトリクス命名のコツ
- 上位のコンポーネントから順に並べる (nginx_system_memory_… など)
- メトリクス名は抽象化し、具体性の高い情報はラベルにする

Chapter 12：Prometheusの周辺ツール

PushGateway
- バッチなど短命なジョブのメトリクス収集
VictoriaMetrics
- Prometheus 専用に作られたリモートストレージ
Prometheus Loki
- Prometheus と親和性の高いログツール

Prometheus実践ガイド: クラウドネイティブな監視システムの構築

仲亀拓馬 (著)

Amazon.co.jpで詳細を見る

読書メモ: Stream Processing with Apache Flink

Kosei Moriyama — Wed, 12 Jun 2024 20:30:00 +0900

Stream Processing with Apache Flink: Fundamentals, Implementation, and Operation of Streaming Applications

英語版 Fabian Hueske (著), Vasiliki Kalavri (著)

Amazon.co.jpで詳細を見る

会社で運用し始めたので、キャッチアップのために読んだ。そしてその目的にはぴったりの本だった。Apache Flink の専門書ではあるが、ストリーミング処理やその周辺のログ基盤技術についてあまり馴染みのない・片手間で対応してきたが体型的には把握できていないエンジニアが素早くキャッチアップするのに、コンパクトにまとまっていることもあり最適だった。一方で全体的に深入りはしていないので、すでにこの分野や Flink そのものに習熟しているエンジニアには物足りないかもしれない。

1 から 3 章は Flink に限らないストリーミング処理一般の概念や設計思想の説明で、特に興味深かった。解決したい要件に対して、既存のアプローチ（バッチ中心の構成やラムダアーキテクチャなど）との比較から始まり、ストリーミング処理独自のチャレンジ、トレードオフの紹介などがまとまっている。

また例えば watermark の仕組みが興味深い。分散システムの一般的な特性だが、ネットワーク越しの外部からのデータが確実にタイムリーに到着するとは仮定できないため、できるだけデータの到着を長く待った方がより正確な計算ができる。一方で無限に待つことはできず、あまりに長く待つとレイテンシが悪化するという、正確性とレイテンシのトレードオフの関係がある。これを調停するのが watermark という仕組みで、その時点でデータは確定しているとみなす閾値、= どの程度待つか、を定めている。

他には、例えば障害時に計算途中から処理を再開するための checkpoint という中間データを永続化する仕組みがあるが、全体のレイテンシと障害時の復旧速度はトレードオフの関係にあり、（他にもチューニングポイントはいくつかあるが） checkpoint 取得頻度というパラメータでそれを調整できるようになっている。また連鎖するオペレーターで上流から checkpoint を取得するためのマーク (checkpoint barrier) を流すことで全体の整合性が取られるというアプローチも綺麗だ。

4 章以降は Flink の具体的なセットアップやアプリケーションの実装の説明となり、基本的には流し読み、必要になってから参照しに戻れるよう頭にインデックスを作るイメージで読んだ。次は実際に手を動かしたり、運用している仕組みの実態を把握していったりしたいと思う。

以降は読書メモ。

1. Introduction to Stateful Stream Processing

A Distributed stream processor
- Stateful Stream Processing Application を実装できる
- 2014 に Apache の incubating project 入り
従来型のデータ基盤
- 従来のデータ基盤は Transactional processing と Analytical processing に分かれている考え方だった
- Transactional
  - いわゆる OLTP の DBMS に各アプリケーションがアクセスする形式
  - データ量が増加した場合の最近のアプローチはマイクロサービスで、分割することでデータストア1つあたりの規模を抑える
- Analytical
  - Transactional DBMS 上のデータは通常 (マイクロサービス構成では特に) 分散しているので、それを一箇所のデータウェアハウスに集約する
  - この集約処理は ETL と呼ばれる
    - データの抽出、変換、バリデーション、正規化、エンコーディング、重複排除などを行う
  - 一般的に ETL はバッチ処理で、ビジネス要件に応じて実行頻度を高めるには相応のコストや技術が必要とされる
  - データウェアハウスにインポートされたデータの利用方法は、定期実行クエリとアドホッククエリに分類できる
  - 今日ではデータストアとしては HDFS、S3、HBase などが、その上で動く処理エンジンとして Hive, Drill, Impalla といった SQL-on-Hadoop エンジンが使われることが多い
Stateful Stream Processing
- すべてのデータは「継続するイベントのストリーム」と抽象化することができる。Stateful Stream Processing はこのイベントストリームを処理し多様なユースケースに対応できるデザインパターン
- 大まかな仕組み
  - イベントストリームは単にその時点のレコードだけを処理するのではなく、なんらかの状態 (中間データ) を参照する必要がある
    - 各所からアクセスできるデータストアに中間データを保持し、アプリケーションがイベントを受け取った際にそのデータを読み書きする
  - Flink は状態をローカルのメモリに保持する。また Flink は分散システムなので、状態を定期的にチェックポイントとして外部ストレージに冗長化し、障害に備えている
    - Figure 1-4. A stateful streaming application より引用
  - イベントの受け取りにはよく Kafka 等の Event log system が使われる
    - イベントストリームを追記のみで immutable な Event Log として扱う
    - この特性は過去の特定の時点からの「リプレイ」を可能にするので、耐障害性が高い。またバグ修正、マイグレーション、AB テストも容易になる
- 代表的なユースケース
  - Event-Driven Applications
    - イベントのストリームをトリガーに動作するアプリケーション。一つのアプリケーションは別のアプリケーションが発したイベントを Consume する (= Event-Driven アプリケーションが数珠繫ぎになっている) 構成もある
    - Real-time recommendation, Pattern detection (Fraund detection), Anomaly detection などが代表的なユースケース
    - Transaction なシステム、またはマイクロサービス、と比較すると、通信手段が REST API から Event-log に、データストアが RDB からローカルのステートに変わっている
      - 状態をより近くに持っているのでパフォーマンスに有利で、またスケールや耐障害性の担保を Stream Processor 側に任せることができるのがメリット
  - Data Pipelines
    - 一般的にシステム全体の中で、パフォーマンス要件のためデータはいろいろなデータストアに分散する
    - これらのデータストア間の同期は、ナイーブには定期的な ETL で行われるが、レイテンシが要件に合わなくなることも多い
    - その場合 Stream Processor がその同期を担うことでレイテンシを大幅に下げられる
      - データソースの変更をイベントとして受け取り、Consumer のデータストアに (必要に応じて正規化などを行った上で) 挿入する
    - Stream Processor には多様なデータ Source, Sink への対応が求められる
  - Streaming Analytics
    - 従来のデータ分析は定期的な ETL、数時間から数日のレイテンシ、に頼っていたが、Stream Processor に置き換えることでほぼリアルタイムの分析が可能になる
      - 例えばモバイルネットワーク回線品質のモニタリング、モバイルアプリのユーザー行動分析、消費者のリアルタイムデータのアドホック分析などが可能になる
    - 隠れたメリットとしては、従来構成では複数のコンポーネント (ETL プロセス、データストア、データプロセッサー、スケジューラーなど) が必要だったが、Stream Processor によって一つのコンポーネントで済むようになる
Stream Processor の歴史
- 第1世代 (Lambda Architecture) (2011 年頃)
  - Stream Processor はレイテンシの改善 (milliseconds レベル) を主目的として、反面正確性と一貫性は保障していなかった。またイベントは more-than-once で処理されていた
  - Lambda Architecture は従来の Batch Layer (正確だが高レイテンシ) と Speed Layer (不正確だが低レイテンシ) を並列させるというもの
  - 主なデメリット
    - 意味的に同じ処理を別の API 向けに 2 回実装する必要がある
    - Speed Layer の結果が概算値のみ
    - セットアップとメンテナンスが複雑
- 第2世代 (2013 年頃)
  - 対障害性と exactly-once を保障し、よりシンプルな API を提供するが、レイテンシは秒レベルまで落ちてしまった
- 第3世代 (2015 年頃)
  - イベントが届いたタイミングと順序に依存する問題を解決し、またスループットとレイテンシを両立させるようになった
  - この時点で Lambda Architecture は不要になり Stream Processor に 1 本化できるようになった
  - Flink は第 3 世代のプロダクト

2. Stream Processing Fundamentals

Introduction of Dataflow Programming
- 有向グラフで表現される処理の流れ
- ノードがオペレータでエッジがデータの依存関係を表し、一つ以上の source と sink がある
- ハッシュタグをカウントする例。これはハイレベルな処理の抽象化なので「ロジカル」と呼ばれる
  - Figure 2-1. A logical dataflow graph to continuously count hashtags より引用
- 一方で実際に各ノードで処理されるグラフは「フィジカル」と呼ばれる
  - Figure 2-2. A physical dataflow plan for counting hashtags より引用
- Data Parallelism と Task Parallelism
  - 前者はデータを分割し、同じ処理を異なるデータのサブセットに対して繰り返すこと
  - 後者は異なる処理を並列に動かすこと
- Data exchange strategy
  - Forward
    - 単純に次のタスクに全データを渡す。同じ何度ならネットワークコストがかからない
  - Broadcast
    - 次の並列タスク全てに全データを渡す。コストが高い
  - Key based
    - キーに合致するものは必ず同じタスクに処理されるよう保障
  - Random
    - ランダムに均等に分散させる
ストリームの並列処理
- Data stream: 区切りのないイベントのシーケンス
- Latency と Thoughtput
  - Latency
    - イベントが登録されてから最終成果が出来上がるまで
    - 低 Latency が Stream Processor の最大の特徴であり従来のバッチ処理との大きな違い
  - Throughout
    - 単位時間あたりの処理量
    - 処理できる最大スループットを超えた入力がある状況を backpressure と呼ぶ
    - レイテンシが下がるとスループットは上がる関係にある
- Operations
  - ステートレスなオペレーションはそれぞれ独立なので並列化や障害時のリトライがしやすいが、ステートフルな場合は簡単ではない。以下でケースごとに詳細を見ていく
  - データの挿入 source と送出 sink (ステートレス)
    - 多様なフォーマットへの対応する
  - Transformation operations (ステートレス)
    - 入力を変換し出力する単純な操作
    - 複数の入出力先に対応する
  - Rolling aggregations (ステートフル)
    - sum, min, max といった集約を行う操作で、ステートフル
    - 集約関数は結合的かつ可換的である必要がある。そうでなければすべてのデータ履歴を保持する必要があるので
  - Window operations (ステートフル)
    - transformation や aggrigation は単一のイベントに対する処理だが、複数のデータに対する処理も必要
    - Window は無限のストリームから有限のデータセットを生成する
    - 1 つの bucket にどのようにデータを入れるかを定める window policy と、どのタイミングで bucket のデータを評価 (計算) するかの trigger policy がある
    - Tumbling window
      - 一定のイベント (カウント、時間ごと等) をオーバーラップしないで bucket に入れる
      - bucket がいっぱいになった時点 (指定したカウントに達したか、指定した時間に達した時点) で計算を行う
    - Sliding window
      - 一定のイベントをオーバーラップさせて bucket に入れる
      - Length (1 bucket あたりのイベント数) と Slide (次の bucket を作成するタイミング) を指定する
      - Figure 2-8. Sliding count-based window with a length of four events and a slide of three events より引用
    - Session window
      - イベントの間隔が一定以上空いた場合に bucket を閉じる。この間隔を session gap と呼ぶ
      - ユーザー行動分析等現実のユースケースに対して有用
  - Parallel windows
    - 例えばデバイス ID でイベントを分けてから、それぞれに対して並列に独立して Window 操作を行う
- Time semantics
  - 正しい順序ではなく届いたイベントの処理や、過去データのリプレイの処理に必要な概念
  - 例えば地下鉄乗車中のゲームプレイ。ネットワークが不通の区間に入るとイベントがローカルにバッファリングされ、復旧した際に一括送信される。このとき、イベントを受け取った時刻 (Processing Time) で処理するよりも、イベントの実際の時刻 (Event Time) で処理できたほうがよい
  - Event Time をもとにした処理で、ネットワーク品質に依存せず、決定論的にストリームを処理できる。この性質は過去データのリプレイにも有効
  - 遅延して届くイベントをどれだけ待つかは、確率論的で簡単に決めることはできない。その調整弁として Watermarks がある。Watermarks は仮にすべてのイベントを処理しきった時刻を表す。短くするとレイテンシは下がるが誤差が増えるというトレードオフがある
    - アプリケーションによっては Watermarks を超えて遅延したイベントを適切に処理する必要がある (ログに残す、再計算するなど)
  - 正確な結果が不要な場合などは Processing Time を使うこともある。Event Time に比べてレイテンシが低い
- State and Consistency Models
  - 状態管理の難しさ
    - State management
      - 複数のオペレーターからの並行したアクセスの制御も必要
    - State partitioning
    - State recovery
      - 最も大きなチャレンジ
  - Task failures
    - イベントを受診してローカルバッファに入れる、イベントを読み取り内部状態を更新する、計算結果を送信する。どの時点での障害からも、一貫した内部状態への復旧を保証したい
      - 従来のバッチ構成だと毎実行がステートレスなのでこの問題は無い
    - ここでは内部状態の一貫性の保証について扱う。出力の一貫性は扱わない。sink 先がトランザクションに対応しているかどうか次第なので。
    - 保証の種類
      - At-most-once
        
        no-guaranteeと同じ。レイテンシが重要で正確さは不要な場合には取りうるオプション
      - At-least-once
        
        イベントのロストはなく、重複はある
        
        冗長化されたイベントログのリプレイや、イベント受信時の acknowledge (ack されて初めて送信側はそのイベントを discard できる）といった実現方法がある
      - Exactly-once
        
        最も厳密で実現が難しい保証
        
        At-least-once 同様のリプレイと、その際にどこまでが内部状態に反映されたかの考慮が行われる
        
        transactional な状態更新がひとつのアプローチだが、パフォーマンスのオーバーヘッドが大きい
        
        他にはより軽量な sharpshooting の仕組みを使うアプローチがあり、Flink はこちらを採用している
      - End-to-end exactly-once
        
        オペレーターごとでなく、パイプライン全体での保証
        
        一般的には個々のオペレーターの保証レベルより、全体の保証レベルは弱いものになる。ただし各オペレーターが冪等な場合、at-least-once 保証から exactly-once が実現できたりする

3. The Architecture of Apache Flink

System architecture
- 一般的な分散システムの難しさ - コンピューティング資源のアロケーションと管理、プロセス間の調停、冗長で高可用性のあるストレージ、障害復旧 - のうち一部は、k8s, HDFS や S3, ZooKeeper といった既存のソリューションに任せている
- コンポーネント
  - Figure 3-1. Application submission and component interactions より引用
  - JobManager
    - アプリケーションごとのマスタープロセス
    - アプリケーションを JobGraph (logical dataflow graph) として受け取り、ExecutionGraph (physical) を組み立てる
      - 必要なクラスやライブラリなどがバンドルされた JAR も必要
    - ResourceManager に必要な資源 (TaskManager slots) を要求し、満たされたらデプロイ
    - アプリケーションの実行中は調停が必要なアクション（障害復旧のためのチェックポイント関連など）に責任を持つ
  - ResourceManager
    - TaskManager slots という単位でリソースを管理
    - バックエンドは k8s, YARN, Mesos, standalone cluster など
  - TaskManager
    - いわゆるワーカープロセス。ひとつの TaskManager に複数の slot がある
  - Dispatcher
    - アプリケーションを登録する REST API や Dashboard の提供
- Application deployment
  - 複数のアプリケーションを受け付けることができる Framework style と、特定のアプリケーションごとバンドルされている Library style がある
- Task execution
  - 一つの JobGraph を複数の TaskManager slot に並列に割り当てられる
  - ひとつの slot には複数のオペレーターが入る。slot 間の通信が少ない方がパフォーマンスに有利
  - 各 slot はスレッドで実装されている。パフォーマンスとスレッド感の独立性（極端には TaskManager ごとに 1 slot にすると独立性は高まる）はトレードオフの関係にある
- Highly available setup
  - 特に JobManager の冗長化について
  - JobManager は JobGraph や JAR などの必要情報を外部ストレージに、そのポインタやメタデータを Zookeeper に保存する
  - 再起動した際や待機系に切り替わった際は Zookeeper の情報を元にクラスタを復旧、再開する
Data transfer in Flink
- TaskManager にはデータを受け取る Receiver と送る Sender があり、それぞれにはバッファがある
  - それぞれ送受信信先の Receiver, Sender ごとにバッファがわかれている
  - 同じノードの TaskManager 同士はメモリを介してネットワークを経ずにデータをやり取りする
  - ネットワークを介す場合、ノード間で永続的な TCP 接続が張られ、その接続内では各 TaskManager の通信が多重化されている
- Credit-Based Flow Control
  - 送信バッファと受信バッファの余裕に応じて適切な送信量を調整する仕組み
  - receiver は sender に受入可能な量を credit として伝える
  - sender は credit の範囲で必要なだけデータを送る。その際に自身の backlog (バッファ内にあり送信準備完了しているデータの量) も receiver に伝える
  - receiver は sender の backlog も考慮して credit を調整する
- Task Chaining
  - 同じ並列性と local forward で繋がれているオペレータを一つのオペレータにまとめて、タスク授受のオーバーヘッドを減らす
  - ただし 1 つのオペレーターの処理が重いなど、あえて chain しないほうが有利なケースもある
Event-time processing
- Event-time で動作させる場合、各データは必ず timestamp を持つ必要がある
  - イベントが発生した時刻が一般的だが、アプリケーションによって定義は変わって良い。ストリームプロセッサーからすると、とにかくイベントはこの timestamp 順に並んでいるとみなして処理する
- Watermarks は単調増加する event-time の時計として機能する
  - Watermark 以前の timestamp を持つイベントは Late records と呼ばれ、そのハンドリングは後述
- オペレータは内部に Timer サービスを持っており、そこにコールバックを (例えば Window 処理で集計を行う処理のコールバックを) 登録する
  - Timer は Watermark を受け取り、それが登録されているコールバックの Event time より進んでいれば、そのコールバックを実行する。その後 Watermark を下流に投げる
  - Watermak は上流のパーティション事に保持している。Timer 内部の Event-time はそれらの最小値を参照し、下流にもそれを Watermark として伝える
  - Figure 3-9. Updating the event time of task with watermarks より引用
  - この設計では、一部の Watermark が著しく遅れたり idle 状態になるとそれ以降のオペレーターに悪影響が出る
    - 一定以上 idle なパーティションは Watermark のハンドリング時に除外するといった対策がされている。詳しくは後述
- Timestamp と Watermark は基本的にはアプリケーションの Srouce で生成され、下流のオペレーターへ流れていく
  - AssignerWithPeriodicWatermarks, AssignerWithPunctuatedWatermarks といったユーザーがカスタムできるインタフェースもある。その場合でも Source の近くでそれを行うことが推奨されている
State management
- Flinkでは状態はオペレーターに紐づく
- Operator state
  - ひとつのオペレーター単位のスコープのデータ
- Keyed state
  - input のキーによってアクセスできるデータ
- state backend
  - メモリまたは RocksDB
  - 高速な前者に対して、大きいサイズにも対応できるのは後者
- スケールイン、アウトの際は、データの種類に応じて、リパーテイション、コピーなどを行う
Checkpoints, Savepoints, and state recovery
- Consistent checkpoints
  - ある時点での内部状態を外部ストレージに永続化する
  - 障害時はアプリケーション全体をリセットし、最新のチェックポイントから状態を復旧、そのチェックポイントが取られた時点まで Source を巻き戻し resume する
    - アプリケーションの各タスクから見るとこれで exactly-once が実現されている
    - Source がリプレイに対応していないと実現できない
    - Sink には障害復旧前後で同じデータが二度流されることになる。そのトランザクションや冪等性を持った実装などでハンドリングする必要がある
  - チェックポイントの取得
    - Stop-the-world: すべてのタスクを停止し、処理中のものがすべて完了するのを待ってからチェックポイントを取得。その後処理を再開する
    - Chandy-Lamport algorithm: タスク実行を継続しながら取得できる。Flink はこれを採用している
      - checkpoint barrier という watermark のような印を JobManager source から sink に流す
      - Source は barrier を受け取るとその時点の状態をチェックポイントに書き込む。また JobManager に Ack を送り、下流に barrier を流す
      - 各オペレータはすべての入力からの barrier が揃うまで待ち、揃ってからチェックポイントに書き込み、下流に barrier を流す。最初に Source A から barrier を受け取り、Source B の barrier を待っている間、Source A からの入力は処理せずバッファリングする
      - Sink は同様に barrier を受け取り、チェックポイントを書き込んだ後 JobManager に Ack を伝える
    - レイテンシを下げるための工夫も行われている
      - チェックポイントバックエンドによっては、状態をローカルコピーしている間だけタスクを止めるが、コピーをリモートストレージに書き込む処理は非同期に行うものもある (FileSystem, RocksDB など)
      - RocksDB は incremental checkpointing をサポートしている
      - exactly-once ではなく at-least-once が許容できる場合、複数 source の barrier が揃うのを待つ間にバッファリングせずに処理を継続する
- Savepoints
  - Checkpointsと同じ仕組みでアプリケーション全体の状態を保存、後ほどそこから resume できる
  - ある状態から再生してデバッグしたり、別クラスタへの移行、クラスタバージョン更新といったユースケースで有用

4. Setting Up a Development Environment for Apache Flink

https://github.com/streaming-with-flink/examples-scala のセットアップの説明。

5. The DataStream API (v1.7)

基本的な構成
- 実行環境の取得
  - val env = StreamExecutionEnvironment.getExecutionEnvironment
    - local か remote かを状況に応じて返す
  - env.setStreamTimeCharacteristic(TimeCharacteristic.EventTime)
    - event-time モードに設定
- 入力ストリームの読み込み
  - val readings: DataStream[SensorReading] = env.addSource(new SensorSource).assignTimestampsAndWatermarks(new SensorTimeAssigner)
    - SensorSource はランダムなセンサーデータを生成する
    - その後タイムスタンプと watermark を付与
- 変換
  - map() 関数で華氏から摂氏に変換
  - KeyBy() で id でグルーピング
  - timeWindow() で 1 秒間のウィンドウを作成
  - apply() でユーザー定義関数を適用し平均を計算
```
val avgTemp: DataStream[SensorReading] = readings
    .map( r => SensorReading(r.id, r.timestamp, (r.temperature - 32) * (5.0 / 9.0)) )
    .keyBy(_.id)
    .timeWindow(Time.seconds(1))
    .apply(new TemperatureAverager)
```
  - 出力
  - 今回は avgTemp: DataStream[SensorReading] に結果が保持され、標準出力に出力される
  - 典型的には Apache Kafka, Filesystem, Database などの Sink に出力される
  - 実行
  - env.execute("Compute average sensor temperature") を呼び出した時点で始めて実行がトリガーされる
    - それまでの API 呼び出しは実行計画の作成までで、実際の変換処理は遅延実行となる
  - 実行計画は JobGraph に変換され、JobManager に送信される

/** Object that defines the DataStream program in the main() method */
object AverageSensorReadings {
    /** main() defines and executes the DataStream program */
    def main(args: Array[String]) {

        // set up the streaming execution environment
        val env = StreamExecutionEnvironment.getExecutionEnvironment

        // use event time for the application
        env.setStreamTimeCharacteristic(TimeCharacteristic.EventTime)
        // configure watermark interval
        env.getConfig.setAutoWatermarkInterval(1000L)

        // ingest sensor stream
        val sensorData: DataStream[SensorReading] = env
            // SensorSource generates random temperature readings
            .addSource(new SensorSource)
            // assign timestamps and watermarks which are required for event time
            .assignTimestampsAndWatermarks(new SensorTimeAssigner)

        val avgTemp: DataStream[SensorReading] = sensorData
            // convert Fahrenheit to Celsius using an inlined map function
            .map( r =>
            SensorReading(r.id, r.timestamp, (r.temperature - 32) * (5.0 / 9.0)) )
            // organize stream by sensorId
            .keyBy(_.id)
            // group readings in 1 second windows
            .timeWindow(Time.seconds(1))
            // compute average temperature using a user-defined function
            .apply(new TemperatureAverager)

        // print result stream to standard out
        avgTemp.print()

        // execute application
        env.execute("Compute average sensor temperature")
    }
}

Transformation
- Stream API programming は複数の変換処理をつなぎ合わせることと同義。またユーザーロジックも User defined function の transformation として扱う
- Basic transformations
  - Map, Filter, FlatMap (一つの入力から、0から複数の出力。Map と Filter を組み合わせて汎用化したもの)
- KeyedStream transformations
  - KeyedStream は DataStream を特定のキーで論理的にパーティショニングしたしたもの。同じキーのイベントは同じ状態にアクセスできる
  - KeyBy
    - キーを指定し DataStream から KeyedStream を生成する
  - Rolling aggregations
    - sum, min, max などを KeyedStream に適用し DataStream を生成する
  - Reduce
    - Rolling aggregation の汎用版で、Reduce関数を全要素に適用して集約する
- Multistream transformation
  - Union, Connect/coMap/coFlatMap (SQL の join に近い), Split and select
- Distribution transformations
  - アプリケーションレベルでデータをパーティショニングしたい場合。通常は Flink が自動で割り振るが、skew がある場合などに使う
  - random, round-robin (rebalance), rescale (送信先のサブセットに対してのラウンドロビン), broadcast, global, custom
Parallelism の設定
- 環境ごととオペレーターごとの設定値がある
- 環境ごとのものは、例えばローカル起動だと CPU のコア数がデフォルト
- オペレーターごとに上書きできる。その際に環境の値を取得してそこからの相対値の指定も可能
Types
- Flink は型情報をもとにデータを伝搬している。特に型に応じて独自のシリアライズを行い効率化している部分もある
  - fallback として汎用型として扱われ Kyro を使ってシリアライズされるケースもあるが、パフォーマンスは劣る
- 対応している型
  - Primitive (Java, Scala のプリミティブ型)
  - Tuples
  - Scala case classes
  - POJOs (Apache Avro で生成されたクラスも含む)
  - Special types
- 型情報は TypeInformation クラスで管理されている
- 通常 Flink は適切な型を推論するが、明示的に指定することもできる
Functions の実装
- Function Classes
  - プログラムが submit されると、Java の serialization でシリアライズされ各ワーカーに配られる
  - そのタイミング以降は変更はできない。イベントに応じた初期化などはできない
- Lambda Functions
- Rich Functions
  - 初期化とファイナライズを行う open(), close() がある
  - getRuntimeContext() が提供されており、タスクの parallelism, subtast index, task name, partitioned state などの情報にアクセスできる

6. Time-Based and Window Operations

StreamExecutionEnvironment で TimeCharacteristic を設定する
- ProcessingTime, EventTime, IngestionTime (イベントが Flink に到達した時刻を Event time とみなす)
Timestamp のアサインと Watermark の生成
- millisecond 単位の epoch time を使う
- SourceFunction (後述) または UDF でアサインと生成を行う
  - TimestampAssigner インタフェースを実装する
  - できるだけ Source の近くで実行することが推奨されるが、タスクのリディストリビューションに影響しなければ任意の箇所でもよい
  - event time 依存の transformation を行う前にアサインする必要がある
- 繰り返しになるが Watermarks は正確性とレイテンシのバランスを取る必要がある。バッチ処理構成ではなかった、区切りのないイベントを扱うストリーム処理の本質的な特徴である
Process functions
- これまで見てきた DataStream API の関数は timestamp へのアクセスが制限されていたが、これらは Process Function という低レベルの API の上に実装されている
- ProcessFunction は RichFunction を実装している、つまり open(), close(), getRuntimeContext() を提供している
- 加えて、KeyedProcessFunction[KEY, IN, OUT] を例にとると、以下の 2 つのメソッドを提供している
  - processElement(v: IN, ctx: Context, out: Collector[OUT])
    - Context が通常の関数との大きな違いで、timestamp へのアクセスはここから可能になっている
  - onTimer(timestamp: Long, ctx: OnTimerContext, out: Collector[OUT])
    - 事前に登録された Timer がトリガーされた際に呼び出されるコールバック
    - こちらも timestamp へのアクセスが可能
- TimeService
  - 現在時刻の取得、タイマーのセット、タイマーの削除ができる
  - 設定したタイマーが発火すると前述の onTimer が呼び出される
- Side outputs
  - 通常は一つの出力を下流に流すだけだが、Process functions はその他に Side outputs という別の出力をすることができる
- CoProcess functions
  - 2 つの入力ストリームを受け取り、それぞれのイベントに対して処理を行う。CoFlatMapFunction と同様の機能を持つが、こちらは Context がわたってくるのでタイマーや Side output が可能
Window operators
- 区切りのないストリームを一定のグループ (Bucket) に区切り、そのグループに対して処理を行う
- Window operator は 2 つの構成要素から成る
  - Window assigner: 入力ストリームをどう window にグループ分けするかを定義する。window assigner は WindowStream を生成する
  - Window function: WindowStream に適用される処理
- Window は最初の要素がアサインされた際に作成される。Finlk は空の window を評価しない
- Built-in Window Assigners
  - Tumbling widows
  - 固定の時間間隔のウインドウ。オーバーラップなし
  - Sliding windows
    - 固定幅でインターバルごとにスライドする
      - インターバルがウインドウ幅より小さければオーバーラップするし、大きければ間のイベントは欠損する
  - Session windows
    - イベントとイベントの間が一定以上インアクティブな場合に別バケットとする
- Windows への関数の適用
  - 関数は2種類に分類できる
    - Incremental aggregation function: イベントがウインドウに追加されるたびに計算する。空間効率がよい
      - ReduceFunction, AggregateFunction
    - Full window functions: ウインドウ内の全イベントをループして計算する。より複雑なロジックを実現できる
      - ProcessWindowFunction (Context として Window の開始終了時刻や、グローバル・ウインドウごとの状態へのアクセスが可能。内部的にそのウインドウのイベントが全て List で保持されており、複雑なロジックが実装できる)
  - Reduce などの Incremental な関数の第二引数に ProcessWindowFunction を渡すことで、届いたイベントごとに Reduce などを適用した後に ProcessWindowFunction を適用するということもできる
- カスタムの Windows 関数の定義も可能
  - windows の Lifecycle
    - Assigner が最初の要素を追加したときに作られる
    - Window ごとに以下の要素を持つ
      - Window content: incremental aggregation が適用された後の計算結果
      - Window object: window ごとに別のオブジェクト。開始終了時刻などを持つ
      - Timers and triggers
        
        Windows の評価や削除のタイミングでトリガーする
      - カスタムの状態
    - Window の破棄時に content や object も破棄されるが、カスタムのトリガーや状態は自動では破棄されず、自身でちゃんと掃除しないとリークする
Joining streams on time
- 複数のストリームを結合するために、Interval joinと window join というビルトイン関数が準備されている。またカスタムロジックも実装できる
- interval join
  - 指定したインターバルの期間内のイベントでキーが一致したら結合する
  - Inner Join のセマンティクスを提供する。つまりマッチするレコードがなければ破棄される
- window join
  - assigner が振り分けて同じ window に入ったもの同士で結合する
Handling late data
- Dropする。最もシンプルでデフォルトの動作
- 別のストリームに Side output で流す。それをどう処理するかは要件による
- 再計算し更新を伝搬する
  - 実現には以下の2点がクリアになっていないといけない
    - 計算済みのウインドウ、状態をどれだけ保持し続けるか
      - Allowed lateness というパラメータで調整する
    - Sink 先が後からの更新に対応しているか

7. Stateful Operators and Applications

Statefulな関数の実装
- KeyedState
  - Keyed Steamのみ
  - 同じキーを処理する並列タスクがスコープ
  - 単体の値やList, Map, ReduceState, AggregateState
  - StateDescriptor を登録する
- Operator List State
  - オペレーター単位のスコープ
  - スナップショットをとる時やリストアする時の処理を実装する必要がある
  - スケールイン、アウトに合わせて状態も統合、分割する必要があり、その実装を行う必要がある
- Broadcast State
  - 例えば高温検知システムで閾値を動的に変えるような場合に閾値を前オペレータにブロードキャストするというユースケース
- CheckpointedFunction interface
  - チェックポイントと状態の整合性を管理するためのインタフェース
  - オペレーターの起動時、再起動時に初期化を行う関数と、チェックポイント取得直前に呼び出される状態のスナップショット取得関数を実装する
- 例えば exactly-once を要求する sink への書き込みは、checkpoint が完了した時点のデータを書き込まないと、障害時に再計算されデータが変わる可能性がある。そのような要件のオペレーターのために JobManager から checkpoint の完了通知を受け取るインタフェースもある
Checkpoint 作成の有効化
- 明示的に有効化する必要がある
- Checkpoint 取得のインターバルはアプリケーション全体のパフォーマンスと障害復旧時間のトレードオフになる
- インターバル以外にもチューニングポイントがある。保証レベル（exactly-once or at-least-once）、checkpoint 並列数、checkpoint のタイムアウト、backend特有のパラメータなど
Savepoint 利用時に必須の設定
- オペレーターごとの unique identifier と Keyed State operator の最大並列数の指定がされていないと、Savepoint を適切に利用できない
  - 前者がないと状態をどのオペレーターに割り振れば良いか判断できない。後者もデータの分散に影響があるので必須
- Savepoint が利用できないとアプリケーションの改修やデバッグが極めてしづらくなる
頑健性とパフォーマンス維持
- どのようなセットアップにするかによって変わる
- State Backend
  - Memory
    - TaskManager のメモリ上に状態を保存し、JobManager のメモリ上に Checkpoint する
    - 高速だが、それぞれの JVM プロセスのメモリサイズまでしか状態を持てず、必然的に GC されやすい。また JobManager の障害からは復旧できない
    - 基本的には開発環境用
  - Fs
    - 状態は引き続きメモリ上に持つが、checkpoint は外部ストレージに保存する
    - レイテンシを維持しつつ永続化もできるが、TaskManager のメモリサイズの制約と GC されやすいという制約は残る
  - RocksDB
    - 大きいサイズの状態が必要な場合の選択肢。テラバイト水準での実績もある
    - その分メモリに比べるとレイテンシは劣る
- RocksDB のようにデータをシリアライズして格納するバックエンドの場合、その実装方法とどの型を使うかでパフォーマンスが大きく変わる
  - 例えば ValueState は全体をシリアライズ、デシリアライズするが、MapState はキーごとにシリアライズされるので、高速になるケースもある
- アプリケーションを長期間稼働させるには状態が肥大化しないことが重要
  - 状態はオペレーターの要件と深く関わっているので、Flink が自動で各状態をクリーンアップすることはできず、各オペレーターにその管理の責任がある
  - よくあるケースは Keyed State に stale key が残り続けるというもの。expire したものはクリアする
  - またビルトイン関数であっても状態のクリーンアップは自前で行う必要がある。例えば KyedStream の aggregation は一定の範囲のキーが何度も登場するストリームを前提としている
Stateful Application の拡張
- アプリケーションの更新は savepoint 取得、旧アプリケーションの停止、savepoint からの新アプリケーションの起動という手順で行われるので、新旧で savepoint compatible である必要がある
- savepoint の互換性にはオペレーターの識別子と状態名の一致が必要
- 更新は 3 つのケースに分類できる
- 1. 既存の状態は変更せず、ロジックを更新、または新しい状態を追加する
  - このパターンでは常に savepoint 互換性は保たれる。新しい状態は空で初期化されるだけ
- 2. 状態を削除する
  - デフォルトでは Flink はすべての状態がリストアできなければアプリケーションを起動しない。そのためこの safety check を明示的に一時無効化し新アプリケーションを起動する必要がある
- 3. 状態の型やプリミティブを変更する
  - 1.7 時点では、一部の型変更は可能だが、プリミティブの変更はサポートされていない
    - 前者は Apache Avro の schema evolution rules の範囲内で可能
  - コミュニティから要望の多い機能だがまだ実現されていない
Queryable State
- ストリーミングアプリケーションの処理結果は sink のデータストアに書き込まれ別のアプリケーションから参照されるのが通常の構成
- Flink は Queryable State という機能を提供しており、アプリケーション稼働中の各状態を外部から read-only で参照できる
  - この機能によりリアルタイムダッシュボードなど一部のユースケースの実装が容易になる
- TaskManager ごとに Proxy プロセスが動作し、クライアントからのリクエストに応じて JobManager にその状態を管理する TaskManager やキャッシュの有無を問い合わせる
- Query 可能な状態はストリーミング処理のコード上で指定する

8. Reading from and Writing to External Systems

Application consistency guarantee
- エンドツーエンドの一貫性の保証には source と sink 側の対応も必要になる
- source はチェックポイントからのリプレイに対応していないと、At-most-once 保証相当になる
- sink は冪等性を持つか、transactionalな書き込みに対応していないと At-least-once 相当になる
  - 冪等に処理を行える sink の場合、最終結果は exactly-once 相当になる
    - ただしリカバリ中に過去のデータが見えてしまうという一貫性の崩れが起こり得る
  - transaction の実現には WAL と 2PC のアプローチがある
    - 前者はチェックポイントが確定した WAL のみ sink に送る。一度に sink に書き込まれる量がスパイキーになるリスクがある
    - 後者はストリーミングアプリケーションと sink 側で 2PC を実現する
Provided connectors
- Apache Kafka
  - Source
    - Kafka の各パーティションのオフセットをリーダーが checkpoint として保持している
    - Kafka 0.10.0 以降は message timestamp に対応しており、Flink はこれを event timeとして使う
  - sink
    - at-least-once 保証の場合、書き込みに失敗した際には指定した回数のリトライを行う
    - exactly-once の場合はトランザクション機能が使われる
      - ログを uncommitted 状態で記録し、確定後に committed ラベルを付ける。consumerは分離レベルに応じて uncommitted なレコードを読み取るかを決める
      - 長時間 open なトランザクションは timeout 設定に応じて自動でクローズされる
      - そのため、Flink 側でリカバリに時間がかかりすぎた場合などに、この Kafka 側のタイムアウトを超えないよう注意する
- Filesystem
  - source
    - 与えられたパスのファイルをスキャンし、ファイル名とその中のレンジに分割し、複数のタスクにそれを渡して並列読み込みをする
    - ワンショットの読み取りが、mtime ペースの継続読み取りが可能
    - 後者の典型的な実装パターンは、ファイルを書き込み、完了後にそれを Flink がモニターしているディレクトリに mv するというもの
    - filesystem を source とする場合、watermark の生成は単純ではない。複数に分割され複数のリーダーで読み取りをしているものの中から、最小の timestamp を特定する必要がある
  - sink
    - ローテーションの設定や encoding の設定 (行ごと、全体をバルクで) などの設定もできる
    - in-progress/pending/complete 各状態でファイルを管理し、checkpoint がとられたものが complete としてコミットされる。この機構で exactly-once が実現される
- Apache Cassandra
  - sink connector を提供
  - デフォルトでは casandra の upsert semantics を利用した、eventual excatly-once 保障が提供される
    - 一時的な inconsistency も許容できない場合は WAL モードを使うとよい
Custom Source Function
- Source|RichFunction (1並列用) と (Rich)ParalllelSourcFunction (複数並列用) というインタフェースが提供されている
  - それぞれ run() と cancel() を実装する
- これまでに述べたように、Flink の checkpointing 機構と連携した読み取り位置 (やファイルパス、パーティション ID などのメタデータ) を保持し checkpoint として永続化すること、savepoint からの起動ではその情報を復元すること、savepoint なしではデフォルト値から開始することが、一貫性の保障のためには求められる
- また run() メソッドは別スレッドで動作するので、checkpoint 取得中は読み取り位置を前に進めないよう、ロックなどで保護する必要がある
- Source function で timestamp と watermark を生成するのがベター
  - 複数並列で読み取る場合は、それぞれの source ごとに watermark を生成する必要がある
- source が stale した際に、source function はそれを検知して idle 状態に遷移する必要がある。前述したようにそうしないと watermark が進まず、アプリケーション全体が滞留してしまう
Custom Sink Function
- 冪等性を持つ sink との連携の場合、レコードを特定できる識別子があること、sink 先がそのキーでの upsert に対応していることが必要とされる
- transactional なアプローチの場合、WAL 方式か 2PC 方式かが必要になる。それぞれのテンプレートがありそれを実装する
  - WAL
    - GenericWriteAheadSink の sendValues() を実装する
    - WAL 方式は次のケースで厳密な exactly-once にはならない
      - sendValues() の途中で失敗した場合。特に sink バルクインサートに対応していない場合、途中までのレコードが書き込まれていて、その後もう一度おなじ書き込みが走ることになる
      - sendValue() は成功したが、その後 CheckpointCommitter の呼び出し前や呼び出し中に失敗した場合。やはり全レコードが再度書き込まれる
  - 2PC
    - 基本的に重いプロトコルなので、本当に必要かは吟味したほうがよい
    - 2PC を採用するには sink は以下を満たす必要がある
      - transaction サポート (または sink function によるエミュレーション)
      - transaction を open し checkpoint interval の間に追加の write を受け付けられること
      - checkpoint completion notification を受け取るまでコミットを待てること
        
        もし sink が timeout でトランザクションをクローズした場合、その間のデータはロストする
        
        Cassandra sink はこのケースではデータをロストするので、条件付きの exactly-once 保証になる
      - 問題発生時にはトランザクションを復旧できること
        
        transaction id を発行し、それに対してコミットかロールバックを発行できる sink もある
      - transaction のコミットは冪等であること。同じ transaction id への複数回のコミットがありえる
- オペレータ内で POST API を呼び出すなど、ストリームアプリケーションに sink は必須のものではない。ただ exactly-once の保障などが必要な場合は sink の機構を利用したほうがよい
外部システムへの非同期アクセス
- source と sink 以外に、ストリームの途中で外部システムに問い合わせ、入力値の情報を補完するというユースケースがある
  - 例えば https://github.com/yahoo/streaming-benchmarks にはクリックデータにキャンペーン情報を補完するというパターンがある
- 単純にオペレータ内で同期的にに外部へクエリし結果を待っていると、全体のレイテンシが悪化する
- 非同期なアクセス手法が提供されており、この問題を緩和できる
  - event-time, watermark や savepoint の考慮もされている

9. Setting Up Flink for Streaming Applications

セットアップに関しては、概要は以前の章でカバーされており、詳細は実際に必要な部分をその時参照した方が良いので、メモは割愛
パラメータチューニング
- cpu
  - 明示的なパラメータはない
  - TaskManager ごとに最大何スロット起動できるかの設定はある
    - 主にスタンドアローンクラスタ向けのもので、k8s 上などに展開するクラスタの場合 pod ごとに 1 slot とし pod 数自体を伸縮させた方がわかりやすい
    - 後述のメモリ管理的にも、例えば jvm のヒープサイズはその上で動く slot 全体で共有になるので、1 slot ごとの方がやはり管理しやすい
- memory
  - まずは jvm のヒープサイズ
    - master プロセスは中程度のスペックで良いが、TaskManager はそれよりも豊富な方が良い
  - ネットワークバッファのメモリ使用量も多くなる傾向がある
    - Netty library が使われており、接続先ごとにネットワークバッファを持っている
    - タスクの並列度や組み合わせによって、接続数は大きく増えることがある
    - ネットワークバッファは native (off-heap) memory に確保される
  - RocksDB のメモリ使用量も増加することが多い
    - どの程度になるかはワークロードによる
- Disk storage
  - JAR ファイル、ログ、RocksDB バックエンドの場合の状態保持などで、 disk storage を利用している
- Checkpoint and state backend
  - コードレベル、アプリケーションレベルでの指定が主だが、クラスタレベルでのデフォルト値も指定できる
  - バックエンドによりサポート状況は異なるが、async checkpointing や incremental checkpointing はパフォーマンスに影響する
- Security
  - Kerberos 認証や内部、外部通信の SSL 化に対応している

10. Operating Flink and Streaming Applications

Streaming application の運用
- Savepoint は checkpoint とは異なり、手動でトリガーする必要があり、また自動では削除されない
- flink cli tool
  - job id: アプリケーションの識別子
  - flink savepoint <jobId> [savepointPath] で savepoint を取得
  - flink savepoint -d savepointPath で savepoint を削除
    - savepoint の取得が完了するまでは削除してはいけいない。checkpoint と同じように完了 notification に依存する処理がありうるので
  - flink cancel <jobId> でアプリケーションをキャンセル
    - cancel -s <savepointPath> で savepoint を取得してからキャンセル
  - flink run -s <savepointPath> [options] <jobJar> [arguments] で savepoint からアプリケーションを起動
- scale-in/out は savepoint からの起動時に設定を変更するだけで良い
  - アプリケーション全体の並列数設定ではなく、コード中で指定している場合はリコンパイルが必要になる
  - exactly-once を保障している場合は cancel -s で savepoint を取得してからキャンセルすること
  - アプリケーション全体の並列していだけで構成されている場合は flink modify <jobId> -p <newParallelism> というコマンドだけで変更が可能
- cli tool の内部では REST API を利用している。直接 REST API を利用することも可能
- ここまでは fremework style depolyment の話だったが、前述のように library style もある
  - ./flink-container/docker/build.sh でイメージを作成し、./flinc-container/kubernetes 配下の yaml テンプレートを参考に構築できる
Controlling task scheduling
- Task chaning の制御
  - 複数の処理を 1 スレッドにまとめ、データ転送のオーバーヘッドをなくす task chaning はデフォルトで有効になっている
  - ただし自動判定で結合・分断されたものが最適で無い場合、無効化することもできる
  - 特定のオペレータに対して明示的に chain させる、させない指定もできる
- Slot-sharing group
  - オペレーターをどのスロットグループに所属させるかを明示できる
  - 同じグループのオペレーターはそのグループのスロットで実行される
  - 各グループに何スロット割り当てられるかは parallelism 設定により割り出される
  - Figure 10-1. Controlling task scheduling with slot-sharing groups より引用
Checkpointing のチューニング
- 取得するインターバル
- 保証レベル (at-least-once or exactly-once)
- 前回の取得からの最少インターバル
  - チェックポイントの取得完了までに時間がかかるケースのため
- 並列数
- タイムアウト
- エラー時の挙動（例外を出して再起動するか否か）
- 圧縮の有無（バックエンドのサポート状況にもよる）
- アプリケーションエラー時にチェックポイントを保持するかどうか
State backend のチューニング
- メモリ: 非同期のオンオフ、最大サイズ
- FileSystem: パス、非同期のオンオフ
- RocksDB: パス、インクリメンタルバックアップのオンオフ
Recovery のチューニング
- リカバリ時には入力が溜まっている。最新にキャッチアップするよう十分なリソースが必要
- 時には何度再起動しても失敗し続けるケースもある。そのため再起動には３つのモードがある
  - 固定のインターバル後に再起動
  - ある期間にある回数だけ失敗できるという割合を指定し、その範囲内で再起動
  - 再起動しない
- 同じマシンでの再起動など、チェックポイントが外部ストレージだけでなく内部にも残っていることがある。local recovery を有効化するとそのようなケースでの復旧が速くなる
  - あくまで source of truth は外部ストレージ
監視
- 出発点としてはバンドルされている Web UI がある
- Prometheus など各種監視バックエンドへのメトリクスの連携も可能
- 独自のメトリクス定義も可能
- レイテンシの計測
  - 各イベントの厳密なレイテンシを計測するのは分散システムでは非常に難しい
  - そこで flink ではレイテンシ計測用の特殊なイベントを source から流し、sink に到達するまでの時間を計測することでレイテンシを概算している
  - この専用イベントは latency marker と呼ばれる。利用時にはインターバルを指定する
ロギング
- デフォルトは log4j で logback にも対応している

11. Where to Go from Here

本書では紹介していないハイレベル API
- DataSet API
  - バッチ処理が可能になる
- Table API
  - SQL を解釈しジョブグラフに落とし込んでくれる
- FlinkCEP
  - 複雑なパターンマッチ。金融、不正検知、異常の監視などがユースケース
- Gelly
  - グラフの作成
コミュニティ
- Mailing list
  - user@flink.apache.org
  - dev@flink.apache.org
  - community@flink.apache.org
- Blogs
  - https://flink.apache.org/posts/
  - https://www.ververica.com/blog
- Meetups, conferences
  - https://www.flink-forward.org
  - https://www.meetup.com/topics/apache-flink/

Stream Processing with Apache Flink: Fundamentals, Implementation, and Operation of Streaming Applications

英語版 Fabian Hueske (著), Vasiliki Kalavri (著)

Amazon.co.jpで詳細を見る

読書メモ: Web配信の技術―HTTPキャッシュ・リバースプロキシ・CDNを活用する

Kosei Moriyama — Tue, 21 May 2024 20:30:00 +0900

Web配信の技術―HTTPキャッシュ・リバースプロキシ・CDNを活用する

田中祥平 (著)

Amazon.co.jpで詳細を見る

Cache-Control ヘッダから始まり、クライアント (ブラウザ) のローカルのキャッシュから CDN まで、Web システムの「配信」の最適化技術を網羅的に解説してくれている本。

業務の必要に応じて、CDN など個別のソリューション (の必要な一部の機能) は使ったことがあったり、Cache-Control の一部のディレクティブは都度調べて指定したことはあった。こうした「配信」に関する知識は各論の寄せ集めになっていて、体系的に理解できていないなという実感が以前からあった。また例えば HTTP のヘッダの仕様は歴史的経緯もあり複雑で、RFC から追おうと思っても必要な文章が複数あったり、実際の世の中の実装にばらつきがあったりと、キャッチアップコストが高い知識も多い。こうした領域を一冊でカバーしてくれている、稀有な本だった。「配信」はすべての Web システムが多かれ少なかれ必ず行っているので、ニッチな知識ではなく、活用できる場面も多いと思う。

自分の現在の業務を鑑みる。今はモバイルアプリのバックエンド開発が主務で、クライアントはブラウザではなくネイティブアプリ。それは HTTP クライアントライブラリを使ってサーバと通信している。そのため Cache-Control ヘッダ等の知識がすぐにそのまま使えるわけではない。ただベースラインとして標準技術を把握しておくことは重要だと思う。最近、データ転送量削減のため、動画ファイル等サイズが大きいコンテンツをクライアント側で独自にローカルキャッシュする対策が行われた。これを標準技術にあてはめると、TTL をほぼ無限に、キャッシュキーは URL のみ、キャッシュストレージは LRU、更新は実質的に Cache Busting、stale-while-revalidate/stale-if-error などは未実装でエッジケースで問題が出るかどうかは要検証、といった具合に理解を整理できる。

以降は読書メモ。

1. はじめに

定義
- 配信: Web において主に HTTP でコンテンツをサーバからクライアントに届けること
- 配信最適化: 配信をより高速・安定・安全にすること
- 配信システム: Proxy や CDN などの技術を組み合わせたシステム
配信最適化は実施コストに対して費用削減、UX 改善のベネフィットが大きく、中小規模システムでも取り組む価値がある
サービスダウン、情報漏洩といった事故につながるリスクがあり、正しい知識が必要
基本的な構成
- オリジン
- キャッシュレイヤー (Proxy, CDN)
- クライアント

2. 配信の基礎

基本的な考え方
- 最適化の目標
  - 共通
    - クライアントがコンテンツを高速にダウンロードできる
    - 突発的なリクエストに耐える
    - 低コストで実現する
  - 個別
    - 低遅延など
- 標準化されたプロトコル + 要件に応じた個別実装という視点を持つ
  - よってプロトコルをまずは押さえる。その実装状況も把握する
  - bandwidth, throughput, latency などの指標を理解する
- 配信経路を理解する
  - ファースト|ミドル|ラストマイル、DNS、ISP や IX など
    - なお本書では実施が容易なものを扱うので、例えば ISP との直接接続といったトピックは対象外
  - そうすると、ボトルネックがどこか・ある技術はどこを最適化するのかといった見通しが立つ
    - 例えば 5G はラストマイルを高速化する
最適化の方針
- 各所でのキャッシュ
- その他: コンテンツの圧縮やオリジンの増強
キャッシュの分類
- 格納場所による分類
  - クライアント (ローカルキャッシュ)
  - 経路上 (CDN, Proxy)
  - オリジン (ゲートウェイキャッシュ)
    - 一般化すると CDN, Proxy と近いが、実運用で細かい差異があるため、別トピックとして本書では扱う
- 性質による分類
  - private
  - shared
    - 文献によっては格納場所による分類を private/shared と呼ぶこともあるので注意。例えばローカルキャッシュは private、CDN は shared といった具合
Topics: EDNS Client Subnet (ECS)
- CDN は名前解決リクエストを送信した ISP の IP に応じて位置的に近いエッジの IP を返している
- もし Google Public DNS のような DNS キャッシュサービスを使うと、ナイーブには CDN が最適化できない
- ECS は DNS 問い合わせ時にクライアントの IP アドレスの一部を添えて送信する。この情報をもとに CDN が最適化した IP を返す
- Quad9 などプライバシー対策として ECS に対応していない DNS もある

3. HTTPヘッダ・設定とコンテンツの見直し

CDN 導入やサーバ増強以前にやるべき細かい改善
総転送量 = リクエスト数 x 平均コンテンツサイズ
- 前者は標準にのっとったヘッダ設定でローカルキャッシュを適切に効かせる
- 後者はコンテンツ自体の適切な圧縮やリサイズを行う
ローカルキャッシュ
- RFC 7234 - Hypertext Transfer Protocol (HTTP/1.1): Caching には次のように、クライアントはデフォルトでキャッシュし、それを防ぎたい (あるいは伸ばすなど制御したい) 場合は Cache-Control 等のヘッダを適切に設定するよう記述されている。実装によるがこの原則で様々なクライアントは動作する
  - > Although caching is an entirely OPTIONAL feature of HTTP, it can be assumed that reusing a cached response is desirable and that such reuse is the default behavior when no requirement or local configuration prevents it.

HTTP キャッシュ仕様

キャッシュをする条件 RFC7234#3 とキャッシュを利用する条件 RFC7234#4
デフォルトでキャッシュ可能なメソッド RFC7231#4.2.3
- GET, HEAD, POST
- 実態として POST がキャッシュされることは少ない
デフォルトでキャッシュ可能なステータスコード RFC7231#6.1
- 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501
- 421 (RFC7540#9.1.2), 451 (RFC7725#3)

Cache-control (RFC7234, RFC9111)

[memo] 本書は RFC7234 ベースで記述されている。当時ドラフトだった RFC9111 は現在は発行済で、曖昧だった部分が明確化されている。

保存方法の指定 (未指定, public, private) RFC7234#5.2.2.5, RFC7234#5.2.2.6

複数クライアントで共有できる shared キャッシュか、そうではない private キャッシュかの指定だが、通常キャッシュができないケース (例えばキャッシュできないステータスコード) でもキャッシュをするという強い指定だという点に注意する
通常の shared キャッシュをしたいだけなら未指定でよい。public は一部の CDN の仕様に合わせる場合や、未認証でも見られるコンテンツに Authorization ヘッダが付いてしまい強制的にキャッシュさせたい場合など、限られたケースでしか必要ない。private は private キャッシュ利用の際に必要だが、あらためて通常キャッシュできないケースでもキャッシュされてしまうことに注意する

指定	キャッシュ許可の対象	クライアントとの対応	経路上への格納	ローカルへの格納	通常キャッシュできないパターンもキャッシュ
未指定	複数クライアント (shared) に許可	1:n	YES	YES	NO
public	複数クライアント (shared) に許可	1:n	YES	YES	YES
private	特定のクライアントのみ (private) 許可	1:1	NO	YES	YES

no-store (RFC7234#5.2.2.3) と no-cache (RFC7234#5.2.2.2)
- 前者はキャッシュ格納時、後者はキャッシュ利用時に評価される
- no-store が指定されていると、キャッシュは保存されない
  - 全くキャッシュさせないというユースケースには、仕様上 no-store 指定だけで良いことになるが、実装上走でないケースがあり、後述される
- no-cache が指定されていると、格納されているキャッシュを利用してよいか、オリジンに条件付きリクエストで問い合わせを行う。最新であれば (302 が返れば) キャッシュから、そうでなければ (200 が返れば) 新たに取得したコンテンツを使う
キャッシュの再利用 must-revalidate (RFC7234#5.2.2.1), proxy-revalidate (RFC7234#5.2.2.7), immutable (RFC8246)
- must-revalidate は有効期限切れ時に再検証を行う
  - 対して no-cache は毎回検証を行う
  - must-revalidate は max-age と共存できる
  - 期限切れ後にオリジンがダウンしている場合、must-revalidate が指定されていると検証失敗でキャッシュは使われない。指定がない場合はキャッシュが使われる
- proxy-revalidate は private キャッシュに適用されない以外は must-revalidate と同じ
- immutable はコンテンツが不変であると認識し、再検証は一切行われなくなる。更新したい場合は URL を変更する必要がある。慎重な取り扱いが求められる
no-transform (RFC7234#5.2.2.4)
- proxy などの中間でオブジェクトに対して変更、通信量削減を目的として圧縮等、を許可しない
期限
- キャッシュの状態遷移
  - Fresh: 有効期限内, Stale: 期限切れだが条件付きで再利用可能
  - Stale なキャッシュは検証に成功すれば Fresh に移行する
- max-age
  - オリジンがレスポンスを生成した時刻を起点とした相対的なキャッシュの期限
  - 起点となる時刻はクライアントがリクエストを行った時刻とする (RFC7234#4.2.3)
    - Date ヘッダもあるが、クライアントとオリジンの時刻が同期されているとは限らないため
  - CDN 等の中間キャッシュからの取得の場合、Age ヘッダも考慮される。Age は中間に格納されてからの経過時間を示す。クライアントは max-age - age を fresh な時間として扱う
- s-maxage (RFC7234#5.2.2.9)
  - 経路上の CDN, proxy などにだけ有効なキャッシュ
  - 通常のユースケースでは s-maxage <= max-age となるのがほとんどのはず
    - 逆だと、CDN で max-age 以上経過したコンテンツは、その後クライアントキャッシュが常に stale になる
- stale-while-revalidate (RFC5861)
  - stale キャッシュの再検証をバックグランドで行っている間、何秒まで stale キャッシュを使ってもいいかという指定
- stale-if-error (RFC5861)
  - stale キャッシュの再検証がダウンなどで失敗した場合、何秒まで stale キャッシュを使ってもいいかという指定
- Expires
  - キャッシュの有効期限の絶対時間
  - max-age を解さない古いクライアント向けで、基本的には max-age を使うべき。両方指定があれば max-age が優先される
- Date, Last-Modified
  - max-age などを指定していない場合、ブラウザがデフォルトでキャッシュを行うことがある
  - その際の TTL は TTL = Date - Last-Modified / ブラウザ実装による定数 (10 が一般的) となる
    - 例えば 10 日間更新のないコンテンツは 1 日キャッシュする

条件付きリクエスト
- 検証子
  - Last-Modified: 最終更新日時
  - ETag: エンティティタグ (フィンガープリント)
- If-Modified-Since (RFC7232#3.3)
  - Last-Modified 以降に更新があればコンテンツを送る、そうでなければ 304
- If-None-Match (RFC7232#3.2)
  - ETag が一致すれば 304、そうでなければコンテンツを送る
- その他にも If-Unmodified-Since, If-Match, If-Range などがある
- サーバは 304 を返す際も 200 のときと同じヘッダをきちんと検討して返さないと事故につながる
  - Cache-Control, Content-Location, Date, ETag, Expires, Vary
  - 例えばオリジンは 200 で no-cache を返しており、CDN は 200 の場合は max-age=3600 で上書きしているというケース
    - CDN からは毎回条件付きリクエストで検証してほしいという意図
    - このときオリジンが 304 を返すと、CDN は (200 でないので) Cache-Control を上書きしない
    - 結果としてクライアントは no-cache としてキャッシュを取り扱い、クライアントから毎回検証リクエストが行われてしまう
Vary ヘッダ (RFC7234#4.1)
- クライアントがこのヘッダの値をキャッシュ時のセカンダリーキーとして使う
  - 例えば Accept-encoding が指定されると、クライアントは URL と圧縮方式ごとにキャッシュを持つ
実践時のテクニック
- Cache-controlが指定されているかの確認
- ETag がコンテンツの更新がなくても変わるケース
  - Apache が inode ペースで ETag を生成しており、LB 配下に複数のサーバがある場合は、同じコンテンツでもオリジンのサーバによって ETag が変わる
- ヘッダクレンジング
  - 稼働中のシステムを最適化する場合、ヘッダ設定箇所をすべて把握するのは簡単ではない
  - まずはゲートウェイで一括書き換えを行うのがスタートポイントとして良い

コンテンツ圧縮

アプリケーションサーバでやるのがおすすめ
- そこまで CPU リソースは使わず、Proxy などよりアプリケーションサーバの方がスケールアウトしやすいことが多いため
S3, GCS 等はデフォルトで圧縮してくれるような機能はないため自身で設定する必要がある
最適化済みの画像や動画は圧縮効果が低いので外す
本画像とサムネイルでサイズを分ける

画像フォーマット

フォーマット	圧縮	透過	アニメ	サポートブラウザ
jpeg	非可逆	なし	なし	主要ブラウザ全て
png	可逆	あり	なし	主要ブラウザ全て
gif	可逆	あり	あり	主要ブラウザ全て
webp	可逆/非可逆	あり	あり	主要ブラウザすべて (一定のOSバージョンが必要)
avif	可逆/非可逆	あり	あり	Chrome

png
- bpp: 8bit, 24bit, 32biy (24bit+alpha)
jpeg
- q値でクオリティの変更
- SSIM でクオリティの数値化
- ベースラインとプログレッシブ
webp
- 一般的に圧縮率は高いが、古いフォーマットのほうがカバレッジは高い
ちょっとした動画でも gif や apng より mp4 など専用フォーマットの方が効率的な場合は多い

Topics: HTTP/2 misc
- ヘッダが小文字になる
  - Cache-Control と cache-control など
  - HTTP/1.1 以前は case-insensitive だったが、サーバ実装によっては大文字小文字を区別してしまっているケースがあるので注意
- 開始行は存在せず、疑似ヘッダからメッセージが始まる # リクエスト例 :method: GET # 以下4行が疑似ヘッダ :scheme: https :path: / :authority: example.com foo: bar # レスポンス例 :status: 200
Topics: リクエスト時の Cache-control
- Cache-Control: max-age=0 などと、指定された秒数を超えるキャッシュは受け付けないというリクエストを送信することができる。実勢に Chrome のリロードではこのヘッダが付与される
- 実態としては経路上のキャッシュはこうしたリクエストの指示を無視する
- ローカルキャッシュには有効で、例えば XHR を使う際にキャッシュを使わないよう no-cache を指定することなどがある
- Cache-Control - HTTP | MDN
Topics: 中間でのデータ変更
- Chrome の Data saver 機能や通信キャリアによる通信最適化によって、中間でコンテンツが変更されることがある
- 変更を防ぐには、根本的には HTTPS 通信を行うことが必要だが、それが難しい場合は Cache-Control: no-transform を指定することで変更を禁止できる
- ただし中間 proxy によっては no-transform を無視することがある
Topics: キャッシュをさせたくない場合の厳密な指定
- Cache-Control: private, no-store, no-cache, must-revalidate
- 経路上のキャッシュを防ぎ、保存の不許可、利用の不許可、オリジンダウン時の再利用を防ぐための must-revalidate
- Last-Modified をなくすことで TTL 未指定の挙動を排除でき、より厳密になる
Topics: RFC 9205 also known as BCP 56
- HTTP を使う上でのベストプラクティスで RFC3205の置き換え
- 本書執筆時点では策定中だったが現在はRFC9205となっている
- RFC7230-7235など HTTP の仕様が長大になっているので BCP をまず読むのがリーズナブル

4. キャッシュによる負荷対策

最も致命的な事故は、キャッシュが混ざることによる情報漏洩。中間の CDN, Proxy 視点からの、対策の基本的な考え方

適切なキャッシュキーの設定とキャッシュ対象の精査

キャッシュ	ユーザー情報	最低限設定すべきキャッシュキー	オリジンへのリクエストヘッダ	クライアントへのレスポンスヘッダ
する	含む	ホスト名 + パス + ユーザー情報	そのまま	Set-cookie 削除
する	含まない	ホスト名 + パス	Cookie, Authorization 削除	Set-cookie 削除
しない	含む	na	そのまま	そのまま
しない	含まない	na	そのまま	そのまま

Cookie, Authorization 以外にも、ACL 判定結果 (特定の IP 帯のみ許可するケースなど)、端末種別、CORS の Origin ヘッダ、URL スキーム、リクエストメソッドなども注意する

オリジンを信用しない
- 常に適切な実装 (Cache-control ヘッダ等) はされていないと前提する
- 中間キャッシュ側でコントロールする
Allowlist
- 「デフォルトはすべてキャッシュ」ではなく、キャッシュ対象を Allowlist で明示する

キャッシュキーとセカンダリキー (Vary ヘッダ)
- Vary レスポンスヘッダはキャッシュのセカンダリーキーを指定する。これは次のようにキャッシュキーの小分類としてセカンダリーキーを持つという理解に等しい
```
// Vary: Accept-Encoding の場合の概念データ構造
{
    "host + path": {
        "gzip": "content1",
        "none": "content2"
    }
}


// 仮に Accept-Encoding をキャッシュキーとした場合の概念データ構造
{
    "host + path + gzip": "content1",
    "host + path + none": "content2",
}
```
  - 各要素の出所で整理すると
  - キャッシュキー: クライアント (リクエストの host, path)
  - セカンダリキー
    - 指定: サーバ (レスポンスの Vary ヘッダ)
    - 値: クライアント (リクエストの Vary で指定されたヘッダ。Accept-Encoding 等)
  - キャッシュ箇所ごとの、キャッシュキーとセカンダリキーの挙動変更可能性で整理すると
  - 中間 (CDN, Proxy)
    - キャッシュキーを変更できる
    - セカンダリキーを Vary で変更できる
  - ローカルキャッシュ (ブラウザ等)
    - キャッシュキーは変更できず、原則 host + path でキャッシュされる
    - セカンダリキーを Vary で変更できる
  - 以上を踏まえて、host + path (+ method など) 以外の情報でレスポンスが変わるコンテンツの場合、Vary を指定しないとローカルキャッシュがうまく扱えない。反対に (各クライアント視点で) host + path でレスポンスが変わることが無ければキャッシュキーで問題ない
  - 例えば、pc/sp でコンテンツが切り替わるケース。pc/sp は user-agent で判定
    - 中間から見ると pc/sp 区別ごとにコンテンツが変わる
    - ローカルのクライアントから見ると、意図的でなければ pc/sp (user-agent) が変わることはない
    - よって中間で pc/sp の判定結果をキャッシュキーに持たせるといった対応でよい
  - 例えば CORS
    - リクエスト元の Origin ヘッダによってコンテンツが変わる (コンテンツが返されたり拒否されたりする)
    - 中間から見ると Origin によってコンテンツが変わるので、キャッシュキーかセカンダリキーのどちらかの対応が必須
    - ローカルから見ると、Origin はアクセス元によって変わるので、ローカルでも Origin ごとのキャッシュが必要。これが実現できるのは Vary を用いたセカンダリキーの指定のみ
TTL
- クライアントキャッシュの TTL の決め方
  - 短いところから徐々に伸ばしていくのが運用しやすい
  - クライアントのセッションの持続時間と間隔から決めていく
    - まずは平均のセッション継続時間キャッシュが保つように設定
    - 問題なければセッション間隔の時間から、次のセッションでもキャッシュが効くように伸ばす
  - 長時間のキャッシュが不可能な場合
    - 多少古いコンテンツが出ても良いなら短い max-age
    - そうでなければ no-cache
    - いずれも頻繁に条件付きリクエストで検証が行われる動きになる。つまりリクエスト数う自体はかわらなくても、リクエストボディの転送を抑えられる
- 中間キャッシュの TTL の決め方
  - 全体の rps から決めていく
    - 10rps なら数分のキャッシュでも効果が高い
  - ローカルキャッシュとのバランスを取る
    - 中間でキャッシュしすぎるとローカルキャッシュの残 TTL が減り、結果として中間で受ける総リクエストは増える
    - s-maxage を使いバランスを取る
- 通常は TTL = max-age - Age と考える。Expires では Expires - Date となるが、基本的には max-age の利用が推奨
- stale-while-revalidate の決め方
  - TTL (max-age) とあわせて考える。TTL の一部を stale-while-revalidate に割り当て、TTL はその分短くする
  - その他には、リクエストの頻度やコンテンツの生成にかかる時間を考慮して決める
- stale-if-error の決め方
  - あくまでエラー時の動作なので、TTL から割り当てるのではなく追加で指定する
- max-age=0 は「常に stale キャッシュを保存する」という意味になる。キャッシュさせたくない場合は前述の Cache-Control: private, no-store, no-cache, must-revalidate を使う
- エラーキャッシュ
  - バグなどで一時的にコンテンツが 404 になった場合、キャッシュされないとオリジンにリクエストが殺到してしまう
  - エラーキャッシュ・ネガティブキャッシュをするとこうした事態を緩和できる
  - ただしエラーキャッシュの TTL が長すぎると復旧が遅れる
Invalidation
- 無効化と削除
  - 無効化
    - キャッシュを stale にする。stale キャッシュは使われないが、revalidate 中やエラー時には使われる、またキャッシュストアには暫く残る
  - 削除
    - 確実にキャッシュされたコンテンツを削除する
    - ほとんどは無効化で問題ないが、例えば著作権侵害コンテンツの削除など、削除が必要なユースケースもある
- 手法
  - cache busting
    - パスにタイムスタンプを含めるなど、キャッシュキー事態を更新ごとに変える
    - 多くのケースで必要十分な方法
    - 無効化に属する
  - cdn の機能での削除
    - 無効化なのか削除なのかは確認する
    - 最近は各社高速化されたが、コンピューティングリソース的には重いオペレーションで課金対象であることも多い。削除に依存した運用設計よりも、TTL をうまく調整することでコントロールできるならそのほうが良い
- 削除時はオリジンへのリクエスト急増に注意する
  - 上流 (オリジン側) から順に削除していく。上段の中間キャッシュが更新されてから下段のキャッシュを削除するなど
  - 一度に複数コンテンツを削除するのではなく、削除タイミングをばらけさせる
Topics: POST リクエストのキャッシュ
- 考慮事項が多く基本的には推奨されない
- キャッシュする場合の注意点
  - キャッシュキーを注意深く選択することは GET と同じ
  - リクエストボディの取り扱い
    - application/x-www-form-urlencoded、multipart/form-data などパースが (中間では) 容易でなかったりサイズが大きくなりがち
    - 中間ではリクエストボディは無視する、ボディのハッシュ値をキーとする、application/x-www-form-urlencoded の時のみクエリ文字列と同等の扱いでキーとする、といった対応を行う
    - 一定のボディサイズ以上はキャッシュしない
  - multipart/formdata のリクエストはブラウザによって形式が違うので「リクエストボディは無視する」の対応しかできない
  - 100-continue を利用した分割リクエストはキャッシュできないので、そのようなクライアント実装を避ける
    - 100-continue はリクエストボディを送信する前にヘッダだけを送信し、サーバが受け入れ可能かどうかを確認するための仕組み
    - 例えば AWS ELB は 100-continue を受け取ると即座に 100 Continue を返すため、オリジンでは検知できない
Topics: キャッシュフレンドリなパス設計
- /cache/user のようにパス自体にキャッシュキーが何かという情報を含めてしまうとわかりやすい
  - 中間では /cache/user のリクエストは、例えばクッキーから user_id を取得してキャッシュキーに入れるといった実装をする
  - オリジンはその前提で実装する。この知識がパスから明確にわかるのが利点

5. より効果的・大規模な配信とキャッシュ

メトリクス
- キャッシュヒット率が導出しやすく使いやすい指標
  - ただし次のようなケースはヒット率だけを追うと隠されてしまう
    - 全ユーザー共通の静的画像とユーザーごとの動的画像
    - 単純な実装だと当然前者のキャッシュヒット率が高い
    - 後者はよりオリジンの CPU リソースを使うので、ヒット率に寄らずケアすることでシステム全体の安定性を増すことができる可能性がある
Proxy/CDN システムの抽象化
- p210 図5.1 Proxy/CDNの基本的な処理フローより引用
- コンポーネント
  - Client Trx, Origin Trx と、対クライアントと対オリジンでトランザクション (プロセスくらいのイメージで良い) が分かれており、それぞれ非同期に動作する。非同期な関係の代表例が stale-while-revalidate
- 処理ステップ
  - 以下のステップに分かれている。Rx*, Tx* はそれぞれフックポイントのようなもので、個別の処理を記述できる
  - Receiver Request (RxReq)
    - フックしてACL 処理、キャッシュキー操作、セカンダリキー操作、Cookie 削除、クエリソートなど
  - Cache lookup
  - Wait for cache
    - フックポイントではない
    - 一定時間待機することで、キャッシュがない場合の同時リクエストが複数オリジンに飛ぶことを防いでいる
    - 一方で、キャッシュしないリクエストが誤ってこのフローに入ると、不要な wait が生じるため注意する
  - Transmitter Request (TxReq)
    - フックして複数オリジンがある場合の選択、キャッシュキーに影響を与えないオリジン問い合わせのホスト名・パス名変更など
  - Receiver Response (RxResp)
    - フックしてカスタムした TTL の設定、キャッシュ前に Set-Cookie を削除するなどキャッシュするオブジェクトの操作、Vary ヘッダの変更など
  - Transmitter Response (TxResp)
    - CORS などキャッシュは変わらないがクライアントごとにヘッダを変える場合の対応、内部用の不要ヘッダの削除など
  - [memo] これらのフックを組み合わせて、例えばヘッダをパース・カスタムの Vary ヘッダ生成といった、それなりに複雑な処理を実装する例が挙げられているが、第一印象としては認知負荷の高さが気になった。やむを得ないケースを除き、どの程度の処理をどのレイヤーで行うのが妥当なのかの基準があれば知りたい。一方で組織の境界やシステムの境界から、こうした処理を中間側で行った方がベターなケースも容易に想定できる
同一 URL で複数種類のキャッシュがあるケースの対応方法比較
- キャッシュキーを変える (パスに pc/sp と入れるなど)
  - 素直に単に URL を指定してもキャッシュ削除ができず、工夫が必要
- Vary でセカンダリキーを指定する (Vary に x-device を入れるなど)
  - RxReq + RxResp + TxResp にてフックの実装が必要
  - 中間で追加したヘッダがオリジンに渡る
  - クライアントにも Vary ヘッダが渡る
- クエリパラメータを追加する (URL に ?device=pc など)
  - 中間で追加したパラメータがオリジンに渡る
  - 削除時にクエリパラメータの指定も必要。パラメータのカーディナリティが高い場合は注意
キャッシュの効率化
- クエリパラメータの正規化、ソート、不要削除
- セカンダリキーの正規化
  - 例えば Accept-encoding について、サーバが対応しているのは gzip のみの場合、そのままではなく gzip 値の有無をセカンダリキーにする
- キャッシュ対象の優先度付け
  - 平均レスポンスタイム x 一定期間でのリクエスト数が高いものを優先する
動的コンテンツ
- 定義
  - TTL を概ね1時間以上にできる、またはTTL を明確に定められるものは静的
  - 動的コンテンツは TTL が要件上決めづらい、あるいはそもそもキャッシュができないため難しい
- キャッシュの難しさの分類
  - コンテンツが個別のライフサイクルを持つサブコンテンツから構成されている
    - 分割してキャッシュする
      - ESI
      - クライアントスクリプトで実装
  - ユーザー単位など同一の URL でもステートフルな別の挙動をする
    - 同上
  - リクエストのたびに取得が必要だったり、極めて高いリアルタイム性が必要
    - キャッシュできないのはこのパターンだけ
  - API で動的生成するコンテンツの場合、検証リクエストへの対応が高コストになることが多い（ETag を生成しようにも、コンテンツ自体を普段通り組み立てないといけないなど）。そのため no-cache + 検証リクエストよりは、ごく短い TTL を設ける、CDN ではキャッシュし終端クライアントには no-cache を返すがオリジンには普通にリクエストする、といったアプローチの方が取りやすい
ESI https://www.w3.org/TR/esi-lang/
- 中間でコンテンツを結合しクライアントに返す
- 一般的に平均応答時間（TTFB）は短縮し、平均ダウンロード時間が伸びる動きになる
- アプリケーション側の変更が必要になる、各所での結合処理にかかるオーバーヘッドが発生するといったデメリットがある
- まずはヘッドとボディを分けるだけでも、ブラウザがヘッドにあるコンテンツを先にロードできてメリットがある
Topics: Vary ヘッダが自動付与されるケース
- 例えば Apache でオリジンへの直接アクセスを禁止するために Require expr %{HTTP_REFERER} == “foobar” と設定すると、Vary: referrer が自動で返される
- S3 で CORS の設定を行うと Allow origin などが含まれる Vary ヘッダが自動的に返される
Topics: ローカルキャッシュの削除
- 現実的な手法としては Cache Busting
- no-store で毎回検証リクエストをさせる方法もある
- 更新が少ない静的ファイルなどは前者、よりリアルタイム性の高いニュースフィードなどは後者が適切
Topics: 多段 Proxy
- 主に CDN を利用せず自前構築する際のノウハウ
- （オリジンへのリクエスト元を集約することで）キャッシュデータの整合性を保ちやすくする、可用性が高まる、全体としてのストレージ容量を（スケールアウト方向に）増やしやすいといったメリットがある
- 一方で TTL の取り扱いなど考慮点も増える
Topics: ドメイン分割の使い所
- HTTP/1 時代にあったブラウザのドメインごとの接続数上限を緩和するためのドメインシャーディングは、HTTP/2 以降で不要になった
- 一方でサービスの拡張しやすさのため静的・動的ファイルでドメインを分けておく（あとから CDN に載せやすい）、ZoneApex 問題対策といった場面でドメイン分割が有効なケースがある

6. CDN を活用する

CDN の特徴
- 「分散されたネットワーク品質の良いコンピューティングリソースのプラットフォーム」
- キャッシュは機能のうちの一部。キャッシュがなくても、例えば中間 - オリジン間の接続が使い回されることで、キャッシュミスの場合でも直接オリジンアクセスよりも速いこともある
- DDoS 対策や WAF などセキュリティ機能、エッジコンピューティング等
- 全面的に導入しなくても、地理的に遠いクライアントへの配信や突発的なトラフィック増加への対応などを賄う目的でも利用できる
選定のポイント
- 対応地域
  - 特に中国本土やロシア等の旧共産圏は対応の厚さや価格が異なるケースがある
- ピーク帯域
- キャッシュ制御の方法 (VCL, Lambda@Edge など)
- TLS 対応 (Pinning のケアなど)
- キャッシュ消去の方法、Apex ドメイン対応、多段構成が可能かなど
利用時に気をつけるポイント
- キャッシュされない設定を把握する
  - Cache-Control の解釈は各ベンダーで異なる。特にキャッシュしないケースは情報漏洩リスクにつながるため念入りに確認する
  - オリジンがダウンしている場合にキャッシュを返さないか、同着リクエストの際にキャッシュを返さないかといったエッジケースも確認すると良い
- クエリパラメータ、Vary ヘッダの解釈
- トラフィック (帯域幅) やコンテンツサイズの上限と超えた場合の挙動
- デバッグ機能
  - 独自のヘッダを付けることでデバッグ可能なベンダーもある
  - 本番ではオフにしないと、例えばオリジンの IP アドレスが漏れるなどのリスクがある
障害
- 分類
  - ファーストマイル（オリジン、CDN間）
  - ミドルマイル（CDN内）
  - エッジ自体
  - ラストマイル（エッジ、クライアント間）
- 切り分け
  - キャッシュされているオブジェクトのリクエストに失敗し、かつ別 ISP からのリクエストも失敗するならエッジ障害、別 ISP から成功ならラストマイル
  - キャッシュされていないオブジェクトのリクエストに失敗し、キャッシュされていると成功するならファーストマイルかミドルマイル
  - ファースト、ミドルの切り分けは単純化できない
    - ISP、リージョン、CDN 単位でのメトリクス確認、ステータスページ、SNS で他社障害の確認
- キャッシュ異常
  - TLS 通信にし経路上の不確定要素を排除
  - キャッシュとオリジンの比較
Topics: CPDoS
- Cache Poisoning Denial of Service
- CDN 上のキャッシュを汚染しサービスを利用できなくさせる手法
- 例えば許容できるヘッダサイズがオリジン < CDN だった場合に、大きなヘッダサイズのリクエストを送り、CDN 側にエラーレスポンスをキャッシュさせる
  - RFC 通りであれば 400 Bad Request はキャッシュされないが、キャッシュする CDN ベンダーの場合この攻撃が成立する
Topics: 動的コンテンツのキャッシュ
- キャッシュ戦略を適切に設計すれば問題ない
  - 静的コンテンツでも慎重に検討すべきなので、動的だから特別考え方が変わるわけではない
- キャッシュせず CDN を通すだけでもセキュリティなどメリットがある

7. 自作 CDN

必要性
- 超大規模サービスで自社構築の方がコストやカスタマイズ性にメリットがある
- CDN を契約する予算がなく費用を抑えたい小規模サービス
- ハイブリッド構成を取りたい場合
  - 静的コンテンツのオフロードのみ CDN を使う
  - 基本は自社配信を使い、突発的なトラフィックのみ CDN にオフロードする
  - コンテンツを一貫させるために CDN と自社配信の多段構成にする

Web配信の技術―HTTPキャッシュ・リバースプロキシ・CDNを活用する

田中祥平 (著)

Amazon.co.jpで詳細を見る

MySQL オンラインスキーマ変更ツールの spirit と gh-ost

Kosei Moriyama — Tue, 23 Jan 2024 20:30:00 +0900

MySQL のスキーマ変更は、データ量が大きくなると一般的に時間がかかり、その間の DML の実行にも影響が出る。このような状況でサービスを止めずにスキーマ変更をするためのツールとして github/gh-ost が有名だが、cashapp/spirit は gh-ost をベースにして Cash App チーム (旧 Square、現 Block, Inc.) のニーズに合わせて作られた新しい [1] オンラインスキーマ変更ツールだ。

[1] 紹介ブログ Introducing Spirit | Cash App Code Blog が書かれたのが 2023 年 9 月。

spirit の特徴

基本的なアプローチは gh-ost も spirit も同じだが、より大きなデータサイズ [2] のユースケースに対応した機能が追加されている

データコピーを並列に行う
- gh-ost は一並列のため、この規模のデータコピーには数週間という水準の時間がかかる
処理途中からの resume に対応
- 現代的なインフラはおおよそ k8s 上に構築されており、disposable な作りになっていた方が扱いやすい
- 前述のように数日程度では済まない長い時間がかかる。この規模になると中断後、最初から処理を再開するのはかなり運用負荷が高い
- この機能によりマイグレーション中だけ DB インスタンスをスケールアップしておき、一時中断して戻すなど柔軟な対応も可能になる

README にはベンチマークも記載されている。

Aurora v3 上の 10TB の finch.xfers テーブルのマイグレーションが 2.7 日で完了
- gh-ost だと 10 日でも完了せずキャンセルした
テーブルはアイドル状態だったので、実際のワークロードではより差が開くと予想される
- m1 mac 上でのマイクロベンチで比較
- finch.balances (800MB/1M rows), idle load では spirit は gh-ost の約 2 倍高速
- 同じテーブルでベンチマークツールでクエリを発行しながらマイグレーションしたところ、差は 8.5 倍まで広がった

[2] spirit は 10 TiB 規模のテーブルのマイグレーションを 5 日以内に完了させるのが性能の目安になっている。対して gh-ost や pt-ost は ~1TiB 程度の規模が想定されていて、かつそれでも 1 週間以上かかることもあるという水準らしい。

gh-ost の実装

gh-ost はおおまかに次の戦略でオンラインスキーマ変更を実現している。

gh-ost: GitHub's online schema migration tool for MySQL - The GitHub Blogから引用

セットアップ
- 対象のテーブルと同じ定義のテーブルを CREATE TABLE … LIKE … 文で作成し、後者に ALTER を適用する
- gh-ost では後者を ghost table と呼んでいる
データコピー
- 元テーブルのデータを ghost デーブルにコピーする
- この時 gh-ost は binlog を購読し、ghost テーブルが最新の状態に常に（極力小さいラグで）追従するようにしている
カットオーバー
- ghost テーブルと元テーブルを RENAME TABLE 文で入れ替える

主要な処理はコントローラー的役割の logic.Migrator.Migrate から順に呼び出されている。コードリーディングはここから始めると良い。

データコピー

データコピーは logic.Migrator と logic.Applyer クラスが主に担当する
INSERT IGNORE INTO … SELECT … 文で元テーブルから ghost テーブルへデータを移していく
- コピーはチャンクという単位で処理されていくが、チャンクの大きさは固定値
同時に自身をレプリカとして登録し binlog を購読する
- binlog を購読するのは logic.EventStreamer
- EventStreamer にイベントリスナーを登録する。リスナーは binlog の DML イベントを applyEventsQueue に登録する
- 定期的にキューからイベントを取り出し、変更を ghost テーブルに適用していく

EventStreamer が実際に binlog を読み込む部分は go-mysql-org/go-mysql の replication パッケージを利用している。

レプリケーション、binlog の購読、MySQL のクライアント、サーバーのプロトコル解釈など、MySQL 周辺ツールを作るのに便利でコアなツールが揃っている
いずれも Pure Go 実装
もともとは現 PingCap VPoE のエンジニアによって開発されたライブラリの模様
gh-ost は replication を使っているが、spirit はこれよりもさらにハイレベルのインタフェースを提供する canal を利用している
- それぞれのツールは別言語に参考元と思われるものがある
  - alibaba/canal: 阿里巴巴 MySQL binlog 增量订阅&消费组件
  - julien-duponchelle/python-mysql-replication: Pure Python Implementation of MySQL replication protocol build on top of PyMYSQL

カットオーバー

ghost テーブルが元テーブルに追いついたら、両テーブルの切り替えを行う。この作業をカットオーバーと呼ぶ。

gh-ost がそれ以前のツールよりも優れているのは、binlog 購読によるキャッチアップがトリガーなどによる実装に比べて高速低コストにできることで、そのおかげでカットオーバー時のロック取得が短時間で済むことだと思われる。

gh-ost のカットオーバーは次のように少々複雑な手順を踏む。

元テーブルと swap 用の一時テーブル (名前は 元テーブル_old) にロックをかける
- LOCK TABLE 元テーブル WRITE, 元テーブル_old WRITE
binlog 購読バッファをフラッシュし、ghost テーブルが元テーブルに追いついたことを確認する
テーブルのリネームを行う
- RENAME TABLE 元テーブル TO 元テーブル_old, ghost テーブル TO 元テーブル
- この時点では RENAME 処理はロックでブロックされている。ただしロック中に発行された INSERT などの DML よりも高い優先度になっている
processlist に RENAME TABLE が出てくることを確認する
元テーブル_old を DROP する
- この時点ではロックでブロッキングされている
最後にロックを開放する
- まず RENAME が実行される。ロック中に発行され待たされていた DML はその後リネーム後のテーブルに対して実行される

詳細は次の issue にドキュメント化されている。Describing safe, blocking, atomic, pure-mysql cut-over phase · Issue #82 · github/gh-ost

これは MySQL 8.0.13 以前はテーブルロック中にリネームができなかったことに起因している。MySQL 8.0.13 以降はこの制約がないので、ロック・リネーム・アンロックというシンプルなフローで良くなるが、gh-ost は古い MySQL バージョンをサポートしているのでまだ実装されていない。

MySQL :: MySQL 8.0 Reference Manual :: 13.1.36 RENAME TABLE Statement

As of MySQL 8.0.13, you can rename tables locked with a LOCK TABLES statement, provided that they are locked with a WRITE lock or are the product of renaming WRITE-locked tables from earlier steps in a multiple-table rename operation.

なお以前はリネームのステップが (1) 元テーブルを一時テーブルにリネーム (2) ghostテーブルを元テーブルにリネームと 2 ステップに分かれていたらしい [3]。(1) と (2) の間に何らかの理由でロックを取っていたセッションが死ぬと、元テーブルがなくなった状態になってしまい事故となる。現行アルゴリズムはリネームがアトミックに行われるのでこの懸念はない。またこの点に限らず、フローのどの時点でクラッシュしても、データ一貫性が壊れる事故は起きなくなっている。

[3] Describing safe, blocking, pure-mysql cut-over phase · Issue #65 · github/gh-ost

spirit の実装

基本的なアプローチは gh-ost と同じで、実装もセットアップ、データコピー、カットオーバーの流れでされている。ただし以下のアイデアがデータコピーの実装に追加されている。

並列化によるデータコピーの短縮
データコピーの途中再開

また MySQL 8 以降を原則サポート対象としていたり、gh-ost にある細かなオプションの対応が省かれていることで、コア部分以外のコード量が少なくすっきりしている。全体的にドキュメントも充実している。もしスキーマ変更ツールの実装を読んでみたい人がいれば、先に spirit から読むと理解しやすいと思う。

migration.Runner.Run がコントローラー的なメソッドで、ここから順に追っていくと良い。また ghost テーブルは spirit では New Table と呼ばれている。

データコピー

spirit では row.Copier クラスが担当する。

Chunker が元テーブル全体をいくつかのチャンクに分割する
- チャンクサイズは処理時間に応じて動的に変更している
Copier が複数のスレッドを起動し、それぞれに担当するチャンクを割り当てる
- INSERT IGNORE INTO … SELECT … FORCE INDEX (PRIMARY) WHERE … で元テーブルから New テーブルにコピーする
- このときの WHERE 句は Chunker (Chunk オブジェクト) が生成する
- コピー完了後は watermark を更新する
  - どこまでのコピーが済んだのかの記録
同時に binlog の購読も開始する
- repl.Client が担当するが、後述のようにコアな実装は go-mysql/canal に移譲している
  - repl.Client 自体を canal にイベントハンドラの実装として登録、binlog イベントがバッファに貯められ、定期的にフラッシュされる
- 以下の最適化を行っている
  - binlog イベント到着時、watermark を確認し、コピー済みのレコードのみ更新する
    - 未コピーのレコードは今後 copier スレッドがその時の最新状態をコピーしてくれるので、binlog のイベントは無視して良い
  - binlog イベントを PK ごとのバッファにまとめ、重複排除をしている
    - binlogChangeset という map[string]bool という型の map で string が PK に、bool が delete か否か を表している
      - 更新内容は保持しておらず、あくまで更新や削除があった PK のみを記録している
    - binlog イベント受信時、INSERT, UPDATE なら false で、DELETE なら true でその PK のエントリを map に追加している
    - フラッシュ時には delete の場合は DELETE 文を、そうでなければ REPLACE 文で、元テーブルのデータで新テーブルの該当レコードを置き換えしている
      - その時の最新情報を元テーブルから取得しているので、そのため個別の binlog イベント内容は無視できる
    - 加えて反映クエリを並列実行し高速化を図っている
進捗状況は checkpoint テーブルに保存される
- watermark や binlog の読み取り位置を定期的にこのテーブルに記録している
- resume する場合はセットアップ時にこのテーブルをチェックし、存在すれば進捗状況を読み取って処理を再開する
replication lag を監視し、大きくなった場合はデータコピー処理をスロットリングする
- performance_schema.replication_applier_status_by_worker を見ている
- 似た機構は gh-ost にもある

binlog の購読は gh-ost 同様 go-mysql-org/go-mysql を利用している。ただし replication ではなく canal というよりハイレベルなライブラリを使っている。

canal はある MySQL サーバーの変更を別のデータスストアに反映させるために使うことができる、汎用的なツール
- 例えば MySQL から elasticsearch へのデータ同期といったユースケースの実装に有用
- binlog イベントを受け取った際にやりたい処理をイベントハンドラとして登録するだけで、簡単に使える

カットオーバー

デフォルトでは MySQL 8 をサポート対象としているので、gh-ost に比べシンプルでストレートな実装になっている。

migration.Cutover が担当する
元テーブルのロック、binlog バッファのフラッシュをしたあと、RENAME TABLE 元テーブル TO _元テーブル_old, 新テーブル TO 元テーブルで入れ替える

フォールバックとして gh-ost と同様のアルゴリズムも実装されている。

ALGORITHM=INSTANT の試行

spirit にも gh-ost にも、処理に入る前にまずは ALGORITHM=INSTANT でのスキーマ変更ができないかチェックする仕組みが入っている。

MySQL 8 から導入された ALGORITHM=INSTANT は、メタデータの更新だけで ALTER 文が完了するため、非常に高速。ただし全てのスキーマ変更操作で可能なわけではなく制約がある。

spirit も gh-ost も、重くリスクの高い作業を開始する前に ALGORITHM=INSTANT を試みるのは理にかなっている。またこの機能は spirit 側から gh-ost に提案・移植してくれたらしい。

PR

Efficient MySQL Performance (English Edition)

英語版 Daniel Nichter (著) 形式: Kindle版

Amazon.co.jpで詳細を見る

最近読んだもの 59 - DB 動向年間レビュー、各社のシャーディング事例など

Kosei Moriyama — Tue, 09 Jan 2024 20:30:00 +0900

Databases in 2023: A Year in Review | OtterTune
- Andy Pavlo (CMU, OtterTune) による毎年恒例の DB 業界動向年間レビュー
- LLMs による Vector Databases の隆盛 (専用の DB ではなく、既存 DBMS の機能としての提供も追いついてきそう)
- 新標準 SQL:2023、目玉はグラフ構造へのクエリと、多次元配列のサポート。いずれも実装はまだほぼ無し
- MariaDB (会社側) のごたごた
- NOTAM というシステムの障害でアメリカ国内線が不通に。80年代に作られたままの、RDBMS を使っていない、おそらく CSV か何かを編集するような自家製 DBMS らしい
- などなど。相変わらず技術面からファイナンス含めた企業の隆盛までカバーしており面白い
Big Data and Beyond: My Predictions for 2024 - me.0xffff.me
- PingCap (TiDB) 共同創業者, CTO の Ed による年頭所感
- 大規模データでのパフォーマンスのスケーリング問題はほぼ解かれ、次はコスト最適化に主眼が置かれる
- TiDB をはじめ Spanner や Vitess が取り組んできたスケーリングという課題は問いとしては解かれている。大量のデータでのパフォーマンスや可能性の問題が無いとすると、次に目が向くのがコストの最適化になる。通常すべてのデータが等しく使われるわけでは無いので、ホットデータもコールドデータも等しくリソースをかけてサーブするのはナンセンス。前者によりリソースを集中させ、後者は安価に保持する
- ベクターサーチをはじめより多様なインタフェースに対応する
- データベースのカーネル機能によりクラウドネイティブな作りが求められる
- オブザーバビリティ、多様な認証、エッジからの直接アクセスなど
The growing pains of database architecture | Figma Blog
- Figma の PostgreSQL シャーディング事例
- まずシャーディング開始前時点で接続多重化プロキシ (PgBouncer) の導入までは済んでいた
- その上でまずは垂直分割(テーブルを別インスタンスに分ける。一つのデーブルが複数インスタンスにまたがることはない) から実施した
  - 水平分割よりもアプリケーションの変更量や運用懸念が少なく、また負荷分散への一定の効果が見込め、さらに将来の水平分割を妨げないため
- 分割計画
  - テーブルごとのインパクト（DBにかける負荷）と独立性（他のテーブルとの関連度）を定量化して分割方法と順序を決める
  - 前者は pg_stat_activityというクエリごとの平均セッション数を集計
  - 後者は ActiveRecord のフックで、発行したクエリとその発行元をデータレイク（SnowFlake）に送り集計
- Cut Over は独自ツールで無停止切り替えを達成
- まずアプリケーションをテーブルごとに適切な接続先に切り替えられるよう変更
  - デグレのリスクを下げるため、実際に DB を分ける前に、PgBouncer だけを分割しておき、接続先が間違っているとエラーになるようにした
- 分割先 DB にテーブルをコピーしレプリケーションする
  - テラバイト級のデータコピーには時間がかかるが、一旦インデックスなしでデータを移動させ、後からインデックスを追加する高速化をした
- ここまで準備ができるといよいよカットオーバーを行う
  - 旧テーブルへのクエリを短時間止め、新テーブルがキャッチアップしたことを最終確認し、新 DB を primary にプロモートし、クエリ先を新テーブルに切り替える
  - キャッチアップの確認は LSNsで行う
  - 新 DB をプロモートする際、逆向きのレプリケーションを設定し、切り戻しができるようにする
- 50 回の分割作業を行い、カットオーバー時の停止時間は 30 秒程度、その間のリクエストエラー率は高々 2%、最も大きいシャードの CPU 使用率は 10% 程度になった
You Broke Reddit: The Pi-Day Outage
- RedditのPi day (³⁄₁₄) に起こった障害の振り返り
- k8s のバージョンで発生。直接の原因は master という語が廃止され control plane に置き換わったこと
- 遠因として、独自構築された知識がよく共有できていないクラスタだったということ。より一般化すると、社内で使われる技術、環境がばらばらで標準化されていないこと
- 少なくともマネージドでできるだけデフォルトパラメータで運用するように心がけようと個人的には思った
- またバックアップからの復旧を試みるなど、障害対応の緊張感が伝わる
A CAP tradeoff in the wild - decomposition ∘ al
- k8s のとある issue が典型的な CAP 定理のトレードオフに該当するという話
- あるホストA, B の状態が何らかの理由で同期されていない場合、A, B からの応答は「レイテンシを重視して間違っていても即座に返す」か「一貫性を重視して同期が取られるまで待つ（ただし無限に取られない可能性もある）」かのいずれかにしか、本質的にはならないというジレンマ
- k8s のケースでは etcd の状態とより手前にあるキャッシュの状態が同期しないケースで、同じジレンマが避けようなく存在する
Debugging network stalls on Kubernetes - The GitHub Blog
- GitHub の k8s クラスタで起こった定期的なレイテンシの悪化のデバッグ。2019 年の記事
- これだけの深さまで掘り進めるのは難しいが、状況（関連するコンポーネント）を図示して原因を切り分けていくステップは参考になった
- k8s は特にそうだがコンポーネントの層が厚く複雑なので、図を取り入れて進めるやり方はよさそう
Sharding Pinterest: How we scaled our MySQL fleet | by Pinterest Engineering | Pinterest Engineering Blog | Medium
- 2015 年の記事。当時の Pinterest での MySQL シャーディング事例
- 今仕事で Vitess を使っておりそれでも複雑さを感じるが、このようにすべて自前で行うのに比べれば、遥かに楽だと改めて認識できた
Sharding & IDs at Instagram. With more than 25 photos and 90 likes… | by Instagram Engineering | Instagram Engineering
- 2012年の記事。当時の Instagram のシャードを跨いだ ID 生成を、タイムスタンプ・シャード番号をベースに DB の PL/PGSQL で行ったという話
- UUID に比べて短くソート可能で、専用の採番サービスを用意する方針に比べて単一障害点になりづらいなど運用面で有利
Scaling Kubernetes to 7,500 nodes
- 2021 年の記事。当時の OpenAI で 7,500 ノードを k8s で管理する話
- リサーチャーが学習で利用するクラスタで、GPU を利用するのでワークロードごとに 1 ノードを占有する必要がある、パブリックにサービスを公開しないなど、普通の Web アプリケーションクラスタとは異なるポイントも多い
The USE Method
- Brendan Gregg による、システム高負荷時に素早く原因を切り分ける USE Method の解説
- リソースごとの Utilization, Saturation, Errors を見ること
- 具体的なコマンドやチェックリストもあり
Linux Performance Analysis in 60,000 Milliseconds | by Netflix Technology Blog | Netflix TechBlog
- Linuxで問題調査をする際に使う基本的なコマンド集。2015 年の記事

PR

詳説データベース ―ストレージエンジンと分散データシステムの仕組み

Alex Petrov (著), 小林隆浩 (監修), 成田昇司 (翻訳)

Amazon.co.jpで詳細を見る

読書メモ: A Philosophy of Software Design

Kosei Moriyama — Thu, 16 Nov 2023 23:00:00 +0900

A Philosophy of Software Design, 2nd Edition (English Edition)

英語版 John K. Ousterhout (著) 形式: Kindle版

Amazon.co.jpで詳細を見る

良い設計をするためのコンセプトを解説した本。類書はいろいろとあるが、自分が読んだものの中では一番良かった。ソフトウェアエンジニアリングを行う人には広くおすすめできる。コンパクトですぐに読み切れるのも良い。

複雑さをいかに削減するかという観点と、その対策としての深いモジュールというコンセプトを導入し、この軸ですべての章を論じている。筋が通っていて読みやすいし、納得感も高い
これらのコンセプトを通して、従来は良しとされているプラクティスの再検討も行っていて、こちらも面白く納得しながら読めた。例えばできるだけメソッドは小さくするという慣習や、Clean Code でのコメントの不要論など。同意する部分は認めつつ、それがマッチしない、むしろシステム全体の複雑さを増やしてしまうケースを示している
ソフトウェアを書いて終わりではなく時間をかけて保守開発していくものという観点に立っているのも良い
- Googleのソフトウェアエンジニアリングもそのような視点で書かれていたのが思い出された。単純なプログラミングとソフトウェアエンジニアリングの違いは、この時間経過の概念があるかどうかと定義していた記憶がある
目から鱗が落ちる、すぐに普段の開発に取り入れたい知見がいろいろとあった
- 印象に残っているのは somewhat general-purpose にモジュールを設計しようというアイデア
- 先が見通せない状態で汎用的に作りすぎるのはリスクがあるので、まずは要件を最短で満たす実装をし、そこから必要に応じてリファクタリングするという、インクリメンタルな進め方は良いものだと考えていた
- それはそうなのだが、最初からある程度 (この塩梅も重要) 汎用性のあるつくりにしたほうが、シンプルさも実装量も減るという知見が目新しく、取り入れていきたいと思った
先にコメントを書いてから実装に入るというコメントファーストという設計手法は、生成 AI 時代にもマッチしている方法論だと思った
- まずはできるだけ Copilot に書いてもらい、それを手で修正するやり方を、普段から取るようにしている
  - ref. サイバーエージェントのGitHub Copilot導入と開発生産性 - Speaker Deck
- コメントファーストの方針はこうしたプログラミングスタイルともマッチしている気がする
- もちろん第一義は実装に入る前に設計をブラッシュアップできるという、設計ツールとしての側面だが

以降は読書メモだが、本文のコード例も合わせて読んだほうが理解が深まる。

1 - Introduction (It’s All About Complexity)

この本では、デザインの良し悪しの判断基準を複雑さ complexity に置いている。

物理的な制約がないソフトウェアエンジニアリングでは「複雑さ」、いかにシステムを容易に理解でき変更できるか、が生産性のボトルネックになる
複雑さは時間を経るごとに増し、反比例して開発生産性は減るので、なおさら重要
良いデザインは複雑さをなくしたり、モジュールに押し込めることで、トータルの複雑さを減らす

2 - The Nature of Complexity

ここでは複雑さを「システムの理解と変更を難しくする、ソフトウェアの構造に関するすべてのもの」と定義している。

簡単に理解でき変更できるソフトウェアは複雑さが少ない。また複雑なシステムは小さな変更に労力がかかるので、費やしたコストに対して便益が少ないとも言える
- コードベースの大きさとは独立した概念。大きいコードは理解するのが大変なので複雑な傾向にはあるが、小さくても複雑なソフトウェアは存在し得る

次のように定式化できる。

定義
- C はシステム全体の複雑さ
- p はそのシステムを構成するサブシステムやコンポーネント
- c_p はサブシステムの複雑さ
- t_p はそのサブシステムに開発者が費やす時間
つまり以下のアプローチがある
- 複雑さそのもの c_p を減らしたり無くす
- 複雑さをモジュールに切り出す。サブシステムに費やす時間 t_p が小さければ、その複雑さ c_p が大きくても全体はシンプルになる

複雑なソフトウェアには以下の症状が現れる。

変更箇所の増幅 Change amplification
- 簡単な変更でも多くの作業箇所が発生する
認知負荷の増加 Cognitive load
- 作業するために把握すべきことが多い・把握が難しい
知らない知らないこと Unknown unknowns
- 把握すべきことがコードからもドキュメントからも知りようがない状況
この中で Unknown unknowns がワーストケース。開発時には問題にすら気づくことができず、リリース後のバグ報告で把握するしかなくなる

こうした複雑さの原因は依存関係 Dependency と不明瞭さ Obscurity によって引き起こされる。

依存関係はある変更をする際に特定の箇所以外の変更も必要になる場合と定義している
- 依存関係は本質的に必要なものだが、その数を減らし、関係を明確にすることで複雑さを下げることができる
重要な情報が分かりづらい場合不明瞭さが現れる
- 設計とドキュメントで解決すべき問題。また良い設計は必要なドキュメントを減らす
依存関係は Change amplificationと Cognitive loadを増やし、不明瞭さは Cognitive loadと Unknown unknownsを増やす関係にある

また複雑さは一つの大きな原因があるのではなく、小さな問題が累積して全体の大きな複雑さになる。

素早く仕事をこなすために追加した小さな複雑さが、時間を経て incrementalに全体の複雑さを増加させていく

3 - Working Code Isn’t Enough

日々の開発では、戦略的目線で少しずつ投資をしていくマインドセットが求められる。

機能開発やバグ修正を最短で行う方針を戦術的プログラミングと呼ぶ
- 最速で動くことが最優先される
- 複雑さは追加、蓄積される。多くの場合技術的負債が全て返済されることはなく、複雑さは常に増える
- 一般的な組織では高速に実装する人は高く評価されがちで、その時どれだけ複雑さが追加されたかが評価に加味されることは少ない。また負債を残さない開発をしている人、負債を返している人が高く評価されることは少ない
反対に良い設計を目指して進める方針を戦略的プログラミングと呼ぶ
- 「動くこと」は当然満たしながら、あるべき設計への投資も行う
- 良い設計のためにはこちらのマインドセットを持つ必要がある
開発期間の 10-20 % を、この戦略的目線での投資にあてることを推奨
- 一度に大きなリファクタリングは失敗しやすい。インクリメンタルな進め方を推奨している
- 複雑さは個々の小さなものの累積なので、それを出さない、減らす活動にも大きな意味がある
- この水準の時間投資ならば比較的早く回収できる
  - 客観的ではないが、筆者の見込みでは 6-18 ヶ月で投資が回収できるとのこと

A Philosophy of Software Design (p. 16) Figure 3.1 より

スタートアップなど速度が重視される環境でも例外ではない
- 戦術的プログラミングを行う組織の代表例として Facebook が挙げられる
  - 彼らの Move fast and break things というモットーはそれを象徴しているが、後日 Move fast and solid infrastructure に変更されている
- 戦略的アプローチをとる代表例は Googleや VMWare
- これらを見ると戦略的・戦術的プログラミングどちらでも事業が大きく成功することがあるとわかる。そうであればエンジニアとしてより満足度が高い後者のアプローチをとってもいいのではないか

4 - Modules Should Be Deep

モジュール化は代表的な複雑さへの対応方法で、その良し悪しは「深さ」で測る。

以下の議論はメソッドやクラスからサブシステム、サービスまで、あらゆる粒度に適用できる。わかりやすさのためモジュールと呼んでいる。

モジュールはインタフェースと実装に分けて考えることができる
インタフェースは広義にそのモジュールを使うために利用者が把握しなければいけないことで、以下の二つに分類できる
- フォーマルなインタフェース
  - プログラミング言語により検証されるもの
  - メソッドのシグネチャが例。メソッド名や引数、戻り値の型にミスがあればコンパイラが指摘してくれる
- インフォーマルなインタフェース
  - フォーマルなもの以外で、利用者が把握しなければ、そのモジュールを正しく使えないような情報
  - 例えば「別のメソッドを事前に呼び出さなければならない」といった情報や、どんな例外が投げられるかなど
  - 基本的にはドキュメントに記載するしかない

「深い」モジュールとは、シンプルなインタフェースに対して多くの仕事をするもの。

A Philosophy of Software Design (p. 23) Figure 4.1 より

四角形の縦軸がそのメソッドのこなせる仕事の量、上辺の太線がインタフェースで、短いほどシンプル
深いモジュールは縦に長い
例えば Unix の File IO の仕組みが挙げられる。５つのシステムコールで単純なファイルからネットワーク通信まであらゆる入出力に対応している

反対に浅いモジュールは相対的に複雑なインタフェースに対して仕事が少ないもの。

例えば別のメソッドに値を受け渡しているだけのメソッドが極端な例
浅いメソッドは悪い設計のレッドフラグ（兆候）
メソッドやクラスを小さく保つというプラクティスがあるが、それはこの議論の文脈では浅いモジュールを引き起こす悪いものということになる
- 実装を理解しやすくするのは重要だが、単に行数で複雑さを判断するのは間違っている

インタフェースの設計は、その対象をどう抽象化するかと言い換えることができる。

あるエンティティから不要な詳細を省き、シンプルな見方を提供するのが抽象化の定義
「不必要なものをインタフェースに含めてしまう」「必要なものがインタフェースから漏れてしまう」とインタフェースの複雑さが増し、浅いモジュールに近づいてしまう
不必要なものをインタフェースに含めてしまった場合、利用者の認知負荷が高まる
- 標準的な使い方では不要なケースへの対応のために必要な引数がが必須になっているなど
必要なものがインタフェースから漏れてしまった場合、Unknown unknownsを引き起こす
- インフォーマルなインタフェースがドキュメント化されていないなどが例になる

5 - Information Hiding (and Leakage)

情報をモジュールに隠す（漏らさない）ことは、深いモジュールを作るための方法論のひとつ。

Information hidingはある情報を実装の中だけにとどめてインタフェースには出さないこと
- 例えばデータを B-tree に格納するとか、スレッドをどうスケジューリングするかといったデータ構造・アルゴリズムの詳細はインタフェースには現れるべきではない
Information leakageはその反対で、これが起こるとインタフェースが複雑化し浅いモジュールに近づく
- 例えば順序によるモジュール分割
  - ファイルを読み込み、編集して保存する機能を考える。この順序に着目し読み込み、編集、保存の 3 クラスを作ったとする。読み込みと保存を担うクラスはファイルフォーマットの知識を暗黙に共有していることになり、フォーマットに変更があるとこの2クラスを両方修正しなくてはいけない
  - 設計の際にはタスクの順序ではなく、各タスクが必要とする知識に着目したほうが良い。この例の場合は読み書きを両方行う汎用的なクラスを作り、ファイルに関する知識を一箇所にまとめたほうが良い
- 他にも特定のケースのチューニングに必要なパラメータという例もある。理想的には設定値をユーザーに指定させるのではなく、最適な数値を自動計算できたほうが良い
Information leakageに気づくことができる能力は、設計スキルにおいて重要

6 - General-Purpose Modules are Deeper

モジュールを汎用的に (General-Purpose) に作ることで深いモジュールを実現できる。始めから適度に汎用的に設計したほうが良いことが経験からわかった。ロジックの特殊な部分を汎用的な部分から分離する方針には、上方向・下方向の二種類がある。

汎用的なモジュールをつくり、色々な用途で共通して利用できれば、そのモジュールは深く、複雑さも少なくなる
ただし始めから汎用的な設計をすることは簡単ではなく、世の中にはそれを推奨しない方針もある
- まずは要件にあわせて最低限の（特殊な Special-purpose）実装をして、後から別の要件が出た際に汎用的にリファクタリングする
- 完全に未来を見通すことは不可能だし、インクリメンタルな進め方という見方でも好ましい
筆者ももともとこの方針を支持していたが、経験を通じて始めから適度に汎用的な設計をしたほうが良いことに気がついた
- 最低限の特殊な実装は、ほとんどのケースで、汎用的に作るよりもインタフェースの複雑さ、コード量で劣った。つまり仮に将来の再利用がされなくてもメリットがあると言える
- もちろん過度な汎用化は非推奨。目安として、インタフェースの設計は汎用性を目指し、実装はそこまではやらないという塩梅
テキストエディタの設計という課題での例
- テキストをファイルから読み込み、変更し、保存するテキストクラスを基盤として、その上に UI のクラスを作る方針
- ここで削除操作について考える。バックスペースを押すとカーソルの前、デリートを押すとカーソルの後、範囲選択中ならその範囲を削除する
- ここで操作ごとの専用メソッドをテキストクラスに作るとする

void backspace(Cursor cursor);
void delete(Cursor cursor);
void deleteSelection(Selection selection);

// Ousterhout, John K. . A Philosophy of Software Design, 2nd Edition (p. 41). Yaknyam Press. Kindle Edition.

この方針には次の問題がある
- 大量の浅いメソッドが生まれる。UI の操作ごとにメソッドが必要で、それぞれは簡単なロジックしか持たない。利用者は多くのメソッドを把握しないと UI を実装できないし、各メソッドのドキュメントやコードを把握しないと実際の挙動がわからない
- UI の要件の変更ごとに基盤のはずのテキストクラスに変更が必要になる
代わりにテキストクラスには次のシンプルなメソッドだけを持たせる方針を考える

void insert(Position position, String newText);
void delete(Position start, Position end);

// Ousterhout, John K. . A Philosophy of Software Design, 2nd Edition (p. 42). Yaknyam Press. Kindle Edition.

シンプルで汎用的な少数のメソッドだけを覚えれば、UI 側はほとんどの要件を実装できる
UI ごとの特殊な処理は UI 側に切り出されており、基盤側の変更が不要になる
設計時のチェックポイント
- 全ての要件を満たす最もシンプルなインタフェースは何か
  - もしメソッドとして一つでも多くの引数が必要な場合、うまくシンプルにできていないと言える
- このメソッドがカバーするユースケースはどれだけあるか
- この API は現在の要件を満たすのにシンプルに使えるか
  - 例えたくさんのユースケースをカバーするインタフェースでも、利用に複雑な手続きが必要ならそれはシンプルではない。汎用的かつシンプルなものを目指す
汎用的な部分から特殊な部分を切り出す際、上への切り出し、下への切り出しの2種類がある
- テキストエディタの例は上への切り出し。基盤となるテキストクラスは汎用性を保ち、UI に紐づく特殊な処理は上側（UI 側）に寄せられた
- 下への切り出しの例は Linux のデバイスドライバ。共通のインタフェースが定義され、各デバイスの特殊な部分は下側（ドライバ側）に切り出されている

7 - Different Layer, Different Abstraction

レイヤー分けはソフトウェアには必須の抽象化技法。レイヤーごとに違う抽象化を提供するのが原則（それがレイヤーを分ける意味）だが、そうなっていなければ、つまり別のレイヤーに同じような API が重複しているのは、危険な兆候。

そのひとつが Pass-through methodというパターン。ほぼ別レイヤーの関数を呼び出しているだけのメソッドで、シグネチャも重複している。
- クラス間（レイヤー間）の役割の切り分けに失敗している可能性が高い
- シグネチャが同じだけでは Pass-though methodとは限らない。それぞれのレイヤーでなにか役に立つ機能が提供されているかどうかが問題（別の関数を呼び出すだけの一行メソッドは価値を追加しておらず、層が増え複雑さを増しているだけなので問題）
デコレーターも浅いモジュールになりがちで、濫用注意
Peas-through variableというパターンもある。レイヤー間で引数を引き回しているもの。変更箇所が増えてしまうので避けたほうがよいが、解消は簡単ではない
- グローバル変数を使うか（それはそれで別問題をはらむ）、コンテキストオブジェクトを導入するといった対策

8 - Pull Complexity Downwards

避けることのできない複雑さが存在することはままある。通常、モジュールの制作者より利用者の方が多い。そのため複雑さはモジュールの中に押し込めたほうが、全体がシンプルになる場合が多い。

例えば TCP の下位レイヤーの仕事、パケロスの検出や再送など、が上位レイヤーに漏れていると、利用者の認知負荷が高まる
モジュール制作者はいくらか追加の工数を払うことになるが、長期目線、全体目線では効率的
ただ通常は制作者はモジュールの実装をシンプルに保つため利用者に知識や実装を求める方に短期的なインセンティブがあるので、注意しなければいけない
例えばチューニングパラメータを提供することも、できるだけ避けたほうが良い。そのモジュールが最適なパラメータを自動で算出するなど、追加で実装して済むならそのほうが良い
常に複雑さを下に押し込めればいいわけではない。以下を満たしている場合に下に切り出すのがよい
- その複雑さが、下位レイヤーのクラスの役割と関係が深い
- そうすることで利用方法がシンプルになる
- そうすることでインタフェースがシンプルになる

9 - Better Together or Better Apart?

ロジックを分割するか、統合するかの判断基準。内容が近いものは近くに置くのが原則。メソッドやクラスを細かく分割すると、ひとつひとつの量は小さくなり一見理解しやすいかもしれないが、インタフェースの数が増えること（浅いモジュールが増えること）そのものが全体の複雑さを増加させるので注意。

同じデータ、情報、知識を共有しているものは統合する
- 前述のテキストエディタの例だと、ファイルの読み込みと書き込みクラスはいずれもファイルフォーマットの知識を共有している
統合することでインタフェースがシンプルになるのならそうする
- ある一連の処理のステップごとにクラスが分かれているような場合。統合すると中間生成物の受け渡しが不要になる
同じコードが繰り返し登場したら赤信号。統合を検討する
汎用処理と特殊処理はわける

これらの考え方はクラスだけでなくメソッドの設計にも適用できる。ただしメソッドの場合は（も）細かく分けすぎないように注意する

ある単体のメソッドだけをみて実装が理解できないようなら赤信号。本来一箇所にあるべきものが分けられている可能性がある
- Clean Code ではメソッドを細かく分割することを推奨しているが、単に行数だけで判断するのは浅いモジュールを増やすためよくない

10 - Define Errors Out of Existence

例外の難しさ
- 正常系より実装が複雑になりがち
  - 例外発生時に、それでも処理を前に進めるにしてもその処理は複雑になりがちだし、abort する場合でも不整合が起こらないよう状態を巻き戻す作業が煩雑になりがち
- 例外状態が別の問題を引き起こすこともある
- 例外ハンドリングのコードは読みづらくなりがち
- 例外をテスト環境で実際に起こすのは難しく、長い間気づかれないバグが入り込みやすい
  - 分散データ指向システムのバグの 90% はエラーハンドリングが原因という報告もある
例外もインタフェースの一種
- 利用者はそれを把握していないといけないので
- さらに、呼び出し元だけでなく、その上のレイヤーにまで例外は波及することもある。例外は複雑さの増加に大きく影響する
- 無駄な例外を可能な限り無くすほうがよい
- しかし意識しないとなかなか難しい
  - 予期しない状態が起こった時、例外を出してしまうのが簡単。それを内部でハンドリングするほうが難しい。ただそうしないとシンプルなインタフェースが実現できない
可能なら例外そのものをなくしてしまえると良い。異常な状態を内部でケアして、正常系の範疇に収める
- 例えば Unix のファイル削除。削除時に別のプロセスがそのファイルを開いていても、削除は成功する。OS がファイルに削除マークをつけておき、実際の削除は全プロセスがアクセスを辞めた後に行う。一方で Windows では削除時にエラーを出すため、呼び出しごとに毎回、他に開いているプロセスが居ないかのチェックを書かなければいけない
- Java の substring 関数は、指定した範囲が境界を超えていたら例外を出す。これをエラーとせず単に空文字列を返したり最大長へ切り詰めて返すことで例外を無くせる。関数の定義を「何であれ指定した範囲の部分文字列を返す」とすることで、エラーをエラーでは無くしている
  - この例外で気づけていたバグもあったかもしれない。しかし全ての substring 呼び出し箇所に指定範囲チェックのコードを入れるほうがバグの確率を高めている
例外のマスク
- 下位のレイヤーで例外をハンドリングしてしまう
- 例えば TCP では下位のレイヤーが問題時に自動的にパケットを再送する
例外の集約
- 例外を各所でハンドリングするのではなく、一箇所で行う
- 例えば Web サーバを考える。リクエストに応じてディスパッチャーがハンドラを呼び出す。リクエストパラメータのパースで例外が起こった場合、各ハンドラで例外を捕捉するよりも、上位のディスパッチャーがまとめて対応したほうがよい
- ディスパッチャーはエラーに応じてどのようなレスポンスをクライアントに返すかを知っている。また例外の raise 元はどのような場合にどの例外を出すか、また例外のヒューマンリーダブルな表現は何かを知っている
- マスクと集約はそれぞれ別方向で同じことをしている
  - 色々なところから呼び出されるモジュールの場合、マスクで補足箇所をまとめられる。色々な箇所から発せられる例外の場合、集約で補足箇所をまとめられる
プログラムの Abort
- エラーをハンドリングしようが無く、また頻度も低い場合、エラー時にプログラムを即座に Abort する
- 例えばメモリ不足で malloc に失敗した場合、それ以上できることが無ければ Abort してしまった方がシンプルになる

ここで、必要なエラー情報まで隠してしまうのは問題であることを再確認すること。何が重要で何が重要でないかを見極め、後者だけを取り除く。

11 - Design it Twice

「二度設計する」というスローガン。

設計をする際に、最初に思いついたアプローチだけだなく、他のアプローチも比較検討する
その際にあえて極端なものを考えると長所短所や問題がわかりやすい
あきらかに一案目が正しいと確信していても、別アプローチとの比較はした方がよい。隠れた問題点がないかの確認や長所短所の明確化につながる
検討したどちらの案も適当ではない場合。比較するプロセスで問題点が明らかになっているはずなので、それを解消する別のアプローチを検討する
検討にかかる時間はそれほど多くない。クラスレベルの設計なら 1, 2 時間程度で、まずい設計が将来与える生産性低下に比べるとすぐに元がとれる。より大きなコンポーネントの設計の場合さらに時間がかかるが、その際は実装にもさらに時間がかかるはず

12 - Why Write Comments? The Four Excuses

ドキュメントは開発者の理解を効率化するため、良い抽象化のために必須で、設計において重要な位置を占める。コード中のコメントも同様。しかしコメントに対するネガティブな印象やポリシーは業界内に多い。ここではコメントを書かない理由を検討しながら、必要性を確認する。

良いコードを書けばコメントは不要である
- 確かに命名などを適切に行うと可読性は劇的に良くなる
- ただコードで説明できることとコメントが説明できることは別である。メソッドのシグネチャをだけを見て、例えば引数の単位といったインフォーマルな情報を読み取ることはできない（または説明のために名前が長くなる）
- コードを読めばわかるが、そもそもコードを読まなければ利用できないモジュールは抽象化が不完全といえる
コメントを書く時間がない
- 前述の投資するマインドセットを持つ。少ない時間の投資で長期のリターンが得られる
- 後述するコメントファーストのデザイン技法であればコメントを書くストレスはさらに下がる
コメントは古くなり、ミスリードを誘いがちになる。コメントを最新に保つのは工数がかかる
- 後述するコメントを書く技術で低減できる
- キーポイントは「重複をなくし、関連するドキュメントとコードを近くに置く」こと
役に立つコメントを見たことがない
- コメントには悪い書き方と良い書き方があり、技術で解決できる部分
- 後述の章で解説している

コメントの意義はコードでは表現できない情報を記載できること。

複雑なシステムの問題である Cognitive load、Unknown unknowns に有効
複雑さは依存関係と不明瞭さから産まれるが、良いコメントは依存関係を明確にし不明瞭さを減らす

Clean Code はコメントに対して強く否定的な議論をしている。確かに悪い書き方をすると、何の情報も伝えない、ミスリードを誘うコメントになる。一方で繰り返しになるがコメントはコードで表現できない情報を伝達するという重要な役割がある。一律にコメントを否定すべきではない。

13 - Comments Should Describe Things That Arent Obvious from the Code

コードだけでは全ての情報を伝えることができないので、コメントにはコードからは明確にわからないことを記載すべき。全てのコードを読むのは時間がかかるし、詳細すぎるため、コメントも通じて抽象化（必要な情報だけを伝えること）を実現する。

悪いコメントの例として、コードをリピートしているだけのものが挙げられる。次のようなコメントはほとんど何の情報も伝えられていない。よくある兆候として、変数名やメソッド名にある単語がそのまま使われているだけのコメントは不要なことが多い。

ptr_copy = get_copy(obj)              # Get pointer copy
if is_unlocked(ptr_copy):             # Is obj free?
    return obj                        # return current obj
if is_copy(ptr_copy):                 # Already a copy?
    return obj                        # return obj
thread_id = get_thread_id(ptr_copy)
if thread_id == ctx.thread_id:        # Locked by current ctx
    return ptr_copy                   # Return copy

# Ousterhout, John K. . A Philosophy of Software Design, 2nd Edition (p. 103). Yaknyam Press. Kindle Edition.

大切なのはコードとは違う抽象レベルの情報を記載すること。

抽象レベルを下げたコメント: より正確な情報
- 変数のコメントを書く際は、例えば変数の単位は何か、範囲の場合境界は含むか、nullを受けいる場合何が起こるか、誰がメモリ解放に責任を持つか、普遍条件はあるかといった、変数についてのより詳細な情報を提供する
抽象レベルを上げたコメント: より直感的理解を助ける情報
- 詳細は省き、全体感を素早く把握するための情報を提供する

コメントは次の 4 つに分類できる。

インタフェースコメント
- クラスやメソッドの冒頭に記載する。概要とそれを使うために必要な知識（引数や返り値の説明など）を伝える
- 実装に関するコメントとインタフェースに関するコメントとを分けて考え、後者を記載すること。後者はこの機能を利用するために必要な情報を提供し、実装には立ち入らない
データ構造のメンバー
- インスタンス変数の説明など
- 動詞ではなく名詞で考えるのがコツ。その変数がどう扱われるのではなく、何を表しているのかにフォーカスする
実装コメント
- 実装コード中に記載されるコメント
- 理想的には、一つのことをするメソッドでインタフェースコメントがあれば、全く不要なことも多い
- what と why を記載する。howは記載しない
クロスモジュールコメント
- 複数のモジュールにわたる依存関係を説明するコメント
- 理想的には全ての重要な知識はそれぞれのモジュール内に隠蔽されるが、現実的には難しい。ひとつの知識に対して複数のモジュールがどうしても関連してしまうことがある
- そのような情報をどこに記載するかが最大の問題
- ひとつの解決法としては、中央の Wiki などにまとまった情報を記載し、コードの各所にはそこへの参照を記載する方法

このうち重要なのは最初の 2 つ。実装コメントは適切な命名や分割によってはほぼ必要なくなる。クロスモジュールコメントが必要になることは稀だが、必要になった先には非常に重要な情報となる。

14 - Choosing Names

命名ほど重要性が過小評価されているものはない。良い名前は理解を助け、ドキュメントの必要性を減らし、ミスに気づきやすくする。反対に悪い名前は認知負荷を高め、バグの温床になる。

良い名前はそれだけで多くの情報を伝える。命名する際には、それだけで（定義やドキュメントや実装をの読まなくても）どれだけ多くそのエンティティを推測できるかと、自分に問いかけてみると良い。

良い命名に必要とされるのは正確さと一貫性。

正確さについて。よくあるミスは一般的で曖昧な名前をつけてしまうこと
- 例えば getCountよりも numActiveIndexlets、blinkStatus (bool) よりも cursorVisible (book) のほうが好ましい
一貫性について。同じ概念には同じ単語を使う
- 違う概念には違う単語を使うことも重要

また良い名前が思いつかない時は、ひとつのエンティティで複数の概念を表そうとしているなど、そのエンティティ自体が適切でない可能性がある。

File クラスのプロパティに FileBlock と名付けるなど、重複した単語は避けると良い。

Go のコーディングスタイルで、b []byte といった非常に短い変数名を推奨するものがある。筆者の考えではわざわざこんなに短くしなくても、buffer といった普通の名前をつけても可読性は落ちないと述べている。ただ定義場所と利用場所が離れている場合は短い名前をつけないという方針には賛同している。

15 - Write the Comment First

一般的にコメントは開発フェーズの最後に書かれることが多いが、ここではコメントファーストの開発プロセスを推奨している。コメントを先に書くことで、ドキュメントの質はもとより、設計の質も上げることができる。

一般的なコメントを後に書くアプローチには次のデメリットがある。

コメントがそもそも書かれない
- 実装完了後には次の新しい開発に早く取り掛かることにインセンティブがある
設計時から時間が経っており、良いドキュメントを書くのが難しい

一方コメントファーストの場合、次のような流れで設計実装は進む。

新しいクラスを作る際、そのインタフェースコメントをまず書く
次に重要な公開メソッドのシグネチャとインタフェースコメントを書く。この時中身は実装はまだ空
全体の大まかな構造ができるまでこれを繰り返す
重要なインスタンス変数があればそのコメントを記載する
最後にロジックを実装する。必要があれば実装コメントも記載する
実装中にメソッドの不足や設計の不備が見つかることもある。既存のコメントを更新しながら修正する

このアプローチには以下のメリットがある。

ドキュメントの質が上がる
- 記憶がフレッシュなうちにコメントが書かれるし、実装に応じて最新に保たれる
設計の質が上がる
- コメントを先に書くことが、初期設計に対するレビュー効果を生み出す。実装に入る前に設計を改善できる
- コメントが長くなったり書きづらかったりしたら、それは設計が悪い兆候
コメントを書く作業が楽しくなる
- 設計はソフトウェアエンジニアリング全体の中でも楽しいフェーズ。その時にコメントを設計ツールとして使い、質を高めるのは楽しい作業

実装に入る前に設計を改善できるので、コメントファーストは投資対効率も良い。

16 - Modifying Existing Code

これまでは主に初期設計を念頭に置いた議論をしてきたが、既存のシステムに手を入れる際の注意点も考察する。

投資マインドセットを改修時にも持つ
- 機能追加やバグ修正はいかに小さい変更で完了させるかにインセンティブが働くので、戦術的プログラミングになりがち
- 戦略的にすることでシンプルな設計を保てるようにする
- 理想的には「はじめからこの要件だっとして、最初から設計し直すとしたらこうなっている」という状態にすること
- ただ既存の仕組みのままコードを追加するだけだと、複雑さは維持ではなく悪化していると考える
改修にあわせてコメントも追従する
- これはコードの位置とコメントの位置を近づけておくとそれほど大変ではなくなる
  - 例えば実装コメントは、メソッドの先頭に全文記載するのではなく、そのコードの位置にそれぞれのコメントを記載するなど
コミットログに詳細な情報を載せるのではなく、コメントに載せる
- コミットログに比べるとコメントの方が開発者の目につきやすい
コメントの重複を省く
- 複数の影響箇所がある場合、どこに書くのが一番適切かを考える
- 適切な一箇所がない場合は別の文章に記載し、コードからはそれをリファレンスする
PR を作る前に差分全体を見返す習慣をつけるのも良い
抽象度の高いコメントは書き換え頻度は低くなる
- 不要な箇所で詳細なコメントを避ける

17 - Consistency

一貫性は知識にレバレッジをかけ認知負荷を減らし、ミスも防ぐ。

一貫性を持たせる対象は多岐にわたる。

名前
コーディングスタイル
- 小さな組織では既存のスタイルを取り入れるところから始めると良い
インタフェース
デザインパターン
invariants

複数人のチームで一貫性を保つのには相応の努力が必要になる。新メンバーがそれと気付かず一貫性違反を犯してしまうことはままある。

ドキュメントに記載する
- コーディングスタイルのような重要で対象範囲のひろい規約は目につきやすい場所に置いておく
ツールで強制する
- 違反がある場合コミット、マージできないようにし担保する
コードレビューで共有する
（個人のマインドセットとして）郷に従う
- 開発時には既存のコードベースをよく観察する

既存の規約を安易に変更しない。新しい方針のほうが優れている確かな証拠と、時間をかけて変更するメリットが確実にあることを確認してから行う。

18 - Code Should Be Obvious

前述のように明確さはシステムの複雑さに影響する重要な要素。コードが不明確だと認知負荷が高まりバグの温床にもなる。

明確さはあくまで読み手にとってのもの。書き手にとっては明確でもレビュアーがわかりづらいと感じたらそれは分かりづらい。

明確なコードのために気をつけるポイント。

良い名前をつける
一貫性を保つ
空白を使ってわかりやすくコードを整える
コメントの活用
- どうしてもコードにわかりづらい箇所は残る。そうした箇所はコメントで補う
Event-driven programmingは可読性が落ちる
- 処理の流れが追いづらいので
- その処理がいつ呼び出されるのかをコメントで補足する
Java の pair のような generic containerは別々のものを一つの変数に曖昧な名前でまとめてしまうので、避ける
- ソフトウェアは書き手よりも読み手が楽できるようにするべき
読み手の予想を裏切る実装にはコメントで補足する

19 - Software Trends

オブジェクト指向と継承
- 継承にはインタフェースの継承と実装の継承の2種類があり、後者は複雑さを増やしかねない
- インタフェースの継承: シグネチャだけが定義されていて、サブクラスはそれを実装する
  - 様々な用途に同じインタフェースを使い回せるので、知識のレバレッジが効く。利用者は別の問題を同じやり方で解くことがてきるので、認知負荷が下がる
- 実装の継承: ベースとなる実装がされていて、サブクラスはそれを使うかオーバーライドする
  - 実装に関する知識がサブクラス（継承ヒエラルキーの各所）に漏れることになる
  - そのため最悪のケースでは、変更のために継承ヒエラルキー全体を影響確認しないといけない。変更にかかるコストが非常に高くなる
  - できるだけ使用せずコンポジションでの代替などを検討する
アジャイル開発
- ソフトウェアの開発をインクリメンタルな取り組みと捉えている点が良いところ
- リスクがあるのは、アジャイルの開発プロセスは動くものを短期間に作ることにフォーカスしているため、戦術的プログラミングをしがちになること
- 機能に対してではなく、抽象化に対してインクリメンタルにアプローチする、戦略的な進め方が理想
ユニットテスト
- リファクタリングをするためにはユニットテストは必須。非常に重要な役割を担っている
テスト駆動開発
- ユニットテストが大切なことに対して、テスト駆動開発にはリスクがある
- テスト駆動開発はある機能が動作することにフォーカスを置いており、これは戦術的なアプローチ
- ただしバグ修正には有効。まずバグを再現するテストを追加、失敗を確認してから修正し成功を確認する
デザインパターン
- 過剰適用のリスクに注意する。フィットしない問題に無理やりパターンを適用しない
Getter, Setter
- Java ではポピュラーなパターン
- こちらも過剰適用に注意。盲目的に全ケースで必要なものでは無いはず

20 - Designing for performance

シンプルでパフォーマンスも良いプログラムはチャレンジングな面がある。遅いがシンプルなコードと、速いが複雑なコードの両極端の間を取る必要がある。ただ原則的には、シンプルなコードはやることが少ない分複雑なものよりも速いはずなので、シンプルかつ速いプログラムを目指す。

まずは処理の速度に対する一般的な常識を身につけて普段の開発時には発揮する。

常識とは例えば DC 内のネットワーク通信はローカルと比べて 10-100 倍オーダーで時間がかかるといったもの
二つの同じようなアプローチがある場合、こうした常識に照らし合わせて、要件を満たしつつ速い方を選ぶ
例えばマップ構造のデータを保持したいケースで、Hash Table と Ordered Map （インタフェースはほぼ同じ）の選択肢がある場合、順序が不要ならば前者を選ぶ

速い方のアプローチが複雑さを増やす場合、

あまり複雑にはならず、インタフェースも変わらない場合は、悩まずに実施する
かなり複雑になりそうな場合、まずはシンプルなアプローチから始めて、実際にパフォーマンスの問題が発生してから対処する

変更の前後では必ず計測をすること。現状を計測し、影響が大きいボトルネックを特定し、計測値をベースラインに改善する。改善効果は同じ計測で評価する。

ボトルネックを特定した後、まずは根本的な変更（キャッシュ導入、別アルゴリズムの導入など）が可能かを検討する。

それができない場合はコードの再設計が必要になる。その際は Critical-path から始めると良い。

一般的なケースだけに対応していて最低限のコードからまず始める
特殊ケースのハンドリングが入っていないので、無駄な分岐がなくシンプルで最速になっているはず
この状態を理想として、特殊ケースのハンドリングを加えていく。できるだけ理想状態から乖離させないことを目指す

21 - Decide What Matters

良い設計の重要な要素のひとつに、何が重要で何がそうで無いかを決めるということがある。重要なことを中心に設計し、重要じゃないことの影響を可能な限り下げる。

重要なことは、時にはパフォーマンス要件といった外部要因に起因する
レバレッジに着目する。汎用化で議論したような、多くの場所から使われたり影響したりするものに着目する
特定が難しい場合、あるオプションが最重要と一度仮定して設計をすすめ、評価するのが良い

要素数を最小化する。引数を減らす、例外のハンドリング箇所を減らすなど。

重要なことが特定できたらそれを強調する。

ドキュメントや変数、引数名に使い目立たせる
何度も繰り返し利用する
その概念を中心にして設計する
重要で無い概念にはこれらの反対をする

よくある失敗。

重要な要素が多すぎる
重要性を見誤る

A Philosophy of Software Design, 2nd Edition (English Edition)

英語版 John K. Ousterhout (著) 形式: Kindle版

Amazon.co.jpで詳細を見る

Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス

竹辺靖昭 (監修), Titus Winters (編集), Tom Manshreck (編集), Hyrum Wright (編集), 久富木隆一 (翻訳)

Amazon.co.jpで詳細を見る

GCP CloudSQL MySQL での Replication Lag と innodb_flush_log_at_trx_commit

Kosei Moriyama — Thu, 27 Jul 2023 20:30:00 +0900

Primary (Source) - Replica 構成の MySQL クラスタを GCP の CloudSQL で構築し本番運用している。このうち一台の Replica の Replication Lag が急増したことがあった。同僚のアドバイスで innodb_flush_log_at_trx_commit を調整し Lag は解消した。

これは後日 innodb_flush_log_at_trx_commit の意味を調べた際のメモ。

レプリケーションの仕組みのおさらい

以前読んだ Efficient MySQL Performance の図と説明がわかりやすいのでそちらから引用する。

Efficient MySQL Performance (p. 235) Figure 7-1. Foundation of MySQL source to replica replication より

Source でトランザクションがコミットされるとデータの変更が Binarly Log (binlog) に書き出される
Replica の IO Thread が Source の binary log events を取得する
Replica の IO Thread が取得した binary log events を Relay Log に書き出して永続化する
Replica の SQL Thread (applier と呼ばれることもある) が Relay Log から binary log events を読み込む
Replica の SQL Thread が読み込んだ binary log events をデータに反映させる
Replica は適用された変更を Replica の binlog に書き出す
- 冗長性のため (Source にプロモートするときに備えて) 書き出している。後述するが CloudSQL ではデフォルトオフのようだった

Source にトランザクションがコミットされてから、それが Replica に反映されるまでの遅延が Replication Lag と呼ばれる。

SQL Thread で遅延することが多い
- ネットワークの遅延は相対的に少なく、IO Thread はイベント単位にまとめられた情報をシーケンシャルにログファイルに書き出すだけなので、それを解釈して適用する SQL Thread に比べてスループットが出る
Source が Replica の ack を待ったりしない限り、仕組み上レプリケーションにラグは不可避だが、以下の理由で通常は Source よりも高速に動作する
- Replica は Source よりも少ないワークロードしか扱わないので。特に Read しか発生しないので
- binary log events (変更適用済みの row image) を元に作業するので。Source はクエリを解釈し対象行を探しそこに変更を加えるが、Replica は変更の適用の作業だけをしている

Binary Log

補足として、バイナリログについて MySQL のドキュメントから引用しておく。

MySQL :: MySQL 8.0 Reference Manual :: 5.4.4 The Binary Log

バイナリログはデータベースへの変更を “イベント” として記録したもの。主に以下の用途がある。

レプリケーション。バイナリログが Source から Replica に転送され、レプリカはそれを順に適用することで Source と同じ状態に追従して言っている
リカバリ。ある時点のバックアップを空のデータベースにリストアした後、バイナリログから残りの差分を適用することで Source と同じ状態にすることができる

今回の主旨とは関係ないが、バイナリログのフォーマットには Row-based, Statement-based, Mixed-base がある。

Row-based はあるデータがどう変更されたかが記録されている。デフォルト
Statement-based は発行されたクエリが記録されている。クエリによっては結果が非決定的なリスクがある
Mixed-base は statement-based と row-based を適切に使い分ける

またレプリケーション時にトランザクションごとにグローバルな ID (GTID) が割り振られている。この ID を使うことで binlog のどこから反映すればよいかの特定などが容易になる。

MySQL :: MySQL 8.0 Reference Manual :: 17.1.3 Replication with Global Transaction Identifiers

CloudSQL ではデフォルトで Row-based フォーマット、GTID 有効となっている。

遅延箇所の切り分け

前述のように Replication Lag は SQL Thread で起こることが多いとのことだが、実環境で遅延がどこで起こっているかを切り分ける方法が CloudSQL のドキュメントに簡潔にまとまっていた。

Replication lag | Cloud SQL for MySQL | Google Cloud

GCP では Replication lag (cloudsql.googleapis.com/database/replication/replica_lag) と Network lag (cloudsql.googleapis.com/database/replication/network_lag) というモニタリング指標が提供されている。

Replication lag はいわゆる SHOW REPLICA STATUS の Seconds_Behind_Master で Source からの遅れを秒単位で記録している
Network lag は Source の Binlog が Replica の IO Thread に到着するまでの時間

Replication lag が大きい状況で Network lag が小さければ、遅延は SQL Thread で起こっていると判断することができる。

より一般的には SHOW REPLICA STATUS の結果を解釈する。

-- 出力例。
-- https://cloud.google.com/sql/docs/mysql/replication/replication-lag#verify_replication より引用。
mysql> SHOW SLAVE STATUS\G;
*************************** 1. row ***************************
               Slave_IO_State: Queueing master event to the relay log
                  Master_Host: xx.xxx.xxx.xxx
                  Master_User: cloudsqlreplica
                  Master_Port: 3306
                Connect_Retry: 60
              Master_Log_File: mysql-bin.199927
          Read_Master_Log_Pos: 83711956
               Relay_Log_File: relay-log.000025
                Relay_Log_Pos: 24214376
        Relay_Master_Log_File: mysql-bin.199898
             Slave_IO_Running: Yes
            Slave_SQL_Running: Yes
              Replicate_Do_DB:
          Replicate_Ignore_DB:
           Replicate_Do_Table:
       Replicate_Ignore_Table:
      Replicate_Wild_Do_Table:
  Replicate_Wild_Ignore_Table:
                   Last_Errno: 0
                   Last_Error:
                 Skip_Counter: 0
          Exec_Master_Log_Pos: 24214163
              Relay_Log_Space: 3128686571
              Until_Condition: None
               Until_Log_File:
                Until_Log_Pos: 0
           Master_SSL_Allowed: Yes
           Master_SSL_CA_File: master_server_ca.pem
           Master_SSL_CA_Path: /mysql/datadir
              Master_SSL_Cert: replica_cert.pem
            Master_SSL_Cipher:
               Master_SSL_Key: replica_pkey.pem
        Seconds_Behind_Master: 2627
Master_SSL_Verify_Server_Cert: No
                Last_IO_Errno: 0
                Last_IO_Error:
               Last_SQL_Errno: 0
               Last_SQL_Error:
  Replicate_Ignore_Server_Ids:
             Master_Server_Id: 321071839
                  Master_UUID: 437d04e9-8456-11e8-b13d-42010a80027b
             Master_Info_File: mysql.slave_master_info
                    SQL_Delay: 0
          SQL_Remaining_Delay: NULL
      Slave_SQL_Running_State: System lock
           Master_Retry_Count: 86400
                  Master_Bind:
      Last_IO_Error_Timestamp:
     Last_SQL_Error_Timestamp:
               Master_SSL_Crl:
           Master_SSL_Crlpath:
           Retrieved_Gtid_Set: 437d04e9-8456-11e8-b13d-42010a80027b:52111095710-52120776390
            Executed_Gtid_Set: 437d04e9-8456-11e8-b13d-42010a80027b:1-52113039508
                Auto_Position: 1
         Replicate_Rewrite_DB:
                 Channel_Name:
           Master_TLS_Version:
1 row in set (0.00 sec)

Master_Log_File (IO Thread が読み込んだ最新の Binary log ファイル名) と Relay_Master_Log_File (SQL Thread が適用した最新の Relay log ファイル名) を比較し、ここが大きく離れていれば SQL Thread で遅延しているとみなすことができる。また Network lag 相当の情報は Source の SHOW MASTER STATUS での binlog 位置と Replica のそれとを比べることで判断することができる。

なお Binary log, Relay log はファイル名に通し番号がついているので、そこを見比べで比較できるようになっている。上記の例では mysql-bin.199898 のようなフォーマットになっている。

mysqld appends a numeric extension to the binary log base name to generate binary log file names. The number increases each time the server creates a new log file, thus creating an ordered series of files.

この他にも IO Thread、SQL Thread のエラーも確認することができる。また同じ情報は GCP のモニタリング指標として Last I/O thread error number (cloudsql.googleapis.com/database/mysql/replication/last_io_errno)、Last SQL thread error number (cloudsql.googleapis.com/database/mysql/replication/last_sql_errno) が提供されている。

innodb_flush_log_at_trx_commit

SQL Thread で遅延している場合、解決策のひとつとして innodb_flush_log_at_trx_commit の調整が挙げられる。GCP のドキュメントにも記載があるとおり、前提としてこれは durability を犠牲にしてパフォーマンスを向上させるというトレードオフを伴う。

MySQL :: MySQL 8.0 Reference Manual :: 15.14 InnoDB Startup Options and System Variables

innodb_flush_log_at_trx_commit は Redo log を Disk に flush する頻度を管理しているフラグ。デフォルトは 1 でこれはトランザクションのコミットごとに flush する。そのため意図しない DB インスタンスのクラッシュなどがあった場合も、確実にトランザクションが永続化されていることを保証できる。

0 は 1 秒ごとに Redo log への書き込みと flush を行う。2 はトランザクションのコミットごとに Redo log への書き込みは行うが、flush は 1 秒おきになる。いずれも意図しないクラッシュが起こるとコミットされたトランザクションの変更が失われる可能性があるが、相対的に時間がかかる Disk への sync を非同期にすることでパフォーマンスは向上する。

一般的に Replica においては innodb_flush_log_at_trx_commit を 1 以外にする余地がある。Replica インスタンスがクラッシュし一部のトランザクションが欠けるとたいていは Replication でエラーが出て開発者が検出可能だと思われる。またクラッシュが起こった時点でその Replica を作り直すという運用方針も考えられる。

Redo Log

Redo Log について補足しておく。こちらも以前読んだ Efficient MySQL Performance から引用する。

Transaction log、あるいは単に The log と呼ばれることもある
データに変更があった際にログに書き込みディスクに永続化する
- データの耐久性のため
- buffer pool の page flushing とは別の概念
- transaction log への書き込みはすぐに (buffer pool とは別に) フラッシュされ永続化される。それとは別に buffer pool の dirty page のフラッシュがされているという考え方になる。例えば transaction log は永続化されているが、buffer pool への適用はまだ disk にフラッシュされていないという状態も起こる

sync_binlog

sync_binlog オプションについても補足しておく。Cloud SQL ドキュメントの以下のセクションには、innodb_flush_log_at_trx_commit と共に sync_binlog オプションも調整するよう記載されている。

Configure database flags | Cloud SQL for MySQL | Google Cloud

sync_binlog は、Binary log のディスクへの flush を管理するフラグ。Redo log に対する innodb_flush_log_at_trx_commit と似ている。1 はトランザクションのコミットごとで、0 は明示的な sync はしない (OS の挙動に任せる)、N (2 以上) は binary log commit group が N 以上溜まったら sync するという設定になる。デフォルトは 1 で、意図しないクラッシュ時でもトランザクションがレプリカに反映されない状況を防いでいる。

その DB インスタンスで Binary log を有効化している場合、デフォルトではトランザクションのコミットごとに、(1) Redo log への書き込みと sync、(2) Binary log への書き込みと sync が同期的に行われていることになる。innodb_flush_log_at_trx_commit を 1 以外の値に変更した場合、(1) の sync は非同期化されるが (2) は同期のままなので、あわせて sync_binlog も 1 外の値に調整しておいたほうが、よりパフォーマンス向上効果が発揮されることになる。Redo log の durability を一部犠牲にできるのなら、binlog だけコミット都度 sync にするメリットはあまりないので、合わせて調整しておくのは妥当だと思われる。

なお CloudSQL の場合、Replica インスタンスではデフォルトで Binary log は無効化されているようだった。その場合 sync_binlog の調整は必要ない。

About replication in Cloud SQL | Cloud SQL for MySQL | Google Cloud

Binary logging is supported on read replica instances (MySQL 5.7 and 8.0 only).

CloudSQL MySQL の挙動

Replication lag | Cloud SQL for MySQL | Google Cloud の以下の記載によると、CloudSQL MySQL では Replica で innodb_flush_log_at_trx_commit が変更されていて、かつクラッシュが検出された場合、自動でその Replica を作り直してれるらしい。実際に遭遇したことは無いが、運用の手間が減り助かる機能だと思う。

When the innodb_flush_log_at_trx_commit flag is set on the read replica and Cloud SQL detects that a crash might have occurred, Cloud SQL automatically recreates the replica.

CloudSQL MySQL では innodb_flush_log_at_trx_commit として 0 は指定できない。また 2 が指定されている Replica を Primary にプロモートした際には、自動で 1 に書き換えられる。

Configure database flags | Cloud SQL for MySQL | Google Cloud

参考

PR

Efficient MySQL Performance (English Edition)

英語版 Daniel Nichter (著) 形式: Kindle版

Amazon.co.jpで詳細を見る

最近読んだもの 58 - SQLite の過去現在未来など

Kosei Moriyama — Sun, 23 Apr 2023 23:20:00 +0900

SQLite: Past, Present, and Future
The tail at scale
How Big Tech Runs Tech Projects and the Curious Absence of Scrum - The Pragmatic Engineer
MySQL Data Caching Efficiency
- Innodb_buffer_pool_read_requests と Innodb_buffer_pool_reads からいわゆるバッファプールのキャッシュヒット率を計算できる
GNU/Linux shell related internals | Viacheslav Biriukov
- File descripter, pipe, process groups, terminal といった話題を解説する一連の記事
- リチャードスティーブンスの APUE のファイルに関する章のような内容を説明しているが、より現代の視点から書かれているのと、説明のテンポが良く読みやすいのがいい
MySQL 5.7 Upgrade Issue: Reserved Words
- MySQL 8 系にアップグレードすると、予約語が増える
- rank, system, skip, lead などは引っかかりやすそう
COMMIT Latency: Aurora vs. RDS MySQL 8.0
- SELECT や UPDATE はおおむねメモリ上での操作ナノに対して、COMMIT はディスクへの書き込みを伴う
- Aurora と RDS で COMMIT のレイテンシを調査したところ、Aurora のほうが安定して良い結果だった
MySQL :: What is the “(scanning)” variant of a loose index scan?
- GROUP BY などでインデックスを走査する際に、インデックスを全走査せず不要な部分を飛ばす最適化をした際に、実行計画に loose index scan と表示される
- 例えば GROUP BY でグループごとの最小値を集計する場合、インデックスのソート順がうまく使える場合は、GROUP BY の各キーの最初の値だけを見てそれ移行は飛ばすことができる
Announcing Blip: A New MySQL Monitor
- 新しい MySQL のモニタリングツール
How I became a machine learning practitioner
- OpenAI の共同創業者で元 Stripe の CTO である Greg Brockman が、OpenAI に参画してから、自分の専門性とは異なる AI 分野に対して試行錯誤した記録
- このレベルの人でも泥臭く失敗しながらやっていることが綴られていて興味深い
Connection pooling in Vitess
- Vitess のコネクションプールについて、その意義、セッション単位の設定とコネクションプールの相性の悪さ、それを回避するための各種方法など
- セッション単位の設定があるクエリでコネクションプールの旨味をできるだけ活かすために、書き換えられるものは SET_VAR に書き換えて、それが難しければ専用の接続をそのクライアント用に確保する
- Vitess15 からは Settings Pool という新しい仕組みが導入された。特定の設定に変更されたセッションをプールに保持するというアプローチ
Comparisons of Proxies for MySQL
- MySQL Proxy の比較
- 性能は haproxy > Porxy SQL だが、機能的には後者が多機能なので使い分け
- MySQLRouter はかなり悪い結果となっている
A Healthy Bundle
- Gemfile などパッケージ管理システムで定義するライブラリのバージョン指定は、特定のバージョン固定やメジャーバージョンだけ指定するなど柔軟にできるが、どのような方針で指定すべきか
- 例えば Rails といった影響範囲が大きいものは細かくバージョンを指定する、まだ安定していないライブラリ (後方互換性を壊す変更が入ったり、ブレイキングチェンジがまだまだあり得るもの) はメジャーバージョン・マイナーバージョンまで固定する悲観的な指定を、安定していて後方互換性を壊す変更が入ることもないものはバージョン指定をなくすなど楽観的な指定をする