Parse Datadog trace and span id headers without exceptions

[dougqh]

What Does This Do

Parses x-datadog-trace-id and x-datadog-parent-id headers without throwing.

• LongStringUtils.parseUnsignedLongOrSentinel(CharSequence, start, len, ifInvalid): a new single-pass parser that never throws. It accepts 1 to 20 ASCII digits and returns a sentinel the caller chooses. An unsigned 64 bit id uses every bit (values above Long.MAX_VALUE are stored as negative longs), so the library cannot reserve a value for "invalid". The name says so, unlike the throwing parseUnsignedLong(String) and parseUnsignedLongHex(CharSequence, int, int, boolean).
• LongStringUtils.isUnsignedLongZero(CharSequence, start, len): tells a real zero (1 to 20 '0' characters) apart from the 0 sentinel. Callers check it only when the parse returned 0.
• LongStringUtils.parseUnsignedLong(String) now uses the new parser. A zero result falls back to the previous strict parser, so the input it accepts and the exceptions it throws are unchanged. Valid input gets faster (see below).
• DD64bTraceId.fromOrNull(String): internal, returns null instead of throwing. It keeps the parsed string, so toString() on inject still doesn't re-format the id. Calling DDTraceId.from(long) would have lost that.
• DatadogHttpCodec: malformed trace and span ids still invalidate the context and stop extraction, exactly as today, but there is no throw/catch, and the debug log is marked EXCLUDE_TELEMETRY. Bad input from a caller is not a tracer bug, and it repeats on every request from that caller.

Why 0 as the sentinel. 0 already means "no id" (ContextInterpreter treats a ZERO trace id as no context), so a caller that forgets the zero check still fails safe: a malformed header starts a fresh trace. A rarely seen valid value such as -1 would avoid most collisions, but a missed check would put every request with a bad header into one fake trace with id MAX. A Maybe / Try return would depend on escape analysis to avoid allocating on every request (and on boxing for a primitive payload), which is too risky on this path.

Motivation

Exceptions from parsing propagation headers are the largest group in Error Tracking for dd-trace-java 1.66 (the #apm-java-error-bots monitor scope). Over 30 days, issues 7d56e638 (numberFormatOutOfLongRange, 7.9M), 7d83ac0e (parseUnsignedLong, 3.6M), 4bd96434 (NumberFormatException.forInputString, 2.9M) and 7d4ce1b0 (DatadogHttpCodec.accept, 1.3M) all come through this path. They are marked IGNORED, which only stops the alerts: each one is still a thrown exception, with a full stack trace, on the request thread.

Additional Notes

Behavior change

On the header path only, a leading + and non-ASCII digits are now rejected. Before, ids of 18 digits or fewer went through Long.parseLong, which accepts both, while the hand-written 19 to 20 digit path rejected +. That mismatch suggests + support was never intended. The public DDTraceId.from / DDSpanId.from still accept both through the strict fallback.

Benchmarks

DatadogIdParseBenchmark (new; results also in its Javadoc). JDK 25, Apple M1 Max, 5 forks × 5 × 2s measurement. "Before" is origin/master running the same benchmark, without the fromOrNull arm. Each cell is the median of the 5 per-fork means, with the per-fork min-max in brackets, in ns/op (lower is better). I'm using medians and ranges because master's valid-id extraction is bimodal (one fork at 598 ns), and a mean with ± error hides that.

Full Datadog extraction (extract: trace id, parent id, sampling priority, user-agent):

x-datadog-trace-id	before (ns)	after (ns)	change
invalid, not decimal	882 [760-884]	21 [21-21]	~42x faster
invalid, unsigned max + 1	840 [821-947]	43 [42-43]	~20x faster
valid, 18 digits	153 [152-153]	107 [100-109]	-46 ns
valid, 19 digits	149 [119-598]	109 [108-110]	-40 ns (median)

Parsing the id alone:

x-datadog-trace-id	from + catch, before (ns)	from + catch, after (ns)	fromOrNull, after (ns)
invalid, not decimal	815 [804-836]	804 [792-809]	3 [3-3]
invalid, unsigned max + 1	875 [771-953]	919 [915-926]	24 [23-24]
valid, 18 digits	31 [31-31]	22 [22-23]	22 [22-23]
valid, 19 digits	32 [32-33]	24 [23-24]	24 [24-24]

• Invalid headers drop from 840-880 ns to 21-43 ns per extraction, because no exception is built. The benchmark's call stack is shallow; in a real server the stack trace runs through the whole server and decorator chain, so the saving in production is larger.
• Overflow vs not-decimal: overflow (24 ns to parse) is slower than not-decimal (3 ns) because all 20 digits are read before the overflow shows. Still about 36x cheaper than throwing.
• Valid ids parse about 9 ns faster, because a plain ASCII loop replaces Long.parseLong and Character.digit. The throwing from gets the same gain, since it now uses the new parser first.
• Extraction stability: every fork of this PR lands within a few ns. Master's valid-id extraction varies between forks and between runs (the 18-digit case was 119 ns in an earlier 2-fork run, 152 ns here). I haven't looked into why, so treat the valid-path extraction gain as roughly 40 ns at the median rather than a precise figure.
• Throwing path unchanged: from + catch on invalid input costs about the same before and after (800-920 ns). That's expected; the public throwing API still builds the exception.
• Logging: the test logback.xml on the JMH classpath sets the root logger to DEBUG. The benchmark resets it to INFO in @Setup. Otherwise the invalid arms measure console logging (about 240 µs/op on master).

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
  Use solves instead, and assign the PR milestone to the issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors
• Once approved, use merge queue to merge the PR

🤖 Generated with Claude Code

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.00 s	13.90 s	[+0.1%; +1.3%] (maybe worse)
startup:insecure-bank:tracing:Agent	12.97 s	12.99 s	[-0.9%; +0.6%] (no difference)
startup:petclinic:appsec:Agent	16.65 s	17.05 s	[-6.6%; +1.9%] (no difference)
startup:petclinic:iast:Agent	16.99 s	16.97 s	[-0.8%; +1.0%] (no difference)
startup:petclinic:profiling:Agent	16.06 s	16.65 s	[-7.9%; +0.8%] (no difference)
startup:petclinic:sca:Agent	17.12 s	16.85 s	[+0.5%; +2.6%] (maybe worse)
startup:petclinic:tracing:Agent	16.19 s	16.15 s	[-0.6%; +1.1%] (no difference)

Commit: 232328c9 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T13:58:13.797055Z	232328c	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 232328c94b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Avoid the compound extractor's remaining span-id exception

When two or more propagation styles are enabled—which is the default—CompoundExtractor first populates ExtractionCache, whose cacheDatadogSpanId still calls the throwing DDSpanId.from(value) before this interpreter runs. Therefore every malformed x-datadog-parent-id still constructs and catches a NumberFormatException on the request path under the normal configuration, preserving the cost this change is intended to remove; update that cache path to use the non-throwing parser too.

Useful? React with 👍 / 👎.

[datadog-datadog-prod-us1]

Overflowing start indices bypass the new helpers’ bounds checks, making an invalid slice appear to contain zero. Propagation callers use start=0, so this is an edge-case utility defect.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 232328c · @DataDog review to ask questions}

[datadog-datadog-prod-us1]

Prevent index overflow in both range helpers

For input "1", start=Integer.MAX_VALUE, and len=1, start + len wraps negative and bypasses the bounds check. The parser returns 0 instead of the chosen sentinel, while isUnsignedLongZero incorrectly returns true without reading a character. Both helpers need overflow-safe bounds checks; the parser's start + 18 calculation also needs overflow-safe arithmetic.

Was this helpful? React 👍 or 👎
_{🤖 Bits Code Review · @DataDog review to ask questions · Open Bits AI session}

[mhlidd]

Overall LGTM. Note that there is a call in HttpCodec.java that can still throw an exception. Not sure if that belongs in this PR or a follow-up.

edit: also mentioned in this AI comment.