Ingestion Controls

Ingestion Sampling Rules

Ingestion controls affect what traces are sent by your applications to Datadog. Stats and metrics are always calculated based on all traces, and are not impacted by ingestion controls.

The Ingestion Control page provides visibility at the Agent and tracing libraries level into the ingestion configuration of your applications and services. From the ingestion control configuration page, you can:

  • Investigate and act on potential ingestion configuration issues, such as limited CPU or RAM resources for the Agent.
  • Check service-level ingestion configuration and adjust traces-per-second sampling rates for high throughput services.
  • Understand which ingestion mechanisms are responsible for sampling most of your traces.
Ingestion Control Page Overview

All metrics used in the page are based on live traffic data of the past 1 hour. Any Agent or library configuration change is reflected in the page.

Summary across all environments

Get an overview of the total ingested data over the past hour, and an estimation of your monthly usage against your monthly allocation, calculated with the active APM intrastructure (hosts, Fargate tasks, and serverless functions).

If the monthly usage is under 100%, the projected ingested data fits in your monthly per-host allotment. A quota over 100% means that the monthly ingestion volume is projected to be over your monthly allocation.

Service table view

The service table contains information by service about the ingestion configuration:

The name of each service sending traces to Datadog. The table contains root and non-root services for which data was ingested in the past one hour.
Ingested Traces/s
Average number of traces per second ingested into Datadog for the service in the past one hour.
Ingested Bytes/s
Average number of bytes per second ingested into Datadog for the service in the past one hour.
Downstream Bytes/s
Average number of bytes per second ingested, including spans from downstream services whose ingestion decisions are set at this service. This includes the bytes of all descending child spans, as well as spans caught by the Error sampler, the Rare sampler, and the App Analytics mechanism.
Traffic Breakdown
A detailed breakdown of the destination of every trace generated by the service. See Traffic breakdown for more information.
Ingestion Configuration
Shows Automatic if the default head-based sampling mechanism from the Agent applies. If the ingestion was configured in the tracing libraries with user-defined rules, the service is marked as Configured. For more information about configuring ingestion for a service, read about changing the default ingestion rate.
Hosts, containers, and functions on which the service is running.
Service status
Shows Limited Resource when some spans are dropped due to the Datadog Agent reaching CPU or RAM limits set in its configuration, Legacy Setup when some spans are ingested through the legacy App Analytics mechanism, and OK the rest of the time.

Filter the page by environment, configuration, and status to view services for which you need to take an action. To reduce the global ingestion volume, sort the table by the Downstream Bytes/s column to view services responsible for the largest share of your ingestion.

Note: The table is powered by the usage metrics datadog.estimated_usage.apm.ingested_spans and datadog.estimated_usage.apm.ingested_bytes. These metrics are tagged by service, env and ingestion_reason.

Traffic breakdown

The Traffic Breakdown column breaks down the destination of all traces originating from the service. It gives you an estimate of the share of traffic that is ingested and dropped, and for which reasons.

Traffic breakdown of trace ingestion

The breakdown is composed of the following parts:

  • Complete traces ingested (blue): The percentage of traces that have been ingested by Datadog.

  • Complete traces not retained (gray): The percentage of traces that have intentionally not been forwarded to Datadog by the Agent or the tracer. This can happen for one of two reasons depending on your configuration:

    1. By default, the Agent distributes an ingestion rate to services depending on service traffic.
    2. When the service is manually configured to ingest a certain percentage of traces at the tracing library level.
  • Complete traces dropped by the tracer rate limiter (orange): When you choose to manually set the service ingestion rate as a percentage with rules, a rate limiter is automatically enabled, set to 100 traces per second by default. See the rate limiter documentation to manually configure this rate.

  • Traces dropped due to the Agent CPU or RAM limit (red): This mechanism may drop spans and create incomplete traces. To fix this, increase the CPU and memory allocation for the infrastructure that the Agent runs on.

Service ingestion summary

Click on any service row to view the Service Ingestion Summary, a detailed view providing actionable insights on the ingestion configuration of the service.

Service Ingestion Summary

Explore the Ingestion reasons breakdown to see which mechanisms are responsible for your service ingestion. Each ingestion reason relates to one specific ingestion mechanism. After changing your service ingestion configuration, you can observe the increase or decrease of ingested bytes and spans in this timeseries graph based on the past hour of ingested data.

If most of your service ingestion is due to decisions taken by upstream services, investigate the detail of the top upstream decision makers. For example, if your service is non-root, (meaning that it never decides to sample traces), observe all upstream services responsible for your non-root service ingestion. Configure upstream root services to reduce your overall ingestion volume.

For further investigations, use the APM Trace - Estimated Usage Dashboard, which provides global ingestion information as well as breakdown graphs by service, env and ingestion reason.

Configure the service ingestion rate

Click Manage Ingestion Rate to configure your service ingestion rate.

Change the Service Ingestion Rate

To specify that a specific percentage of a service’s traffic should be sent, add a generated code snippet to your tracer configuration for that service.

  1. Select the service you want to change the ingested span percent for.
  2. Choose the service language.
  3. Choose the desired ingestion percentage.
  4. Apply the appropriate configuration generated from these choices to the indicated service and redeploy.
  5. Confirm on the Ingestion Control Page that your new percentage has been applied. A share of the Ingestion Reason Breakdown should be allocated to ingestion_reason:rule.

Further Reading