Plusieurs mécanismes déterminent si les spans générés par vos applications sont envoyés à Datadog (ingérés). La logique derrière ces mécanismes se trouve dans les SDKs et dans l’Agent Datadog. Selon la configuration, tout ou une partie du trafic généré par les services instrumentés est ingéré.

Chaque span ingéré a une raison d’ingestion unique qui fait référence à l’un des mécanismes décrits sur cette page. Les métriques d’utilisation datadog.estimated_usage.apm.ingested_bytes et datadog.estimated_usage.apm.ingested_spans sont étiquetées par ingestion_reason.

Utilisez le tableau de bord des raisons d’ingestion pour examiner chaque raison d’ingestion dans son contexte et identifier les options de configuration sur lesquelles se concentrer.

Échantillonnage basé sur la tête

Le mécanisme d’échantillonnage par défaut s’appelle échantillonnage basé sur la tête. La décision de conserver ou de supprimer une trace est prise au début du span racine et ensuite propagée à d’autres services dans le cadre de leur contexte de demande (par exemple, en tant qu’en-tête de requête HTTP).

Parce que la décision est prise au début de la trace et transmise à toutes les parties, la trace est conservée ou supprimée dans son ensemble.

Vous pouvez définir les taux d’échantillonnage pour l’échantillonnage en amont à deux endroits :

• Au niveau de l’Agent (par défaut)
• Au niveau du SDK : tout mécanisme SDK remplace la configuration de l’Agent.

Dans l’Agent

ingestion_reason: auto

L’Agent Datadog envoie en continu des taux d’échantillonnage aux SDK pour les appliquer à la racine des traces. L’Agent ajuste les taux pour atteindre un objectif de dix traces par seconde au total, réparties entre les services en fonction du trafic.

Par exemple, si le service A a plus de trafic que le service B, l’Agent pourrait varier le taux d’échantillonnage pour A de sorte que A ne conserve pas plus de sept traces par seconde, et ajuster de manière similaire le taux d’échantillonnage pour B afin que B ne conserve pas plus de trois traces par seconde, pour un total de 10 traces par seconde.

Configuration à distance

La configuration du taux d’échantillonnage dans l’Agent est configurable à distance si vous utilisez la version de l’Agent 7.42.0 ou supérieure. Pour commencer, configurez Configuration à distance puis paramétrez le paramètre ingestion_reason depuis la page de contrôle d’ingestion. La Configuration à distance vous permet de modifier le paramètre sans redémarrer l’Agent. La configuration à distance a la priorité sur les configurations locales, y compris les variables d’environnement et les paramètres de datadog.yaml.

Configuration locale

Définissez le nombre de traces par seconde de l’Agent dans son fichier de configuration principal (datadog.yaml) ou en tant que variable d’environnement :

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

Notes :

• Le taux d’échantillonnage en traces par seconde défini dans l’Agent ne s’applique qu’aux SDK Datadog. Il n’a aucun effet sur d’autres SDK tels que les SDK OpenTelemetry.
• La cible n’est pas une valeur fixe. En réalité, elle fluctue en fonction des pics de trafic et d’autres facteurs.

Les spans des traces échantillonnées par les taux d’échantillonnage automatiques de l’Agent Datadog sont étiquetés avec la raison d’ingestion auto. Le tag ingestion_reason est également défini sur métriques d’utilisation. Les services utilisant ce mécanisme par défaut sont étiquetés Automatic dans la colonne Configuration de la page de contrôle d’ingestion.

Dans les SDK : règles définies par l’utilisateur

ingestion_reason: rule

Pour un contrôle plus granulaire, utilisez les options de configuration d’échantillonnage des SDK :

• Définissez un taux d’échantillonnage spécifique à appliquer à la racine de la trace par nom de service ou de ressource, en remplaçant le mécanisme par défaut de l’Agent.
• Définissez une limite de taux sur le nombre de traces ingérées par seconde. La limite de taux par défaut est de 100 traces par seconde par instance de service. Lors de l’utilisation du mécanisme par défaut, le limiteur de taux est ignoré.

Remarque : Les règles d’échantillonnage sont également des contrôles d’échantillonnage basés sur l’en-tête. Si le trafic pour un service est supérieur au maximum configuré de traces par seconde, alors les traces sont supprimées à la racine. Cela ne crée pas de traces incomplètes.

Les options de configuration peuvent être définies via des variables d’environnement ou directement dans le code :

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

Remarque : Tous les spans d’une trace échantillonnée à l’aide d’une configuration SDK sont étiquetés avec la raison d’ingestion rule. Les services configurés avec des règles d’échantillonnage définies par l’utilisateur sont marqués comme Configured dans la colonne Configuration de la Page de Contrôle d’Ingestion.

Traces d’erreur et traces rares

Pour les traces non capturées par l’échantillonnage basé sur l’en-tête, deux mécanismes d’échantillonnage supplémentaires de l’Agent Datadog capturent des traces critiques et diverses qui seraient autrement perdues. Ces échantillonneurs conservent un ensemble diversifié de traces locales (spans du même hôte) en capturant toutes les combinaisons d’un ensemble prédéterminé de balises :

• Traces d’erreur : L’échantillonnage des erreurs fournit une visibilité sur les potentielles défaillances du système.
• Traces rares : L’échantillonnage des traces rares maintient la visibilité sur les services et ressources à faible trafic dans votre système.

Remarque : Les échantillonneurs d’erreurs et de traces rares sont ignorés pour les services pour lesquels vous avez défini des règles d’échantillonnage de bibliothèque.

Traces d’erreur

ingestion_reason: error

L’échantillonneur d’erreurs capture des morceaux de traces contenant des spans d’erreur non capturés par l’échantillonnage basé sur l’en-tête, à un taux allant jusqu’à 10 traces par seconde par Agent. Cela aide à maintenir la visibilité sur les erreurs lorsque le taux d’échantillonnage basé sur l’en-tête est faible.

Avec la version 7.33 de l’Agent et les versions ultérieures, vous pouvez configurer l’échantillonneur d’erreurs dans le fichier de configuration principal de l’Agent (datadog.yaml) ou avec des variables d’environnement :

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

Notes :

1. Définissez le paramètre sur 0 pour désactiver l’échantillonneur d’erreurs.
2. L’échantillonneur d’erreurs capture les traces d’erreur locales au niveau de l’Agent. Si la trace est distribuée, la trace complète peut ne pas être envoyée à Datadog.
3. Par défaut, les spans perdus par les règles SDK ou la logique personnalisée telles que manual.drop sont exclus sous l’échantillonneur d’erreurs.

Agent Datadog 7.42.0 et supérieur

L’échantillonnage des erreurs est configuré à distance si vous utilisez la version de l’Agent 7.42.0 ou supérieure. Suivez la documentation pour activer la configuration à distance dans vos Agents. Avec la configuration à distance, vous pouvez activer la collecte de spans rares sans redémarrer l’Agent Datadog.

Agent Datadog 6/7.41.0 et supérieur

Pour remplacer le comportement par défaut afin que les spans perdus par les règles SDK ou la logique personnalisée telles que manual.drop soient inclus par l’échantillonneur d’erreurs, activez la fonctionnalité avec : DD_APM_FEATURES=error_rare_sample_tracer_drop dans l’Agent Datadog (ou le conteneur dédié de l’Agent de traces dans le pod de l’Agent Datadog dans Kubernetes).

Agent Datadog 6/7.33 à 6/7.40.x

Le comportement par défaut d’échantillonnage des erreurs ne peut pas être modifié pour ces versions de l’Agent. Mettez à niveau l’Agent Datadog vers l’Agent Datadog 6/7.41.0 et supérieur.

Traces rares

ingestion_reason: rare

L’échantillonneur de traces rares envoie un ensemble de spans rares à Datadog. Il capture des combinaisons de env, service, name, resource, error.type et http.status à raison de jusqu’à 5 traces par seconde par Agent. Cela aide à maintenir la visibilité sur les ressources à faible trafic lorsque le taux d’échantillonnage basé sur la tête est faible.

Remarque : L’échantillonneur rare capture les traces locales au niveau de l’Agent. Si la trace est distribuée, il n’y a aucune garantie que la trace complète soit envoyée à Datadog.

Agent Datadog 7.42.0 ou supérieur

L’échantillonnage rare est configuré à distance si vous utilisez la version de l’Agent 7.42.0 ou supérieure. Suivez la documentation pour activer la configuration à distance dans vos Agents. Avec la configuration à distance, vous pouvez changer la valeur du paramètre sans redémarrer l’Agent Datadog.

Agent Datadog 6/7.41.0 ou supérieur

Par défaut, l’échantillonneur rare n’est pas activé.

Remarque : Lorsque activé, les spans supprimés par les règles SDK ou la logique personnalisée telles que manual.drop sont exclus sous cet échantillonneur.

Pour configurer l’échantillonneur rare, mettez à jour le paramètre apm_config.enable_rare_sampler dans le fichier de configuration principal de l’Agent (datadog.yaml) ou avec la variable d’environnement 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

Pour évaluer les spans supprimés par les règles SDK ou la logique personnalisée telles que manual.drop, activez la fonctionnalité avec : DD_APM_FEATURES=error_rare_sample_tracer_drop dans l’Agent de Trace.

Agent Datadog 6/7.33 à 6/7.40.x

Par défaut, l’échantillonneur rare est activé.

Remarque : Lorsque activé, les spans supprimés par les règles SDK ou la logique personnalisée telles que manual.drop sont exclus sous cet échantillonneur. Pour inclure ces spans dans cette logique, mettez à niveau vers l’Agent Datadog 6.41.0/7.41.0 ou supérieur.

Pour modifier les paramètres par défaut de l’échantillonneur rare, mettez à jour le paramètre apm_config.disable_rare_sampler dans le fichier de configuration principal de l’Agent (datadog.yaml) ou avec la variable d’environnement 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

Forcer la conservation et la suppression

ingestion_reason: manual

Le mécanisme d’échantillonnage basé sur l’en-tête peut être remplacé au niveau du SDK. Par exemple, si vous devez surveiller une transaction critique, vous pouvez forcer la conservation de la trace associée. En revanche, pour des informations inutiles ou répétitives comme les vérifications de santé, vous pouvez forcer la suppression de la trace.

• Définir la conservation manuelle sur un span pour indiquer que celui-ci et tous les spans enfants doivent être ingérés. La trace résultante peut sembler incomplète dans l’interface utilisateur si le span en question n’est pas le span racine de la trace.

• Définir la suppression manuelle sur un span pour s’assurer que aucun span enfant n’est ingéré. Les échantillonneurs liés aux erreurs et à l’échantillonnage rare sont ignorés dans l’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

Définir la conservation manuelle avant la propagation du contexte. Si elle est définie après la propagation du contexte, la trace entière peut ne pas être conservée à travers les services. Parce que cette décision est prise au niveau du client de traçage, la trace peut toujours être supprimée par l’Agent ou le serveur en fonction des règles d’échantillonnage.

Spans uniques

ingestion_reason: single_span

Si vous devez échantillonner un span spécifique mais que vous n’avez pas besoin de la trace complète, les SDK vous permettent de définir un taux d’échantillonnage pour un seul span.

Par exemple, si vous construisez des métriques à partir de spans pour surveiller des services spécifiques, vous pouvez configurer des règles d’échantillonnage de spans afin que ces métriques soient basées sur 100 % du trafic de l’application, sans ingérer 100 % des traces pour toutes les requêtes transitant par le service.

Cette fonctionnalité est disponible pour Datadog Agent v7.40.0+.

Remarque : Les règles d’échantillonnage de spans uniques ne peuvent pas être utilisées pour supprimer des spans qui sont conservés par l’échantillonnage basé sur l’en-tête, mais seulement pour conserver des spans supplémentaires qui sont supprimés par l’échantillonnage basé sur l’en-tête.

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

Spans ingérés par le produit

Traces RUM

ingestion_reason:rum

Une requête d’une application web ou mobile génère une trace lorsque les services backend sont instrumentés. L’intégration APM avec la surveillance des utilisateurs réels relie les requêtes des applications web et mobiles à leurs traces backend correspondantes afin que vous puissiez voir vos données frontend et backend complètes à travers un seul prisme.

À partir de la version 4.30.0 du SDK navigateur RUM, vous pouvez contrôler les volumes ingérés et conserver un échantillonnage des traces backend en configurant le paramètre d’initialisation traceSampleRate. Définissez traceSampleRate sur un nombre compris entre 0 et 100. Si aucune valeur traceSampleRate n’est définie, une valeur par défaut de 100 % des traces provenant des requêtes du navigateur est envoyée à Datadog.

Vous pouvez également contrôler le taux d’échantillonnage des traces dans d’autres SDK :

Traces synthétiques

ingestion_reason:synthetics et ingestion_reason:synthetics-browser

Les tests HTTP et navigateur génèrent des traces lorsque les services backend sont instrumentés. L’intégration APM avec les tests synthétiques relie vos tests synthétiques aux traces backend correspondantes. Naviguez depuis une exécution de test ayant échoué jusqu’à l’origine du problème en consultant la trace générée lors de cette exécution.

Par défaut, 100 % des tests HTTP et Browser Synthetic génèrent des traces en backend.

Autres produits

D’autres motifs d’ingestion peuvent être attribués aux spans générées par certains produits Datadog :

Mécanismes d’ingestion dans OpenTelemetry

ingestion_reason:otel

Selon votre configuration avec les SDK OpenTelemetry (en utilisant le Collecteur OpenTelemetry ou l’Agent Datadog), vous avez plusieurs façons de contrôler l’échantillonnage d’ingestion. Voir Échantillonnage d’Ingestion avec OpenTelemetry pour des détails sur les options disponibles pour l’échantillonnage au niveau des SDK OpenTelemetry, du Collecteur OpenTelemetry et de l’Agent Datadog dans diverses configurations OpenTelemetry.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Paramètres d'ingestionDOCUMENTATION Rétention des tracesDOCUMENTATION Métriques d'utilisationDOCUMENTATION Optimisation de Datadog à grande échelle : observabilité rentable chez ZendeskBLOG Limitation de taux APM et rétentionCENTRE D'APPRENTISSAGE