取り込みのメカニズム

アプリケーションで生成されたスパンを 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 の取り込み構成のためのリモート構成はベータ版です。アクセスリクエストは Datadog サポートにご連絡ください。

Agent のバージョン 7.42.0 以降を使用している場合、Agent のサンプリングレート構成はリモートで構成可能です。Agent でリモート構成を有効にする方法については、リモート構成の仕組みをお読みください。リモート構成では、Agent を再起動することなく、パラメーターを変更することができます。

ローカル構成

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

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

注:

リモートで構成されたパラメーターは、ローカルでの構成 (環境変数や datadog.yaml の構成) よりも優先されます。
PHP アプリケーションの場合は、代わりにトレーシングライブラリのユーザー定義ルールを使用してください。
Agent で設定した traces-per-second サンプリングレートは、PHP 以外の 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_RULES を使って、サービスごとのサンプリングレートを設定します。

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

# ステムプロパティを使用する
java -Ddd.trace.sampling.rules='[{\"service\": \"my-service\", \"sample_rate\":0.2}]' -javaagent:dd-java-agent.jar -jar my-app.jar

# 環境変数を使用する
export DD_TRACE_SAMPLING_RULES=[{"service": "my-service", "sample_rate": 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}]

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

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

例えば、トレースの 10% を送信するには

@env DD_TRACE_SAMPLE_RATE=0.1

サンプリングコントロールについては、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}]

サンプリングコントロールについては、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' }
            ]
        }
    }
});

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

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}]

サンプリングコントロールについては、.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 に送信される保証はありません。
デフォルトでは、トレーシングライブラリのルールや manual.drop などのカスタムロジックによってドロップされたスパンは、エラーサンプラーでは除外されます。

Datadog Agent 7.42.0 以降

この機能は現在ベータ版です。この機能へのアクセスをリクエストするには、Datadog サポートにご連絡ください。

Agent のバージョン 7.42.0 以降を使用している場合、レアサンプリングはリモート構成が可能です。ドキュメントに従って、Agent のリモート構成を有効にしてください。リモート構成を使用すると、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 以降

この機能は現在ベータ版です。この機能へのアクセスをリクエストするには、Datadog サポートにご連絡ください。

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 - ブール値 - オプション - デフォルト: 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>
...

auto tracer = ...
auto span = tracer->StartSpan("operation_name");
// 常にこのトレースを保持
span->SetTag(datadog::tags::manual_keep, {});
//続いて実装方法を入力

手動でトレースを削除:

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

auto tracer = ...
auto another_span = tracer->StartSpan("operation_name");
// 常にこのトレースを削除

another_span->SetTag(datadog::tags::manual_drop, {});
//続いて実装方法を入力

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

シングルスパン

ingestion_reason: single_span

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

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

注: この機能は、Datadog Agent のバージョン 7.40.0 から利用可能です。

トレーシングライブラリのバージョン 1.7.0 から、Java アプリケーションの場合、環境変数 DD_SPAN_SAMPLING_RULES でサービス名別と操作名別の span サンプリングルールを設定します。

例えば、my-service という名前のサービスから、http.request という操作で、1 秒間に最大 50 スパンを 100% 収集するには

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

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

バージョン v1.4.0 以降、Python アプリケーションでは、環境変数 DD_SPAN_SAMPLING_RULES でサービス名別と操作名別の span サンプリングルールを設定します。