アプリケーションによって生成されたスパンを 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 個のトレースとなります。

リモート設定

Agent のサンプリングレート設定は、Agent バージョン 7.42.0 以上を使用している場合、リモートで設定可能です。始めるには、Remote Configuration をセットアップした後、取り込み制御ページ から 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 のトレースライブラリにのみ適用されます。OpenTelemetry SDK などの他のトレースライブラリには影響しません。 目標は固定値ではありません。実際には、トラフィックの急増や他の要因に応じて変動します。

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

トレースライブラリ: ユーザー定義のルール

ingestion_reason: rule

よりきめ細かい制御を行うには、トレースライブラリのサンプリング構成オプションを使用します。 サービスおよび/またはリソース名ごとに、トレースのルートに適用する特定のサンプリングレートを設定し、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}]"
}

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

エラーとレアトレース

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

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

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

エラートレース

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. デフォルトでは、トレースライブラリのルールや manual.drop などのカスタムロジックによって削除されたスパンは、エラーサンプラーでは 除外されます。

Datadog Agent 7.42.0 以降

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

Datadog Agent 6/7.41.0 以降

トレースライブラリのルールや 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 以降

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

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

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

@params apm_config.enable_rare_sampler - boolean - optional - default: false
@env DD_APM_ENABLE_RARE_SAMPLER - boolean - optional - default: 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 - boolean - optional - default: false
@env DD_APM_DISABLE_RARE_SAMPLER - boolean - optional - default: false

強制保持と削除

ingestion_reason: manual

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

スパンに手動保持を設定して、それとすべての子スパンを取り込むことを示します。該当するスパンがトレースのルートスパンでない場合、結果として得られるトレースが 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

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

たとえば、特定のサービスをモニターするために スパンからのメトリクス を構築する場合、スパンのサンプリングルールを構成することで、サービスを流れるすべてのリクエストのトレースを 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 でも同様のパラメーターでトレースサンプリングレートを制御してください。

| SDK | パラメーター | 最小バージョン | |||| | ブラウザ | traceSampleRate | v4.30.0 | | iOS | tracingSamplingRate | 1.11.0 サンプリングレートは、1.13.0 以降、Ingestion Control ページで報告されます。 | | Android | traceSampleRate | 1.13.0 サンプリングレートは、1.15.0 以降、Ingestion Control ページで報告されます。 | | Flutter | tracingSamplingRate | 1.0.0 | | React Native | tracingSamplingRate | 1.0.0 サンプリングレートは、1.2.0 以降、Ingestion Control ページで報告されます。 |

Synthetic トレース

ingestion_reason:synthetics および ingestion_reason:syntheticsbrowser

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

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

その他の製品

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

| 製品 | 取り込み理由 | 取り込みメカニズムの説明 | |||| | Serverless | lambda と xray | Datadog トレースライブラリまたは AWS XRay インテグレーションでトレースした Serverless アプリケーション から受信したトレース。| | App and API Protection | appsec | Datadog トレースライブラリから取り込まれ、AAP によって脅威としてフラグ付けされたトレース。| | Data Observability: Jobs Monitoring | data_jobs | Datadog Java Tracer Spark インテグレーションまたは Databricks インテグレーションから取り込まれたトレース。|

OpenTelemetry の取り込みメカニズム

ingestion_reason:otel

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

参考資料

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

取り込みのコントロールDOCUMENTATION トレースの保持DOCUMENTATION 使用量メトリクスDOCUMENTATION Datadog の大規模な最適化: Zendesk におけるコスト効率に優れた観測可能性BLOG