リテンションフィルター
リテンションフィルターとは、Datadog APM が取り込んだスパンのうち、15 日間検索できる索引 (Indexed Spans) に残すものをタグ条件と保持率で決める規則のこと。送る量を絞る取り込みコントロールとは別の段で働く。
概要
リテンションフィルターは、Datadog に届いたスパンを「索引に残すか、残さないか」で振り分ける規則です。フィルターごとにタグ条件のクエリと 0〜100% の保持率を持ち、条件に合うスパンのうち保持率ぶんが 15 日間の索引に入って Trace Explorer で検索できるようになります。Datadog が常時動かす Intelligent Retention Filter、エラーを残す既定のフィルター、そして自分で作るカスタムフィルターの 3 層で構成されます。気にする場面は、障害の調査で「あのトレースが見つからない」と困ったとき、索引スパンの割当を超えて課金が増えたとき、そして重要な取引だけは必ず残したいと決めるときです。
取り込んだスパンのうち、15 日間残すものを選ぶ規則
リテンションフィルターは、Datadog APM に取り込まれたスパンのうち、どれを 15 日間保持される索引に入れるかを決める規則です。公式ドキュメントは、取り込み後のスパンが「アカウントに設定されたリテンションフィルターに従って 15 日間保持される」と説明しています (2026 年 9 月時点・出典: Trace Retention)。1 つのフィルターは、名前、タグを条件にしたクエリ、そして条件に合ったスパンの何 % を索引に入れるかを示す保持率で構成され、保持されるスパンは条件に合うものから一様に選ばれます。索引に入ったスパンは Trace Explorer、ダッシュボード、モニターから 15 日間扱えます。Intelligent Retention Filter の多様性サンプリング分だけは 30 日残ります。作成や変更には apm_retention_filter_write の権限が必要です。
送る量と残す量は別の段で決まる
スパンが検索できる状態になるまでには 2 つの関門があります。前段の取り込みコントロールは Datadog へ送る量を決め、後段のリテンションフィルターは送られてきた量のうち索引に残す量を決めます。
- アプリケーションがスパンを生成する
- 取り込みコントロール: Agent とトレーサーの設定で、Datadog へ送る割合を決める (送る量)
- リテンションフィルター: 届いたスパンをタグ条件と保持率で振り分ける (残す量)
- Indexed Spans: 選ばれたスパンが 15 日間の索引に入り、検索と集計の対象になる
この 2 段を分けて考えないと、送る量を絞ったのに索引スパンの費用が変わらない、あるいは全量を送っているのに障害時のトレースが見つからない、という食い違いに悩みます。前段の仕組みは取り込みコントロールの項に譲り、ここでは後段だけを扱います。
3 層のフィルター - 常時稼働のものと自分で作るもの
公式ドキュメントはリテンションフィルターを 3 層で説明しています (2026 年 9 月時点・出典: Trace Retention)。
| 層 | 何を残すか | 索引スパンの使用量 |
|---|---|---|
| Intelligent Retention Filter (常時稼働) | 多様性サンプリング = 環境 / サービス / 操作 / リソースの組み合わせごとに 15 分に少なくとも 1 スパン、p75 / p90 / p95 の高レイテンシ、エラーの代表例を 30 日。加えて trace_id 基準の一様 1% サンプリングと、RUM セッション 1% に連動したトレース | 数えない (請求に影響しない) |
| 既定フィルター | Error Default が status:error のスパンを残す (クエリと保持率は変更可 / 無効化も可)。App and API Protection / Synthetics / Dynamic Instrumentation を使っていれば各既定も有効 | 数える |
| カスタムフィルター | 任意のスパンタグや属性のクエリに、条件に合うスパンの何 % を残すかの span rate を設定。任意で、そのトレース全体を残す割合の trace rate も設定できる | 数える。trace rate は使用量を大きく増やし得る |
フィルターは上から順に評価され、上流のフィルターが残したスパンは下流のフィルターの編集画面に現れません。残った理由はスパンの retained_by 属性に入り、retention_filter / trace_retention_filter / diversity_sampling / flat_sampled の値で見分けられます。「なぜこのトレースは残ったのか」を確かめる入口はこの属性です。
割当と課金にどう効くか
索引スパンには割当があります。2026 年 8 月時点の公式料金ページでは、APM ホスト 1 台につき月 100 万スパン (15 日保持) が含まれ、全ホストで合算されます (出典: Datadog Pricing)。本記事は課金の仕組みを解説するものです。具体的な単価や料金は Datadog 公式の料金ページで確認してください。Intelligent Retention Filter が残すスパンはこの使用量に数えられず、請求に影響しないと公式ドキュメントは明記しています (2026 年 9 月時点・出典: Trace Retention)。使用量を動かすのは既定とカスタムのフィルターで、特に trace rate は条件に合わない親子スパンまで索引に入れるため、使用量が大きく増え得ると警告されています。作成や変更の際は索引量が何 % 変わるかの見積りが表示されるので、保存前にこの数字を見る習慣が費用の事故を防ぎます。割当を超えた分の単価と見積りの手順は Datadog APM 料金の考え方に譲ります。
索引から外れたスパンは消えたわけではない
フィルターで索引に入らなかったスパンは、検索の対象から外れるだけです。索引に入ったスパンを Trace Explorer で開くと、同じトレースの親子スパンが索引されていなくても、フレームグラフには完全なトレースの文脈が表示されます (2026 年 9 月時点・出典: Trace Retention)。検索で見つかるのは索引されたスパンだけ、見つけた後に読めるのはトレース全体、という 2 つの範囲を分けて覚えておくと、調査で迷いません。送ったスパンと後から検索できるスパンが別に決まる事情は、スパンの項に譲ります。逆向きの取り違えも 1 つあります。Intelligent Retention Filter が残したスパンは、APM のトレース分析モニターの評価から除外されます。モニターで数えたい条件は、自分のカスタムフィルターで明示的に残す必要があります。分散トレーシングを「全部残す」前提で設計せず、残す規則を先に決めるのが、この仕組みとの付き合い方です。