Ignorer les ressources non désirées dans l'APM

Ignorer les ressources non désirées dans l'APM

Un service peut gérer une multitude de requêtes. Il est possible que vous ne souhaitiez pas tracer certaines d’entre elles ni les inclure dans les métriques de trace. Cela peut par exemple être le cas des checks de santé dans une application Web.

Pour éviter qu’un endpoint spécifique soit tracé et inclus dans les métriques de trace, vous pouvez adopter deux approches différentes :

Remarque : le filtrage des traces à l'aide d'une des options suivantes supprime les requêtes concernées des métriques de trace. Pour découvrir comment réduire l'ingestion sans toucher aux métriques de trace, consultez la section relative aux contrôles de l'ingestion.

Si vous avez besoin d’aide, contactez l'assistance Datadog.

Options de configuration de l’Agent de trace

Le composant « Agent de trace » de l’Agent Datadog peut empêcher de deux façons différentes la transmission de certaines traces : en ignorant des tags de span, ou en ignorant des ressources. Si, avec une de ces configurations, des traces sont ignorées, les métriques de trace excluent les requêtes concernées.

Lorsque vous configurez l’Agent de trace de façon à ce qu’il ignore certaines spans ou ressources, ce comportement s’applique à l’ensemble des services qui envoient des traces à cet Agent Datadog spécifique. Si vous devez répondre à certaines exigences spécifiques pour votre application, utilisez plutôt la méthode reposant sur la configuration du traceur.

Ignorer des traces en fonction des tags de span

Depuis la version 6.27.0/7.27.0 de l’Agent Datadog, l’option filter tags ignore les traces dont les spans racines correspondent aux tags de span spécifiés. Cette option s’applique à l’ensemble des services qui envoient des traces à cet Agent Datadog spécifique. Les traces qui sont ignorées en raison des tags filtrés sont exclues des métriques de trace.

Si vous pouvez identifier par programmation un ensemble de traces que vous ne souhaitez pas envoyer à Datadog, et qu’aucune suggestion de cette page ne répond à vos besoins, envisagez d’ajouter un tag de span personnalisé afin de pouvoir ignorer les traces. Contactez l’assistance afin de présenter votre cas d’utilisation. Nous pourrons ainsi continuer à étendre cette fonctionnalité.

Vous devez indiquer une correspondance de chaîne exacte pour le filtrage des tags. Si vous devez ignorer les expressions régulières pour votre cas d’utilisation, consultez la rubrique Ignorer des traces en fonction des ressources.

Vous pouvez spécifier les tags de span qui doivent être acceptés ou refusés à l’aide de variables d’environnement :

DD_APM_FILTER_TAGS_REQUIRE
Recueille uniquement les traces qui possèdent des spans racines correspondant exactement aux valeurs et aux tags de span spécifiés. Si la trace ne respecte pas cette règle, elle est ignorée.
DD_APM_FILTER_TAGS_REJECT
Rejette les traces qui possèdent des spans racines correspondant exactement aux valeurs et aux tags de span spécifiés. Si la trace respecte cette règle, elle est ignorée.

Vous pouvez également définir ces tags de span dans le fichier de configuration de l’Agent :

datadog.yaml

apm_config:
  filter_tags:
    require: ["db:sql", "db.instance:mysql"]
    reject: ["outcome:success"]

Par exemple, pour ignorer les checks de santé lorsque http.url correspond à l’endpoint pertinent :

datadog.yaml

apm_config:
  filter_tags:
    reject: ["http.url:http://localhost:5050/healthcheck"]
Remarque : le filtrage des traces à l'aide de cette méthode supprime les requêtes concernées des métriques de trace. Pour découvrir comment réduire l'ingestion sans toucher aux métriques de trace, consultez la section relative aux contrôles de l'ingestion.

Ignorer des traces en fonction des ressources

L’option ignore resources permet d’exclure des ressources lorsque la span racine globale de la trace répond à certains critères. Consultez la section Empêcher la collecte de certaines ressources pour en savoir plus. Cette option s’applique à l’ensemble des services qui envoient des traces à cet Agent Datadog spécifique. Puisque les ressources ignorées sont exclues des métriques de trace, les traces sont également ignorées.

Vous pouvez indiquer les ressources à ignorer dans le fichier de configuration de l’Agent (datadog.yaml) ou avec la variable d’environnement DD_APM_IGNORE_RESOURCES. Consultez les exemples ci-dessous :

datadog.yaml

## @param ignore_resources - liste de chaînes, facultatif
## Vous pouvez fournir une liste d'expressions régulières afin d'exclure certaines traces en fonction du nom de leur ressource.
## Toutes les valeurs doivent être placées entre guillemets et séparées par des virgules.

  ignore_resources: ["(GET|POST) /healthcheck","API::NotesController#index"]

Remarques :

  • La syntaxe acceptée par l’Agent de trace pour les expressions régulières est évaluée par le système d’expressions régulières Go.
  • Selon votre stratégie de déploiement, vous devrez potentiellement modifier vos expressions régulières en échappant les caractères spéciaux.
  • Si vous utilisez des conteneurs dédiés avec Kubernetes, vérifiez que la variable d’environnement permettant d’ignorer des ressources est appliquée au conteneur trace-agent.

Exemple

Imaginons qu’une trace contient des appels vers /api/healthcheck que vous ne souhaitez pas tracer :

Notez le nom de ressource de la span racine globale.

  • Nom de l’opération : rack.request
  • Nom de la ressource : Api::HealthchecksController#index
  • Http.url : /api/healthcheck

Pour ignorer correctement des ressources, la règle d’expression régulière spécifiée doit correspondre au nom de la ressource, à savoir Api::HealthchecksController#index. Plusieurs expressions régulières peuvent être spécifiées. Toutefois, pour exclure les traces de cette ressource précise, vous pouvez utiliser l’expression Api::HealthchecksController#index$.

La syntaxe peut varier en fonction de votre déploiement 

datadog.yaml

apm_config:
  ignore_resources: Api::HealthchecksController#index$

Ajoutez DD_APM_IGNORE_RESOURCES à la liste des variables d’environnement du conteneur de l’Agent Datadog, en indiquant un pattern similaire à celui de l’exemple ci-dessous. Docker Compose utilise sa propre fonctionnalité de substitution de variables. Vous devez donc en tenir compte lorsque vous indiquez des caractères spéciaux, comme $.

    environment:
      // autres variables d'environnement de l'Agent Datadog
      - DD_APM_IGNORE_RESOURCES=Api::HealthchecksController#index$$

Ajoutez DD_APM_IGNORE_RESOURCES à votre commande docker run permettant de lancer l’Agent Datadog :

docker run -d --name datadog-agent \
              -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -e DD_API_KEY=<> \
        -e DD_APM_IGNORE_RESOURCES="Api::HealthchecksController#index$" \
              -e DD_APM_ENABLED=true \
              -e DD_APM_NON_LOCAL_TRAFFIC=true \
              gcr.io/datadoghq/agent:latest

Dans le conteneur de trace-agent dédié, ajoutez la variable d’environnement DD_APM_IGNORE_RESOURCES :

    - name: trace-agent
        image: "gcr.io/datadoghq/agent:latest"
        imagePullPolicy: IfNotPresent
        command: ["trace-agent", "-config=/etc/datadog-agent/datadog.yaml"]
        resources: {}
        ports:
        - containerPort: 8126
          hostPort: 8126
          name: traceport
          protocol: TCP
        env:
        - name: DD_API_KEY
          valueFrom:
            secretKeyRef:
              name: "datadog-secret"
              key: api-key
        - name: DD_KUBERNETES_KUBELET_HOST
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        - name: KUBERNETES
          value: "yes"
        - name: DOCKER_HOST
          value: unix:///host/var/run/docker.sock
        - name: DD_LOG_LEVEL
          value: "INFO"
        - name: DD_APM_ENABLED
          value: "true"
        - name: DD_APM_NON_LOCAL_TRAFFIC
          value: "true"
        - name: DD_APM_RECEIVER_PORT
          value: "8126"
        - name: DD_KUBELET_TLS_VERIFY
          value: "false"
        - name: DD_APM_IGNORE_RESOURCES
          value: "Api::HealthchecksController#index$"

Dans la section traceAgent du fichier values.yaml, ajoutez DD_APM_IGNORE_RESOURCES sous la section env, puis lancez Helm comme d’habitude.

values.yaml

    traceAgent:
      # agents.containers.traceAgent.env -- Variables d'environnement supplémentaires pour le conteneur trace-agent
      env:
        - name: DD_APM_IGNORE_RESOURCES
          value: Api::HealthchecksController#index$

Vous avez également la possibilité de définir agents.containers.traceAgent.env dans la commande helm install :

helm install dd-agent -f values.yaml \
  --set datadog.apiKeyExistingSecret="datadog-secret" \
  --set datadog.apm.enabled=true \
  --set agents.containers.traceAgent.env[0].name=DD_APM_IGNORE_RESOURCES, \
    agents.containers.traceAgent.env[0].value="Api::HealthchecksController#index$" \
  datadog/datadog

Si vous utilisez AWS ECS (par exemple, EC2), dans votre définition du conteneur de l’Agent Datadog, ajoutez la variable d’environnement DD_APM_IGNORE_RESOURCES avec des valeurs permettant au JSON d’évaluer un contenu similaire à ce qui suit :

    "environment": [
    // autres variables d'environnement pour l'Agent Datadog
        {
          "name": "DD_APM_IGNORE_RESOURCES",
          "value": "Api::HealthchecksController#index$"
        }
     ]
Remarque : le filtrage des traces à l'aide de cette méthode supprime les requêtes concernées des métriques de trace. Pour découvrir comment réduire l'ingestion sans toucher aux métriques de trace, consultez la section relative aux contrôles de l'ingestion.

Options de configuration du traceur

Pour certains langages, les traceurs permettent de modifier les spans avant leur envoi à l’Agent Datadog. Utilisez cette option si vous devez répondre à certaines exigences spécifiques pour votre application dans l’un des langages répertoriés ci-dessous.

Attention : si la requête est associée à une trace distribuée, lorsque vous ignorez une partie de la trace obtenue en raison des règles de filtrage, la trace peut inclure des erreurs d'échantillonnage.

Le traceur Ruby possède un pipeline de post-traitement qui supprime toutes les traces répondant à certains critères. Pour en savoir plus et obtenir des exemples, consultez la rubrique Post-traitement des traces.

Par exemple, pour le nom de ressource Api::HealthchecksController#index, utilisez la méthode trace.delete_if afin de supprimer les traces qui contiennent le nom de ressource. Ce filtre peut également être utilisé pour établir une correspondance avec d’autres métadonnées disponibles pour l'objet span.

Datadog::Pipeline.before_flush do |trace|
  trace.delete_if { |span| span.resource =~ /Api::HealthchecksController#index/ }
end

Le traceur Python possède un filtre FilterRequestsOnUrl, qui peut être configuré de façon à supprimer les traces provenant de certains endpoints. Vous avez également la possibilité de créer un filtre personnalisé. Consultez la section Filtrage des traces (en anglais) pour en savoir plus.

Imaginons que le tag de span http.url de la span racine soit défini sur http://<domaine>/healthcheck. Utilisez l’expression régulière suivante pour faire correspondre tous les endpoints se terminant par healthcheck :

from ddtrace import tracer
from ddtrace.filters import FilterRequestsOnUrl
tracer.configure(settings={
    'FILTERS': [
        FilterRequestsOnUrl(r'http://.*/healthcheck$'),
    ],
})

Configurez une liste d’éléments à exclure sur le plug-in Http. Consultez la documentation sur l’API pour bien comprendre les éléments inclus dans la liste. Par exemple, Http trouve des correspondances dans les URL. Ainsi, si le tag de span http.url de la trace a pour valeur http://<domaine>/healthcheck, créez une règle qui s’applique à l’URL healthcheck :

const tracer = require('dd-trace').init();
tracer.use('http', {
  blocklist: ["/healthcheck"]
})

//import http

Remarque : la configuration du traceur pour l'intégration doit être fournie avant l'importation de ce module instrumenté.

Le traceur Java possède une option permettant à un TraceInterceptor personnalisé de filtrer certaines spans. Consultez la section Extensions de traceurs pour en savoir plus.

Par exemple, pour la ressource GET /healthcheck, créez un intercepteur de traces qui ignore les traces contenant ce nom de ressource. Modifiez la logique pour répondre aux exigences de votre déploiement.

public class GreetingController {
   static {
       // Dans un bloc statique de classe, pour éviter de multiples initialisations
       GlobalTracer.get().addTraceInterceptor(new TraceInterceptor() {
           @Override
           public Collection<? extends MutableSpan> onTraceComplete(Collection<? extends MutableSpan> trace) {
               for (MutableSpan span : trace) {
                   if ("GET /healthcheck".contentEquals(span.getResourceName())) {
                       return Collections.emptyList();
                   }
               }
               return trace;
           }
           @Override
           public int priority() {
               return 200;  // Un nombre unique
           }
       });
   }
}
Remarque : le filtrage des traces à l'aide de cette méthode supprime les requêtes concernées des métriques de trace. Pour découvrir comment réduire l'ingestion sans toucher aux métriques de trace, consultez la section relative aux contrôles de l'ingestion.