スパン

概要

スパンは、分散システムの中で行われた 1 つの作業を、期間を持つ単位として記録したものです。Datadog の公式用語集はスパンを、ある期間における論理的な作業の単位と説明し、公式の APM 用語ページは 1 本のトレースが 1 つ以上のスパンで構成されると述べています。この関係を押さえると、性能調査の解像度がどこで決まるのかが見えてきます。トレースだけを見ていると分かるのは「このリクエストに何秒かかったか」までで、内訳は分かりません。データベースへの問い合わせが遅いのか、外部サービスの応答を待っていたのか、自分のコードで時間を使っているのか。この切り分けを可能にしているのがスパンの入れ子構造です。この記事では、スパンが何を記録した単位なのか、親子関係がどう作られるのか、そして送ったスパンのうちどれが後から検索できるのかを順にたどります。

1 つの作業の始まりと終わりを持つ単位

Datadog の公式用語集は、スパンを分散システムにおけるある期間の論理的な作業単位と説明しています。つまりスパンは点ではなく区間です。ログが「この時刻にこの出来事が起きた」という点の記録であるのに対し、スパンは「この作業はここから始まってここで終わった」という幅を持ちます。この違いが、性能の話をするときにスパンが必要になる理由です。 1 つのスパンには名前が付きます。公式の APM 用語ページでは、動的な Web エンドポイントを web.request という静的なスパン名でまとめる例と、データベースへの問い合わせに db.query というスパン名を使う例が挙げられています。名前を静的に保つのは、URL のように無数に変わる文字列をそのまま名前にすると集計できなくなるためです。集計の軸としてはリソースという概念が別にあり、公式ページはリソースを、計装された Web エンドポイント、データベースクエリ、あるいはバックグラウンドジョブが典型だと説明しています。 スパンという単位を持たない監視では、遅さの原因を確かめる作業が推測から始まります。応答時間のグラフが跳ねたことはメトリクスで分かり、エラーが出たことはログで分かりますが、その 1 件のリクエストが 2 秒のうち何にどれだけ使ったかは、どちらからも読み取れません。結果として「たぶんデータベースだろう」と当たりを付け、ログを追加して再現を待つという回り道になります。スパンがあれば、その 1 件を開いて内訳を見るだけで済みます。調査の初動が推測ではなく観察から始まる、という違いです。

入れ子で読む - 1 リクエストの中の親子構造

スパンは並列に列挙されるのではなく、親子の入れ子として記録されます。公式の APM 用語ページは、トレースの入口となるスパンを entry-point span と呼び、そのスパン名でサービスとエンドポイントを結び付けると説明しています。サービスをまたぐ場合の仕組みも明記されており、トレース ID と親スパン ID といった識別子を HTTP ヘッダーに注入して伝播させることで、別々のサービスで生まれたスパンを 1 本の分散トレースとして縫い合わせます。

この形になっていると、時間の内訳を引き算で読めます。入口のスパンの長さから子のスパンの長さを差し引けば、そのサービス自身が使った時間が残ります。「合計 2 秒のうち 1.7 秒は外部サービスの応答待ちで、自分のコードは 0.3 秒しか使っていない」と分かれば、直す先はコードではありません。 ただし引き算がそのまま成り立つのは、子が順番に実行される場合だけです。子の処理が並行して走る構成では、子の長さを足し上げた値が親の長さを超えることもあります。入れ子の図を見るときは、縦に足せる前提を置かず、各スパンが時間軸のどこに置かれているかを見るほうが確実です。トレースの画面が滝のような形で表示されるのは、この位置関係を読ませるためです。

送るスパンと、後から検索できるスパンは別に決まる

スパンを増やせば調査が楽になる、という理解には 1 つ抜けがあります。送ったスパンすべてが、いつまでも検索できるわけではないという点です。 2026 年 8 月時点の公式の APM 用語ページには、2 つの仕組みが並べて説明されています。1 つは取り込みの制御で、最大 100% のトレースを Datadog に送り、ライブ検索と分析に使えるのは 15 分間とされています。もう 1 つがリテンションフィルタで、Datadog の画面上でタグを条件に設定し、どのスパンを 15 日間索引付けするかを決める制御だと書かれています。公式用語集では、このリテンションフィルタは索引付けと同義の仕組みとして扱われています。 運用に直すと、次のような時間の差になります。障害が起きているまさにその最中は、送っているスパンをほぼそのまま検索できます。ところが翌日に同じ条件で探すと、索引付けの対象になっていたスパンしか出てきません。「昨日は見えたのに今日は無い」という体験の正体はこれで、データが壊れたわけでも設定が消えたわけでもありません。 したがってリテンションフィルタは、費用の設定ではなく調査の設計として考えるほうが実態に合います。決めるべきなのは「どういうスパンなら 1 週間後に振り返る可能性があるか」です。エラーを含むもの、閾値を超えて遅いもの、決済のように業務上重いエンドポイントのもの。逆に、正常でかつ速い大量のスパンを全部残しても、後から見返す機会はほとんど訪れません。 課金の構造も 2 段になっています。取り込んだスパンはデータ量で、索引付けしたスパンは件数で数えられます。金額そのものは Datadog の料金ページで確認でき、保持の仕組みは保持期間とログインデックスのページで扱っています。ログの取り込みと索引付けが 2 段に分かれているのと同じ考え方が、スパンにも当てはまるという整理です。

細かくすれば分かる、とは限らない

計装を始めると、スパンをどこまで細かく作るべきかという問いに必ず行き当たります。ここは公式ドキュメントが答えを持たない領域なので、判断の軸を自分で持つ必要があります。 細かくしすぎた側の失敗は分かりやすい形で現れます。繰り返し処理の 1 周ごとにスパンを作れば、1 リクエストのスパン数は数千に達し得ます。取り込む量が増えるだけでなく、滝の図が縦に伸びて何も読み取れなくなります。スパンに付けるタグに注文番号やセッション ID のような上限のない値を入れると、カーディナリティの問題がそのまま持ち込まれ、集計の軸として使えなくなります。 粗すぎた側の失敗は静かです。サービス全体で 1 つのスパンしか作っていなければ、画面には「アプリの処理に 800 ミリ秒」とだけ出ます。数字は正しいのに、次の行動が決まりません。計装を入れた達成感の割に調査時間が縮まらないのは、この状態です。 判断の軸として使いやすいのは、「その境界でスパンを切ったとき、切り分けの結論が変わるか」という問いです。データベースと外部サービスの呼び出しを分ければ、直す先が変わります。同じ関数の中の 3 行を分けても、直す先は変わりません。結論を変えない境界にスパンを置くのは、費用と読みにくさだけを増やす作業です。 粒度が課金の対象範囲まで左右する例もあります。2026 年 8 月時点の料金ページによると、LLM Observability で課金対象になるのはモデルを呼び出す LLM スパンで、tool・workflow・retrieval のスパンは対象外とされています。同じスパンという言葉で呼ばれていても、種類によって数えられ方が違うという例で、細かく作れば必ず高くつくとも限らない、ということです。まず結論が変わる境界を洗い出し、それから量と課金を確かめる順序にしておくと、あとから計装を剥がす作業を避けられます。

同じ画面に並ぶ言葉を分けておく

APM の画面には近い言葉が同時に並ぶため、混ざったまま覚えてしまうと設定を触る場面で迷います。分けておきます。 トレースとスパンの関係は包含です。公式の APM 用語ページは、トレースがアプリケーションのリクエスト処理に費やした時間とその結果を追跡するものであり、各トレースは 1 つ以上のスパンで構成されると述べています。1 件のリクエストの全体像がトレース、その中の 1 つの作業がスパンです。 スパンとリソースは記録と集計軸の違いです。スパンは 1 回の作業の実測値で、リソースは公式ページの説明では計装された Web エンドポイントやデータベースクエリ、バックグラウンドジョブといった単位を指します。同じリソースに対する多数のスパンをまとめて、処理量や待ち時間、エラーの割合として読むわけです。1 件を見るのがスパン、傾向を見るのがリソースという分担になります。 リテンションフィルタと保持期間も別物です。前者はどのスパンを索引付けするかを選ぶルール、後者は残す期間そのものを指す値です。費用を下げたいときに触るのは前者で、調査できる範囲を決めるのは両方です。 スパンとログの違いは、区間か点かという最初の話に戻ります。両者は排他ではなく、Datadog ではタグとトレース ID を通じて相互に行き来できる設計になっています。遅い区間をスパンで特定し、その区間に出ていたログを読む、という順序が取れることが APM とログ管理を同じ基盤に置く利点です。 一次情報は Datadog の公式ドキュメント Glossary と APM Terms and Concepts にあります。製品としての位置づけは APM のページで確認できます。