Package 

Class ApmNetworkInstrumentationConfiguration

  • 
public final class ApmNetworkInstrumentationConfiguration

    Configuration for APM distributed tracing of network requests.

    This class controls how the Datadog SDK instruments outgoing HTTP requests with distributed tracing headers and optional client-side APM spans.

    At minimum, you must provide a list of first-party hosts (or a map of hosts to TracingHeaderTypes) so that the SDK knows which requests to instrument.

    Example usage:

    val apmConfig = ApmNetworkInstrumentationConfiguration(
    listOf("api.example.com", "cdn.example.com")
)
    .setTraceSampleRate(75f)
    .setTraceContextInjection(TraceContextInjection.ALL)

    • Constructor Detail

      • ApmNetworkInstrumentationConfiguration

        ApmNetworkInstrumentationConfiguration(List<String> tracedHosts)
        Creates a configuration with a list of traced hosts using default header types (TracingHeaderType.DATADOG and TracingHeaderType.TRACECONTEXT).
        Parameters:
        tracedHosts - a list of hosts to trace.

      • ApmNetworkInstrumentationConfiguration

        ApmNetworkInstrumentationConfiguration(Map<String, Set<TracingHeaderType>> tracedHostsWithHeaderType)
        Creates a configuration with a map of hosts to their associated tracing header types.
        Parameters:
        tracedHostsWithHeaderType - a map of host names to sets of TracingHeaderType to use for each host.

    • Method Detail

      • setTraceOrigin

        @JvmOverloads() final <ERROR CLASS> setTraceOrigin(String traceOrigin, Boolean replace)

        Set the origin of the trace.

        Parameters:
        traceOrigin - the origin of the trace.
        replace - if true (default), always replaces the current trace origin; if false, only sets the trace origin when it hasn't been set yet.

      • setTraceOrigin

        @JvmOverloads() final <ERROR CLASS> setTraceOrigin(String traceOrigin)

        Set the origin of the trace.

        Parameters:
        traceOrigin - the origin of the trace.

      • setSdkInstanceName

         final <ERROR CLASS> setSdkInstanceName(String sdkInstanceName)

        Set the SDK instance name to bind to, the default value is null.

        Parameters:
        sdkInstanceName - SDK instance name to bind to, the default value is null.

      • setTracedRequestListener

         final <ERROR CLASS> setTracedRequestListener(NetworkTracedRequestListener tracedRequestListener)

        Set the listener for automatically created DatadogSpans.

        Parameters:
        tracedRequestListener - a listener for automatically created DatadogSpans

      • setTraceSampleRate

         final <ERROR CLASS> setTraceSampleRate(@FloatRange(from = 0.0.toDouble(), to = 100.0.toDouble()) Float sampleRate)

        Set the trace sample rate controlling the sampling of APM traces created for auto-instrumented requests. If there is a parent trace attached to the network span created, then its sampling decision will be used instead.

        When headerPropagationOnly is enabled, the effective trace sample rate is automatically combined with the active RUM session sample rate, ensuring the backend receives correct sampling metadata (_dd.agent_psr / _dd.rule_psr) for RUM-to-APM correlation.

        Parameters:
        sampleRate - the sample rate to use (percentage between 0f and 100f, default is 100f).

      • setTraceSampler

         final <ERROR CLASS> setTraceSampler(Sampler<DatadogSpan> traceSampler)

        Set the trace sampler controlling the sampling of APM traces created for auto-instrumented requests. If there is a parent trace attached to the network span created, then its sampling decision will be used instead.

        Note: custom samplers passed here do not participate in cross-product rebasing with the RUM session sample rate (even when headerPropagationOnly is enabled). Subclasses of DeterministicTraceSampler are also treated as custom samplers and bypass rebasing — only an exact DeterministicTraceSampler instance (equivalent to calling setTraceSampleRate) participates in rebasing. Use setTraceSampleRate if you need correlated sampling between RUM sessions and APM traces.

        Parameters:
        traceSampler - the trace sampler controlling the sampling of APM traces.

      • setTraceContextInjection

         final <ERROR CLASS> setTraceContextInjection(TraceContextInjection traceContextInjection)

        Set the trace context injection behavior for the intercepted requests. By default this is set to TraceContextInjection.SAMPLED, meaning that only the sampled request will propagate the trace context. In case of TraceContextInjection.ALL all the trace context will be propagated in the intercepted requests no matter if the span created around the request is sampled or not.

        Parameters:
        traceContextInjection - the trace context injection option.

      • set404ResourcesRedacted

         final <ERROR CLASS> set404ResourcesRedacted(Boolean redacted)

        Set whether network requests returning a 404 status code should have their resource name redacted. In order to reduce the cardinality of resource names in APM, 404 URLs are automatically redacted to "404".

        Parameters:
        redacted - if true, all 404 requests will have a resource name set to "404", else the resource name will be the URL

      • setHeaderPropagationOnly

         final <ERROR CLASS> setHeaderPropagationOnly()

        Disables client-side APM span reporting while keeping tracing header propagation active.

        When called, the SDK will still inject distributed tracing headers (e.g. x-datadog-trace-id, x-datadog-parent-id) into outgoing requests for first-party hosts, enabling RUM-APM linking and end-to-end distributed traces. However, no client-side APM spans will be sent to the Datadog backend.

        This is useful when you want distributed tracing visibility without the overhead of client-side network spans.

      • copy

         final ApmNetworkInstrumentationConfiguration copy()

        Creates a deep copy of this configuration.

        Mutable collection fields are deeply copied to ensure the returned instance is independent. Immutable and shared-by-design fields (scalars, enums, lambdas) are reused as-is.