Customizable headers

* Fixed the HttpServlet extractors
    (now the response can contain custom headers)
    * Changed header names to be Zipkin compatible
    * removed qualifiers and properties
    * updated the docs

fixes #19

docs/src/main/asciidoc/features.adoc

@@ -30,6 +30,10 @@ latency in your applications. Sleuth is written to not log too much, and to not
 * Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints,
 rest template, scheduled actions, message channels, zuul filters, feign client).
 
+* Sleuth includes default logic to join a trace across http or messaging boundaries. For example, http propagation
+works via Zipkin-compatible request headers. This propagation logic is defined and customized via
+`SpanInjector` and `SpanExtractor` implementations.
+
 * Provides simple metrics of accepted / dropped spans.
 
 * If `spring-cloud-sleuth-zipkin` then the app will generate and collect Zipkin-compatible traces.
@@ -45,6 +49,6 @@ IMPORTANT: If using Zipkin or Stream, configure the percentage of spans exported
 
 NOTE: the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example
  above. Other logging systems have to configure their own formatter to get the same result. The default is
- `logging.pattern.level` set to `%clr(%5p) %clr([${spring.application.name:},%X{X-Trace-Id:-},%X{X-Span-Id:-},%X{X-Span-Export:-}]){yellow}`
+ `logging.pattern.level` set to `%clr(%5p) %clr([${spring.application.name:},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}]){yellow}`
  (this is a Spring Boot feature for logback users).
  *This means that if you're not using SLF4J this pattern WILL NOT be automatically applied*.

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

@@ -191,7 +191,92 @@ adding a Channel Binder implementation
 (e.g. `spring-cloud-starter-stream-rabbit` for RabbitMQ or
 `spring-cloud-starter-stream-kafka` for Kafka). This will
 automatically turn your app into a producer of messages with payload
-type `Spans`. 
+type `Spans`.
+
+== Customizations
+
+Thanks to the `SpanInjector` and `SpanExtractor` you can customize the way spans
+are created and propagated.
+
+There are currently two built-in ways to pass tracing information between processes:
+
+ * via Spring Integration
+ * via HTTP
+
+Span ids are extracted from Zipkin-compatible (B3) headers (either `Message`
+or HTTP headers), to start or join an existing trace. Trace information is
+injected into any outbound requests so the next hop can extract them.
+
+=== Spring Integration
+
+For Spring Integration these are the beans responsible for creation of a Span from a `Message`
+ and filling in the `MessageBuilder` with tracing information.
+
+[source,java]
+----
+	@Bean
+	public SpanExtractor<Message> messagingSpanExtractor() {
+		...
+	}
+
+	@Bean
+	public SpanInjector<MessageBuilder> messagingSpanInjector() {
+		...
+	}
+----
+
+You can override them by providing your own implementation and by adding a `@Primary` annotation
+to your bean definition.
+
+=== HTTP
+
+For HTTP these are the beans responsible for creation of a Span from a `HttpServletRequest`
+  and filling in the `HttpServletResponse` with tracing information.
+
+[source,java]
+----
+@Bean
+public SpanExtractor<HttpServletRequest> httpServletRequestSpanExtractor() {
+    ...
+}
+
+@Bean
+public SpanInjector<HttpServletResponse> httpServletResponseSpanInjector() {
+	...
+}
+----
+
+You can override them by providing your own implementation and by adding a `@Primary` annotation
+to your bean definition.
+
+=== Example
+
+Let's assume that instead of the standard Zipkin compatible tracing HTTP header names
+you have
+
+* for trace id - `correlationId`
+* for span id - `mySpanId`
+
+This is a an example of a `SpanExtractor`
+
+[source,java]
+----
+include::../../../..//spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterCustomExtractorTests.java[tags=extractor,indent=0]
+----
+
+The following `SpanInjector` could be created
+
+[source,java]
+----
+include::../../../..//spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterCustomExtractorTests.java[tags=injector,indent=0]
+----
+
+And you could register them like this:
+
+[source,java]
+----
+include::../../../..//spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/TraceFilterCustomExtractorTests.java[tags=configuration,indent=0]
+----
 
 === Zipkin Consumer