取り込みのメカニズム

取り込みサンプリングルール

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

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

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

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

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

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

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

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

Agent で

ingestion_reason: auto

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

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

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

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

: Agent で設定した traces-per-second サンプリングレートは、Datadog トレースライブラリにのみ適用されます。OpenTelemetry SDK など他のトレースライブラリには影響を与えません。

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

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

ingestion_reason: rule

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

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

ルートサービスのみサンプリング制御を設定することができます。

: これらのルールは、ヘッドベースサンプリング制御でもあります。あるサービスのトラフィックが構成された最大トレース数/秒より大きい場合、トレースはルートでドロップされます。不完全なトレースを作成することはありません。

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

Java アプリケーションでは、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。環境変数 DD_TRACE_SAMPLING_SERVICE_RULES を使って、サービスごとのサンプリングレートを設定します。

例えば、my-service という名前のサービスのトレースの 20% を送信するには

# システムプロパティを使用する
java -Ddd.trace.sampling.service.rules=my-service:0.2 -javaagent:dd-java-agent.jar -jar my-app.jar

# 環境変数を使用する
export DD_TRACE_SAMPLING_SERVICE_RULES=my-service:0.2

環境変数 DD_TRACE_RATE_LIMIT に、サービスインスタンスごとの秒あたりのトレース数を設定して、レートリミットを構成します。DD_TRACE_RATE_LIMIT の値が設定されていない場合、1 秒あたり 100 のトレース制限が適用されます。

サンプリングコントロールについては、Java トレースライブラリドキュメントを参照してください。

Python アプリケーションでは、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。環境変数 DD_TRACE_SAMPLING_RULES を使って、サービスごとのサンプリングレートを設定します。

例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

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

環境変数 DD_TRACE_RATE_LIMIT に、サービスインスタンスごとの秒あたりのトレース数を設定して、レートリミットを構成します。DD_TRACE_RATE_LIMIT の値が設定されていない場合、1 秒あたり 100 のトレース制限が適用されます。

サンプリングコントロールについては、Python トレースライブラリドキュメントを参照してください。

Ruby アプリケーションでは、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。環境変数 DD_TRACE_SAMPLING_RULES を使って、サービスごとのサンプリングレートを設定します。

例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

@env DD_TRACE_SAMPLE_RATE=0.1
@env DD_TRACE_SAMPLING_RULES=[{"service": `my-service`, "sample_rate": 0.5}]

環境変数 DD_TRACE_RATE_LIMIT に、サービスインスタンスごとの秒あたりのトレース数を設定して、レートリミットを構成します。DD_TRACE_RATE_LIMIT の値が設定されていない場合、1 秒あたり 100 のトレース制限が適用されます。

サンプリングコントロールについては、Ruby トレースライブラリドキュメントを参照してください。

Go アプリケーションでは、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。環境変数 DD_TRACE_SAMPLING_RULES を使って、サービスごとのサンプリングレートを設定します。

例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

@env DD_TRACE_SAMPLE_RATE=0.1
@env DD_TRACE_SAMPLING_RULES=[{"service": `my-service`, "sample_rate": 0.5}]

環境変数 DD_TRACE_RATE_LIMIT に、サービスインスタンスごとの秒あたりのトレース数を設定して、レートリミットを構成します。DD_TRACE_RATE_LIMIT の値が設定されていない場合、1 秒あたり 100 のトレース制限が適用されます。

サンプリングコントロールについては、Go トレースライブラリドキュメントを参照してください。

Node.js アプリケーションの場合は、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。

また、サービス別のサンプリングレートを設定することもできます。例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

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

環境変数 DD_TRACE_RATE_LIMIT に、サービスインスタンスごとの秒あたりのトレース数を設定して、レートリミットを構成します。DD_TRACE_RATE_LIMIT の値が設定されていない場合、1 秒あたり 100 のトレース制限が適用されます。

サンプリングコントロールについては、NodeJS トレースライブラリドキュメントを参照してください。

PHP アプリケーションでは、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。環境変数 DD_TRACE_SAMPLING_RULES を使って、サービスごとのサンプリングレートを設定します。

例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

@env DD_TRACE_SAMPLE_RATE=0.1
@env DD_TRACE_SAMPLING_RULES=[{"service": `my-service`, "sample_rate": 0.5}]

サンプリングコントロールについては、PHP トレースライブラリドキュメントを参照してください。

バージョン 1.3.2 からは、Datadog C++ ライブラリは以下の構成をサポートしています。

  • グローバルサンプリングレート: 環境変数 DD_TRACE_SAMPLE_RATE
  • サービス別のサンプリングレート: 環境変数 DD_TRACE_SAMPLING_RULES
  • レートリミットの設定: 環境変数 DD_TRACE_RATE_LIMIT

例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

@env DD_TRACE_SAMPLE_RATE=0.1
@env DD_TRACE_SAMPLING_RULES=[{"service": `my-service`, "sample_rate": 0.5}]

C++ では、すぐに使えるインスツルメンテーションのインテグレーションは提供されていませんが、Envoy、Nginx、Istio などのプロキシトレーシングで利用されています。プロキシに対するサンプリングの構成方法については、プロキシのトレースで詳しく説明しています。

.NET アプリケーションでは、DD_TRACE_SAMPLE_RATE 環境変数を使って、ライブラリのグローバルサンプリングレートを設定します。環境変数 DD_TRACE_SAMPLING_RULES を使って、サービスごとのサンプリングレートを設定します。

例えば、my-service という名前のサービスのトレースを 50% 送信し、残りのトレースを 10% 送信するには

@env DD_TRACE_SAMPLE_RATE=0.1
@env DD_TRACE_SAMPLING_RULES=[{"service": `my-service`, "sample_rate": 0.5}]

環境変数 DD_TRACE_RATE_LIMIT に、サービスインスタンスごとの秒あたりのトレース数を設定して、レートリミットを構成します。DD_TRACE_RATE_LIMIT の値が設定されていない場合、1 秒あたり 100 のトレース制限が適用されます。

サンプリングコントロールについては、.NET トレースライブラリドキュメントを参照してください。

: トレースライブラリ構成を使用してサンプリングされたトレースのすべてのスパンには、取り込み理由 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

: エラーサンプラーを無効にするには、このパラメーターを 0 に設定します。

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

レアトレース

ingestion_reason: rare

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

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

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

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

強制維持と削除

ingestion_reason: manual

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

  • スパンに ManualKeep を設定して、そのスパンとすべての子スパンを取り込むように指示します。問題のスパンがトレースのルートスパンでない場合、結果のトレースは UI で不完全に表示されることがあります。
// dd-trace-go で
span.SetTag(ext.ManualKeep, true)
span.SetTag(ext.ManualDrop, true)

シングルスパン (App Analytics)

ingestion_reason: analytic

2020 年 10 月 20 日、App Analytics は Tracing without Limits に置き換わりました。これは、レガシーの App Analytics に関連する構成情報を持つ非推奨のメカニズムです。代わりに、新しい構成オプションのヘッドベースサンプリングを使用して、データ取り込みを完全に制御します。

特定のスパンをサンプリングする必要があるが、トレース全体を利用する必要がない場合、トレーサーでは、単一のスパンに対してサンプリングレートを構成することが可能です。このスパンは、包含するトレースが削除された場合でも、構成されたレートを下回ることなく取り込まれます。

トレーシングライブラリで

分析メカニズムを使用するには、環境変数またはコード内のいずれかで有効にします。また、すべての analytics_enabled スパンに適用されるサンプリングレートを定義します。

@env  DD_TRACE_ANALYTICS_ENABLED - ブール値 - オプションの false
// dd-trace-go で
// デフォルトで analytics_enabled を設定
tracerconfig.WithAnalytics(on bool)
// すべての analytics_enabled スパンに適用される生のサンプリングレートを設定
tracerconfig.SetAnalyticsRate(0.4)

任意のシングルスパンに analytics_enabled:true のタグを付けます。さらに、そのスパンに関連付けるサンプリングレートを指定します。

// dd-trace-go で
// スパン analytics_enabled を作成
span.SetTag(ext.AnalyticsEvent, true)
// 0.5 のレートでスパン analytics_enabled を作成
s := tracer.StartSpan("redis.cmd", AnalyticsRate(0.5))

Agent で

Agent では、追加のレートリミッターが 200 スパン/秒に設定されています。この制限に達した場合、一部のスパンは削除され、Datadog に転送されません。

Agent のメインコンフィギュレーションファイル (datadog.yaml) または環境変数でレートを設定します。

@param max_events_per_second - 整数 - オプションの 200
@env DD_APM_MAX_EPS - 整数 - オプションの 200

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

RUM トレース

ingestion_reason:rum

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

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

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

SDKパラメーター最小バージョン
BrowsertracingSampleRatev4.10.0
iOStracingSamplingRate1.11.0
AndroidtraceSamplingRate1.13.0
FluttertracingSamplingRate1.0.0-beta.2
React NativetracingSamplingRate1.0.0-rc6

Synthetic トレース

ingestion_reason:syntheticsingestion_reason:synthetics-browser

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

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

その他の製品

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

製品取り込み理由取り込みのメカニズムの説明
サーバーレスlambdaxrayDatadog トレーシングライブラリまたは AWS X-Ray インテグレーションでトレースしたサーバーレスアプリケーションから受信したトレース。
アプリケーション セキュリティ モニタリングappsecDatadog トレーシングライブラリから取り込まれたトレースで、ASM によって脅威としてフラグが立てられたもの。

その他の参考資料