Renames spring.sleuth.propagation-keys to remote-keys (#1604)

spring.sleuth.local-keys and spring.sleuth.remote-keys make sense
together, especially as baggage-keys will be removed.

README.adoc

@@ -383,18 +383,20 @@ spring.sleuth:
   baggage-keys:
     - baz
     - bizarrecase
-  propagation-keys:
-    - foo
-    - upper_case
+  local-keys:
+    - bp
+  remote-keys:
+    - country-code
+    - x-vcap-request-id
 ----
 
 .The code
 [source,java]
 ----
-initialSpan.tag("foo",
-		ExtraFieldPropagation.get(initialSpan.context(), "foo"));
-initialSpan.tag("UPPER_CASE",
-		ExtraFieldPropagation.get(initialSpan.context(), "UPPER_CASE"));
+static final BaggageField COUNTRY_CODE = BaggageField.create("country-code");
+
+COUNTRY_CODE.updateValue(span.context(), "FO");
+Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, span);
 ----
 
 [[sleuth-adding-project]]
@@ -983,4 +985,4 @@ Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on t
 - `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL.
 - `checkstyle.additional.suppressions.file` - this variable corresponds to suppressions in your local project. E.g. you're working on `spring-cloud-contract`. Then point to the `project-root/src/checkstyle/checkstyle-suppressions.xml` folder. Example for `spring-cloud-contract` would be: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`.
 
-IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources.
+IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources.

docs/src/main/asciidoc/_configprops.adoc

@@ -16,7 +16,7 @@
 |spring.sleuth.integration.enabled | true | Enable Spring Integration sleuth instrumentation.
 |spring.sleuth.integration.patterns | [!hystrixStreamOutput*, *, !channel*] | An array of patterns against which channel names will be matched. @see org.springframework.integration.config.GlobalChannelInterceptor#patterns() Defaults to any channel name not matching the Hystrix Stream and functional Stream channel names.
 |spring.sleuth.integration.websockets.enabled | true | Enable tracing for WebSockets.
-|spring.sleuth.local-keys |  | Same as {@link #propagationKeys} except that this field is not propagated to remote services. @see brave.propagation.ExtraFieldPropagation.FactoryBuilder#addRedactedField(String)
+|spring.sleuth.local-keys |  | Same as {@link #remoteKeys} except that this field is not propagated to remote services. @see brave.baggage.BaggagePropagationConfig.SingleBaggageField#local(BaggageField)
 |spring.sleuth.log.slf4j.enabled | true | Enable a {@link Slf4jScopeDecorator} that prints tracing information in the logs.
 |spring.sleuth.log.slf4j.whitelisted-mdc-keys |  | A list of keys to be put from baggage to MDC.
 |spring.sleuth.messaging.enabled | false | Should messaging be turned on.
@@ -28,7 +28,7 @@
 |spring.sleuth.messaging.rabbit.enabled | true | Enable tracing of RabbitMQ.
 |spring.sleuth.messaging.rabbit.remote-service-name | rabbitmq | 
 |spring.sleuth.opentracing.enabled | true | 
-|spring.sleuth.propagation-keys |  | List of fields that are referenced the same in-process as it is on the wire. For example, the name "x-vcap-request-id" would be set as-is including the prefix. <p> Note: {@code fieldName} will be implicitly lower-cased. @see brave.propagation.ExtraFieldPropagation.FactoryBuilder#addField(String)
+|spring.sleuth.remote-keys |  | List of fields that are referenced the same in-process as it is on the wire. For example, the name "x-vcap-request-id" would be set as-is including the prefix. <p> Note: {@code fieldName} will be implicitly lower-cased. @see brave.baggage.BaggagePropagationConfig.SingleBaggageField#remote(BaggageField)
 |spring.sleuth.propagation.tag.enabled | true | Enables a {@link TagPropagationFinishedSpanHandler} that adds extra propagated fields to span tags.
 |spring.sleuth.propagation.tag.whitelisted-keys |  | A list of keys to be put from extra propagation fields to span tags.
 |spring.sleuth.reactor.decorate-on-each | true | When true decorates on each operator, will be less performing, but logging will always contain the tracing entries in each operator. When false decorates on last operator, will be more performing, but logging might not always contain the tracing entries.

docs/src/main/asciidoc/spring-cloud-sleuth.adoc

@@ -88,13 +88,14 @@ In order to use the rate-limited sampler set the `spring.sleuth.sampler.rate` pr
 
 == Baggage
 With the `spring.sleuth.baggage-keys`, you set keys that get prefixed with `baggage-` for HTTP calls and `baggage_` for messaging.
-You can also use the `spring.sleuth.propagation-keys` property to pass a list of prefixed keys that are propagated to remote services without any prefix.
+You can also use the `spring.sleuth.remote-keys` property to pass a list of prefixed keys that are propagated to remote services without any prefix.
 You can also use the `spring.sleuth.local-keys` property to pass a list keys that will be propagated locally but will not be propagated over the wire.
 Notice that there's no `x-` in front of the header keys.
 
 In order to automatically set the baggage values to Slf4j's MDC, you have to set
 the `spring.sleuth.log.slf4j.whitelisted-mdc-keys` property with a list of whitelisted
-baggage and propagation keys. E.g. `spring.sleuth.log.slf4j.whitelisted-mdc-keys=foo` will set the value of the `foo` baggage into MDC.
+local or remote keys. E.g. `spring.sleuth.log.slf4j.whitelisted-mdc-keys=country-code` will set the
+value of the `country-code` baggage into MDC.
 
 IMPORTANT: Remember that adding entries to MDC can drastically decrease the performance of your application!
 

spring-cloud-sleuth-core/src/main/java/org/springframework/cloud/sleuth/autoconfig/PropertyBasedBaggageConfiguration.java

@@ -66,7 +66,7 @@ public class PropertyBasedBaggageConfiguration implements BeanFactoryPostProcess
 			baggageConfigs.add(SingleBaggageField.local(BaggageField.create(key)));
 		}
 
-		for (String key : collectKeysOfType(env, "propagation")) {
+		for (String key : collectKeysOfType(env, "remote")) {
 			baggageConfigs.add(SingleBaggageField.remote(BaggageField.create(key)));
 		}
 

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/autoconfig/TraceAutoConfigurationTests.java

@@ -92,31 +92,31 @@ public class TraceAutoConfigurationTests {
 				.run((context -> {
 					final Baggage bean = context.getBean(Baggage.class);
 					BDDAssertions.then(bean.fields).containsOnly(
-							BaggageField.create("userId"),
-							BaggageField.create("userName"));
+							BaggageField.create("country-code"),
+							BaggageField.create("x-vcap-request-id"));
 				}));
 	}
 
 	@Test
 	public void should_use_local_keys_from_properties() {
-		this.contextRunner.withPropertyValues("spring.sleuth.local-keys=test-key")
+		this.contextRunner.withPropertyValues("spring.sleuth.local-keys=bp")
 				.withUserConfiguration(Baggage.class).run((context -> {
 					final Baggage bean = context.getBean(Baggage.class);
 					BDDAssertions.then(bean.fields)
-							.containsExactly(BaggageField.create("test-key"));
+							.containsExactly(BaggageField.create("bp"));
 				}));
 	}
 
 	@Test
 	public void should_combine_baggage_beans_and_properties() {
-		this.contextRunner.withPropertyValues("spring.sleuth.local-keys=test-key")
+		this.contextRunner.withPropertyValues("spring.sleuth.local-keys=bp")
 				.withUserConfiguration(WithBaggageBeans.class, Baggage.class)
 				.run((context -> {
 					final Baggage bean = context.getBean(Baggage.class);
 					BDDAssertions.then(bean.fields).containsOnly(
-							BaggageField.create("userId"),
-							BaggageField.create("userName"),
-							BaggageField.create("test-key"));
+							BaggageField.create("country-code"),
+							BaggageField.create("x-vcap-request-id"),
+							BaggageField.create("bp"));
 				}));
 	}
 
@@ -151,13 +151,13 @@ public class TraceAutoConfigurationTests {
 	static class WithBaggageBeans {
 
 		@Bean
-		BaggagePropagationConfig userId() {
-			return SingleBaggageField.remote(BaggageField.create("userId"));
+		BaggagePropagationConfig countryCode() {
+			return SingleBaggageField.remote(BaggageField.create("country-code"));
 		}
 
 		@Bean
-		BaggagePropagationConfig userName() {
-			return SingleBaggageField.remote(BaggageField.create("userName"));
+		BaggagePropagationConfig requestId() {
+			return SingleBaggageField.remote(BaggageField.create("x-vcap-request-id"));
 		}
 
 	}

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/multiple/MultipleHopsIntegrationTests.java

@@ -25,7 +25,6 @@ import brave.Span;
 import brave.Tags;
 import brave.Tracer;
 import brave.Tracer.SpanInScope;
-import brave.Tracing;
 import brave.baggage.BaggageField;
 import brave.baggage.BaggagePropagationConfig;
 import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
@@ -57,11 +56,10 @@ import static org.springframework.boot.test.context.SpringBootTest.WebEnvironmen
 
 @SpringBootTest(classes = MultipleHopsIntegrationTests.Config.class,
 		webEnvironment = RANDOM_PORT, properties = { "spring.sleuth.baggage-keys=baz",
-				"spring.sleuth.propagation-keys=foo" })
+				"spring.sleuth.remote-keys=country-code" })
 public class MultipleHopsIntegrationTests {
 
-	@Autowired
-	Tracing tracing;
+	static final BaggageField COUNTRY_CODE = BaggageField.create("country-code");
 
 	@Autowired
 	Tracer tracer;
@@ -106,19 +104,18 @@ public class MultipleHopsIntegrationTests {
 	@Test
 	public void should_propagate_the_baggage() {
 		// TODO: make a DemoBaggage type instead of saying to use the api directly
-		BaggageField foo = BaggageField.create("foo");
 		BaggageField bar = BaggageField.create("bar");
 		BaggageField baz = BaggageField.create("baz");
 
 		// tag::baggage[]
 		Span initialSpan = this.tracer.nextSpan().name("span").start();
-		foo.updateValue(initialSpan.context(), "1");
+		COUNTRY_CODE.updateValue(initialSpan.context(), "FO");
 		bar.updateValue(initialSpan.context(), "2");
 		// end::baggage[]
 
 		try (SpanInScope ws = this.tracer.withSpanInScope(initialSpan)) {
 			// tag::baggage_tag[]
-			Tags.BAGGAGE_FIELD.tag(foo, initialSpan);
+			Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, initialSpan);
 			Tags.BAGGAGE_FIELD.tag(bar, initialSpan);
 			// end::baggage_tag[]
 
@@ -138,16 +135,16 @@ public class MultipleHopsIntegrationTests {
 		});
 
 		List<zipkin2.Span> withBagTags = this.reporter.getSpans().stream()
-				.filter(s -> s.tags().containsKey(foo.name())).collect(toList());
+				.filter(s -> s.tags().containsKey(COUNTRY_CODE.name())).collect(toList());
 
 		// set with tag api
 		then(withBagTags).as("only initialSpan was bag tagged").hasSize(1);
-		assertThat(withBagTags.get(0).tags()).containsEntry("foo", "1")
+		assertThat(withBagTags.get(0).tags()).containsEntry("country-code", "FO")
 				.containsEntry("bar", "2");
 
 		// set with baggage api
-		then(this.application.allSpans()).as("All have foo")
-				.allMatch(span -> "1".equals(foo.getValue(span.context())));
+		then(this.application.allSpans()).as("All have country-code")
+				.allMatch(span -> "FO".equals(COUNTRY_CODE.getValue(span.context())));
 		then(this.application.allSpans()).as("All have bar")
 				.allMatch(span -> "2".equals(bar.getValue(span.context())));
 

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/opentracing/BraveTracerTest.java

@@ -55,7 +55,7 @@ import static org.springframework.boot.test.context.SpringBootTest.WebEnvironmen
  * @author Marcin Grzejszczak
  */
 @SpringBootTest(webEnvironment = NONE,
-		properties = "spring.sleuth.baggage-keys=country-code,user-id")
+		properties = "spring.sleuth.baggage-keys=country-code,country-code")
 public class BraveTracerTest {
 
 	@Autowired

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/log/Slf4JSpanLoggerTest.java

@@ -18,6 +18,7 @@ package org.springframework.cloud.sleuth.log;
 
 import brave.Span;
 import brave.Tracer;
+import brave.baggage.BaggageField;
 import brave.baggage.CorrelationScopeConfig.SingleCorrelationField;
 import brave.propagation.CurrentTraceContext.Scope;
 import brave.propagation.CurrentTraceContext.ScopeDecorator;
@@ -41,13 +42,15 @@ import static org.assertj.core.api.Assertions.assertThat;
  */
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE, properties = {
 		"spring.sleuth.baggage-keys=my-baggage,my-baggage-two",
-		"spring.sleuth.propagation-keys=my-propagation",
-		"spring.sleuth.local-keys=my-local",
-		"spring.sleuth.log.slf4j.whitelisted-mdc-keys=my-baggage,my-propagation,my-local" })
+		"spring.sleuth.remote-keys=country-code", "spring.sleuth.local-keys=bp",
+		"spring.sleuth.log.slf4j.whitelisted-mdc-keys=my-baggage,country-code,bp" })
 @SpringBootConfiguration
 @EnableAutoConfiguration
 public class Slf4JSpanLoggerTest {
 
+	static final BaggageField COUNTRY_CODE = BaggageField.create("country-code");
+	static final BaggageField BUSINESS_PROCESS = BaggageField.create("bp");
+
 	@Autowired
 	Tracer tracer;
 
@@ -78,37 +81,35 @@ public class Slf4JSpanLoggerTest {
 	@Test
 	public void should_set_entries_to_mdc_from_span_with_baggage() throws Exception {
 		ExtraFieldPropagation.set(this.span.context(), "my-baggage", "my-value");
-		ExtraFieldPropagation.set(this.span.context(), "my-propagation",
-				"my-propagation-value");
-		ExtraFieldPropagation.set(this.span.context(), "my-local", "my-local-value");
+		COUNTRY_CODE.updateValue(this.span.context(), "FO");
+		BUSINESS_PROCESS.updateValue(this.span.context(), "ALM");
 		Scope scope = this.slf4jScopeDecorator.decorateScope(this.span.context(), () -> {
 		});
 
 		assertThat(MDC.get("my-baggage")).isEqualTo("my-value");
-		assertThat(MDC.get("my-propagation")).isEqualTo("my-propagation-value");
-		assertThat(MDC.get("my-local")).isEqualTo("my-local-value");
+		assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("FO");
+		assertThat(MDC.get(BUSINESS_PROCESS.name())).isEqualTo("ALM");
 
 		scope.close();
 
 		assertThat(MDC.get("my-baggage")).isNullOrEmpty();
-		assertThat(MDC.get("my-propagation")).isNullOrEmpty();
-		assertThat(MDC.get("my-local")).isNullOrEmpty();
+		assertThat(MDC.get(COUNTRY_CODE.name())).isNull();
+		assertThat(MDC.get(BUSINESS_PROCESS.name())).isNull();
 	}
 
 	@Test
 	public void should_remove_entries_from_mdc_for_null_span() throws Exception {
 		ExtraFieldPropagation.set(this.span.context(), "my-baggage", "my-value");
-		ExtraFieldPropagation.set(this.span.context(), "my-propagation",
-				"my-propagation-value");
+		COUNTRY_CODE.updateValue(this.span.context(), "FO");
 
 		try (Scope scope1 = this.slf4jScopeDecorator.decorateScope(this.span.context(),
 				NOOP)) {
 			assertThat(MDC.get("my-baggage")).isEqualTo("my-value");
-			assertThat(MDC.get("my-propagation")).isEqualTo("my-propagation-value");
+			assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("FO");
 
 			try (Scope scope2 = this.slf4jScopeDecorator.decorateScope(null, NOOP)) {
 				assertThat(MDC.get("my-baggage")).isNullOrEmpty();
-				assertThat(MDC.get("my-propagation")).isNullOrEmpty();
+				assertThat(MDC.get(COUNTRY_CODE.name())).isNullOrEmpty();
 			}
 		}
 	}
@@ -117,25 +118,25 @@ public class Slf4JSpanLoggerTest {
 	public void should_remove_entries_from_mdc_for_null_span_and_mdc_fields_set_directly()
 			throws Exception {
 		MDC.put("my-baggage", "my-value");
-		MDC.put("my-propagation", "my-propagation-value");
+		MDC.put(COUNTRY_CODE.name(), "FO");
 
 		// the span is holding no baggage so it clears the preceding values
 		try (Scope scope = this.slf4jScopeDecorator.decorateScope(this.span.context(),
 				NOOP)) {
 			assertThat(MDC.get("my-baggage")).isNullOrEmpty();
-			assertThat(MDC.get("my-propagation")).isNullOrEmpty();
+			assertThat(MDC.get(COUNTRY_CODE.name())).isNullOrEmpty();
 		}
 
 		assertThat(MDC.get("my-baggage")).isEqualTo("my-value");
-		assertThat(MDC.get("my-propagation")).isEqualTo("my-propagation-value");
+		assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("FO");
 
 		try (Scope scope = this.slf4jScopeDecorator.decorateScope(null, NOOP)) {
 			assertThat(MDC.get("my-baggage")).isNullOrEmpty();
-			assertThat(MDC.get("my-propagation")).isNullOrEmpty();
+			assertThat(MDC.get(COUNTRY_CODE.name())).isNullOrEmpty();
 		}
 
 		assertThat(MDC.get("my-baggage")).isEqualTo("my-value");
-		assertThat(MDC.get("my-propagation")).isEqualTo("my-propagation-value");
+		assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("FO");
 	}
 
 	@Test
@@ -161,15 +162,15 @@ public class Slf4JSpanLoggerTest {
 		});
 
 		MDC.put("my-baggage", "A");
-		MDC.put("my-propagation", "B");
+		MDC.put(COUNTRY_CODE.name(), "FO");
 
 		assertThat(MDC.get("my-baggage")).isEqualTo("A");
-		assertThat(MDC.get("my-propagation")).isEqualTo("B");
+		assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("FO");
 
 		scope.close();
 
 		assertThat(MDC.get("my-baggage")).isNullOrEmpty();
-		assertThat(MDC.get("my-propagation")).isNullOrEmpty();
+		assertThat(MDC.get(COUNTRY_CODE.name())).isNullOrEmpty();
 	}
 
 	@Test
@@ -178,29 +179,29 @@ public class Slf4JSpanLoggerTest {
 				.asInstanceOf(
 						InstanceOfAssertFactories.array(SingleCorrelationField[].class))
 				.extracting(SingleCorrelationField::name).containsOnly("traceId",
-						"parentId", "spanId", "spanExportable", "my-baggage", "my-local",
-						"my-propagation"); // my-baggage-two is not in the whitelist
+						"parentId", "spanId", "spanExportable", "my-baggage", "bp",
+						COUNTRY_CODE.name()); // my-baggage-two is not in the whitelist
 	}
 
 	@Test
 	public void should_pick_previous_mdc_entries_when_their_keys_are_whitelisted() {
 
 		MDC.put("my-baggage", "A1");
-		MDC.put("my-propagation", "B1");
+		MDC.put(COUNTRY_CODE.name(), "FO");
 
 		Scope scope = this.slf4jScopeDecorator.decorateScope(this.span.context(), () -> {
 		});
 
 		MDC.put("my-baggage", "A2");
-		MDC.put("my-propagation", "B2");
+		MDC.put(COUNTRY_CODE.name(), "BV");
 
 		assertThat(MDC.get("my-baggage")).isEqualTo("A2");
-		assertThat(MDC.get("my-propagation")).isEqualTo("B2");
+		assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("BV");
 
 		scope.close();
 
 		assertThat(MDC.get("my-baggage")).isEqualTo("A1");
-		assertThat(MDC.get("my-propagation")).isEqualTo("B1");
+		assertThat(MDC.get(COUNTRY_CODE.name())).isEqualTo("FO");
 	}
 
 }

spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/propagation/TagPropagationFinishedSpanHandlerTest.java

@@ -21,6 +21,7 @@ import java.util.Map;
 
 import brave.ScopedSpan;
 import brave.Tracer;
+import brave.baggage.BaggageField;
 import brave.propagation.ExtraFieldPropagation;
 import brave.propagation.TraceContext;
 import brave.sampler.Sampler;
@@ -41,19 +42,18 @@ import static org.assertj.core.api.Assertions.assertThat;
  */
 @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE, properties = {
 		"spring.sleuth.baggage-keys=my-baggage",
-		"spring.sleuth.propagation-keys=my-propagation,others-propagation",
-		"spring.sleuth.propagation.tag.whitelisted-keys=my-baggage,my-propagation" },
+		"spring.sleuth.remote-keys=country-code,x-vcap-request-id",
+		"spring.sleuth.propagation.tag.whitelisted-keys=my-baggage,country-code" },
 		classes = TagPropagationFinishedSpanHandlerTest.TestConfiguration.class)
 public class TagPropagationFinishedSpanHandlerTest {
 
+	static final BaggageField COUNTRY_CODE = BaggageField.create("country-code");
+	static final BaggageField REQUEST_ID = BaggageField.create("x-vcap-request-id");
+
 	private static final String BAGGAGE_KEY = "my-baggage";
 
 	private static final String BAGGAGE_VALUE = "332323";
 
-	private static final String PROPAGATION_KEY = "my-propagation";
-
-	private static final String PROPAGATION_VALUE = "332323";
-
 	@Autowired
 	private Tracer tracer;
 
@@ -68,8 +68,8 @@ public class TagPropagationFinishedSpanHandlerTest {
 		this.span = this.tracer.startScopedSpan("my-scoped-span");
 		TraceContext context = this.span.context();
 		ExtraFieldPropagation.set(context, BAGGAGE_KEY, BAGGAGE_VALUE);
-		ExtraFieldPropagation.set(context, PROPAGATION_KEY, PROPAGATION_VALUE);
-		ExtraFieldPropagation.set(context, "others-propagation", "some value");
+		COUNTRY_CODE.updateValue(context, "FO");
+		REQUEST_ID.updateValue(context, "f4308d05-2228-4468-80f6-92a8377ba193");
 	}
 
 	@Test
@@ -79,9 +79,9 @@ public class TagPropagationFinishedSpanHandlerTest {
 		List<zipkin2.Span> spans = this.arrayListSpanReporter.getSpans();
 		assertThat(spans).hasSize(1);
 		Map<String, String> tags = spans.get(0).tags();
-		assertThat(tags).hasSize(2);
+		assertThat(tags).hasSize(2); // REQUEST_ID is not in the whitelist
 		assertThat(tags).containsEntry(BAGGAGE_KEY, BAGGAGE_VALUE);
-		assertThat(tags).containsEntry(PROPAGATION_KEY, PROPAGATION_VALUE);
+		assertThat(tags).containsEntry(COUNTRY_CODE.name(), "FO");
 	}
 
 	@Configuration