Try it free

Settings API - Trace ingest control schema table

  • Published Dec 15, 2025

Trace ingest control (builtin:trace.ingest.control)

Dynatrace OneAgent automatically manages the volume of ingested trace data via Adaptive Traffic Management (ATM). It continuously adjusts the adaptive trace sampling rate to keep ingested trace data within your total licensed Full-Stack trace volume. By default, this equals your Full-Stack included trace volume, but you can increase it via extended trace ingest.

With trace ingest control, you can steer how your licensed trace volume is used at a deployment scope level, such as a specific host group, Kubernetes namespace, or process group. Use the adaptive sampling switch to select which option to configure for this scope:

• Adaptive sampling: Adjust the adaptive trace ingest rate factor to increase or decrease how much of the usable adaptive trace volume a scope receives relative to other scopes. ATM continues to manage the overall volume.

• Fixed-rate sampling: Set a deterministic capture rate for all traces initiated within this scope, bypassing ATM for that scope. Fixed-rate sampled traces are not counted against the usable adaptive trace volume.

For details, see Adaptive Traffic Management with DPS.

Schema IDSchema groupsScope
builtin:trace.ingest.control
  • group:service-monitoring
  • group:preferences
PROCESS_GROUP_INSTANCE - Process
PROCESS_GROUP - Process Group
CLOUD_APPLICATION - Kubernetes workload
CLOUD_APPLICATION_NAMESPACE - Kubernetes namespace
KUBERNETES_CLUSTER - Kubernetes cluster
HOST_GROUP - Host Group
environment
Retrieve schema via Settings API
GETManagedhttps://{your-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:trace.ingest.control
GETSaaShttps://{your-environment-id}.live.dynatrace.com/api/v2/settings/schemas/builtin:trace.ingest.control
GETEnvironment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v2/settings/schemas/builtin:trace.ingest.control

Authentication

To execute this request, you need an access token with Read settings (settings.read) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

PropertyTypeDescriptionRequired
Adaptive Sampling
adaptiveSamplingSwitch		boolean

Determines which sampling configuration is applied for this scope. When enabled, the adaptive trace ingest rate factor can be configured. When disabled, a fixed sampling rate can be configured instead.

For details on both options, see Adaptive Traffic Management with DPS.

Required
Adaptive trace ingest rate factor
adaptiveTraceIngestRateFactor		float

Setting the factor to 1 enables OneAgents within this scope to capture traces at a standard, adaptively determined rate. You can increase or decrease this rate limit. For example, choosing a factor of 0.5 means that the trace ingest rate limit will be halved, and choosing a factor of 10 means the trace ingest rate will be 10 times the default limit.

For details, see Adjust adaptive trace sampling rate.

Required
(Preview) Fixed sampling rate
fixedSamplingRate		enum

This is a preview feature available to selected customers starting with OneAgent version 1.337.

Sets a deterministic capture rate for all traces initiated by OneAgents within this scope. When fixed-rate sampling is active, Adaptive Traffic Management does not control the sampling decision: every trace is independently and probabilistically sampled at the configured rate. Fixed-rate sampled traces do not count against the usable adaptive trace volume and are billed separately.

This setting only applies to traces that originate within the configured scope. Traces that are started outside the scope inherit the sampling decision made at the trace origin. Configure the scope to match the entry point of the traces you want to control.

For details, see Configure fixed-rate sampling and Fixed-rate sampling.

The element has these enums
  • 0
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
Required