「遅い」の次は「どこが」 — 分散トレーシング入門

分散トレーシング入門。複数のサーバーと処理時間のバーが並ぶ画面、虫眼鏡。

※本記事はアフィリエイト広告(PR)を含みます。

「遅い」の次に必要なのは「どこが」です。1つの要求が通った経路を時系列で並べ、時間を食っている処理を特定します。

roadmap.sh のどこをやっているか

DevOps/Backend›Observability
  • OpenTelemetry
  • Jaeger
  • トレースとスパン

この記事は、上の項目を実際に手を動かして確かめる回です。

前回: ステージング環境を自力で足す — 本番を壊さずに試す場所 作業場所はVMの中(Ubuntu Server)です。前回までに作った ~/monitoring(Prometheus + Grafana + Loki + Promtail)と、~/server(Express + MySQL + Redis)が動いている状態から始めます。

ここまでで、2つ手に入れました。

持っているもの答えてくれること
メトリクス(Prometheus の回)「いま遅いか」「いつから遅いか」
ログ(Loki の回)「そのとき何が起きたか」

それでも、答えが出ない質問が1つ残っていました。

「この1本のリクエスト、260ms のうち、どこで時間を使ったのか」

パフォーマンス改善の回で、私はこれをやりました。

const t0 = process.hrtime.bigint();
const tasks = await knex("tasks").where({ user_id: req.session.userId }).limit(100);
const t1 = process.hrtime.bigint();

手で、時刻を挟み込んでいます。 これは効きました。「DBだと思っていたら外部APIだった」が一発で分かったからです。

ただ、この方法にははっきりした限界があります。

  • 怪しいと思った場所にしか仕込めない。 仕込んでいない場所が犯人なら、永遠に見つからない
  • 全部の関数に書いたら、コードがそれで埋まる
  • 仕込んだ数字は console.log に流れて終わり。 並べて比べられない
  • サーバーが2つに増えたら、繋がらない。 A の 260ms のうち 200ms が B だった、が見えない

この記事でやるのは、これを道具に肩代わりさせることです。

console.time を、全部の処理に、自動で入れる。 それが分散トレーシングです。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • メトリクスとログでは「どこが遅いか」に答えられないこと。3つ目が要る理由
  • 1リクエスト=1トレース、その中の各処理=スパンで、スパンは入れ子になること
  • OpenTelemetry は道具ではなく規格だということ。だから見る場所(バックエンド)を後から差し替えられること
  • 自動計装を入れると、アプリのコードをほとんど書き換えずにトレースが出ること。なぜそんなことができるのか
  • 全部のリクエストを記録するとディスクとメモリを食うこと。サンプリングは「まびく」設定だということ
  • 1台のアプリなら、ログと console.time で足りる場合があること

この記事でやること

  1. 追加で必要なメモリを見積もる(free -h の available を確認する)
  2. Jaeger を Docker Compose に足す(画面は外に出さない)
  3. ~/server に自動計装を入れる。アプリのコードは1行も変えない
  4. 実際に遅いリクエストを1本見つけて、内訳を開く(この記事の山場)
  5. サンプリングを設定する。使い終わったら片づける

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
トレースリクエスト1本の、最初から最後までの記録。 「このボタンを押したときに起きたこと全部」
スパントレースの中の、ひとつの処理。 「MySQLに問い合わせた」「認証した」など。入れ子になる
トレースID1本のトレースに付く番号。 同じリクエストの処理には、全部これが付く
計装(instrumentation)プログラムに「いま何をしているか」を報告させる仕込みのこと。手で書けば手動計装、道具が入れれば自動計装
分散トレーシングサーバーをまたいでもトレースが繋がるようにしたもの。「分散」はサーバーが複数ある前提という意味
可観測性(Observability)中を開けずに、外に出てくるものだけで中の状態が分かる度合い。メトリクス・ログ・トレースの3つで支える、と言われます
OTLPOpenTelemetry Protocol。計装したデータを送るときの、共通の話し方
サンプリング全部は記録せず、一部だけ残すこと。まびくこと

先に — 追加で必要なメモリ

このVMには、すでにだいぶ載っています。 立ててから固まると困るので、先に測ります。

bash
$ free -h
               total        used        free      shared  buff/cache   available
Mem:           3.8Gi       2.4Gi       201Mi        12Mi       1.2Gi       1.2Gi

見るのは available の列です。前回・前々回と同じで、free ではありません。

今回足すものの目安です。

足すものメモリの目安
Jaeger(all-in-one・メモリ保存)200〜400MB
Node.js 側の計装ライブラリアプリのプロセスに +50〜100MB
今回の追加分の合計おおよそ 250〜500MB
(参考)Prometheus + Grafana + node-exporter400〜600MB
(参考)Loki + Promtail200〜400MB
監視まわりの合計おおよそ 1GB〜1.5GB

available が 1GB を切っている状態では始めないでください。 Jaeger の all-in-one は、この記事の設定ではトレースをメモリに置きます。 貯まるほど増えます。 私は VMのメモリを 4GB にしています。2GB では、MySQL・Redis・Node・Prometheus・Loki と合わせて確実に足りません。

足りないときの選び方です。上から順に試してください。

やり方どうする
前回のものを止めるcd ~/monitoring && docker compose stop loki promtail。今日はトレースだけ見る
保存する本数を減らす後述の MEMORY_MAX_TRACES を小さくする(この記事では 5000)
VMのメモリを増やすVMware側で 4GB 以上に。シャットダウンしてから変更します
飛ばす手を動かさなくても構いません。 ただし「トレースとスパン」と「やりすぎない」の節だけは読んでください

[スクリーンショット: 01_free確認.png] Jaeger を入れる前に free -h を実行した結果を撮ってください。available の値が読めることが条件です。

VM の空きがどうしても足りないときは、VM にメモリを足すほかに、検証用のサーバーを外に 1 台借りる選択肢もあります。クラウド VPS byGMOなら 4GB(仮想 4 コア・200GB)が 12 ヶ月契約で月 2,618 円、別途サーチャージ費が加わって合計月 3,927 円(税込・2026-11 時点)で、初めての申し込みなら 1GB/2GB/4GB プランに 15 日間の無料お試しがあります。お試しは最終日の 2 営業日前までに解約しないと本契約になり、料金は日割りではなく利用開始月と解約月も 1 ヶ月分かかります。

メトリクスとログの、その次

3つ目が要る理由を、具体的な場面で書きます。

前回までで、こういう追い方ができるようになりました。

  1. Grafana のグラフで、応答時間が跳ねているのに気づく(メトリクス)
  2. その時刻のログを Loki で見る(ログ)
  3. エラーが出ていれば、原因が書いてある

エラーなら、これで終わります。 問題は、エラーが出ていないのに遅いときです。

[200] GET /api/stats 268.3ms

ログにはこれしか書いてありません。 ステータスは 200、エラーは無し、ただ遅い。

ここでログにできることは、もうありません。 ログは「起きたことを1行ずつ書いたもの」で、行と行の間に何秒あったかを語る形式ではないからです。

道具形答えられること
メトリクス時系列の数字遅い / 多い / 増えた。「全体の傾向」
ログ時刻つきの文の列何が起きたか。「1つの出来事」
トレース入れ子になった時間の区間どこで何ミリ秒使ったか。「1本の中の構造」

同じ「観測」でも、形が違います。 トレースだけが「入れ子の時間」という形を持っています。 だから「内訳」に答えられます。

そして、console.time を手で書いていたときと、決定的に違う点が1つあります。

仕込む場所を、自分で選ばなくてよくなります。

怪しいところに仕込むのではなく、全部に入れてから、遅いところを探す。 順番が逆になります。

トレースとスパン

用語を2つだけ、先に確実にしておきます。ここが分かればこの記事の半分は終わりです。

1リクエスト = 1トレース。 その中のひとつひとつの処理 = スパン。

GET /api/stats を1回叩いたときの中身を、絵にするとこうなります。

トレース(全体 268ms)
└─ GET /api/stats                                    268ms  ← ルートスパン
   ├─ middleware - session                            41ms
   │  └─ redis-GET sess:abc123                         2ms
   ├─ mysql-SELECT appdb.users                         3ms
   ├─ mysql-SELECT appdb.tasks                       201ms  ← ここ
   └─ mysql-SELECT appdb.tasks                        18ms

読み方です。

見るもの意味
一番上の1本ルートスパン。 リクエスト全体。これが「合計」
字下げ入れ子。 「この処理の中で呼ばれた処理」。親子関係がある
横の長さ(実際の画面では棒)その処理にかかった時間
親より子の合計が短い差は「自分で使った時間」。 待っていない時間

そしてここが大事です。

入れ子になっているから、「内訳」が読めます。 平らな一覧では読めません。

上の例なら、268ms のうち 201ms が1本のSQLです。残りを全部速くしても、体感は変わりません。 パフォーマンス改善の回で書いた「ボトルネックは1箇所で決まる」が、そのまま目で見える形になります。

「分散」の意味も、ここで分かります。

トレース(全体 900ms)
└─ [Webサーバー] POST /api/order      900ms
   ├─ mysql-INSERT                     20ms
   └─ HTTP POST → 在庫サービス        860ms  ← 別のサーバー
      └─ [在庫サーバー] POST /reserve  850ms
         └─ mysql-SELECT              840ms  ← 真犯人はここ

サーバーが2台に分かれても、1本のトレースとして繋がっています。 これができるのは、トレースIDをHTTPヘッダーに載せて次のサーバーに渡しているからです。この受け渡し方には W3C の Trace Context という決まりがあり、traceparent というヘッダーが使われます。

この記事の構成はサーバー1台なので、2台目は出てきません。 ただ、仕組みは今日入れるものと同じです。

OpenTelemetry は「規格」であって道具ではない

ここを間違えると、記事や公式ドキュメントを読んでも噛み合いません。

OpenTelemetry(OTel)は、「観測データの形と送り方の決まり」です。 アプリではありませんし、画面もありません。

分けて考えます。

役割中身差し替えられるか
計装する側OpenTelemetry の SDK とライブラリ。アプリに入れる規格なので共通
送り方OTLP(共通の話し方)規格なので共通
受けて見せる側(バックエンド)Jaeger / Grafana Tempo / Zipkin / 各社のSaaSここが差し替えられる

これが効いてくる場面は、はっきりしています。

アプリに入れた計装を捨てずに、見る場所だけ替えられます。

昔は、道具ごとに専用のライブラリを入れる必要がありました。乗り換えるならアプリを書き直しです。だから乗り換えられませんでした。

OpenTelemetry が解いたのは、性能の問題ではなく、この「囲い込み」のほうです。

今日は Jaeger を選びますが、理由はこれだけです。

候補この記事で選ばなかった理由
Jaeger(今日使う)1コンテナで完結し、画面も付いてくる。 学習には一番速い
Grafana Tempoすでにある Grafana から見られるのは魅力。 ただし保存先の設定が要り、初回の手数が多い
Zipkin軽い。ただし OTLP まわりの情報が Jaeger より探しにくい
SaaS(各社)無料枠はあるが、アカウントを作る話になる。 VMの中で完結させたい

選んだ理由は「軽くて画面が付いている」だけです。あとで替えられます。 それが規格の効き目です。

見る場所を立てる — Jaeger

前回の ~/monitoring/compose.yaml に足します。 前回と同じく、差分ではなく編集後の全文を出します。

bash
$ nano ~/monitoring/compose.yaml
services:
  prometheus:
    image: prom/prometheus:v2.53.0
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=7d'
      - '--storage.tsdb.retention.size=1GB'
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

  grafana:
    image: grafana/grafana:11.1.0
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - "127.0.0.1:3001:3000"
    depends_on:
      - prometheus
      - loki
    restart: unless-stopped

  node-exporter:
    image: prom/node-exporter:v1.8.2
    command:
      - '--path.rootfs=/host'
    pid: host
    volumes:
      - /:/host:ro,rslave
    restart: unless-stopped

  loki:
    image: grafana/loki:3.1.0
    command: -config.file=/etc/loki/loki-config.yaml
    volumes:
      - ./loki-config.yaml:/etc/loki/loki-config.yaml:ro
      - loki-data:/loki
    ports:
      - "127.0.0.1:3100:3100"
    restart: unless-stopped

  promtail:
    image: grafana/promtail:3.1.0
    command: -config.file=/etc/promtail/config.yml
    user: root
    volumes:
      - ./promtail-config.yaml:/etc/promtail/config.yml:ro
      - /var/log:/var/log:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - /etc/machine-id:/etc/machine-id:ro
      - promtail-positions:/var/lib/promtail
    depends_on:
      - loki
    restart: unless-stopped

  jaeger:
    image: jaegertracing/all-in-one:1.57
    environment:
      COLLECTOR_OTLP_ENABLED: "true"
      MEMORY_MAX_TRACES: "5000"
    ports:
      - "127.0.0.1:16686:16686"
      - "127.0.0.1:4318:4318"
    restart: unless-stopped

volumes:
  prom-data:
  grafana-data:
  loki-data:
  promtail-positions:

足したのは jaeger: の10行だけです。 意味を1つずつ書きます。

項目意味
all-in-one受け口・保存・画面が1コンテナに入ったもの。 学習と開発用で、公式も本番向けとは言っていません
COLLECTOR_OTLP_ENABLED: "true"OTLP で受け取る口を開ける。 このバージョンでは既定で有効ですが、明示しておくと読んだ人に伝わります
MEMORY_MAX_TRACES: "5000"メモリに置くトレースの上限。 これを書かないと、古いものが消えずに増え続けます。 超えたら古い順に捨てられます
127.0.0.1:16686:16686Jaeger の画面。 127.0.0.1: を落とすとufwを素通りして世界に公開されます
127.0.0.1:4318:4318OTLP over HTTP の受け口。 アプリがここに送ります
ボリュームを付けていないわざとです。 メモリ保存なので、コンテナを消せばトレースも消えます。 ディスクを増やさないための選択です

127.0.0.1: を必ず付けてください。 Jaeger の画面にはログイン画面がありません。 開けたら、誰でも中のトレースを読めます。 そしてトレースには URL・SQL・ユーザーID が入ります。前々回・前回と同じ話です。

ports を "16686:16686" と書くと、Docker が ufw の許可を飛び越えて公開します。 nginx リバースプロキシの回でやった「外に出す口は1つだけ」を、ここでも守ります。

バージョンのタグは、この記事を書いた時点のものです。 Jaeger は v2 系への移行が進んでいて、設定の書き方も画面の見た目も変わります。 最新は公式ドキュメントで確認してください。latest にすると、ある日いきなり設定が読めなくなります。

起動します。

bash
$ cd ~/monitoring
$ docker compose up -d
$ docker compose ps
NAME                        IMAGE                            STATUS
monitoring-grafana-1        grafana/grafana:11.1.0           Up 20 seconds
monitoring-jaeger-1         jaegertracing/all-in-one:1.57    Up 22 seconds
monitoring-loki-1           grafana/loki:3.1.0               Up 22 seconds
monitoring-node-exporter-1  prom/node-exporter:v1.8.2        Up 22 seconds
monitoring-promtail-1       grafana/promtail:3.1.0           Up 20 seconds
monitoring-prometheus-1     prom/prometheus:v2.53.0          Up 22 seconds

6つとも Up になっていること。 Restarting を繰り返しているなら、docker compose logs jaeger に理由が出ます。

受け口が開いているか確かめます。

bash
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:4318/v1/traces
405

405(Method Not Allowed)で正解です。 curl は GET で聞きましたが、この口は POST しか受け付けません。 「口はあるが、聞き方が違う」という返事なので、開いていることの確認になります。 000 や Connection refused なら、開いていません。 docker compose ps に戻ってください。

画面を見ます。Jaeger の画面は外に出していないので、前回の Grafana と同じくSSHで手元に引きます。 Windows の PowerShell で打ちます。

PowerShell
PS> ssh -L 16686:127.0.0.1:16686 ユーザー名@VMのIPアドレス

この接続をつないだまま、Windows のブラウザで http://localhost:16686/ を開きます。

Jaeger の画面が出ますが、まだ何もありません。 Service の欄に選べるものが無いはずです。まだ誰も送っていないので、正常です。

[スクリーンショット: 02_jaeger起動.png] docker compose ps で6つのコンテナが Up になっている画面を撮ってください。

アプリに自動計装を入れる

ここが、この記事で一番あっけない部分です。

アプリのコードは、1行も変えません。

入れる

VMの中で、~/server に入れます。

bash
$ cd ~/server
$ npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node

2つだけです。 @opentelemetry/auto-instrumentations-node は、中でたくさんのパッケージを引き連れてきます。 npm の回でやった通り、node_modules は膨らみます。消してよいものなので、気にしなくて構いません。

bash
$ du -sh node_modules

入ったか確かめます。

bash
$ ls node_modules/@opentelemetry | head
api
auto-instrumentations-node
context-async-hooks
core
instrumentation
instrumentation-express
instrumentation-http
instrumentation-mysql2
instrumentation-redis-4

instrumentation-express、instrumentation-mysql2、instrumentation-redis-4 が並んでいます。 自分で指定していません。 「よく使われるものの計装を全部入り」で持ってくるのが auto-instrumentations-node です。

設定を環境変数で渡す

設定ファイルは書きません。すべて環境変数です。 ~/server/.env に足します。

bash
$ nano ~/server/.env

末尾にこの4行を足してください。既にある行は消さないでください。

OTEL_SERVICE_NAME=myserver
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
変数意味
OTEL_SERVICE_NAMEJaeger の画面で選ぶ名前。 これを書かないと unknown_service になって、後で自分が困ります
OTEL_TRACES_EXPORTER=otlpOTLP で送る。 既定値ですが、明示します
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufHTTPで送る。 さきほど開けた 4318 はこちらの口です
OTEL_EXPORTER_OTLP_ENDPOINT送り先。 末尾に /v1/traces を付けません。 ライブラリが足します

localhost:4318 で合っています。 アプリはコンテナの中ではなく、VMの上で直接動いているからです。前回 Grafana から Loki を呼ぶときに http://loki:3100 と書いたのと逆なので、混ざりやすいところです。「呼ぶ側がどこにいるか」で決まります。

起動のしかたを変える

変えるのは、起動コマンドだけです。

bash
$ cd ~/server
$ node --env-file=.env --require @opentelemetry/auto-instrumentations-node/register app.js

--require が1つ増えただけです。

うまくいくと、起動時にこういう行が出ます(OTEL_LOG_LEVEL=debug を付けたときだけ。既定では出ません)。

@opentelemetry/instrumentation-mysql2 Applying instrumentation patch for module
@opentelemetry/instrumentation-express Applying instrumentation patch for module
サーバー起動: http://localhost:3000

app.js が import 文で書いてある(ESM)場合は --require では効きません。 --require を --import に替えてください。 どちらか分からないときは、app.js の先頭が require( なら --require、import なら --import です。

なぜコードを変えなくても入るのか

ここは、気持ち悪いままにしないでおきます。

--require で読ませたコードが、express や mysql2 の関数を、あとから包み直しているからです。

アプリより先に動いて、「これから読み込まれるライブラリ」に割り込みます。 そして、たとえば mysql2 の「クエリを投げる関数」を、「時刻を記録 → 元の関数を呼ぶ → 時刻を記録」に置き換えます。

やっていることは、パフォーマンスの回で手で書いたのと同じです。

const t0 = process.hrtime.bigint();
const tasks = await knex("tasks")... ;
const t1 = process.hrtime.bigint();

これを、自分ではなくライブラリ側が、全部の関数に対して自動でやっている。 それだけです。魔法ではありません。

そして、ここが限界でもあります。

自動計装が知っているライブラリしか、包めません。 あなたが自分で書いた関数は、名前も意味も知られていないので、スパンになりません。

自分の関数を測りたくなったら、そこだけ手で足します。(今日は必須ではありません)

const { trace } = require("@opentelemetry/api");
const tracer = trace.getTracer("myserver");

async function makeReport(userId) {
  return tracer.startActiveSpan("makeReport", async (span) => {
    try {
      // もとの処理
    } finally {
      span.end();   // ⚠️ これを忘れると、そのスパンは永遠に終わりません
    }
  });
}

手動計装は「自動が拾えないところだけ」に使います。 最初から全部手で書くと、console.time に戻るだけです。

送れているか確かめる

別のターミナルで、APIを何回か叩きます。

bash
$ cd ~/server
$ curl -s -c cookie.txt -X POST http://localhost:3000/api/login \
    -H "Content-Type: application/json" \
    -d '{"email":"me@example.com","password":"pass12345"}' > /dev/null

$ for i in $(seq 1 20); do curl -s -o /dev/null -b cookie.txt http://localhost:3000/api/tasks; done

ブラウザの http://localhost:16686/ を再読み込みします。

左上の Service に myserver が出ていれば、届いています。 Find Traces を押すと、いま叩いた分が並びます。

出てこないときは、まずアプリ側の起動ログを見てください。 ECONNREFUSED 127.0.0.1:4318 が出ていれば、Jaeger に届いていません。 つまずいたところへ。

[スクリーンショット: 03_トレース一覧.png] Jaeger の画面で myserver のトレースが一覧に並んでいるところを撮ってください。1本ずつの所要時間が読めることが条件です。

遅い1本を開いて、内訳を見る

ここがこの記事の中心です。 一覧を眺めるのは目的ではありません。

遅い1本を探す

Jaeger の一覧には、時間の長い順に並べ替える指定があります。 画面右上あたりの並べ替えで Longest First(最長順)を選びます。

項目の名前と位置はバージョンで変わります。 見当たらなければ、一覧の散布図で右のほう(=時間が長いほう)の点をクリックしても同じことができます。

分かりやすい獲物が無ければ、意図的に作ります。 パフォーマンス改善の回で作ったN+1のエンドポイントか、索引を消したテーブルを叩いてください。あの回で潰したものを、もう一度出します。

開く

遅い1本をクリックすると、横向きの棒が縦に並んだ画面が出ます。 これがトレースの中身です。

この記事の実機では、GET /api/stats の1本がこうなっていました。

GET /api/stats                                            268.31ms
├─ middleware - expressInit                                 0.12ms
├─ middleware - session                                    41.02ms
│  └─ redis-GET                                             1.98ms
├─ request handler - /api/stats                           226.44ms
│  ├─ mysql2-SELECT appdb.users                             3.11ms
│  ├─ mysql2-SELECT appdb.tasks                            201.77ms
│  └─ mysql2-SELECT appdb.tasks                             18.90ms
└─ ...

数字は環境で変わります。 形だけ見てください。

ここで、目で読めることが3つあります。

① appdb.tasks に、3回問い合わせている

1本のリクエストで、同じテーブルを3回引いています。 ソースを読んで気づいたのではなく、画面に3本並んでいるから気づきました。

これが、console.time では手に入らなかったものです。 手で仕込むとき、私は「DBは1回だろう」と思って1組しか挟みませんでした。 回数を数えるという発想が無かったからです。

② 268ms のうち 201ms が、その中の1本

残りを全部ゼロにしても、201ms は残ります。 直すべき場所は、議論の余地なく1つに決まりました。

③ session の 41ms

認証だけで 41ms 使っています。 Redis の回で入れたはずのセッションが、Redis を引いたあとに何かしているように見えます。これは今日の主役ではありませんが、次に見る場所として控えておけます。

スパンを1つ開く

棒をクリックすると、その処理の詳細(タグ)が出ます。 mysql2-SELECT を開くと、こういう情報が入っています。

db.system         mysql
db.name           appdb
db.statement      SELECT * FROM `tasks` WHERE `user_id` = ?
net.peer.name     localhost
net.peer.port     3306

db.statement に、実際のSQLが入っています。 ここが後で効きます(サンプリングと秘密情報の節)。

このSQLを、そのまま パフォーマンス改善の回でやった EXPLAIN にかけられます。

bash
$ sudo mysql
USE appdb;
EXPLAIN SELECT * FROM tasks WHERE user_id = 1;

トレースは「どこが遅いか」までしか言いません。 「なぜ遅いか」は EXPLAIN の仕事です。 道具の役割分担は、ここでも同じです。 メトリクスで気づき、トレースで場所を絞り、EXPLAIN で理由を見て、直す。

N+1 は、トレースだと一目で分かる

もし N+1 のエンドポイントを叩いたなら、画面はこうなります。

GET /api/tasks-with-comments                             1,204.55ms
├─ mysql2-SELECT appdb.tasks                                4.10ms
├─ mysql2-SELECT appdb.comments                             9.82ms
├─ mysql2-SELECT appdb.comments                             9.44ms
├─ mysql2-SELECT appdb.comments                             9.71ms
│  (同じ行が100本続く)

これが N+1 の見た目です。 短いスパンが、同じ形で延々と並びます。 1本ずつは 10ms 以下です。「遅いクエリ」を探しても、どれも引っかかりません。 数が問題だからです。 スロークエリログでは、これは見つかりません。 トレースの一番分かりやすい勝ち筋がここです。

[スクリーンショット: 04_遅いトレースの内訳.png] 遅いトレースを1本開いて、中のスパンが入れ子で並んでいる画面を撮ってください。どれか1本だけ長い、または同じスパンが何本も並んでいることが読めるものが理想です。

どこまで採るか — サンプリング

ここまでは、全部のリクエストを記録していました。 練習では正しいですが、そのままにはできません。

1リクエストにつき、スパンが10本から100本以上できます。 ログの何倍ものデータが出ます。

具体的に何が起きるかです。

困ること中身
Jaeger のメモリこの記事の設定はメモリ保存。MEMORY_MAX_TRACES の上限に当たって、古いものから消えます
ディスク(保存先を使う構成なら)ログより速く増えます。 N+1 のあるAPIが1本あるだけで跳ねます
アプリ側の負荷スパンを作って送る処理そのもの。普通は数%ですが、ゼロではありません
ネットワーク別サーバーに送るなら、その帯域

そこで、まびきます。

bash
$ nano ~/server/.env

さきほどの4行に、2行足します。

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
変数意味
traceidratioトレースIDを見て、決めた割合だけ残す。 0.1 なら10本に1本
parentbased_「呼び出し元が残すと決めたなら、自分も残す」。 これが無いと、サーバーをまたいだときにトレースが途中で切れます

サーバーを立て直して、20回叩いてみてください。 Jaeger に出るのは2本前後のはずです。

parentbased_ の意味は、サーバー1台では実感できません。 ただ、2台目を足した日に効きます。 「Aは残すと決めたのにBが捨てた」を防ぐための指定です。

割合の決め方に、正解はありません。 考え方だけ書きます。

状況目安理由
学習・開発(いまここ)1.0(全部)数が少ない。 叩いたものが出ないと練習にならない
アクセスの少ない個人サービス0.1〜1.0全部でも大した量にならない
アクセスの多いサービス0.01 以下も普通100本に1本でも、傾向は十分見える

まびくと、「あの1本」が残っていない可能性が出ます。 たまたま遅かった1本を追いたいのに、それが捨てられている。 これがサンプリングの代償です。 「エラーになったトレースだけ必ず残す」「遅かったものだけ残す」というやり方(テールサンプリング)もありますが、送られてきた後で判断する部品が別に要ります。 今日はやりません。そういう手があると知っていれば十分です。

練習を続けるなら、いったん 1.0 に戻して構いません。

OTEL_TRACES_SAMPLER_ARG=1.0

トレースには、中身が全部入っている

サンプリングと並んで、先に言っておくべきことです。

さきほど開いたスパンには、こう入っていました。

db.statement      SELECT * FROM `tasks` WHERE `user_id` = ?
http.target       /api/tasks?token=abcdef123456

前回、ログについて同じことを書きました。 トレースはもっと露骨です。

入ってしまうものどこから
SQL文db.statement。値を埋め込む書き方をしていると、値まで入ります
URLのクエリ文字列http.target。トークンをURLに入れていたら、全部残ります
ユーザーID自分で足したタグや、SQLの条件

だから、127.0.0.1: を付けました。 Jaeger の画面にはログインがありません。

やることは、前回と同じです。

  • 秘密情報をURLのクエリに入れない(REST APIの設計の回)
  • 見る場所を外に出さない
  • 消したくなったら、コンテナごと消す(メモリ保存なので、これで消えます)

「潰す」より「出さない」。 前回と同じ結論です。

やりすぎない

ここまで書いておいて逆のことを言いますが、これも書きます。

アプリが1台で、コードが自分の手の中にあるなら、ログと console.time で足ります。

パフォーマンスの回で書いた「泥臭く見えますが、これが正解です」は、いまも正しいです。 今日やったのは、その上位互換ではなく、別の道具です。

トレースの価値が出るのは、ここからです。

状況トレースの価値
アプリ1本・自分だけが書いた薄い。 console.time を4箇所に挟むほうが速い
アプリ1本+DB+キャッシュ+外部API(いまここ)少しある。 「回数」が見えるのが効く。N+1 は明確に得意
人が書いたコードを読むはっきりある。 どこを通っているか知らなくても内訳が出る
サーバーが2台以上はっきりある。 どちらが遅いかを、ログの突き合わせなしで言える
Kubernetes・マイクロサービス必須に近い。 Podは消えます。 呼び出しの連鎖を人が追うのは無理

そして、前回と同じコストが、ここにも付いてきます。

トレースの仕組み自体が、面倒を見る対象です。

  • Jaeger が落ちたら、トレースは消えます(この構成では、そもそもメモリなので再起動で消えます)
  • アプリの起動コマンドが変わりました。 systemd のユニットや GitHub Actions のデプロイにも、同じ変更が要ります
  • 送り先が落ちているとき、アプリ側にエラーが出続けます(送信は諦めるので止まりはしませんが、ログは汚れます)

この記事で入れた価値は、私の場合はっきりしていました。

同じテーブルに3回問い合わせていたことを、コードを読まずに見つけたこと。

これは console.time では見つけられませんでした。 1組しか挟んでいなかったからです。 「回数を数えていなかった」という自分の見落としを、道具が代わりに見つけたということです。

逆に、判断の基準はこれだけです。

「みんな使っているから」ではなく、「いま自分が、何を見落としていると思うか」。

つまずいたところ

症状原因と直し方
Jaeger の Service に何も出ないアプリを --require 付きで起動していない。 起動コマンドを確認。古いプロセスが残っていることもあります(ps aux | grep app.js)
Service が unknown_service:node になるOTEL_SERVICE_NAME を書き忘れている。 .env に足して再起動
アプリ起動時に ECONNREFUSED 127.0.0.1:4318Jaeger が上がっていないか、4318 を公開していない。 docker compose ps と compose.yaml の ports を確認
--require を付けたのに何も起きないapp.js が ESM(import 文)。 --require を --import に替える
トレースは出るが、SQL のスパンが無いmysql2 ではなく別のドライバを使っているか、knex が内部で使うドライバが対応表に無い。 ls node_modules/@opentelemetry に該当の instrumentation-* があるか見る
スパンが全部ぶつ切りで、親子にならない手で startActiveSpan を書いた場所で span.end() を呼び忘れているか、コールバックの外で作っている
http://localhost:16686/ が開かないSSHポートフォワードを繋いだままにしていない。 PowerShell の窓を閉じると切れます
叩いたのに一覧に出ないサンプリングを 0.1 にしたまま。 練習中は 1.0 に戻す
VMが重い・固まるメモリ不足。 free -h を見て、docker compose stop loki promtail で一時的に空ける
Jaeger を再起動したらトレースが消えた仕様です。 この構成はメモリ保存。残したいなら保存先の設定が要ります

一番時間を取られたのは、--require でした。

入れて、環境変数も書いて、起動して、Jaeger を開いても、Service に何も出ません。 エラーも出ません。「送っていない」のか「届いていない」のかも分かりませんでした。

やったのは、切り分けを1段ずつ戻すことです。 障害対応の回でやった順番と同じです。

  1. Jaeger の口は開いているか → curl で 405 が返る。開いている
  2. アプリは計装されているか → OTEL_LOG_LEVEL=debug を付けて起動し直しても、Applying instrumentation patch が1行も無い
  3. ということは、計装が始まっていない

原因は、起動していたのが古いターミナルのプロセスだったことでした。 --require を付けた新しいコマンドは打ったつもりで、別の窓で node app.js が動いたままだったのです。ポートは埋まっていたので、新しいほうが起動に失敗して、それに気づいていませんでした。

「設定したのに効かない」と思ったら、まず「そもそも自分の変更が動いているか」を疑う。 前回、retention_period で同じことを学んだはずでした。 形を変えて、同じ失敗をしました。

後片づけ

Jaeger はメモリを使い続けます。使わないなら止めてください。

まず、いまどれだけ使っているか見ます。

bash
$ docker stats --no-stream
$ free -h

止めるだけなら、こうです。

bash
$ cd ~/monitoring
$ docker compose stop jaeger

止めた時点で、貯まっていたトレースは全部消えます。 メモリ保存だからです。残したいものがあれば、先にスクリーンショットを撮ってください。

もう使わないなら、イメージも消します。

bash
$ cd ~/monitoring
$ docker compose stop jaeger
$ docker compose rm -f jaeger
$ docker image rm jaegertracing/all-in-one:1.57
$ docker system df

compose.yaml から jaeger: の項目を消すのも忘れずに。 残っていると docker compose up -d で戻ってきます。

アプリ側も戻します。

bash
$ cd ~/server
$ node --env-file=.env app.js

--require を外すだけで、計装は完全に止まります。 .env に足した OTEL_ の行は、残っていても害はありません(送り先が無いので送信に失敗するだけです)が、気になるなら消してください。

パッケージごと消すなら、こうです。

bash
$ cd ~/server
$ npm uninstall @opentelemetry/api @opentelemetry/auto-instrumentations-node
$ du -sh node_modules

~/server と appdb、~/monitoring の Prometheus と Grafana は残してください。 続きの回で使います。

まとめ

  • メトリクスは「遅い」、ログは「何が起きたか」、トレースは「どこで何ミリ秒使ったか」。 形が違うから、答えられることが違う
  • トレースだけが「入れ子になった時間」という形を持つ。 だから内訳が読める
  • 1リクエスト=1トレース、その中の処理=スパン。 スパンは親子になる
  • サーバーをまたいでも繋がるのは、トレースIDをHTTPヘッダーで渡しているから(traceparent)
  • OpenTelemetry は規格。 アプリではないし、画面も無い。だから見る場所を後から差し替えられる
  • Jaeger を選んだ理由は「1コンテナで画面まで付いてくる」だけ。 替えられる
  • 自動計装は、ライブラリの関数をあとから包み直しているだけ。 魔法ではない
  • 自動計装が知らないライブラリと、自分で書いた関数は、スパンにならない
  • console.time との一番の違いは、「仕込む場所を自分で選ばなくていい」こと。 回数の見落としが消える
  • N+1 はトレースの一番の得意分野。 1本ずつは速いので、スロークエリログには出ない
  • トレースはログより量が多い。 1リクエストで10〜100本以上のスパンが出る
  • サンプリングは「まびく」設定。 まびいた1本が、見たかった1本かもしれない
  • parentbased_ を付ける。 1台では実感できないが、2台目を足した日に効く
  • トレースにはSQLもURLもユーザーIDも入る。 画面を外に出さない。秘密はURLに入れない
  • 入れると、起動コマンドが変わる。 デプロイの設定にも同じ変更が要る
  • アプリ1台なら、ログと console.time で足りることがある。 入れた道具は、面倒を見ることになる

参考リンク


次に読む

この記事は 【第6段階】インフラとコンテナ の 15 / 25 本目です。

記事
← 前の記事pushだけで反映まで終わる — DevOpsの到達作品
→ 次の記事同じ設定を3台に手でやらない — Ansible入門

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次