※本記事はアフィリエイト広告(PR)を含みます。
「遅い」の次に必要なのは「どこが」です。1つの要求が通った経路を時系列で並べ、時間を食っている処理を特定します。
roadmap.sh のどこをやっているか
- 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で足りる場合があること
この記事でやること
- 追加で必要なメモリを見積もる(
free -hのavailableを確認する) - Jaeger を Docker Compose に足す(画面は外に出さない)
~/serverに自動計装を入れる。アプリのコードは1行も変えない- 実際に遅いリクエストを1本見つけて、内訳を開く(この記事の山場)
- サンプリングを設定する。使い終わったら片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| トレース | リクエスト1本の、最初から最後までの記録。 「このボタンを押したときに起きたこと全部」 |
| スパン | トレースの中の、ひとつの処理。 「MySQLに問い合わせた」「認証した」など。入れ子になる |
| トレースID | 1本のトレースに付く番号。 同じリクエストの処理には、全部これが付く |
| 計装(instrumentation) | プログラムに「いま何をしているか」を報告させる仕込みのこと。手で書けば手動計装、道具が入れれば自動計装 |
| 分散トレーシング | サーバーをまたいでもトレースが繋がるようにしたもの。「分散」はサーバーが複数ある前提という意味 |
| 可観測性(Observability) | 中を開けずに、外に出てくるものだけで中の状態が分かる度合い。メトリクス・ログ・トレースの3つで支える、と言われます |
| OTLP | OpenTelemetry Protocol。計装したデータを送るときの、共通の話し方 |
| サンプリング | 全部は記録せず、一部だけ残すこと。まびくこと |
先に — 追加で必要なメモリ
このVMには、すでにだいぶ載っています。 立ててから固まると困るので、先に測ります。
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-exporter | 400〜600MB |
| (参考)Loki + Promtail | 200〜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つ目が要る理由を、具体的な場面で書きます。
前回までで、こういう追い方ができるようになりました。
- Grafana のグラフで、応答時間が跳ねているのに気づく(メトリクス)
- その時刻のログを Loki で見る(ログ)
- エラーが出ていれば、原因が書いてある
エラーなら、これで終わります。 問題は、エラーが出ていないのに遅いときです。
[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 に足します。 前回と同じく、差分ではなく編集後の全文を出します。
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:16686 | Jaeger の画面。 127.0.0.1: を落とすとufwを素通りして世界に公開されます |
127.0.0.1:4318:4318 | OTLP over HTTP の受け口。 アプリがここに送ります |
| ボリュームを付けていない | わざとです。 メモリ保存なので、コンテナを消せばトレースも消えます。 ディスクを増やさないための選択です |
127.0.0.1:を必ず付けてください。 Jaeger の画面にはログイン画面がありません。 開けたら、誰でも中のトレースを読めます。 そしてトレースには URL・SQL・ユーザーID が入ります。前々回・前回と同じ話です。
portsを"16686:16686"と書くと、Docker が ufw の許可を飛び越えて公開します。 nginx リバースプロキシの回でやった「外に出す口は1つだけ」を、ここでも守ります。
バージョンのタグは、この記事を書いた時点のものです。 Jaeger は v2 系への移行が進んでいて、設定の書き方も画面の見た目も変わります。 最新は公式ドキュメントで確認してください。
latestにすると、ある日いきなり設定が読めなくなります。
起動します。
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 に理由が出ます。
受け口が開いているか確かめます。
405
405(Method Not Allowed)で正解です。curlはGETで聞きましたが、この口はPOSTしか受け付けません。 「口はあるが、聞き方が違う」という返事なので、開いていることの確認になります。000やConnection refusedなら、開いていません。docker compose psに戻ってください。
画面を見ます。Jaeger の画面は外に出していないので、前回の Grafana と同じくSSHで手元に引きます。 Windows の PowerShell で打ちます。
この接続をつないだまま、Windows のブラウザで http://localhost:16686/ を開きます。
Jaeger の画面が出ますが、まだ何もありません。 Service の欄に選べるものが無いはずです。まだ誰も送っていないので、正常です。
[スクリーンショット: 02_jaeger起動.png] docker compose ps で6つのコンテナが Up になっている画面を撮ってください。
アプリに自動計装を入れる
ここが、この記事で一番あっけない部分です。
アプリのコードは、1行も変えません。
入れる
VMの中で、~/server に入れます。
2つだけです。 @opentelemetry/auto-instrumentations-node は、中でたくさんのパッケージを引き連れてきます。 npm の回でやった通り、node_modules は膨らみます。消してよいものなので、気にしなくて構いません。
入ったか確かめます。
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 に足します。
末尾にこの4行を足してください。既にある行は消さないでください。
OTEL_SERVICE_NAME=myserver
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
| 変数 | 意味 |
|---|---|
OTEL_SERVICE_NAME | Jaeger の画面で選ぶ名前。 これを書かないと unknown_service になって、後で自分が困ります |
OTEL_TRACES_EXPORTER=otlp | OTLP で送る。 既定値ですが、明示します |
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf | HTTPで送る。 さきほど開けた 4318 はこちらの口です |
OTEL_EXPORTER_OTLP_ENDPOINT | 送り先。 末尾に /v1/traces を付けません。 ライブラリが足します |
localhost:4318で合っています。 アプリはコンテナの中ではなく、VMの上で直接動いているからです。前回 Grafana から Loki を呼ぶときにhttp://loki:3100と書いたのと逆なので、混ざりやすいところです。「呼ぶ側がどこにいるか」で決まります。
起動のしかたを変える
変えるのは、起動コマンドだけです。
--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を何回か叩きます。
ブラウザの 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 にかけられます。
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本あるだけで跳ねます |
| アプリ側の負荷 | スパンを作って送る処理そのもの。普通は数%ですが、ゼロではありません |
| ネットワーク | 別サーバーに送るなら、その帯域 |
そこで、まびきます。
さきほどの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:4318 | Jaeger が上がっていないか、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段ずつ戻すことです。 障害対応の回でやった順番と同じです。
- Jaeger の口は開いているか →
curlで405が返る。開いている - アプリは計装されているか →
OTEL_LOG_LEVEL=debugを付けて起動し直しても、Applying instrumentation patchが1行も無い - ということは、計装が始まっていない
原因は、起動していたのが古いターミナルのプロセスだったことでした。 --require を付けた新しいコマンドは打ったつもりで、別の窓で node app.js が動いたままだったのです。ポートは埋まっていたので、新しいほうが起動に失敗して、それに気づいていませんでした。
「設定したのに効かない」と思ったら、まず「そもそも自分の変更が動いているか」を疑う。 前回、
retention_periodで同じことを学んだはずでした。 形を変えて、同じ失敗をしました。
後片づけ
Jaeger はメモリを使い続けます。使わないなら止めてください。
まず、いまどれだけ使っているか見ます。
止めるだけなら、こうです。
止めた時点で、貯まっていたトレースは全部消えます。 メモリ保存だからです。残したいものがあれば、先にスクリーンショットを撮ってください。
もう使わないなら、イメージも消します。
compose.yaml から jaeger: の項目を消すのも忘れずに。 残っていると docker compose up -d で戻ってきます。
アプリ側も戻します。
--require を外すだけで、計装は完全に止まります。 .env に足した OTEL_ の行は、残っていても害はありません(送り先が無いので送信に失敗するだけです)が、気になるなら消してください。
パッケージごと消すなら、こうです。
~/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で足りることがある。 入れた道具は、面倒を見ることになる
参考リンク
- roadmap.sh — DevOps
- OpenTelemetry 公式
- OpenTelemetry — トレースとは
- OpenTelemetry — JavaScript / Node.js
- OpenTelemetry — 自動計装(Node.js)
- OpenTelemetry — サンプリング
- OpenTelemetry — 環境変数の一覧
- opentelemetry-js-contrib(自動計装の中身・GitHub)
- Jaeger 公式ドキュメント
- W3C Trace Context(traceparent の仕様)
- Grafana Tempo(差し替え候補のバックエンド)
次に読む
この記事は 【第6段階】インフラとコンテナ の 15 / 25 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | pushだけで反映まで終わる — DevOpsの到達作品 |
| → 次の記事 | 同じ設定を3台に手でやらない — Ansible入門 |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。

コメント