From 7b1322403901e1369926f4918c2f7b623872ec3b Mon Sep 17 00:00:00 2001 From: Douglas Q Hawkins Date: Sat, 21 Nov 2026 09:45:55 -0500 Subject: [PATCH 1/2] Let carriers hand parse-only header values as transient views The propagation contract for parsing header values in place, with no producer yet, so nothing changes at runtime: - HeaderSchema.isParseOnly(): the Datadog trace id, parent id and sampling priority headers, whose readers only parse their values. - TransientValueConsumer: how a carrier hands such a value as a view valid only during the call. The composite propagator's cache implements it, keeps the view for the extraction (allocating its view slots only when one arrives), and copies it once if something reads it as a String. - IndexedCarrier.valueView(i), and KeyClassifier.acceptTransient(header, key, value), whose default copies the view and calls accept. Extraction hands views to acceptTransient and Strings to accept. ExtractorKeysForkedTest's carrier now hands parse-only values as views, so its per-style and compound equivalence checks cover this path. Co-Authored-By: Claude Opus 5.5 --- .../propagation/CompositePropagator.java | 48 ++++++++- .../context/propagation/HeaderSchema.java | 24 ++++- .../context/propagation/IndexedCarrier.java | 11 ++- .../propagation/TransientValueConsumer.java | 22 +++++ .../context/propagation/CarrierCacheTest.java | 98 +++++++++++++++++++ .../context/propagation/HeaderSchemaTest.java | 17 ++++ .../trace/core/propagation/HttpCodec.java | 15 ++- .../core/propagation/TracingPropagator.java | 2 +- .../propagation/ExtractorKeysForkedTest.java | 12 ++- .../instrumentation/api/AgentPropagation.java | 13 +++ 10 files changed, 251 insertions(+), 11 deletions(-) create mode 100644 components/context/src/main/java/datadog/context/propagation/TransientValueConsumer.java diff --git a/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java b/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java index ebd11bbdc90..68b2af5a4d6 100644 --- a/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java +++ b/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java @@ -79,7 +79,10 @@ public Context extract(Context context, C carrier, CarrierVisitor visitor * walking the carrier again, and readable in place as an {@link IndexedCarrier}. */ static final class CarrierCache - implements BiConsumer, CarrierVisitor, IndexedCarrier { + implements BiConsumer, + TransientValueConsumer, + CarrierVisitor, + IndexedCarrier { /** Enough for the trace headers a carrier usually holds once unread keys are skipped. */ private static final int INITIAL_PAIRS = 8; @@ -92,6 +95,13 @@ static final class CarrierCache */ private byte[] headers = new byte[INITIAL_PAIRS]; + /** + * Values handed as transient views, by pair, until copied; null until the first one, so + * carriers that hand only {@code String}s don't pay for it. The cache lives for one extraction, + * so the views stay in their scope. + */ + private CharSequence[] views; + private int size; /** Classifies keys with {@code keys}, which knows each declared name's constant. */ @@ -107,14 +117,31 @@ static final class CarrierCache @Override public void accept(String key, String value) { + add(key, value, key == null ? null : this.keys.header(key)); + } + + /** Keeps {@code value} as a view until something reads it as a {@code String}. */ + @Override + public void acceptTransient(HeaderSchema header, String key, CharSequence value) { + int index = this.size; + add(key, null, header); + if (this.views == null) { + this.views = new CharSequence[this.headers.length]; + } + this.views[index] = value; + } + + private void add(String key, String value, HeaderSchema header) { int index = 2 * this.size; if (index == this.keysAndValues.length) { this.keysAndValues = Arrays.copyOf(this.keysAndValues, 2 * index); this.headers = Arrays.copyOf(this.headers, this.size * 2); + if (this.views != null) { + this.views = Arrays.copyOf(this.views, this.size * 2); + } } this.keysAndValues[index] = key; this.keysAndValues[index + 1] = value; - HeaderSchema header = key == null ? null : this.keys.header(key); this.headers[this.size] = header == null ? 0 : (byte) (header.ordinal() + 1); this.size++; } @@ -122,7 +149,7 @@ public void accept(String key, String value) { @Override public void forEachKeyValue(CarrierCache carrier, BiConsumer visitor) { for (int i = 0; i < carrier.size; i++) { - visitor.accept(carrier.keysAndValues[2 * i], carrier.keysAndValues[2 * i + 1]); + visitor.accept(carrier.key(i), carrier.value(i)); } } @@ -136,9 +163,22 @@ public String key(int index) { return this.keysAndValues[2 * index]; } + /** The value as a {@code String}, copying a view once (and keeping the copy). */ @Override public String value(int index) { - return this.keysAndValues[2 * index + 1]; + String value = this.keysAndValues[2 * index + 1]; + if (value == null && this.views != null && this.views[index] != null) { + value = this.views[index].toString(); + this.keysAndValues[2 * index + 1] = value; + this.views[index] = null; + } + return value; + } + + @Override + public CharSequence valueView(int index) { + CharSequence view = this.views == null ? null : this.views[index]; + return view != null ? view : this.keysAndValues[2 * index + 1]; } @Override diff --git a/components/context/src/main/java/datadog/context/propagation/HeaderSchema.java b/components/context/src/main/java/datadog/context/propagation/HeaderSchema.java index 8e23137cacd..8291b6e3f5e 100644 --- a/components/context/src/main/java/datadog/context/propagation/HeaderSchema.java +++ b/components/context/src/main/java/datadog/context/propagation/HeaderSchema.java @@ -18,9 +18,9 @@ */ public enum HeaderSchema { // Datadog - X_DATADOG_TRACE_ID("x-datadog-trace-id"), - X_DATADOG_PARENT_ID("x-datadog-parent-id"), - X_DATADOG_SAMPLING_PRIORITY("x-datadog-sampling-priority"), + X_DATADOG_TRACE_ID("x-datadog-trace-id", true), + X_DATADOG_PARENT_ID("x-datadog-parent-id", true), + X_DATADOG_SAMPLING_PRIORITY("x-datadog-sampling-priority", true), X_DATADOG_ORIGIN("x-datadog-origin"), X_DATADOG_TAGS("x-datadog-tags"), // W3C trace context @@ -65,12 +65,30 @@ public enum HeaderSchema { /** {@link #headerName} in ASCII, for matching or writing a key without encoding it. */ private final byte[] asciiName; + /** Whether the header's value is only parsed: see {@link #isParseOnly()}. */ + private final boolean parseOnly; + /** {@code headerName} must be lower case, as {@code HeaderSchemaTest} checks. */ HeaderSchema(String headerName) { + this(headerName, false); + } + + HeaderSchema(String headerName, boolean parseOnly) { this.headerName = headerName; + this.parseOnly = parseOnly; this.asciiName = headerName.getBytes(US_ASCII); } + /** + * Whether every propagator that reads this header only parses its value (into a number, say) and + * keeps nothing of it, so a carrier may hand the value as a transient view instead of decoding it + * (see {@link TransientValueConsumer}). A propagator that starts keeping such a value must copy + * it, or this must change. + */ + public boolean isParseOnly() { + return parseOnly; + } + /** The length of {@link #headerName}, in chars and in ASCII bytes. */ public int length() { return asciiName.length; diff --git a/components/context/src/main/java/datadog/context/propagation/IndexedCarrier.java b/components/context/src/main/java/datadog/context/propagation/IndexedCarrier.java index 09efe7d2c9a..9c3879481c5 100644 --- a/components/context/src/main/java/datadog/context/propagation/IndexedCarrier.java +++ b/components/context/src/main/java/datadog/context/propagation/IndexedCarrier.java @@ -14,9 +14,18 @@ public interface IndexedCarrier { /** The key of pair {@code index}, from 0 to {@link #size()} - 1. */ String key(int index); - /** The value of pair {@code index}, from 0 to {@link #size()} - 1. */ + /** The value of pair {@code index}, from 0 to {@link #size()} - 1, as a {@code String}. */ String value(int index); + /** + * The value of pair {@code index}, possibly a transient view (see {@link TransientValueConsumer}) + * valid only during the extraction: parse it, or copy it to keep it. The default returns {@link + * #value(int)}. + */ + default CharSequence valueView(int index) { + return value(index); + } + /** * The {@link HeaderSchema} constant of pair {@code index}'s key, or null if it has none (an * unknown key, or a key the carrier didn't classify). Lets a propagator switch on the constant diff --git a/components/context/src/main/java/datadog/context/propagation/TransientValueConsumer.java b/components/context/src/main/java/datadog/context/propagation/TransientValueConsumer.java new file mode 100644 index 00000000000..c6cc6059ffe --- /dev/null +++ b/components/context/src/main/java/datadog/context/propagation/TransientValueConsumer.java @@ -0,0 +1,22 @@ +package datadog.context.propagation; + +/** + * A carrier visitor's callback that can take a value as a transient view: a {@code CharSequence} + * valid only during the call, for a carrier that holds values as bytes and can avoid decoding them. + * A carrier may hand a value this way only for a key whose {@link HeaderSchema} constant {@link + * HeaderSchema#isParseOnly() is parse-only}, and only if the visitor implements this interface; + * otherwise it decodes the value and calls {@code accept(key, value)} as usual. + * + *

An implementation must not keep the view past the call, nor hand it to anything that might: it + * may share the carrier's whole buffer. It copies the value ({@code toString()}) to keep it. + */ +public interface TransientValueConsumer { + /** + * Takes {@code key}'s value as a view valid only during this call. + * + * @param header {@code key}'s constant, which is parse-only + * @param key the key + * @param value the value, valid only during this call + */ + void acceptTransient(HeaderSchema header, String key, CharSequence value); +} diff --git a/components/context/src/test/java/datadog/context/propagation/CarrierCacheTest.java b/components/context/src/test/java/datadog/context/propagation/CarrierCacheTest.java index 683f2a2c25d..9b3e668cfc9 100644 --- a/components/context/src/test/java/datadog/context/propagation/CarrierCacheTest.java +++ b/components/context/src/test/java/datadog/context/propagation/CarrierCacheTest.java @@ -3,6 +3,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; import datadog.context.propagation.CompositePropagator.CarrierCache; import java.util.ArrayList; @@ -81,6 +82,103 @@ void keepsHeaderConstantsPastItsInitialCapacity() { } } + @Test + void keepsTransientValuesUntilReadAsStrings() { + CarrierCache cache = new CarrierCache(CarrierKeys.of(HeaderSchema.TRACEPARENT)); + StringBuilder view = new StringBuilder("123"); + cache.accept("traceparent", "tp"); + cache.acceptTransient(HeaderSchema.X_DATADOG_TRACE_ID, "x-datadog-trace-id", view); + + assertSame(HeaderSchema.X_DATADOG_TRACE_ID, cache.header(1)); + assertSame(view, cache.valueView(1)); + assertEquals("tp", cache.valueView(0)); + // reading it as a String copies it once, and keeps the copy + String copy = cache.value(1); + assertEquals("123", copy); + view.setLength(0); + assertSame(copy, cache.value(1)); + assertSame(copy, cache.valueView(1)); + } + + @Test + void visitsTransientValuesAsStrings() { + CarrierCache cache = new CarrierCache(); + cache.acceptTransient( + HeaderSchema.X_DATADOG_PARENT_ID, "x-datadog-parent-id", "456x".subSequence(0, 3)); + List seen = new ArrayList<>(); + cache.forEachKeyValue(cache, (key, value) -> seen.add(value)); + assertEquals(1, seen.size()); + assertEquals("456", seen.get(0)); + assertTrue(seen.get(0) instanceof String); + } + + @Test + void keepsTransientValuesPastItsInitialCapacity() { + CarrierCache cache = new CarrierCache(); + for (int i = 0; i < 20; i++) { + if (i % 2 == 0) { + cache.acceptTransient(HeaderSchema.X_DATADOG_TRACE_ID, "t" + i, new StringBuilder("v" + i)); + } else { + cache.accept("k" + i, "v" + i); + } + } + for (int i = 0; i < 20; i++) { + assertEquals("v" + i, cache.value(i)); + assertEquals(i % 2 == 0 ? HeaderSchema.X_DATADOG_TRACE_ID : null, cache.header(i)); + } + } + + @Test + void transientValueFirstThenStrings() { + CarrierCache cache = new CarrierCache(); + cache.accept("a", "1"); + cache.acceptTransient(HeaderSchema.X_DATADOG_TRACE_ID, "b", new StringBuilder("2")); + cache.accept("c", "3"); + assertEquals("1", cache.valueView(0)); + assertEquals("3", cache.valueView(2)); + assertEquals("2", cache.value(1)); + } + + @Test + void nullValuesWithAndWithoutViews() { + CarrierCache cache = new CarrierCache(); + cache.accept("a", null); + assertNull(cache.value(0)); + assertNull(cache.valueView(0)); + cache.acceptTransient(HeaderSchema.X_DATADOG_TRACE_ID, "b", new StringBuilder("2")); + cache.accept("c", null); + assertNull(cache.value(2)); + assertNull(cache.valueView(2)); + assertNull(cache.value(0)); + } + + @Test + void indexedCarrierViewsDefaultToValues() { + IndexedCarrier carrier = + new IndexedCarrier() { + @Override + public int size() { + return 1; + } + + @Override + public String key(int index) { + return "k"; + } + + @Override + public String value(int index) { + return "v"; + } + + @Override + public HeaderSchema header(int index) { + return null; + } + }; + assertEquals("v", carrier.valueView(0)); + } + @Test void emptyCache() { CarrierCache cache = new CarrierCache(); diff --git a/components/context/src/test/java/datadog/context/propagation/HeaderSchemaTest.java b/components/context/src/test/java/datadog/context/propagation/HeaderSchemaTest.java index 957c537670d..772d09dee12 100644 --- a/components/context/src/test/java/datadog/context/propagation/HeaderSchemaTest.java +++ b/components/context/src/test/java/datadog/context/propagation/HeaderSchemaTest.java @@ -48,6 +48,23 @@ void ordinalsFitInAByte() { assertTrue(HeaderSchema.count() < Byte.MAX_VALUE); } + @Test + void onlyDatadogIdHeadersAreParseOnly() { + Set parseOnly = new HashSet<>(); + for (HeaderSchema header : HeaderSchema.values()) { + if (header.isParseOnly()) { + parseOnly.add(header); + } + } + assertEquals( + new HashSet<>( + java.util.Arrays.asList( + HeaderSchema.X_DATADOG_TRACE_ID, + HeaderSchema.X_DATADOG_PARENT_ID, + HeaderSchema.X_DATADOG_SAMPLING_PRIORITY)), + parseOnly); + } + @Test void lookupsByNameAndOrdinal() { assertEquals(HeaderSchema.values().length, HeaderSchema.count()); diff --git a/dd-trace-core/src/main/java/datadog/trace/core/propagation/HttpCodec.java b/dd-trace-core/src/main/java/datadog/trace/core/propagation/HttpCodec.java index 72e689b75c8..a05509ec55d 100644 --- a/dd-trace-core/src/main/java/datadog/trace/core/propagation/HttpCodec.java +++ b/dd-trace-core/src/main/java/datadog/trace/core/propagation/HttpCodec.java @@ -90,6 +90,19 @@ default CarrierKeys keys() { default void cleanup() {} } + /** + * Hands pair {@code i} of {@code indexed} to {@code classifier}: a transient view through {@link + * AgentPropagation.KeyClassifier#acceptTransient}, a {@code String} through {@code accept}. + */ + static boolean acceptIndexed( + AgentPropagation.KeyClassifier classifier, IndexedCarrier indexed, int i) { + CharSequence value = indexed.valueView(i); + if (value == null || value instanceof String) { + return classifier.accept(indexed.header(i), indexed.key(i), (String) value); + } + return classifier.acceptTransient(indexed.header(i), indexed.key(i), value); + } + public static Injector createInjector( Config config, Set styles, @@ -439,7 +452,7 @@ public void forEachKey(ExtractionCache carrier, AgentPropagation.KeyClassifie IndexedCarrier indexed = carrier.indexed; if (indexed != null) { for (int i = 0, n = indexed.size(); i < n; i++) { - classifier.accept(indexed.header(i), indexed.key(i), indexed.value(i)); + acceptIndexed(classifier, indexed, i); } return; } diff --git a/dd-trace-core/src/main/java/datadog/trace/core/propagation/TracingPropagator.java b/dd-trace-core/src/main/java/datadog/trace/core/propagation/TracingPropagator.java index 465a0c2a164..6a223281bdd 100644 --- a/dd-trace-core/src/main/java/datadog/trace/core/propagation/TracingPropagator.java +++ b/dd-trace-core/src/main/java/datadog/trace/core/propagation/TracingPropagator.java @@ -92,7 +92,7 @@ private static AgentPropagation.ContextVisitor toContextVisitor( // the composite propagator's cache: hand each key's header constant along IndexedCarrier indexed = (IndexedCarrier) carrier; for (int i = 0, n = indexed.size(); i < n; i++) { - classifier.accept(indexed.header(i), indexed.key(i), indexed.value(i)); + HttpCodec.acceptIndexed(classifier, indexed, i); } } else { visitor.forEachKeyValue(carrier, classifier::accept); diff --git a/dd-trace-core/src/test/java/datadog/trace/core/propagation/ExtractorKeysForkedTest.java b/dd-trace-core/src/test/java/datadog/trace/core/propagation/ExtractorKeysForkedTest.java index 18683a94df1..99e77f0b6b5 100644 --- a/dd-trace-core/src/test/java/datadog/trace/core/propagation/ExtractorKeysForkedTest.java +++ b/dd-trace-core/src/test/java/datadog/trace/core/propagation/ExtractorKeysForkedTest.java @@ -252,13 +252,23 @@ public String value(int index) { public HeaderSchema header(int index) { return headers.get(index); } + + /** Parse-only values as views that aren't {@code String}s, as a byte carrier hands them. */ + @Override + public CharSequence valueView(int index) { + HeaderSchema header = headers.get(index); + String value = values.get(index); + return header != null && header.isParseOnly() && value != null + ? new StringBuilder(value) + : value; + } } /** Visits an {@link Indexed} carrier, handing each key's constant to the classifier. */ static final AgentPropagation.ContextVisitor WITH_HEADERS = (carrier, classifier) -> { for (int i = 0; i < carrier.size(); i++) { - if (!classifier.accept(carrier.header(i), carrier.key(i), carrier.value(i))) { + if (!HttpCodec.acceptIndexed(classifier, carrier, i)) { return; } } diff --git a/internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentPropagation.java b/internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentPropagation.java index 0ee46dc6164..2ced8f64a39 100644 --- a/internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentPropagation.java +++ b/internal-api/src/main/java/datadog/trace/bootstrap/instrumentation/api/AgentPropagation.java @@ -69,6 +69,19 @@ default boolean accept(String key, T value, Function transformer) default boolean accept(HeaderSchema header, String key, String value) { return accept(key, value); } + + /** + * Variant of {@link #accept(HeaderSchema, String, String)} for a value handed as a transient + * view (see {@code TransientValueConsumer}), valid only during this call: a classifier that + * overrides this parses it, or copies it ({@code toString()}) to keep it, and never keeps or + * hands on the view. The default copies it and calls {@link #accept(HeaderSchema, String, + * String)}. + * + * @return {@code false} to stop iteration, {@code true} to continue + */ + default boolean acceptTransient(HeaderSchema header, String key, CharSequence value) { + return accept(header, key, value == null ? null : value.toString()); + } } public interface ContextVisitor extends CarrierVisitor { From 14e69c05ca1a989fca90987d6b6fb9b9a8eaca8d Mon Sep 17 00:00:00 2001 From: Douglas Q Hawkins Date: Sat, 21 Nov 2026 10:11:28 -0500 Subject: [PATCH 2/2] Keep transient views in the carrier cache's pairs array The cache allocated a separate CharSequence[] the first time a view arrived, which on Kafka is every extraction (about 48 bytes). Values are now Objects in the one pairs array, a String or a view until read as a String. Co-Authored-By: Claude Opus 5.5 --- .../propagation/CompositePropagator.java | 45 +++++++------------ 1 file changed, 17 insertions(+), 28 deletions(-) diff --git a/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java b/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java index 68b2af5a4d6..782f24f239d 100644 --- a/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java +++ b/components/context/src/main/java/datadog/context/propagation/CompositePropagator.java @@ -86,8 +86,12 @@ static final class CarrierCache /** Enough for the trace headers a carrier usually holds once unread keys are skipped. */ private static final int INITIAL_PAIRS = 8; - /** Keys at even indexes, values at odd ones. */ - private String[] keysAndValues = new String[2 * INITIAL_PAIRS]; + /** + * Keys at even indexes, values at odd ones. A value is a {@code String}, or a transient view + * (handed through {@link #acceptTransient}) until something reads it as a {@code String}; one + * array either way, so views cost no extra allocation. + */ + private Object[] keysAndValues = new Object[2 * INITIAL_PAIRS]; /** * Each pair's {@link HeaderSchema} constant as {@code ordinal() + 1}, or 0 for none: a byte per @@ -95,13 +99,6 @@ static final class CarrierCache */ private byte[] headers = new byte[INITIAL_PAIRS]; - /** - * Values handed as transient views, by pair, until copied; null until the first one, so - * carriers that hand only {@code String}s don't pay for it. The cache lives for one extraction, - * so the views stay in their scope. - */ - private CharSequence[] views; - private int size; /** Classifies keys with {@code keys}, which knows each declared name's constant. */ @@ -123,22 +120,15 @@ public void accept(String key, String value) { /** Keeps {@code value} as a view until something reads it as a {@code String}. */ @Override public void acceptTransient(HeaderSchema header, String key, CharSequence value) { - int index = this.size; - add(key, null, header); - if (this.views == null) { - this.views = new CharSequence[this.headers.length]; - } - this.views[index] = value; + // the cache lives for one extraction, so the view stays in its scope + add(key, value, header); } - private void add(String key, String value, HeaderSchema header) { + private void add(String key, CharSequence value, HeaderSchema header) { int index = 2 * this.size; if (index == this.keysAndValues.length) { this.keysAndValues = Arrays.copyOf(this.keysAndValues, 2 * index); this.headers = Arrays.copyOf(this.headers, this.size * 2); - if (this.views != null) { - this.views = Arrays.copyOf(this.views, this.size * 2); - } } this.keysAndValues[index] = key; this.keysAndValues[index + 1] = value; @@ -160,25 +150,24 @@ public int size() { @Override public String key(int index) { - return this.keysAndValues[2 * index]; + return (String) this.keysAndValues[2 * index]; } /** The value as a {@code String}, copying a view once (and keeping the copy). */ @Override public String value(int index) { - String value = this.keysAndValues[2 * index + 1]; - if (value == null && this.views != null && this.views[index] != null) { - value = this.views[index].toString(); - this.keysAndValues[2 * index + 1] = value; - this.views[index] = null; + Object value = this.keysAndValues[2 * index + 1]; + if (value == null || value instanceof String) { + return (String) value; } - return value; + String copy = value.toString(); + this.keysAndValues[2 * index + 1] = copy; + return copy; } @Override public CharSequence valueView(int index) { - CharSequence view = this.views == null ? null : this.views[index]; - return view != null ? view : this.keysAndValues[2 * index + 1]; + return (CharSequence) this.keysAndValues[2 * index + 1]; } @Override