アプリケーションで生成されたスパンを Datadog に送信する (取り込む) かどうかは、複数のメカニズムによって決定されます。これらのメカニズムの背後にあるロジックは、トレーシングライブラリと Datadog Agent の中にあります。構成によっては、インスツルメントされたサービスによって生成されたトラフィックの全てまたは一部が取り込まれます。

取り込まれた各スパンには、このページで説明されているメカニズムのいずれかを参照する一意の取り込み理由が付加されています。使用量メトリクスdatadog.estimated_usage.apm.ingested_bytes と datadog.estimated_usage.apm.ingested_spans は ingestion_reason によってタグ付けされています。

取り込み理由ダッシュボードを使って、それぞれの取り込み理由を確認することができます。各メカニズムに起因するボリュームの概要を把握し、どの構成オプションに焦点を当てるべきかを迅速に知ることができます。

ヘッドベースサンプリング

デフォルトのサンプリングメカニズムは_ヘッドベースサンプリング_と呼ばれています。トレースを維持するか削除するかの決定は、トレースの一番最初、ルートスパンの開始時に行われます。この決定は、HTTP リクエストヘッダーなどのリクエストコンテキストの一部として、他のサービスに伝搬されます。

この判断はトレースの最初に行われ、その後トレースのすべての部分に伝えられるため、トレースは全体として保持または削除されることが保証されます。

ヘッドベースサンプリングのサンプリングレートは、以下の 2 か所で設定できます。

• Agent レベル (デフォルト)
• トレースライブラリ**レベル: 任意のトレースライブラリのメカニズムが Agent の設定をオーバーライドします。

Agent で

ingestion_reason: auto

Datadog Agent は、トレーシングライブラリにサンプリングレートを継続的に送信し、トレースのルートで適用させます。Agent は、1 秒間に 10 個のトレースを目標にレートを調整し、トラフィックに応じて各サービスに分配します。

例えば、サービス A が B よりもトラフィックが多い場合、Agent は A のサンプリングレートを変化させて、A が 1 秒間に 7 つ以上のトレースを保持しないようにし、同様に B のサンプリングレートを調整して B が 1 秒間に 3 つのトレース、合計 1 秒間に 10 個以上のトレースを保持しないようにします。

リモート構成

Sampling rate configuration in the Agent is configurable remotely if you are using Agent version 7.42.0 or higher. To get started, set up Remote Configuration and then configure the ingestion_reason parameter from the Ingestion Control page. Remote Configuration allows you to change the parameter without having to restart the Agent. Remotely set configuration takes precedence over local configurations, including environment variables and settings from datadog.yaml.

ローカル構成

Agent のメインコンフィギュレーションファイル (datadog.yaml) または環境変数に、Agent の目標の 1 秒あたりのトレースを設定します。

@param max_traces_per_second - 整数 - オプション - デフォルト: 10
@env DD_APM_MAX_TPS - 整数 - オプション - デフォルト: 10

注:

• Agent で設定した traces-per-second サンプリングレートは、Datadog トレースライブラリにのみ適用されます。OpenTelemetry SDK など他のトレースライブラリには影響を与えません。
• The maximum traces per second is a target, not a fixed value. In reality, it fluctuates depending on traffic spikes and other factors.

Datadog Agent の自動計算されたサンプリングレートを使ってサンプリングされたトレースの全てのスパンには、取り込み理由 auto のタグが付けられています。ingestion_reason タグは、使用量メトリクスにも設定されています。Datadog Agent のデフォルトのメカニズムを使用するサービスは、Ingestion Control Page の Configuration の列で Automatic とラベル付けされます。

トレーシングライブラリ: ユーザー定義のルール

ingestion_reason: rule

よりきめ細かい制御を行うには、トレースライブラリのサンプリング構成オプションを使用します。

• Set a specific sampling rate to apply to the root of the trace, by service, and/or resource name, overriding the Agent’s default mechanism.
• 1 秒間に取り込まれるトレース数のレートリミットを設定します。デフォルトのレートリミットは、サービスインスタンスあたり 1 秒あたり 100 トレースです (Agent デフォルトメカニズムを使用している場合、レートリミッターは無視されます)。

Note: Sampling rules are also head-based sampling controls. If the traffic for a service is higher than the configured maximum traces per second, then traces are dropped at the root. It does not create incomplete traces.

構成は、環境変数で設定するか、コードで直接設定することができます。

# using system property
java -Ddd.trace.sampling.rules='[{\"service\": \"my-service\", \"resource\": \"GET /checkout\", \"sample_rate\":1},{\"service\": \"my-service\", \"sample_rate\":0.2}]' -javaagent:dd-java-agent.jar -jar my-app.jar

# using environment variables
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource":"GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource": "GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource": "GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

tracer.init({
    ingestion: {
        sampler: {
            sampleRate: 0.1,
            rules: [
                { sampleRate: 0.5, service: 'my-service' }
            ]
        }
    }
});

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

注: トレースライブラリ構成を使用してサンプリングされたトレースのすべてのスパンには、取り込み理由 rule というタグが付けられます。ユーザー定義のサンプリングルールで構成されたサービスは、Ingestion Control Page の Configuration 列で Configured としてマークされます。

エラーとレアトレース

ヘッドベースサンプリングで捕捉できなかったトレースについては、2 つの Datadog Agent の追加サンプリングメカニズムにより、重要かつ多様なトレースが保持され、取り込まれるようにします。この 2 つのサンプラーは、あらかじめ決められたタグの組み合わせをすべてキャッチすることで、多様なローカルトレースセット (同一ホストからのスパンセット) を保持します。

• Error traces: サンプリングエラーは、システムの潜在的な不具合を可視化するために重要です。
• Rare traces: レアトレースをサンプリングすることで、トラフィックの少ないサービスやリソースを確実に監視し、システム全体の可視性を維持することができます。

注: ライブラリサンプリングルールを設定したサービスでは、エラーサンプリングとレアサンプリングは無視されます。

エラートレース

ingestion_reason: error

エラーサンプラーは、ヘッドベースサンプリングでは捕捉できないエラースパンを含むトレースの断片を捕捉します。最大 10 トレース/秒 (Agent 毎) の速度でエラートレースを捕捉します。ヘッドベースのサンプリングレートが低い場合に、エラーを包括的に可視化することができます。

Agent バージョン 7.33 以降では、Agent のメインコンフィギュレーションファイル (datadog.yaml) または環境変数でエラーサンプラーを構成することが可能です。

@param errors_per_second - 整数 - オプション - デフォルト: 10
@env DD_APM_ERROR_TPS - 整数 - オプション - デフォルト: 10

注:

1. エラーサンプラーを無効にするには、このパラメーターを 0 に設定します。
2. エラーサンプラーは、Agent レベルのエラースパンを持つローカルトレースをキャプチャします。トレースが分散されている場合、完全なトレースが Datadog に送信される保証はありません。
3. デフォルトでは、トレーシングライブラリのルールや manual.drop などのカスタムロジックによってドロップされたスパンは、エラーサンプラーでは除外されます。

Datadog Agent 7.42.0 以降

The error sampling is remotely configurable if you’re using the Agent version 7.42.0 or higher. Follow the documentation to enable remote configuration in your Agents. With remote configuration, you are able to enable the collection of rare spans without having to restart the Datadog Agent.

Datadog Agent 6/7.41.0 以降

トレーシングライブラリのルールや manual.drop などのカスタムロジックによってドロップされたスパンがエラーサンプラーに含まれるようにデフォルトの動作をオーバーライドするには、Datadog Agent (または Kubernetes の Datadog Agent ポッド内の専用 Trace Agent コンテナ) で DD_APM_FEATURES=error_rare_sample_tracer_drop として機能を有効にします。

Datadog Agent 6/7.33〜6/7.40.x

エラーサンプリングのデフォルト動作は、これらの Agent のバージョンでは変更できません。Datadog Agent を Datadog Agent 6/7.41.0 以降にアップグレードしてください。

レアトレース

ingestion_reason: rare

レアサンプラーは、Datadog にレアスパンのセットを送信します。これは、env、service、name、resource、error.type、http.status の組み合わせを最大で毎秒 5 トレース (Agent 毎) 捕捉することができます。ヘッドベースのサンプリングレートが低い場合に、低トラフィックのリソースを確実に可視化することができます。

注: レアサンプラーは、Agent レベルのローカルトレースをキャプチャします。トレースが分散されている場合、完全なトレースが Datadog に送信されることを保証する方法はありません。

Datadog Agent 7.42.0 以降

The rare sampling rate is remotely configurable if you’re using the Agent version 7.42.0 or higher. Follow the documentation to enable remote configuration in your Agents. With remote configuration, you are able to change the parameter value without having to restart the Datadog Agent.

Datadog Agent 6/7.41.0 以降

デフォルトでは、レアサンプラーは有効ではありません。

注: 有効の場合、トレーシングライブラリのルールや manual.drop などのカスタムロジックによってドロップされたスパンは、このサンプラーでは除外されます。

レアサンプラーを設定するには、Agent のメインコンフィギュレーションファイル (datadog.yaml) または環境変数 DD_APM_ENABLE_RARE_SAMPLER で apm_config.enable_rare_sampler 設定を更新してください。

@params apm_config.enable_rare_sampler - ブール値 - オプション - デフォルト: false
@env DD_APM_ENABLE_RARE_SAMPLER - ブール値 - オプション - デフォルト: false

トレーシングライブラリのルールや manual.drop などのカスタムロジックによってドロップされたスパンを評価するには、Trace Agent の DD_APM_FEATURES=error_rare_sample_tracer_drop で機能を有効にします。

Datadog Agent 6/7.33〜6/7.40.x

デフォルトでは、レアサンプラーが有効になっています。

注: 有効の場合、トレーシングライブラリのルールや manual.drop などのカスタムロジックによってドロップされたスパンは、このサンプラーでは除外されます。これらのスパンをこのロジックに含めるには、Datadog Agent 6.41.0/7.41.0 以降にアップグレードしてください。

レアサンプラーのデフォルト設定を変更するには、Agent のメインコンフィギュレーションファイル (datadog.yaml) または環境変数 DD_APM_DISABLE_RARE_SAMPLER で apm_config.disable_rare_sampler 設定を更新してください。

@params apm_config.disable_rare_sampler - ブール値 - オプション - デフォルト: false
@env DD_APM_DISABLE_RARE_SAMPLER - ブール値 - オプション - デフォルト: false

強制維持と削除

ingestion_reason: manual

ヘッドベースのサンプリングメカニズムは、トレーシングライブラリレベルでオーバーライドすることができます。例えば、クリティカルなトランザクションを監視する必要がある場合、関連するトレースを強制的に保持させることができます。一方、ヘルスチェックのような不要または反復的な情報については、トレースを強制的に削除することができます。

• スパンに Manual Keep を設定して、そのスパンとすべての子スパンを取り込むように指示します。問題のスパンがトレースのルートスパンでない場合、結果のトレースは UI で不完全に表示されることがあります。

• スパンに Manual Drop を設定して、子スパンが取り込まれないようにします。エラーとレアサンプラーは Agent では無視されます。

import datadog.trace.api.DDTags;
import io.opentracing.Span;
import datadog.trace.api.Trace;
import io.opentracing.util.GlobalTracer;

public class MyClass {
    @Trace
    public static void myMethod() {
        // トレース方法からアクティブなスパンを取り除く
        Span span = GlobalTracer.get().activeSpan();
        // 常にトレースを保持
        span.setTag(DDTags.MANUAL_KEEP, true);
        // 続いて実装方法を入力
    }
}

import datadog.trace.api.DDTags;
import io.opentracing.Span;
import datadog.trace.api.Trace;
import io.opentracing.util.GlobalTracer;

public class MyClass {
    @Trace
    public static void myMethod() {
        // トレース方法からアクティブなスパンを取り除く
        Span span = GlobalTracer.get().activeSpan();
        // 常にトレースをドロップ
        span.setTag(DDTags.MANUAL_DROP, true);
        // 続いて実装方法を入力
    }
}

from ddtrace import tracer
from ddtrace.constants import MANUAL_DROP_KEY, MANUAL_KEEP_KEY

@tracer.wrap()
def handler():
    span = tracer.current_span()
    # 常にトレースを保持
    span.set_tag(MANUAL_KEEP_KEY)
    # 続いて実装方法を入力

from ddtrace import tracer
from ddtrace.constants import MANUAL_DROP_KEY, MANUAL_KEEP_KEY

@tracer.wrap()
def handler():
    span = tracer.current_span()
    # 常にトレースをドロップ
    span.set_tag(MANUAL_DROP_KEY)
    # 続いて実装方法を入力

Datadog::Tracing.trace(name, options) do |span, trace|
  trace.keep! # アクティブトレースに影響する
  # 続いて実装方法を入力
end

Datadog::Tracing.trace(name, options) do |span, trace|
  trace.reject! # アクティブトレースに影響する
  # 続いて実装方法を入力
end

package main

import (
    "log"
    "net/http"
    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ext"
    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func handler(w http.ResponseWriter, r *http.Request) {
    //  /posts URLでwebリクエストのスパンを作成
    span := tracer.StartSpan("web.request", tracer.ResourceName("/posts"))
    defer span.Finish()

    // 常にこのトレースを保持:
    span.SetTag(ext.ManualKeep, true)
    //続いて実装方法を入力

}

package main

import (
    "log"
    "net/http"

    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/ext"
    "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
)

func handler(w http.ResponseWriter, r *http.Request) {
    //  /posts URLでwebリクエストのスパンを作成
    span := tracer.StartSpan("web.request", tracer.ResourceName("/posts"))
    defer span.Finish()

    // 常にこのトレースを削除:
    span.SetTag(ext.ManualDrop, true)
    //続いて実装方法を入力
}

const tracer = require('dd-trace')
const tags = require('dd-trace/ext/tags')

const span = tracer.startSpan('web.request')

// 常にトレースを保持
span.setTag(tags.MANUAL_KEEP)
//続いて実装方法を入力

const tracer = require('dd-trace')
const tags = require('dd-trace/ext/tags')

const span = tracer.startSpan('web.request')

// 常にトレースを削除
span.setTag(tags.MANUAL_DROP)
//続いて実装方法を入力

using Datadog.Trace;

using(var scope = Tracer.Instance.StartActive("my-operation"))
{
    var span = scope.Span;

    // 常にこのトレースを保持
    span.SetTag(Datadog.Trace.Tags.ManualKeep, "true");
    //続いて実装方法を入力
}

using Datadog.Trace;

using(var scope = Tracer.Instance.StartActive("my-operation"))
{
    var span = scope.Span;

    // 常にこのトレースをドロップ
    span.SetTag(Datadog.Trace.Tags.ManualDrop, "true");
    //続いて実装方法を入力
}

<?php
  $tracer = \DDTrace\GlobalTracer::get();
  $span = $tracer->getActiveSpan();

  if (null !== $span) {
    // 常にこのトレースを保持
    $span->setTag(\DDTrace\Tag::MANUAL_KEEP, true);
  }
?>

<?php
  $tracer = \DDTrace\GlobalTracer::get();
  $span = $tracer->getActiveSpan();

  if (null !== $span) {
    // 常にこのトレースをドロップ
    $span->setTag(\DDTrace\Tag::MANUAL_DROP, true);
  }
?>

...
#include <datadog/tags.h>
#include <datadog/trace_segment.h>
#include <datadog/sampling_priority.h>
...

dd::SpanConfig span_cfg;
span_cfg.resource = "operation_name";

auto span = tracer.create_span(span_cfg);
// Always keep this trace
span.trace_segment().override_sampling_priority(int(dd::SamplingPriority::USER_KEEP));
//method impl follows

...
#include <datadog/tags.h>
#include <datadog/trace_segment.h>
#include <datadog/sampling_priority.h>
...

using namespace dd = datadog::tracing;

dd::SpanConfig span_cfg;
span_cfg.resource = "operation_name";

auto another_span = tracer.create_span(span_cfg);
// Always drop this trace
span.trace_segment().override_sampling_priority(int(dd::SamplingPriority::USER_DROP));
//method impl follows

手動によるトレース保持は、コンテキスト伝搬の前に行われるべきです。コンテキスト伝搬の後に保持される場合、システムはサービス間でトレース全体が保持されることを保証することはできません。手動によるトレース保持はトレースクライアントの位置で設定されるため、サンプリングルールに基づいて Agent またはサーバーの位置によってトレースが削除される可能性があります。

シングルスパン

ingestion_reason: single_span

特定のスパンをサンプリングする必要があるが、完全なトレースは必要ない場合、トレーシングライブラリでは、単一のスパンに設定されるサンプリングレートを設定することができます。

例えば、特定のサービスをモニターするためにスパンからのメトリクスを構築する場合、スパンのサンプリングルールを構成することで、サービスを流れるすべてのリクエストのトレースを 100% 取り込む必要がなく、これらのメトリクスが 100% のアプリケーショントラフィックに基づくことを確認することができます。

この機能は、Datadog Agent v7.40.0+ で利用可能です。

注: ヘッドベースサンプリングによって保持されているスパンをドロップするためにシングルスパンサンプリングルールを使用することはできません。ヘッドベースサンプリングによってドロップされる追加のスパンを保持するためにのみ使用できます。

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES=[{"resource": "POST /api/create_issue", "tags": { "priority":"high" }, "sample_rate":1.0}]

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

@env DD_SPAN_SAMPLING_RULES='[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]'

製品の取り込まれたスパン

RUM トレース

ingestion_reason:rum

Web アプリケーションやモバイルアプリケーションからのリクエストは、バックエンドサービスがインスツルメントされたときにトレースを生成します。APM とリアルユーザーモニタリングのインテグレーションは、Web やモバイルアプリケーションのリクエストを対応するバックエンドトレースにリンクし、フロントエンドとバックエンドの全データを 1 つのレンズで見ることができるようにします。

RUM ブラウザ SDK のバージョン 4.30.0 からは、traceSampleRate という初期化パラメーターを設定することで、取り込み量を制御し、バックエンドのトレースのサンプリングを保持することができます。traceSampleRate には 0 から 100 の間の数値を設定します。 もし traceSampleRate の値が設定されていない場合は、デフォルトでブラウザのリクエストから来るトレースの 100% が Datadog に送信されます。

同様に、他の SDK でも同様のパラメーターでトレースサンプリングレートを制御してください。

Synthetic トレース

ingestion_reason:synthetics と ingestion_reason:synthetics-browser

HTTP テストとブラウザテストは、バックエンドサービスがインストルメントされたときに、トレースを生成します。Synthetic テストと APM のインテグレーションは、 Synthetic テストを対応するバックエンドのトレースとリンクさせます。失敗したテストの実行から、そのテストの実行によって生成されたトレースを見ることで、問題の根本的な原因を突き止めることができます。

デフォルトでは、Synthetic HTTP テストとブラウザテストの 100% がバックエンドトレースを生成します。

その他の製品

いくつかの追加の取り込み理由は、特定の Datadog 製品によって生成されるスパンに起因します。

OpenTelemetry の取り込みメカニズム

ingestion_reason:otel

OpenTelemetry SDK のセットアップ (OpenTelemetry Collector または Datadog Agent を使用) に応じて、取り込みサンプリングを制御する複数の方法があります。様々な OpenTelemetry のセットアップで OpenTelemetry SDK、OpenTelemetry Collector、Datadog Agent レベルでのサンプリングに利用できるオプションの詳細は OpenTelemetry による取り込みサンプリング を参照してください。

その他の参考資料

お役に立つドキュメント、リンクや記事:

Ingestion Controlsドキュメント トレースの保持ドキュメント 使用量メトリクスドキュメント