The tracer's settings, resolved once when the application boots.

Each setting is read from two layers, in order:

1. application config under the :dd_trace_ex key
2. the corresponding DD_* environment variable

Application config wins over the environment, matching the other Datadog tracers, and there is no third layer. A value that is missing, blank or unusable falls through to the next layer, and finally to the default — and so does a whole layer that is not the shape it should be. Bad configuration degrades the tracer, it never stops the host application from booting.

DD_TRACE_ENABLED and DD_LOGS_INJECTION accept true/false, 1/0, yes/no and on/off, in any case. Anything else keeps the default.

:agent_url must be an http:// URL — https and unix sockets are not implemented, and either one is ignored with a warning. An agent named by URL is taken at its word, so one written without a port gets http's default of 80, not 8126; DD_AGENT_HOST and DD_TRACE_AGENT_PORT are the path that defaults the port to 8126. An IPv6 address works either way, bracketed in a URL as http://[::1]:8126 and bare in DD_AGENT_HOST as ::1.

:http_server_error_statuses is which response statuses mark a server span an error — comma-separated single codes and inclusive lo-hi ranges, as in "500-599,429". One malformed part falls back to the whole default with a warning, rather than applying half a policy. DDTrace.Integrations.Phoenix is what reads it.

:http_client_error_statuses is the same for the spans of outbound requests, in the same grammar, and DDTrace.Integrations.Req is what reads it. Its default is the inverse of the server's on purpose: a 4xx says the request this application made was wrong, while a 5xx is the downstream service's own failure, reported on that service's own span.

:sample_rate is the share of traces to keep, 0..1, applied to every trace no rule matched; :sampling_rules is a list of rules, each a map or keyword list with the fields the Datadog docs spell — service, name, resource, tags, sample_rate — or the JSON array of them as a string, the shape the environment variable takes. Rules match a trace's root span with case-insensitive globs (* any run of characters, ? exactly one); the first match decides. A rate outside 0..1 is ignored with a warning; a rule that cannot be read is skipped with a warning and the rest are kept; a rule with no sample_rate keeps everything it matches; max_per_second on a rule is ignored with a warning, because the rate limit is global. :rate_limit caps how many traces the rules may keep per second, across every rule and the global rate together; 0 keeps none of them. A fraction is truncated to a whole number with a warning; a negative value or one that is not a number is ignored with a warning and 100 applies. DDTrace says how the decision is made and what it puts on the wire.

:shutdown_timeout is one budget doing two jobs, which is deliberate: it is how long any single submission may wait for the agent to answer, and how long the tracer's whole shutdown may take. The second is what makes the first true — a request already in flight when the VM starts stopping has to be bounded by something, or it outlives the budget and the payload it carried is lost. A submission that runs out of budget is dropped, not retried.

What the budget bounds is shutdown, not the final flush on its own. A submission already in flight when shutdown begins is waited out first, and the final flush gets what is left. So traces still buffered when an unreachable agent has spent the budget are lost. A final flush that finds the agent already failing does not start another request it cannot finish; it drops what it holds instead. Every one of those losses is counted in [:dd_trace, :exporter, :drop], the skip under its own reason, :agent_unreachable_at_shutdown. Raising the budget buys the last flush more room at the cost of a slower stop.

Correlating logs with traces

While a span is open, the process's Logger metadata carries the keys Datadog's UI correlates on, so a log line links to the trace it happened in and back:

[
  "dd.trace_id": "68d1f4a300000000453f7c31b09a2e04",
  "dd.span_id": "5013951231073820500",
  "dd.service": "storefront",
  "dd.env": "prod",
  "dd.version": "1.4.0"
]

Any JSON logger that emits metadata gets this for free. The keys are quoted atoms, because dd.trace_id is the spelling the UI reads — so a metadata: allowlist has to spell them the same way:

config :logger, :default_formatter,
  metadata: [:request_id, :"dd.trace_id", :"dd.span_id", :"dd.service"]

metadata: :all needs no list. Set :logs_injection to false — or DD_LOGS_INJECTION=false — and the tracer never touches Logger metadata at all.

Every span the agent receives has to name a service, so a span that names none of its own and a tracer configured with none either ship as unnamed-elixir-service — visible in the Datadog UI, and there to be recognized as a tracer nobody configured rather than mistaken for an application.

The x-datadog-tags budget

How many bytes of _dd.p.* trace tags a request may carry onward. It is clamped to 0..512: 512 is what the agent itself accepts, so honoring a larger number would ship a header the agent rejects, and a value outside the range is clamped with a warning rather than obeyed. 0 turns the header off in both directions, silently — an operator who set it to zero is not reporting a failure by doing so.

An explicit agent URL is authoritative: only http is supported for now, and a URL with no port keeps the scheme's default rather than 8126, which applies to the host-and-port form only. Anything else is ignored with a warning, and the host-and-port form takes over.

The resolved config is stored in :persistent_term: written once at boot and read on every DDTrace.info/0 call, which is exactly the read-mostly shape :persistent_term is for.