Ex. once added to `BaggagePropagation`, you can call below to affect the country code * of the current trace context: *
{@code
- * COUNTRY_CODE.updateValue("FO");
- * String countryCode = COUNTRY_CODE.get();
+ * COUNTRY_CODE.updateValue("FO");
+ * String countryCode = COUNTRY_CODE.get();
* }
*
* Or, if you have a reference to a trace context, it is more efficient to use it explicitly: *
{@code
- * COUNTRY_CODE.updateValue(span.context(), "FO");
- * String countryCode = COUNTRY_CODE.get(span.context());
- * Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, span);
+ * COUNTRY_CODE.updateValue(span.context(), "FO");
+ * String countryCode = COUNTRY_CODE.get(span.context());
+ * Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, span);
* }
*
* Correlation
* - * *You can also integrate baggage with other correlated contexts such as logging: *
{@code
+ * import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
+ * import brave.baggage.CorrelationScopeConfig.SingleCorrelationField;
+ *
* AMZN_TRACE_ID = BaggageField.create("x-amzn-trace-id");
*
* // Allow logging patterns like %X{traceId} %X{x-amzn-trace-id}
* decorator = MDCScopeDecorator.newBuilder()
- * .addField(AMZN_TRACE_ID).build();
+ * .add(SingleCorrelationField.create(AMZN_TRACE_ID)).build()
*
* tracingBuilder.propagationFactory(BaggagePropagation.newFactoryBuilder(B3Propagation.FACTORY)
- * .addRemoteField(AMZN_TRACE_ID)
+ * .add(SingleBaggageField.remote(AMZN_TRACE_ID))
* .build())
* .currentTraceContext(ThreadLocalCurrentTraceContext.newBuilder()
* .addScopeDecorator(decorator)
@@ -101,7 +103,7 @@
* propagate "arbitrary stuff" with a request.
*
* @see BaggagePropagation
- * @see CorrelationField
+ * @see CorrelationScopeConfig
* @since 5.11
*/
public final class BaggageField {
@@ -197,7 +199,7 @@ public static List getAll(TraceContextOrSamplingFlags extracted) {
* made current.
*
* @see #getByName(TraceContext, String)
- * @see CorrelationField#name()
+ * @see CorrelationScopeConfig.SingleCorrelationField#name()
* @since 5.11
*/
public final String name() {
diff --git a/brave/src/main/java/brave/baggage/BaggagePropagation.java b/brave/src/main/java/brave/baggage/BaggagePropagation.java
index 86bddc29ab..9ea31605d3 100644
--- a/brave/src/main/java/brave/baggage/BaggagePropagation.java
+++ b/brave/src/main/java/brave/baggage/BaggagePropagation.java
@@ -13,6 +13,7 @@
*/
package brave.baggage;
+import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
import brave.internal.baggage.BaggageHandler;
import brave.internal.baggage.BaggageHandlers;
import brave.internal.baggage.ExtraBaggageFields;
@@ -21,7 +22,6 @@
import brave.propagation.TraceContext.Extractor;
import brave.propagation.TraceContext.Injector;
import brave.propagation.TraceContextOrSamplingFlags;
-import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
@@ -38,13 +38,15 @@
* For example, if you have a need to know the a specific request's country code, you can
* propagate it through the trace as HTTP headers.
*
{@code
+ * import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
+ *
* // Configure your baggage field
* COUNTRY_CODE = BaggageField.create("country-code");
*
* // When you initialize the builder, add the baggage you want to propagate
* tracingBuilder.propagationFactory(
* BaggagePropagation.newFactoryBuilder(B3Propagation.FACTORY)
- * .addRemoteField(COUNTRY_CODE)
+ * .add(SingleBaggageField.remote(COUNTRY_CODE))
* .build()
* );
*
@@ -52,32 +54,38 @@
* Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, span);
* }
*
- * Customizing propagtion keys
- * By default, the name used as a propagation key (header) by {@link
- * FactoryBuilder#addRemoteField(BaggageField, String...)} is the same as the lowercase variant of
- * the field name. You can override this by supplying different key names. Note: they will be
- * lower-cased.
+ * See {@link BaggageField} for baggage usage examples.
+ *
+ *
Customizing propagation keys
+ * {@link SingleBaggageField#remote(BaggageField)} sets the name used as a propagation key (header)
+ * to the lowercase variant of the field name. You can override this by supplying different key
+ * names. Note: they will be lower-cased.
*
* For example, the following will propagate the field "x-vcap-request-id" as-is, but send the
* fields "countryCode" and "userId" on the wire as "baggage-country-code" and "baggage-user-id"
* respectively.
*
*
{@code
+ * import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
+ *
* REQUEST_ID = BaggageField.create("x-vcap-request-id");
* COUNTRY_CODE = BaggageField.create("countryCode");
* USER_ID = BaggageField.create("userId");
*
* tracingBuilder.propagationFactory(
* BaggagePropagation.newFactoryBuilder(B3Propagation.FACTORY)
- * .addRemoteField(REQUEST_ID)
- * .addRemoteField(COUNTRY_CODE, "baggage-country-code")
- * .addRemoteField(USER_ID, "baggage-user-id").build())
+ * .add(SingleBaggageField.remote(REQUEST_ID))
+ * .add(SingleBaggageField.newBuilder(COUNTRY_CODE)
+ * .addKeyName("baggage-country-code").build())
+ * .add(SingleBaggageField.newBuilder(USER_ID)
+ * .addKeyName("baggage-user-id").build())
+ * .build()
* );
* }
*
- * See {@link BaggageField} for usage examples
- *
* @see BaggageField
+ * @see BaggagePropagationConfig
+ * @see BaggagePropagationCustomizer
* @see CorrelationScopeDecorator
* @since 5.11
*/
@@ -91,6 +99,7 @@ public static class FactoryBuilder { // not final to backport ExtraFieldPropagat
final Propagation.Factory delegate;
final Set allKeyNames = new LinkedHashSet<>();
final Map> fieldToKeyNames = new LinkedHashMap<>();
+ final Set configs = new LinkedHashSet<>();
FactoryBuilder(Propagation.Factory delegate) {
if (delegate == null) throw new NullPointerException("delegate == null");
@@ -98,75 +107,43 @@ public static class FactoryBuilder { // not final to backport ExtraFieldPropagat
}
/**
- * Returns an immutable copy of the currently configured fields mapped to names for use in
- * remote propagation. This allows those who can't create the builder to reconfigure this
- * builder.
+ * Returns an immutable copy of the current {@linkplain #add(BaggagePropagationConfig)
+ * configuration}. This allows those who can't create the builder to reconfigure this builder.
*
+ * @see #clear()
* @since 5.11
*/
- public Map> fieldToKeyNames() {
- return Collections.unmodifiableMap(new LinkedHashMap<>(fieldToKeyNames));
+ public Set configs() {
+ return Collections.unmodifiableSet(new LinkedHashSet<>(configs));
}
/**
* Clears all state. This allows those who can't create the builder to reconfigure fields.
*
- * @see #fieldToKeyNames()
+ * @see #configs()
* @see BaggagePropagationCustomizer
* @since 5.11
*/
public FactoryBuilder clear() {
allKeyNames.clear();
fieldToKeyNames.clear();
+ configs.clear();
return this;
}
- /**
- * Adds a {@linkplain BaggageField baggage field}, but does not configure remote propagation.
- *
- * @throws IllegalArgumentException if the field was already added
- * @since 5.11
- */
- public FactoryBuilder addField(BaggageField field) {
- if (field == null) throw new NullPointerException("field == null");
- if (fieldToKeyNames.containsKey(field)) {
- throw new IllegalArgumentException(field.name + " already added");
+ /** @since 5.11 */
+ public FactoryBuilder add(BaggagePropagationConfig config) {
+ if (config == null) throw new NullPointerException("config == null");
+ if (!(config instanceof SingleBaggageField)) {
+ throw new UnsupportedOperationException("dynamic fields not yet supported");
}
- fieldToKeyNames.put(field, Collections.emptySet());
- return this;
- }
-
- /**
- * Adds a {@linkplain BaggageField baggage field} for remote propagation.
- *
- * When {@code keyNames} are not supplied the field is referenced the same in-process as it
- * is on the wire. For example, the {@linkplain BaggageField#name() name} "x-vcap-request-id"
- * would be set as-is including the prefix.
- *
- * @param keyNames possibly empty lower-case {@link Propagation#keys() propagation key names}.
- * @throws IllegalArgumentException if the field was already added or a key name is already in
- * use.
- * @since 5.11
- */
- public FactoryBuilder addRemoteField(BaggageField field, String... keyNames) {
- if (field == null) throw new NullPointerException("field == null");
- if (keyNames == null) throw new NullPointerException("keyNames == null");
- return addRemoteField(field, Arrays.asList(keyNames));
- }
-
- /**
- * Same as {@link #addRemoteField(BaggageField, String...)}.
- *
- * @since 5.11
- */
- public FactoryBuilder addRemoteField(BaggageField field, Iterable keyNames) {
- if (field == null) throw new NullPointerException("field == null");
- if (keyNames == null) throw new NullPointerException("keyNames == null");
- if (fieldToKeyNames.containsKey(field)) {
- throw new IllegalArgumentException(field.name + " already added");
+ SingleBaggageField field = (SingleBaggageField) config;
+ if (fieldToKeyNames.containsKey(field.field)) {
+ throw new IllegalArgumentException(field.field.name + " already added");
}
+ configs.add(field);
Set lcKeyNames = new LinkedHashSet<>();
- for (String keyName : keyNames) {
+ for (String keyName : field.keyNames) {
String lcName = validateName(keyName).toLowerCase(Locale.ROOT);
if (allKeyNames.contains(lcName)) {
throw new IllegalArgumentException("Propagation key already in use: " + lcName);
@@ -175,12 +152,7 @@ public FactoryBuilder addRemoteField(BaggageField field, Iterable keyNam
lcKeyNames.add(lcName);
}
- if (lcKeyNames.isEmpty()) { // add the default name
- allKeyNames.add(field.lcName);
- lcKeyNames.add(field.lcName);
- }
-
- fieldToKeyNames.put(field, Collections.unmodifiableSet(lcKeyNames));
+ fieldToKeyNames.put(field.field, Collections.unmodifiableSet(lcKeyNames));
return this;
}
diff --git a/brave/src/main/java/brave/baggage/BaggagePropagationConfig.java b/brave/src/main/java/brave/baggage/BaggagePropagationConfig.java
new file mode 100644
index 0000000000..418aac1a2c
--- /dev/null
+++ b/brave/src/main/java/brave/baggage/BaggagePropagationConfig.java
@@ -0,0 +1,172 @@
+/*
+ * Copyright 2013-2020 The OpenZipkin Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package brave.baggage;
+
+import brave.propagation.Propagation;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.Locale;
+import java.util.Set;
+
+import static brave.baggage.BaggageField.validateName;
+
+/**
+ * Holds {@link BaggagePropagation} configuration.
+ *
+ * Field mapping
+ * Your log correlation properties may not be the same as the baggage field names. You can override
+ * them with the builder as needed.
+ *
+ * Ex. If your log property is %X{trace-id}, you can do this:
+ *
{@code
+ * import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
+ *
+ * scopeBuilder.clear() // TRACE_ID is a default field!
+ * .add(SingleBaggageField.newBuilder(BaggageFields.TRACE_ID)
+ * .name("trace-id").build())
+ * }
+ *
+ * NoteAt the moment, dynamic fields are not supported. Use {@link
+ * SingleBaggageField} for each field you need to propagate.
+ *
+ * @see BaggagePropagation
+ * @see BaggageField
+ * @see BaggagePropagationConfig
+ * @see BaggagePropagationCustomizer
+ * @since 5.11
+ */
+public class BaggagePropagationConfig {
+
+ /**
+ * Holds {@link BaggagePropagation} configuration for a {@linkplain BaggageField baggage field}.
+ *
+ * @see BaggagePropagation
+ * @see BaggageField
+ * @since 5.11
+ */
+ public static class SingleBaggageField extends BaggagePropagationConfig {
+
+ /**
+ * Configures this field for only local propagation. This will not be read from or written to
+ * remote headers.
+ *
+ * @see #remote(BaggageField)
+ * @since 5.11
+ */
+ public static SingleBaggageField local(BaggageField field) {
+ return new Builder(field).build();
+ }
+
+ /**
+ * Configures this field for remote propagation using its lower-case {@link BaggageField#name()}
+ * as the only {@linkplain #keyNames() propagation key name}.
+ *
+ * @see #local(BaggageField)
+ * @see #newBuilder(BaggageField) to use different propagation key names.
+ */
+ public static SingleBaggageField remote(BaggageField field) {
+ return new Builder(field).addKeyName(field.lcName).build();
+ }
+
+ /** @since 5.11 */
+ public static Builder newBuilder(BaggageField field) {
+ return new Builder(field);
+ }
+
+ /**
+ * Allows decorators to reconfigure correlation of this {@link #field()}
+ *
+ * @see BaggagePropagationCustomizer
+ * @since 5.11
+ */
+ public Builder toBuilder() {
+ return new Builder(this);
+ }
+
+ /** @since 5.11 */
+ public static final class Builder {
+ final BaggageField field;
+ Set keyNames = new LinkedHashSet<>();
+
+ Builder(BaggageField field) {
+ this.field = field;
+ }
+
+ Builder(SingleBaggageField input) {
+ this.field = input.field;
+ this.keyNames = new LinkedHashSet<>(input.keyNames());
+ }
+
+ /**
+ * Configures a {@linkplain Propagation#keys() key name} for remote propagation.
+ *
+ * @see SingleBaggageField#keyNames()
+ * @since 5.11
+ */
+ public Builder addKeyName(String keyName) {
+ if (keyName == null) throw new NullPointerException("keyName == null");
+ String lcName = validateName(keyName).toLowerCase(Locale.ROOT);
+ keyNames.add(lcName);
+ return this;
+ }
+
+ /** @since 5.11 */
+ public SingleBaggageField build() {
+ return new SingleBaggageField(this);
+ }
+ }
+
+ final BaggageField field;
+ final Set keyNames;
+
+ SingleBaggageField(Builder builder) { // sealed to this package
+ field = builder.field;
+ keyNames = builder.keyNames.isEmpty() ? Collections.emptySet()
+ : Collections.unmodifiableSet(new LinkedHashSet<>(builder.keyNames));
+ }
+
+ public BaggageField field() {
+ return field;
+ }
+
+ /**
+ * Returns a possibly empty list of lower-case {@link Propagation#keys() propagation key names}.
+ * When empty, the field is not propagated remotely.
+ *
+ * @since 5.11
+ */
+ public Set keyNames() {
+ return keyNames;
+ }
+
+ @Override public String toString() {
+ return "SingleBaggageFieldConfig{" + field + "}";
+ }
+
+ /** Returns true for any config with the same baggage field. */
+ @Override public boolean equals(Object o) {
+ if (o == this) return true;
+ if (!(o instanceof SingleBaggageField)) return false;
+ return field.equals(((SingleBaggageField) o).field);
+ }
+
+ /** Returns the same value for any config with the same baggage field. */
+ @Override public int hashCode() {
+ return field.hashCode();
+ }
+ }
+
+ BaggagePropagationConfig() { // sealed
+ }
+}
diff --git a/brave/src/main/java/brave/baggage/BaggagePropagationCustomizer.java b/brave/src/main/java/brave/baggage/BaggagePropagationCustomizer.java
index a7892e61d6..485af62b90 100644
--- a/brave/src/main/java/brave/baggage/BaggagePropagationCustomizer.java
+++ b/brave/src/main/java/brave/baggage/BaggagePropagationCustomizer.java
@@ -19,7 +19,7 @@
* This allows configuration plugins to collaborate on building an instance of {@link
* BaggagePropagation.Factory}.
*
- * For example, a customizer can {@link BaggagePropagation.FactoryBuilder#addRemoteField(BaggageField)
+ *
For example, a customizer can {@link BaggagePropagation.FactoryBuilder#add(BaggagePropagationConfig)
* add a baggage field} without affecting the {@link BaggagePropagation#newFactoryBuilder(Propagation.Factory)
* trace propagation format}.
*
@@ -42,6 +42,7 @@
*
*
* @see CorrelationScopeCustomizer
+ * @see BaggagePropagationConfig
* @since 5.11
*/
public interface BaggagePropagationCustomizer {
diff --git a/brave/src/main/java/brave/baggage/CorrelationField.java b/brave/src/main/java/brave/baggage/CorrelationField.java
deleted file mode 100644
index f48d99f2af..0000000000
--- a/brave/src/main/java/brave/baggage/CorrelationField.java
+++ /dev/null
@@ -1,205 +0,0 @@
-/*
- * Copyright 2013-2020 The OpenZipkin Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
- * in compliance with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License
- * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
- * or implied. See the License for the specific language governing permissions and limitations under
- * the License.
- */
-package brave.baggage;
-
-import brave.internal.baggage.BaggageContext;
-import brave.propagation.CurrentTraceContext;
-import brave.propagation.TraceContext;
-
-/**
- * Holds {@link CorrelationScopeDecorator} configuration for a {@linkplain BaggageField baggage
- * field}.
- *
- * Ex. If your log property is %X{trace-id}, you can do this: - *
{@code
- * scopeBuilder.clear() // TRACE_ID is a default field!
- * .add(CorrelationField.newBuilder(BaggageFields.TRACE_ID)
- * .name("trace-id").build())
- * }
- *
- * By default, field updates only apply during {@linkplain CorrelationScopeDecorator scope - * decoration}. This means values set do not flush immediately to the underlying correlation - * context. Rather, they are scheduled for the next scope operation as a way to control overhead. - * {@link CorrelationField#flushOnUpdate()} overrides this. - * - * @see CorrelationScopeDecorator - * @see BaggageField - * @since 5.11 - */ -public final class CorrelationField { - /** @since 5.11 */ - public static CorrelationField create(BaggageField baggageField) { - return new Builder(baggageField).build(); - } - - /** @since 5.11 */ - public static Builder newBuilder(BaggageField baggageField) { - return new Builder(baggageField); - } - - /** - * Allows decorators to reconfigure correlation of this {@link #baggageField()} - * - * @see CorrelationScopeCustomizer - * @since 5.11 - */ - public Builder toBuilder() { - return new Builder(this); - } - - /** @since 5.11 */ - public static final class Builder { - final BaggageField baggageField; - String name; - boolean dirty, flushOnUpdate; - - Builder(BaggageField baggageField) { - this.baggageField = baggageField; - this.name = baggageField.name(); - } - - Builder(CorrelationField input) { - baggageField = input.baggageField; - name = input.name; - dirty = input.dirty; - flushOnUpdate = input.flushOnUpdate; - } - - /** @see CorrelationField#name() */ - public Builder name(String name) { - this.name = BaggageField.validateName(name); - return this; - } - - /** @see CorrelationField#dirty() */ - public Builder dirty() { - this.dirty = true; - return this; - } - - /** @see CorrelationField#flushOnUpdate() */ - public Builder flushOnUpdate() { - this.flushOnUpdate = true; - return this; - } - - /** @since 5.11 */ - public CorrelationField build() { - return new CorrelationField(this); - } - } - - final BaggageField baggageField; - final String name; - final boolean dirty, flushOnUpdate, readOnly; - - CorrelationField(Builder builder) { // sealed to this package - baggageField = builder.baggageField; - name = builder.name; - dirty = builder.dirty; - flushOnUpdate = builder.flushOnUpdate; - readOnly = baggageField.context instanceof BaggageContext.ReadOnly; - } - - public BaggageField baggageField() { - return baggageField; - } - - /** - * The name to use in the correlation context. This defaults to {@link BaggageField#name()} unless - * overridden by {@link Builder#name(String)}. - * - * @since 5.11 - */ - public String name() { - return name; - } - - /** - * Adds a name in the underlying context which is updated directly. The decorator will overwrite - * any underlying changes when the scope closes. - * - *
This is used when there are a mix of libraries controlling the same correlation field. - * For example, if SLF4J MDC can update the same field name. - * - *
This has a similar performance impact to {@link #flushOnUpdate()}, as it requires tracking - * the field value even if there's no change detected. - * - * @since 5.11 - */ - public boolean dirty() { - return dirty; - } - - /** - * When true, updates made to this name via {@linkplain BaggageField#updateValue(TraceContext, - * String)} flush immediately to the correlation context. - * - *
This is useful for callbacks that have a void return. Ex. - *
{@code
- * @SendTo(SourceChannels.OUTPUT)
- * public void timerMessageSource() {
- * // Assume BUSINESS_PROCESS is an updatable field
- * BUSINESS_PROCESS.updateValue("accounting");
- * // Assuming a Log4j context, the expression %{bp} will show "accounting" in businessCode()
- * businessCode();
- * }
- * }
- *
- * Most fields do not change in the scope of a {@link TraceContext}. For example, standard - * fields such as {@link BaggageFields#SPAN_ID the span ID} and {@linkplain - * BaggageFields#constant(String, String) constants} such as env variables do not need to be - * tracked. Even field value updates do not necessarily need to be flushed to the underlying - * correlation context, as they will apply on the next scope operation. - * - * @since 5.11 - */ - public boolean flushOnUpdate() { - return flushOnUpdate; - } - - /** Returns true if this value is immutable within a {@link TraceContext}. */ - public boolean readOnly() { - return readOnly; - } - - @Override public String toString() { - String baggageName = baggageField.name; - if (baggageName.equals(name)) { - return "CorrelationField{" + name + "}"; - } - return "CorrelationField{" + baggageName + "->" + name + "}"; - } - - /** Returns true for any correlation field with the same baggage field. */ - @Override public boolean equals(Object o) { - if (o == this) return true; - if (!(o instanceof CorrelationField)) return false; - return baggageField.equals(((CorrelationField) o).baggageField); - } - - /** Returns the same value for any correlation field with the same baggage field. */ - @Override public int hashCode() { - return baggageField.hashCode(); - } -} diff --git a/brave/src/main/java/brave/baggage/CorrelationFlushScope.java b/brave/src/main/java/brave/baggage/CorrelationFlushScope.java index 2417a99663..016c5cacfe 100644 --- a/brave/src/main/java/brave/baggage/CorrelationFlushScope.java +++ b/brave/src/main/java/brave/baggage/CorrelationFlushScope.java @@ -22,7 +22,7 @@ import static brave.baggage.CorrelationScopeDecorator.equal; -/** Sets up thread locals needed to support {@link CorrelationField#flushOnUpdate()} */ +/** Sets up thread locals needed to support {@link CorrelationScopeConfig#flushOnUpdate()} */ final class CorrelationFlushScope extends AtomicBoolean implements Scope { final CorrelationUpdateScope updateScope; diff --git a/brave/src/main/java/brave/baggage/CorrelationScopeConfig.java b/brave/src/main/java/brave/baggage/CorrelationScopeConfig.java new file mode 100644 index 0000000000..3365080eb7 --- /dev/null +++ b/brave/src/main/java/brave/baggage/CorrelationScopeConfig.java @@ -0,0 +1,224 @@ +/* + * Copyright 2013-2020 The OpenZipkin Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ +package brave.baggage; + +import brave.internal.baggage.BaggageContext; +import brave.propagation.CurrentTraceContext; +import brave.propagation.TraceContext; + +/** + * Holds {@link CorrelationScopeDecorator} configuration. + * + *
Ex. If your log property is %X{trace-id}, you can do this: + *
{@code
+ * import brave.baggage.CorrelationScopeConfig.SingleCorrelationField;
+ *
+ * scopeBuilder.clear() // TRACE_ID is a default field!
+ * .add(SingleCorrelationField.newBuilder(BaggageFields.TRACE_ID)
+ * .name("trace-id").build())
+ * }
+ *
+ * NoteAt the moment, dynamic fields are not supported. Use {@link + * SingleCorrelationField} for each field you need in the correlation context. + * + * @see CorrelationScopeDecorator + * @see BaggageField + * @since 5.11 + */ +public class CorrelationScopeConfig { + + /** + * Holds {@link CorrelationScopeDecorator} configuration for a {@linkplain BaggageField baggage + * field}. + * + *
By default, field updates only apply during {@linkplain CorrelationScopeDecorator scope + * decoration}. This means values set do not flush immediately to the underlying correlation + * context. Rather, they are scheduled for the next scope operation as a way to control overhead. + * {@link SingleCorrelationField#flushOnUpdate()} overrides this. + * + * @see CorrelationScopeDecorator + * @see BaggageField + * @since 5.11 + */ + public static class SingleCorrelationField extends CorrelationScopeConfig { + + /** @since 5.11 */ + public static SingleCorrelationField create(BaggageField baggageField) { + return new Builder(baggageField).build(); + } + + /** @since 5.11 */ + public static Builder newBuilder(BaggageField baggageField) { + return new Builder(baggageField); + } + + /** + * Allows decorators to reconfigure correlation of this {@link #baggageField()} + * + * @see CorrelationScopeCustomizer + * @since 5.11 + */ + public Builder toBuilder() { + return new Builder(this); + } + + /** @since 5.11 */ + public static final class Builder { + final BaggageField baggageField; + String name; + boolean dirty, flushOnUpdate; + + Builder(BaggageField baggageField) { + this.baggageField = baggageField; + this.name = baggageField.name(); + } + + Builder(SingleCorrelationField input) { + baggageField = input.baggageField; + name = input.name; + dirty = input.dirty; + flushOnUpdate = input.flushOnUpdate; + } + + /** @see SingleCorrelationField#name() */ + public Builder name(String name) { + this.name = BaggageField.validateName(name); + return this; + } + + /** @see SingleCorrelationField#dirty() */ + public Builder dirty() { + this.dirty = true; + return this; + } + + /** @see SingleCorrelationField#flushOnUpdate() */ + public Builder flushOnUpdate() { + this.flushOnUpdate = true; + return this; + } + + /** @since 5.11 */ + public SingleCorrelationField build() { + return new SingleCorrelationField(this); + } + } + + final BaggageField baggageField; + final String name; + final boolean dirty, flushOnUpdate, readOnly; + + SingleCorrelationField(Builder builder) { // sealed to this package + baggageField = builder.baggageField; + name = builder.name; + dirty = builder.dirty; + flushOnUpdate = builder.flushOnUpdate; + readOnly = baggageField.context instanceof BaggageContext.ReadOnly; + } + + public BaggageField baggageField() { + return baggageField; + } + + /** + * The name to use in the correlation context. This defaults to {@link BaggageField#name()} + * unless overridden by {@link Builder#name(String)}. + * + * @since 5.11 + */ + public String name() { + return name; + } + + /** + * Adds a name in the underlying context which is updated directly. The decorator will overwrite + * any underlying changes when the scope closes. + * + *
This is used when there are a mix of libraries controlling the same correlation field. + * For example, if SLF4J MDC can update the same field name. + * + *
This has a similar performance impact to {@link #flushOnUpdate()}, as it requires + * tracking the field value even if there's no change detected. + * + * @since 5.11 + */ + public boolean dirty() { + return dirty; + } + + /** + * When true, updates made to this name via {@linkplain BaggageField#updateValue(TraceContext, + * String)} flush immediately to the correlation context. + * + *
This is useful for callbacks that have a void return. Ex. + *
{@code
+ * @SendTo(SourceChannels.OUTPUT)
+ * public void timerMessageSource() {
+ * // Assume BUSINESS_PROCESS is an updatable field
+ * BUSINESS_PROCESS.updateValue("accounting");
+ * // Assuming a Log4j context, the expression %{bp} will show "accounting" in businessCode()
+ * businessCode();
+ * }
+ * }
+ *
+ * Most fields do not change in the scope of a {@link TraceContext}. For example, standard + * fields such as {@link BaggageFields#SPAN_ID the span ID} and {@linkplain + * BaggageFields#constant(String, String) constants} such as env variables do not need to be + * tracked. Even field value updates do not necessarily need to be flushed to the underlying + * correlation context, as they will apply on the next scope operation. + * + * @since 5.11 + */ + public boolean flushOnUpdate() { + return flushOnUpdate; + } + + /** Returns true if this value is immutable within a {@link TraceContext}. */ + public boolean readOnly() { + return readOnly; + } + + @Override public String toString() { + String baggageName = baggageField.name; + if (baggageName.equals(name)) { + return "SingleCorrelationField{" + name + "}"; + } + return "SingleCorrelationField{" + baggageName + "->" + name + "}"; + } + + /** Returns true for any config with the same baggage field. */ + @Override public boolean equals(Object o) { + if (o == this) return true; + if (!(o instanceof SingleCorrelationField)) return false; + return baggageField.equals(((SingleCorrelationField) o).baggageField); + } + + /** Returns the same value for any config with the same baggage field. */ + @Override public int hashCode() { + return baggageField.hashCode(); + } + } + + CorrelationScopeConfig() { // sealed + } +} diff --git a/brave/src/main/java/brave/baggage/CorrelationScopeCustomizer.java b/brave/src/main/java/brave/baggage/CorrelationScopeCustomizer.java index a7f9a724ab..1667dd9062 100644 --- a/brave/src/main/java/brave/baggage/CorrelationScopeCustomizer.java +++ b/brave/src/main/java/brave/baggage/CorrelationScopeCustomizer.java @@ -19,7 +19,7 @@ * This allows configuration plugins to collaborate on building an instance of {@link * CorrelationScopeDecorator}. * - *
For example, a customizer can {@linkplain CorrelationScopeDecorator.Builder#addField(CorrelationField) + *
For example, a customizer can {@linkplain CorrelationScopeDecorator.Builder#add(CorrelationScopeConfig) * configure a baggage field} without instantiating the {@link CorrelationScopeDecorator.Builder). * *
This also allows one object to customize both {@linkplain BaggagePropagation baggage} @@ -40,6 +40,7 @@ *
Setup example: *
{@code
+ * import brave.baggage.CorrelationScopeConfig.SingleCorrelationField;
+ *
* // Add the field "region", so it can be used as a log expression %X{region}
* CLOUD_REGION = BaggageFields.constant("region", System.getEnv("CLOUD_REGION"));
+ *
* decorator = MDCScopeDecorator.newBuilder()
- * .addField(CorrelationField.create(CLOUD_REGION))
+ * .add(SingleCorrelationField.create(CLOUD_REGION))
* .build();
*
* // Integrate the decorator
@@ -57,7 +61,9 @@
* }
* }
*
- * @see CorrelationField
+ * @see CorrelationScopeConfig
+ * @see CorrelationScopeCustomizer
+ * @see BaggagePropagation
* @since 5.11
*/
public abstract class CorrelationScopeDecorator implements ScopeDecorator {
@@ -67,36 +73,36 @@ public static abstract class Builder {
final CorrelationContext context;
// Don't allow mixed case of the same name!
final SetDefaults may include a field you aren't using, such as {@link BaggageFields#PARENT_ID}.
* For best performance, only include the fields you use in your correlation expressions (such
* as log formats).
*
- * @see #fields()
+ * @see #configs()
* @see CorrelationScopeDecorator
* @since 5.11
*/
@@ -106,13 +112,13 @@ public Builder clear() {
return this;
}
- /**
- * Adds a correlation property into the context with its {@link BaggageField#name()}.
- *
- * @since 5.11
- */
- public Builder addField(CorrelationField field) {
- if (field == null) throw new NullPointerException("field == null");
+ /** @since 5.11 */
+ public Builder add(CorrelationScopeConfig config) {
+ if (config == null) throw new NullPointerException("config == null");
+ if (!(config instanceof SingleCorrelationField)) {
+ throw new UnsupportedOperationException("dynamic fields not yet supported");
+ }
+ SingleCorrelationField field = (SingleCorrelationField) config;
if (fields.contains(field)) {
throw new IllegalArgumentException(
"Baggage Field already added: " + field.baggageField.name);
@@ -130,7 +136,7 @@ public final ScopeDecorator build() {
if (fieldCount == 0) return ScopeDecorator.NOOP;
if (fieldCount == 1) return new Single(context, fields.iterator().next());
if (fieldCount > 32) throw new IllegalArgumentException("over 32 baggage fields");
- return new Multiple(context, fields.toArray(new CorrelationField[0]));
+ return new Multiple(context, fields.toArray(new SingleCorrelationField[0]));
}
}
@@ -141,9 +147,9 @@ public final ScopeDecorator build() {
}
static final class Single extends CorrelationScopeDecorator {
- final CorrelationField field;
+ final SingleCorrelationField field;
- Single(CorrelationContext context, CorrelationField field) {
+ Single(CorrelationContext context, SingleCorrelationField field) {
super(context);
this.field = field;
}
@@ -171,9 +177,9 @@ static final class Single extends CorrelationScopeDecorator {
}
static final class Multiple extends CorrelationScopeDecorator {
- final CorrelationField[] fields;
+ final SingleCorrelationField[] fields;
- Multiple(CorrelationContext context, CorrelationField[] fields) {
+ Multiple(CorrelationContext context, SingleCorrelationField[] fields) {
super(context);
this.fields = fields;
}
@@ -184,7 +190,7 @@ static final class Multiple extends CorrelationScopeDecorator {
String[] valuesToRevert = new String[fields.length];
for (int i = 0; i < fields.length; i++) {
- CorrelationField field = fields[i];
+ SingleCorrelationField field = fields[i];
String valueToRevert = context.getValue(field.name);
String currentValue = field.baggageField.getValue(traceContext);
diff --git a/brave/src/main/java/brave/baggage/CorrelationUpdateScope.java b/brave/src/main/java/brave/baggage/CorrelationUpdateScope.java
index c473f62832..756566effd 100644
--- a/brave/src/main/java/brave/baggage/CorrelationUpdateScope.java
+++ b/brave/src/main/java/brave/baggage/CorrelationUpdateScope.java
@@ -13,6 +13,7 @@
*/
package brave.baggage;
+import brave.baggage.CorrelationScopeConfig.SingleCorrelationField;
import brave.internal.CorrelationContext;
import brave.internal.Nullable;
import brave.propagation.CurrentTraceContext.Scope;
@@ -45,14 +46,14 @@ abstract class CorrelationUpdateScope extends AtomicBoolean implements Scope {
static final class Single extends CorrelationUpdateScope {
final Scope delegate;
- final CorrelationField field;
+ final SingleCorrelationField field;
final @Nullable String valueToRevert;
boolean shouldRevert;
Single(
Scope delegate,
CorrelationContext context,
- CorrelationField field,
+ SingleCorrelationField field,
@Nullable String valueToRevert,
boolean shouldRevert
) {
@@ -82,14 +83,14 @@ static final class Single extends CorrelationUpdateScope {
static final class Multiple extends CorrelationUpdateScope {
final Scope delegate;
- final CorrelationField[] fields;
+ final SingleCorrelationField[] fields;
final String[] valuesToRevert;
int shouldRevert;
Multiple(
Scope delegate,
CorrelationContext context,
- CorrelationField[] fields,
+ SingleCorrelationField[] fields,
String[] valuesToRevert,
int shouldRevert
) {
diff --git a/brave/src/main/java/brave/propagation/ExtraFieldPropagation.java b/brave/src/main/java/brave/propagation/ExtraFieldPropagation.java
index 5297156f58..5b37328fe4 100644
--- a/brave/src/main/java/brave/propagation/ExtraFieldPropagation.java
+++ b/brave/src/main/java/brave/propagation/ExtraFieldPropagation.java
@@ -15,6 +15,7 @@
import brave.baggage.BaggageField;
import brave.baggage.BaggagePropagation;
+import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
import brave.internal.Nullable;
import brave.propagation.TraceContext.Extractor;
import brave.propagation.TraceContext.Injector;
@@ -69,9 +70,7 @@
this.baggageFactory = BaggagePropagation.newFactoryBuilder(delegate);
}
- /**
- * @deprecated Since 5.11, use {@link BaggagePropagation.FactoryBuilder#addField(BaggageField)}
- */
+ /** @deprecated Since 5.11, use {@link SingleBaggageField#local(BaggageField)} */
@Deprecated public FactoryBuilder addRedactedField(String fieldName) {
fieldName = validateFieldName(fieldName);
redactedNames.add(fieldName);
@@ -79,20 +78,14 @@
return this;
}
- /**
- * @deprecated Since 5.11, use {@link BaggagePropagation.FactoryBuilder#addRemoteField(BaggageField,
- * String...)}.
- */
+ /** @deprecated Since 5.11, use {@link SingleBaggageField#remote(BaggageField)} */
@Deprecated public FactoryBuilder addField(String fieldName) {
fieldName = validateFieldName(fieldName);
addKeyName(fieldName, fieldName);
return this;
}
- /**
- * @deprecated Since 5.11, use {@link BaggagePropagation.FactoryBuilder#addRemoteField(BaggageField,
- * Iterable)}
- */
+ /** @deprecated Since 5.11, use {@link SingleBaggageField.Builder#addKeyName(String)} */
@Deprecated public FactoryBuilder addPrefixedFields(String prefix, Collection
-
\n"
- + " \n"
- + "
\n"
- + " \n"
- + "
\n"
@@ -112,31 +89,6 @@ public class BaggagePropagationFactoryBeanTest {
.containsExactly("baggage_user_id", "baggage-user-id");
}
- @Test public void remoteFields_defaultKeyName() {
- context = new XmlBeans(""
- + "
\n"
- + "
\n"
- + " \n"
- + " \n"
+ + "
\n"
+ " \n"
- + "
\n"
+ + "
\n"
+ + "