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

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

取り込み理由ダッシュボードを使用することにより、文脈の中で各取り込み理由を調査し、注目すべき構成オプションを特定します。

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

デフォルトのサンプリングメカニズムは、_ヘッドベースサンプリング_と呼ばれています。トレースを保持するか削除するかの決定は、ルートスパンの開始時になされ、その後、リクエストコンテキストの一部として他のサービスに伝播します (たとえば HTTP リクエストヘッダーとして)。

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

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

• エージェント レベルで (デフォルト)
• SDK レベルで: どの SDK メカニズムも Agent の設定をオーバーライドします。

Agent で

ingestion_reason: auto

Datadog Agent は、トレースのルートで適用するために、SDK にサンプリングレートを継続的に送信します。Agent は、トラフィックに応じてサービスに分配される、全体で 1 秒あたり 10 のトレースを取得できるようにレートを調整します。

たとえば、サービス A がサービス B よりもトラフィックが多い場合、Agent は A のサンプリングレートを変化させて、A が 1 秒間に 7 つのトレースを超えないようにし、同じように B のサンプリングレートを調整して B が 1 秒間に 3 つのトレースを超えないようにします。これにより、合計で 1 秒間に最大 10 個のトレースとなります。

リモート設定

Agent のサンプリングレート設定は、Agent バージョン 7.42.0 以上を使用している場合、リモートで設定可能です。始めるには、Remote Configuration をセットアップした後、Ingestion Control ページから ingestion_reason パラメーターを設定します。Remote Configuration を使用すると、Agent を再起動することなくパラメーターを変更できます。リモートで設定された設定内容は、環境変数や datadog.yaml からの設定を含むローカル設定よりも優先されます。

ローカル設定

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

@param target_traces_per_second - integer - optional - default: 10
@env DD_APM_TARGET_TPS - integer - optional - default: 10

注:

• Agent で設定された 1 秒あたりのトレース数のサンプリングレートは、Datadog SDK にのみ適用されます。OpenTelemetry SDK などの他の SDK には影響しません。
• 目標は固定値ではありません。実際には、トラフィックの急増や他の要因に応じて変動します。

Datadog Agent の自動サンプリングレートによってサンプリングされたトレースのスパンには、取り込み理由 auto がタグ付けされます。ingestion_reason タグは 使用状況メトリクス にも設定されています。このデフォルトメカニズムを使用しているサービスは、Ingestion Control ページ の [Configuration] (設定) 列で Automatic としてラベル付けされています。

SDK: ユーザー定義ルール

ingestion_reason: rule

よりきめ細かく制御するには、SDK のサンプリング構成オプションを使用します。

• サービスまたはリソース名ごとに、トレースのルートに適用する特定のサンプリングレートを設定し、Agent のデフォルトメカニズムをオーバーライドします。
• 1 秒間に取り込まれるトレース数のレート制限を設定します。デフォルトのレート制限は、サービスインスタンスごとに 1 秒あたり 100 トレースです。Agent のデフォルトメカニズムを使用している場合、レートリミッターは無視されます。

注: サンプリングルールは、ヘッドベースのサンプリング制御でもあります。サービスのトラフィックが設定された 1 秒あたりの最大トレース数を超える場合、ルートでトレースが削除されます。不完全なトレースは作成されません。

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

# 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", "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}]'

#using powershell
$env:DD_TRACE_SAMPLE_RATE=0.1
$env:DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

#using JSON file   
{
    "DD_TRACE_SAMPLE_RATE": "0.1",
    "DD_TRACE_SAMPLING_RULES": "[{\"service\": \"my-service\", \"resource\": \"GET /checkout\", \"sample_rate\": 0.5}]"
}

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

エラーとレアトレース

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

• エラートレース: エラーサンプリングにより、潜在的なシステム障害の可視性が提供されます。
• レアトレース: レアトレースサンプリングは、システム全体の低トラフィックサービスやリソースに対する可視性を維持します。

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

エラートレース

ingestion_reason: error

エラーサンプラーでは、ヘッドベースのサンプリングで取得されないエラースパンを含むトレースを、最大で Agent につき 1 秒あたり 10 トレースの割合で取得します。これにより、ヘッドベースのサンプリングレートが低い場合でもエラーの可視性が維持されます。

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

@param errors_per_second - integer - optional - default: 10
@env DD_APM_ERROR_TPS - integer - optional - default: 10

注:

1. エラーサンプラーを無効にするには、このパラメーターを 0 に設定します。
2. エラーサンプラーは、Agent レベルでローカルエラートレースを取得します。トレースが分散している場合、完全なトレースが Datadog に送信されないことがあります。
3. デフォルトでは、SDK のルールや manual.drop などのカスタムロジックによってドロップされるスパンは、エラーサンプラーでは除外されます。

Datadog Agent 7.42.0 以降

エラーサンプリングは、Agent バージョン 7.42.0 以降を使用している場合、リモートで設定可能です。ドキュメント に従って、Agent でリモート設定を有効にしてください。リモート構成を使用すると、Datadog Agent を再起動することなく、レアスパンの収集を有効にすることができます。

Datadog Agent 6/7.41.0 以降

SDK のルールや manual.drop などのカスタムロジックではドロップされるスパンが、エラーサンプラーに含められるようにデフォルトの動作をオーバーライドするには、この機能を有効にするため、Datadog Agent (または Kubernetes の Datadog Agent Pod 内の専用 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 の組み合わせを、Agent ごとに 1 秒あたり最大 5 トレースの割合でキャッチします。これにより、ヘッドベースのサンプリングレートが低い場合でも低トラフィックリソースの可視性が維持されます。

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

Datadog Agent 7.42.0 以降

レアサンプリングは、Agent バージョン 7.42.0 以降を使用している場合、リモートで設定可能です。ドキュメント に従って、Agent でリモート設定を有効にしてください。リモート設定を使用すると、Datadog Agent を再起動することなく、パラメーター値を変更できます。

Datadog Agent 6/7.41.0 以降

デフォルトの場合、レアサンプラーは有効になっていません。

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

レアサンプラーを構成するには、Datadog Agent のメイン構成ファイル (datadog.yaml) で apm_config.enable_rare_sampler 設定を更新するか、環境変数 DD_APM_ENABLE_RARE_SAMPLER を使用します。

@params apm_config.enable_rare_sampler - boolean - optional - default: false
@env DD_APM_ENABLE_RARE_SAMPLER - boolean - optional - default: false

SDK ルールや manual.drop のようなカスタムロジックによってドロップされるスパンを評価するには、Trace Agent で DD_APM_FEATURES=error_rare_sample_tracer_drop としてその機能を有効にします。

Datadog Agent 6/7.33 〜 6/7.40.x

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

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

レアサンプラーのデフォルト設定を変更するには、Agent のメイン構成ファイル (datadog.yaml) で apm_config.disable_rare_sampler の設定を更新するか、環境変数 DD_APM_DISABLE_RARE_SAMPLER を使用します。

@params apm_config.disable_rare_sampler - boolean - optional - default: false
@env DD_APM_DISABLE_RARE_SAMPLER - boolean - optional - default: false

強制保持と削除

ingestion_reason: manual

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

• スパンに手動保持を設定して、それとすべての子スパンを取り込むことを示します。該当するスパンがトレースのルートスパンでない場合、結果として得られるトレースが UI で適切に表示されない可能性があります。

• スパンに手動削除を設定して、子スパンが取り込まれないようにします。エラーサンプラーとレアサンプラーは、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() {
        // grab the active span out of the traced method
        Span span = GlobalTracer.get().activeSpan();
        // Always keep the trace
        span.setTag(DDTags.MANUAL_KEEP, true);
        // method impl follows
    }
}

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() {
        // grab the active span out of the traced method
        Span span = GlobalTracer.get().activeSpan();
        // Always Drop the trace
        span.setTag(DDTags.MANUAL_DROP, true);
        // method impl follows
    }
}

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

@tracer.wrap()
def handler():
    span = tracer.current_span()
    # Always Keep the Trace
    span.set_tag(MANUAL_KEEP_KEY)
    # method impl follows

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

@tracer.wrap()
def handler():
    span = tracer.current_span()
    # Always Drop the Trace
    span.set_tag(MANUAL_DROP_KEY)
    # method impl follows

Datadog::Tracing.trace(name, options) do |span, trace|
  trace.keep! # Affects the active trace
  # Method implementation follows
end

Datadog::Tracing.trace(name, options) do |span, trace|
  trace.reject! # Affects the active trace
  # Method implementation follows
end

package main

import (
    "log"
    "net/http"
    "github.com/DataDog/dd-trace-go/v2/ddtrace/ext" 
    "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func handler(w http.ResponseWriter, r *http.Request) {
    // Create a span for a web request at the /posts URL.
    span := tracer.StartSpan("web.request", tracer.ResourceName("/posts"))
    defer span.Finish()

    // Always keep this trace:
    span.SetTag(ext.ManualKeep, true)
    //method impl follows

}

package main

import (
    "log"
    "net/http"

    "github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
    "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func handler(w http.ResponseWriter, r *http.Request) {
    // Create a span for a web request at the /posts URL.
    span := tracer.StartSpan("web.request", tracer.ResourceName("/posts"))
    defer span.Finish()

    // Always drop this trace:
    span.SetTag(ext.ManualDrop, true)
    //method impl follows
}

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

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

// Always keep the trace
span.setTag(tags.MANUAL_KEEP)
//method impl follows

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

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

// Always drop the trace
span.setTag(tags.MANUAL_DROP)
//method impl follows

using Datadog.Trace;

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

    // Always keep this trace
    span.SetTag(Datadog.Trace.Tags.ManualKeep, "true");
    //method impl follows
}

using Datadog.Trace;

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

    // Always drop this trace
    span.SetTag(Datadog.Trace.Tags.ManualDrop, "true");
    //method impl follows
}

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

  if (null !== $span) {
    // Always keep this trace
    $span->setTag(\DDTrace\Tag::MANUAL_KEEP, true);
  }
?>

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

  if (null !== $span) {
    // Always drop this trace
    $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

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

たとえば、特定のサービスをモニターするために スパンからのメトリクス を構築する場合、スパンのサンプリングルールを構成することで、サービスを流れるすべてのリクエストのトレースを 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}]

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

#using JSON file   
{
    "DD_SPAN_SAMPLING_RULES": "[{\"service\": \"my-service\", \"name\": \"http.request\", \"sample_rate\": 1.0, \"max_per_second\": 50}]"
}

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

RUM トレース

ingestion_reason:rum

Web またはモバイルアプリケーションからリクエストがあると、バックエンドサービスがインスツルメントされるときにトレースが生成されます。APM と Real User Monitoring のインテグレーション により、Web およびモバイルアプリケーションからのリクエストが対応するバックエンドトレースにリンクされるため、フロントエンドとバックエンドの完全なデータを同時に確認できます。

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

他の SDK でもトレースサンプリングレートを制御できます。

Synthetic トレース

ingestion_reason:synthetics と ingestion_reason:synthetics-browser

HTTP およびブラウザテストにより、バックエンドサービスがインスツルメントされるときにトレースが生成されます。APM とSynthetic テストインテグレーション により、Synthetic テストと対応するバックエンドトレースがリンクされます。テスト実行が失敗した場合、そのテスト実行によって生成されたトレースを見て問題の根本原因にナビゲートします。

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

その他の製品

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

OpenTelemetry の取り込みメカニズム

ingestion_reason:otel

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

参考資料

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

取り込みのコントロールドキュメント トレースの保持ドキュメント 使用量メトリクスドキュメント Datadog の大規模な最適化: Zendesk におけるコスト効率に優れた観測可能性ブログ APM レート制限と保持ラーニングセンター