Services often handle endpoints whose traffic you may not want to trace (for example, health checks). This guide explains the following approaches for excluding that traffic:

• Sampling: Use when you want requests to remain visible in trace metrics, but reduce trace ingestion volume.
• Filtering in the Datadog Agent: Use to exclude requests entirely (including from trace metrics) across all services reporting to the Agent.
• Tracer configuration: Use when filtering logic must be applied per service or depends on application-specific context (for example, request attributes or runtime state).

If you need assistance deciding which option is the most relevant for your use case, contact Datadog support.

Sampling

If you want the span included in the trace metrics but don’t want it ingested, use sampling rules. For more information on sampling, see Ingestion Controls.

Using sampling rules

The recommended approach is to use sampling rules, which allow you to sample traces based on resource names, service names, tags, and operation names:

DD_TRACE_SAMPLING_RULES='[{"resource": "GET healthcheck", "sample_rate": 0.0}]'

Or to sample based on HTTP URL tags:

DD_TRACE_SAMPLING_RULES='[{"tags": {"http.url": "http://.*/healthcheck$"}, "sample_rate": 0.0}]'

Filtering in the Datadog Agent

If you don’t want the span ingested or reflected in trace metrics, use filtering in the Datadog Agent.

The Trace Agent component within the Datadog Agent has two methods to prevent certain traces from being sent: filtering by span tags or filtering by resources. If traces are dropped due to these settings, the trace metrics exclude these requests.

Configuring the Trace Agent to ignore certain traces or resources applies to all services that send traces to this Datadog Agent. If you have application-specific requirements, use Tracer configuration instead.

Ignoring traces based on span tags

Starting with Datadog Agent 6.27.0/7.27.0, the filter tags option drops traces with root spans that match specified span tags. This option applies to all services that send traces to this Datadog Agent. Traces that are dropped because of filter tags are not included in trace metrics.

Matching behavior:

The filter tags option requires an exact string match. For regex-based filtering, see Ignoring based on resources.

When you specify multiple tags, the filter uses OR logic: traces are dropped if the root span matches any of the tags. To match multiple conditions simultaneously, add a custom tag that represents those combined criteria.

Configuration:

You can specify span tags to require or reject by using a list of keys and values separated by spaces in environment variables:

DD_APM_FILTER_TAGS_REQUIRE

Collects only traces that have root spans with an exact match for the specified span tags and values. If it does not match this rule, the trace is dropped. For example, DD_APM_FILTER_TAGS_REQUIRE="key1:value1 key2:value2". In Datadog Agent 7.49+, regular expressions can be provided with DD_APM_FILTER_TAGS_REGEX_REQUIRE.

DD_APM_FILTER_TAGS_REJECT

Rejects traces that have root spans with an exact match for the specified span tags and values. If it matches this rule, the trace is dropped. For example, DD_APM_FILTER_TAGS_REJECT="key1:value1 key2:value2". In Datadog Agent 7.49+, regular expressions can be provided with DD_APM_FILTER_TAGS_REGEX_REJECT.

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  override:
    nodeAgent:
      containers:
        trace-agent:
          env:
            - name: DD_APM_FILTER_TAGS_REJECT
              value: tag_key1:tag_val2 tag_key2:tag_val2

kubectl apply -n $DD_NAMESPACE -f datadog-agent.yaml

agents:
  containers:
    traceAgent:
      env:
        - name: DD_APM_FILTER_TAGS_REJECT
          value: tag_key1:tag_val2 tag_key2:tag_val2

helm upgrade -f datadog-values.yaml <RELEASE NAME> datadog/datadog

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

apm_config:
  filter_tags:
    reject: ["http.url:http://localhost:5050/healthcheck"]

Available span tags

On the backend, Datadog creates the following span tags on spans after ingestion.

Note: These tags cannot be used to drop traces at the Datadog Agent level. The agent only filters based on tags available before ingestion.

Network communications

HTTP requests

Database

Message Queue

Remote procedure calls

Errors

Ignoring traces based on resources

The ignore resources option allows resources to be excluded if the global root span of the trace matches certain criteria. See Exclude resources from being collected. This option applies to all services that send traces to this particular Datadog Agent. Traces that are dropped because of ignore resources are not included in trace metrics.

You can specify resources to ignore either in the Agent configuration file, datadog.yaml, or with the DD_APM_IGNORE_RESOURCES environment variable. See examples below.

Using datadog.yaml:

apm_config:
## @param ignore_resources - list of strings - optional
## A list of regular expressions can be provided to exclude certain traces based on their resource name.
## All entries must be surrounded by double quotes and separated by commas.

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

Using DD_APM_IGNORE_RESOURCES:

DD_APM_IGNORE_RESOURCES="(GET|POST) /healthcheck,API::NotesController#index"

Notes:

• When using the environment variable format (DD_APM_IGNORE_RESOURCES), values must be provided as a comma-separated list of strings.
• The regex syntax that the Trace Agent accepts is evaluated by Go’s regexp.
• Depending on your deployment strategy, you may have to adjust the regex by escaping special characters.
• If you use dedicated containers with Kubernetes, make sure that the environment variable for the ignore resource option is being applied to the trace-agent container.

Example

Consider a trace that contains calls to /api/healthcheck that you don’t want traces from:

Take note of the resource name of the global root span.

• Operation name: rack.request
• Resource name: Api::HealthchecksController#index
• Http.url: /api/healthcheck

To use the ignore resource option correctly, the regex rule written must match with the resource name, Api::HealthchecksController#index. A few regex options are possible, but to filter out traces from this resource exactly as is, a potential regex to use is Api::HealthchecksController#index$.

Depending on how you deploy, the syntax looks a little different:

apm_config:
  ignore_resources: Api::HealthchecksController#index$

apm_config:
  ignore_resources: ["value1","Api::HealthchecksController#index$"]

    environment:
      // other Datadog Agent environment variables
      - DD_APM_IGNORE_RESOURCES=Api::HealthchecksController#index$$

    environment:
      // other Datadog Agent environment variables
      - DD_APM_IGNORE_RESOURCES="value1","Api::HealthchecksController#index$$"

docker run -d --name datadog-agent \
              --cgroupns host \
              --pid host \
              -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

              -e DD_APM_IGNORE_RESOURCES=["value1","Api::HealthchecksController#index$"] \

    - 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$"

        - name: DD_APM_IGNORE_RESOURCES
          value: '"value1","Api::HealthchecksController#index$"'

    traceAgent:
      # agents.containers.traceAgent.env -- Additional environment variables for the trace-agent container
      env:
        - name: DD_APM_IGNORE_RESOURCES
          value: Api::HealthchecksController#index$

        - name: DD_APM_IGNORE_RESOURCES
          value: value1, Api::HealthchecksController#index$

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

    "environment": [
	// other environment variables for the Datadog Agent
        {
          "name": "DD_APM_IGNORE_RESOURCES",
          "value": "Api::HealthchecksController#index$"
        }
     ]

Tracer configuration

Some language tracers can drop traces before they are sent to the Datadog Agent. Use this option if you have application-specific requirements.

Datadog::Tracing.before_flush(
   Datadog::Tracing::Pipeline::SpanFilter.new { |span| span.resource =~ /Api::HealthchecksController#index/ }
)

from ddtrace.trace import tracer
from ddtrace.trace import TraceFilter
import re

class CustomFilter(TraceFilter):
    def __init__(self, pattern):
        self.pattern = re.compile(pattern)

    def process_trace(self, trace):
        for span in trace:
            if span.get_tag('http.url') and self.pattern.match(span.get_tag('http.url')):
                return None  # Drop the trace
        return trace  # Keep the trace

# Configure the tracer with your custom filter
tracer.configure(trace_processors=[CustomFilter(r'http://.*/healthcheck$')])

const tracer = require('dd-trace').init();
tracer.use('http', {
  // incoming http requests match on the path
  server: {
    blocklist: ['/healthcheck']
  },
  // outgoing http requests match on a full URL
  client: {
    blocklist: ['https://telemetry.example.org/api/v1/record']
  }
})

//import http

public class GreetingController {
   static {
       // In a class static block to avoid initializing multiple times.
       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;  // Some unique number
           }
       });
   }
}