871 lines
174 KiB
HTML
871 lines
174 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>Spring Cloud Sleuth</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Spring Cloud Sleuth</h1></div><div><span xmlns:d="http://docbook.org/ns/docbook" class="author"><span class="firstname">Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer</span></span></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#d0e17"></a></span></dt><dt><span class="chapter"><a href="#_introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#_terminology">1.1. Terminology</a></span></dt><dt><span class="section"><a href="#_purpose">1.2. Purpose</a></span></dt><dd><dl><dt><span class="section"><a href="#_distributed_tracing_with_zipkin">1.2.1. Distributed tracing with Zipkin</a></span></dt><dt><span class="section"><a href="#_visualizing_errors">1.2.2. Visualizing errors</a></span></dt><dt><span class="section"><a href="#_distributed_tracing_with_brave">1.2.3. Distributed tracing with Brave</a></span></dt><dt><span class="section"><a href="#_live_examples">1.2.4. Live examples</a></span></dt><dt><span class="section"><a href="#_log_correlation">1.2.5. Log correlation</a></span></dt><dd><dl><dt><span class="section"><a href="#_json_logback_with_logstash">JSON Logback with Logstash</a></span></dt></dl></dd><dt><span class="section"><a href="#_propagating_span_context">1.2.6. Propagating Span Context</a></span></dt><dd><dl><dt><span class="section"><a href="#_baggage_vs_span_tags">Baggage vs. Span Tags</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_adding_to_the_project">1.3. Adding to the project</a></span></dt><dd><dl><dt><span class="section"><a href="#_only_sleuth_log_correlation">1.3.1. Only Sleuth (log correlation)</a></span></dt><dt><span class="section"><a href="#_sleuth_with_zipkin_via_http">1.3.2. Sleuth with Zipkin via HTTP</a></span></dt><dt><span class="section"><a href="#_sleuth_with_zipkin_via_rabbitmq_or_kafka">1.3.3. Sleuth with Zipkin via RabbitMQ or Kafka</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_additional_resources">2. Additional resources</a></span></dt><dt><span class="chapter"><a href="#_features">3. Features</a></span></dt><dd><dl><dt><span class="section"><a href="#_introduction_to_brave">3.1. Introduction to Brave</a></span></dt><dd><dl><dt><span class="section"><a href="#_tracing">3.1.1. Tracing</a></span></dt><dt><span class="section"><a href="#_tracing_2">3.1.2. Tracing</a></span></dt><dt><span class="section"><a href="#_local_tracing">3.1.3. Local Tracing</a></span></dt><dt><span class="section"><a href="#_customizing_spans">3.1.4. Customizing spans</a></span></dt><dt><span class="section"><a href="#_implicitly_looking_up_the_current_span">3.1.5. Implicitly looking up the current span</a></span></dt><dt><span class="section"><a href="#_rpc_tracing">3.1.6. RPC tracing</a></span></dt><dd><dl><dt><span class="section"><a href="#_one_way_tracing">One-Way tracing</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="chapter"><a href="#_sampling">4. Sampling</a></span></dt><dd><dl><dt><span class="section"><a href="#_declarative_sampling">4.1. Declarative sampling</a></span></dt><dt><span class="section"><a href="#_custom_sampling">4.2. Custom sampling</a></span></dt><dt><span class="section"><a href="#_sampling_in_spring_cloud_sleuth">4.3. Sampling in Spring Cloud Sleuth</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_propagation">5. Propagation</a></span></dt><dd><dl><dt><span class="section"><a href="#_propagating_extra_fields">5.1. Propagating extra fields</a></span></dt><dd><dl><dt><span class="section"><a href="#_prefixed_fields">5.1.1. Prefixed fields</a></span></dt><dt><span class="section"><a href="#_extracting_a_propagated_context">5.1.2. Extracting a propagated context</a></span></dt><dt><span class="section"><a href="#_sharing_span_ids_between_client_and_server">5.1.3. Sharing span IDs between client and server</a></span></dt><dt><span class="section"><a href="#_implementing_propagation">5.1.4. Implementing Propagation</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_current_tracing_component">6. Current Tracing Component</a></span></dt><dt><span class="chapter"><a href="#_current_span">7. Current Span</a></span></dt><dd><dl><dt><span class="section"><a href="#_setting_a_span_in_scope_manually">7.1. Setting a span in scope manually</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_instrumentation">8. Instrumentation</a></span></dt><dt><span class="chapter"><a href="#_span_lifecycle">9. Span lifecycle</a></span></dt><dd><dl><dt><span class="section"><a href="#creating-and-finishing-spans">9.1. Creating and finishing spans</a></span></dt><dt><span class="section"><a href="#continuing-spans">9.2. Continuing spans</a></span></dt><dt><span class="section"><a href="#creating-spans-with-explicit-parent">9.3. Creating spans with an explicit parent</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_naming_spans">10. Naming spans</a></span></dt><dd><dl><dt><span class="section"><a href="#__spanname_annotation">10.1. @SpanName annotation</a></span></dt><dt><span class="section"><a href="#_tostring_method">10.2. toString() method</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_managing_spans_with_annotations">11. Managing spans with annotations</a></span></dt><dd><dl><dt><span class="section"><a href="#_rationale">11.1. Rationale</a></span></dt><dt><span class="section"><a href="#_creating_new_spans">11.2. Creating new spans</a></span></dt><dt><span class="section"><a href="#_continuing_spans">11.3. Continuing spans</a></span></dt><dt><span class="section"><a href="#_more_advanced_tag_setting">11.4. More advanced tag setting</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_extractor">11.4.1. Custom extractor</a></span></dt><dt><span class="section"><a href="#_resolving_expressions_for_value">11.4.2. Resolving expressions for value</a></span></dt><dt><span class="section"><a href="#_using_tostring_method">11.4.3. Using toString method</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_customizations">12. Customizations</a></span></dt><dd><dl><dt><span class="section"><a href="#_spring_integration">12.1. Spring Integration</a></span></dt><dt><span class="section"><a href="#_http">12.2. HTTP</a></span></dt><dt><span class="section"><a href="#_tracefilter">12.3. TraceFilter</a></span></dt><dt><span class="section"><a href="#_custom_service_name">12.4. Custom service name</a></span></dt><dt><span class="section"><a href="#_customization_of_reported_spans">12.5. Customization of reported spans</a></span></dt><dt><span class="section"><a href="#_host_locator">12.6. Host locator</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_sending_spans_to_zipkin">13. Sending spans to Zipkin</a></span></dt><dt><span class="chapter"><a href="#_zipkin_stream_span_consumer">14. Zipkin Stream Span Consumer</a></span></dt><dt><span class="chapter"><a href="#_integrations">15. Integrations</a></span></dt><dd><dl><dt><span class="section"><a href="#_opentracing">15.1. OpenTracing</a></span></dt><dt><span class="section"><a href="#_runnable_and_callable">15.2. Runnable and Callable</a></span></dt><dt><span class="section"><a href="#_hystrix">15.3. Hystrix</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_concurrency_strategy">15.3.1. Custom Concurrency Strategy</a></span></dt><dt><span class="section"><a href="#_manual_command_setting">15.3.2. Manual Command setting</a></span></dt></dl></dd><dt><span class="section"><a href="#_rxjava">15.4. RxJava</a></span></dt><dt><span class="section"><a href="#_http_integration">15.5. HTTP integration</a></span></dt><dd><dl><dt><span class="section"><a href="#_http_filter">15.5.1. HTTP Filter</a></span></dt><dt><span class="section"><a href="#_handlerinterceptor">15.5.2. HandlerInterceptor</a></span></dt><dt><span class="section"><a href="#_async_servlet_support">15.5.3. Async Servlet support</a></span></dt><dt><span class="section"><a href="#_webflux_support">15.5.4. WebFlux support</a></span></dt></dl></dd><dt><span class="section"><a href="#_http_client_integration">15.6. HTTP client integration</a></span></dt><dd><dl><dt><span class="section"><a href="#_synchronous_rest_template">15.6.1. Synchronous Rest Template</a></span></dt><dt><span class="section"><a href="#_asynchronous_rest_template">15.6.2. Asynchronous Rest Template</a></span></dt><dd><dl><dt><span class="section"><a href="#_multiple_asynchronous_rest_templates">Multiple Asynchronous Rest Templates</a></span></dt></dl></dd><dt><span class="section"><a href="#_webclient">15.6.3. WebClient</a></span></dt><dt><span class="section"><a href="#_traverson">15.6.4. Traverson</a></span></dt></dl></dd><dt><span class="section"><a href="#_feign">15.7. Feign</a></span></dt><dt><span class="section"><a href="#_asynchronous_communication">15.8. Asynchronous communication</a></span></dt><dd><dl><dt><span class="section"><a href="#__async_annotated_methods">15.8.1. @Async annotated methods</a></span></dt><dt><span class="section"><a href="#__scheduled_annotated_methods">15.8.2. @Scheduled annotated methods</a></span></dt><dt><span class="section"><a href="#_executor_executorservice_and_scheduledexecutorservice">15.8.3. Executor, ExecutorService and ScheduledExecutorService</a></span></dt><dd><dl><dt><span class="section"><a href="#_customization_of_executors">Customization of Executors</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_messaging">15.9. Messaging</a></span></dt><dt><span class="section"><a href="#_zuul">15.10. Zuul</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_running_examples">16. Running examples</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="d0e17" href="#d0e17"></a></h1></div></div></div><p><span class="strong"><strong>2.0.0.M7</strong></span></p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_introduction" href="#_introduction"></a>1. Introduction</h1></div></div></div><p>Spring Cloud Sleuth implements a distributed tracing solution for <a class="link" href="http://cloud.spring.io" target="_top">Spring Cloud</a>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_terminology" href="#_terminology"></a>1.1 Terminology</h2></div></div></div><p>Spring Cloud Sleuth borrows <a class="link" href="http://research.google.com/pubs/pub36356.html" target="_top">Dapper’s</a> terminology.</p><p><span class="strong"><strong>Span:</strong></span> The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an
|
|
RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span
|
|
is a part of. Spans also have other data, such as descriptions, timestamped events, key-value
|
|
annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address).</p><p>Spans are started and stopped, and they keep track of their timing information. Once you create a
|
|
span, you must stop it at some point in the future.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>The initial span that starts a trace is called a <code class="literal">root span</code>. The value of span id
|
|
of that span is equal to trace id.</p></td></tr></table></div><p><span class="strong"><strong>Trace:</strong></span> A set of spans forming a tree-like structure. For example, if you are running a distributed
|
|
big-data store, a trace might be formed by a put request.</p><p><span class="strong"><strong>Annotation:</strong></span> is used to record existence of an event in time. With
|
|
<a class="link" href="https://github.com/openzipkin/brave" target="_top">Brave</a> instrumentation we no longer need to set special events
|
|
for <a class="link" href="https://zipkin.io/" target="_top">Zipkin</a> to understand who the client and server are and where
|
|
the request started and where it has ended. For learning purposes
|
|
however we will mark these events to highlight what kind
|
|
of an action took place.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>cs</strong></span> - Client Sent - The client has made a request. This annotation depicts the start of the span.</li><li class="listitem"><span class="strong"><strong>sr</strong></span> - Server Received - The server side got the request and will start processing it.
|
|
If one subtracts the cs timestamp from this timestamp one will receive the network latency.</li><li class="listitem"><span class="strong"><strong>ss</strong></span> - Server Sent - Annotated upon completion of request processing (when the response
|
|
got sent back to the client). If one subtracts the sr timestamp from this timestamp one
|
|
will receive the time needed by the server side to process the request.</li><li class="listitem"><span class="strong"><strong>cr</strong></span> - Client Received - Signifies the end of the span. The client has successfully received the
|
|
response from the server side. If one subtracts the cs timestamp from this timestamp one
|
|
will receive the whole time needed by the client to receive the response from the server.</li></ul></div><p>Visualization of what <span class="strong"><strong>Span</strong></span> and <span class="strong"><strong>Trace</strong></span> will look in a system together with the Zipkin annotations:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/trace-id.png" alt="Trace Info propagation"></div></div><p>Each color of a note signifies a span (7 spans - from <span class="strong"><strong>A</strong></span> to <span class="strong"><strong>G</strong></span>). If you have such information in the note:</p><pre class="screen">Trace Id = X
|
|
Span Id = D
|
|
Client Sent</pre><p>That means that the current span has <span class="strong"><strong>Trace-Id</strong></span> set to <span class="strong"><strong>X</strong></span>, <span class="strong"><strong>Span-Id</strong></span> set to <span class="strong"><strong>D</strong></span>. Also, the
|
|
<span class="strong"><strong>Client Sent</strong></span> event took place.</p><p>This is how the visualization of the parent / child relationship of spans would look like:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/parents.png" alt="Parent child relationship"></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_purpose" href="#_purpose"></a>1.2 Purpose</h2></div></div></div><p>In the following sections the example from the image above will be taken into consideration.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_distributed_tracing_with_zipkin" href="#_distributed_tracing_with_zipkin"></a>1.2.1 Distributed tracing with Zipkin</h3></div></div></div><p>Altogether there are <span class="strong"><strong>7 spans</strong></span> . If you go to traces in Zipkin you will see this number in the second trace:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-traces.png" alt="Traces"></div></div><p>However if you pick a particular trace then you will see <span class="strong"><strong>4 spans</strong></span>:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-ui.png" alt="Traces Info propagation"></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to
|
|
Zipkin with Server Received and Server Sent / Client Received and Client Sent
|
|
annotations then they will presented as a single span.</p></td></tr></table></div><p>Why is there a difference between the 7 and 4 spans in this case?</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">2 spans come from <code class="literal">http:/start</code> span. It has the Server Received (SR) and Server Sent (SS) annotations.</li><li class="listitem">2 spans come from the RPC call from <code class="literal">service1</code> to <code class="literal">service2</code> to the <code class="literal">http:/foo</code> endpoint. The Client Sent (CS)
|
|
and Client Received (CR) events took place on <code class="literal">service1</code> side. Server Received (SR) and Server Sent (SS) events took place
|
|
on the <code class="literal">service2</code> side. Physically there are 2 spans but they form 1 logical span related to an RPC call.</li><li class="listitem">2 spans come from the RPC call from <code class="literal">service2</code> to <code class="literal">service3</code> to the <code class="literal">http:/bar</code> endpoint. The Client Sent (CS)
|
|
and Client Received (CR) events took place on <code class="literal">service2</code> side. Server Received (SR) and Server Sent (SS) events took place
|
|
on the <code class="literal">service3</code> side. Physically there are 2 spans but they form 1 logical span related to an RPC call.</li><li class="listitem">2 spans come from the RPC call from <code class="literal">service2</code> to <code class="literal">service4</code> to the <code class="literal">http:/baz</code> endpoint. The Client Sent (CS)
|
|
and Client Received (CR) events took place on <code class="literal">service2</code> side. Server Received (SR) and Server Sent (SS) events took place
|
|
on the <code class="literal">service4</code> side. Physically there are 2 spans but they form 1 logical span related to an RPC call.</li></ul></div><p>So if we count the physical spans we have <span class="strong"><strong>1</strong></span> from <code class="literal">http:/start</code>, <span class="strong"><strong>2</strong></span> from <code class="literal">service1</code> calling <code class="literal">service2</code>, <span class="strong"><strong>2</strong></span> form <code class="literal">service2</code>
|
|
calling <code class="literal">service3</code> and <span class="strong"><strong>2</strong></span> from <code class="literal">service2</code> calling <code class="literal">service4</code>. Altogether <span class="strong"><strong>7</strong></span> spans.</p><p>Logically we see the information of <span class="strong"><strong>Total Spans: 4</strong></span> because we have <span class="strong"><strong>1</strong></span> span related to the incoming request
|
|
to <code class="literal">service1</code> and <span class="strong"><strong>3</strong></span> spans related to RPC calls.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_visualizing_errors" href="#_visualizing_errors"></a>1.2.2 Visualizing errors</h3></div></div></div><p>Zipkin allows you to visualize errors in your trace. When an exception was thrown and wasn’t caught then we’re
|
|
setting proper tags on the span which Zipkin can properly colorize. You could see in the list of traces one
|
|
trace that was in red color. That’s because there was an exception thrown.</p><p>If you click that trace then you’ll see a similar picture</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-error-traces.png" alt="Error Traces"></div></div><p>Then if you click on one of the spans you’ll see the following</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-error-trace-screenshot.png" alt="Error Traces Info propagation"></div></div><p>As you can see you can easily see the reason for an error and the whole stacktrace related to it.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_distributed_tracing_with_brave" href="#_distributed_tracing_with_brave"></a>1.2.3 Distributed tracing with Brave</h3></div></div></div><p>Starting with version <code class="literal">2.0.0</code>, Spring Cloud Sleuth uses
|
|
<a class="link" href="https://github.com/openzipkin/brave" target="_top">Brave</a> as the tracing library. That means
|
|
that Sleuth no longer takes care of storing the context but it delegates
|
|
that work to Brave.</p><p>Due to the fact that Sleuth had different naming / tagging
|
|
conventions than Brave, we’ve decided to follow the Brave’s
|
|
conventions from now on. However, if you want to use the legacy
|
|
Sleuth approaches, it’s enough to set the <code class="literal">spring.sleuth.http.legacy.enabled</code> property
|
|
to <code class="literal">true</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_live_examples" href="#_live_examples"></a>1.2.4 Live examples</h3></div></div></div><div class="figure"><a name="d0e333" href="#d0e333"></a><p class="title"><b>Figure 1.1. Click Pivotal Web Services icon to see it live!</b></p><div class="figure-contents"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/pws.png" alt="Zipkin deployed on Pivotal Web Services"></div></div></div><br class="figure-break"><p><a class="link" href="http://docssleuth-zipkin-server.cfapps.io/" target="_top">Click here to see it live!</a></p><p>The dependency graph in Zipkin would look like this:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/dependencies.png" alt="Dependencies"></div></div><div class="figure"><a name="d0e354" href="#d0e354"></a><p class="title"><b>Figure 1.2. Click Pivotal Web Services icon to see it live!</b></p><div class="figure-contents"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/pws.png" alt="Zipkin deployed on Pivotal Web Services"></div></div></div><br class="figure-break"><p><a class="link" href="http://docssleuth-zipkin-server.cfapps.io/dependency" target="_top">Click here to see it live!</a></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_log_correlation" href="#_log_correlation"></a>1.2.5 Log correlation</h3></div></div></div><p>When grepping the logs of those four applications by trace id equal to e.g. <code class="literal">2485ec27856c56f4</code> one would get the following:</p><pre class="screen">service1.log:2016-02-26 11:15:47.561 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Hello from service1. Calling service2
|
|
service2.log:2016-02-26 11:15:47.710 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Hello from service2. Calling service3 and then service4
|
|
service3.log:2016-02-26 11:15:47.895 INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application : Hello from service3
|
|
service2.log:2016-02-26 11:15:47.924 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service3 [Hello from service3]
|
|
service4.log:2016-02-26 11:15:48.134 INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application : Hello from service4
|
|
service2.log:2016-02-26 11:15:48.156 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service4 [Hello from service4]
|
|
service1.log:2016-02-26 11:15:48.182 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]</pre><p>If you’re using a log aggregating tool like <a class="link" href="https://www.elastic.co/products/kibana" target="_top">Kibana</a>,
|
|
<a class="link" href="http://www.splunk.com/" target="_top">Splunk</a> etc. you can order the events that took place. An example of
|
|
Kibana would look like this:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/kibana.png" alt="Log correlation with Kibana"></div></div><p>If you want to use <a class="link" href="https://www.elastic.co/guide/en/logstash/current/index.html" target="_top">Logstash</a> here is the Grok pattern for Logstash:</p><pre class="screen">filter {
|
|
# pattern matching logback pattern
|
|
grok {
|
|
match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
|
|
}
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern:</p></td></tr></table></div><pre class="screen">filter {
|
|
# pattern matching logback pattern
|
|
grok {
|
|
match => { "message" => "(?m)OUT\s+%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
|
|
}
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_json_logback_with_logstash" href="#_json_logback_with_logstash"></a>JSON Logback with Logstash</h4></div></div></div><p>Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability
|
|
we’re passing the dependencies in the <code class="literal">groupId:artifactId:version</code> notation.</p><p><span class="strong"><strong>Dependencies setup</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Ensure that Logback is on the classpath (<code class="literal">ch.qos.logback:logback-core</code>)</li><li class="listitem">Add Logstash Logback encode - example for version <code class="literal">4.6</code> : <code class="literal">net.logstash.logback:logstash-logback-encoder:4.6</code></li></ul></div><p><span class="strong"><strong>Logback setup</strong></span></p><p>Below you can find an example of a Logback configuration (file named <a class="link" href="https://github.com/spring-cloud-samples/sleuth-documentation-apps/blob/master/service1/src/main/resources/logback-spring.xml" target="_top">logback-spring.xml</a>) that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">logs information from the application in a JSON format to a <code class="literal">build/${spring.application.name}.json</code> file</li><li class="listitem">has commented out two additional appenders - console and standard log file</li><li class="listitem">has the same logging pattern as the one presented in the previous section</li></ul></div><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">resource</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"org/springframework/boot/logging/logback/defaults.xml"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><springProperty</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">scope</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"context"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"springAppName"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">source</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"spring.application.name"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Example for logging into the build folder of your project --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><property</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"LOG_FILE"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">value</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"${BUILD_FOLDER:-build}/${springAppName}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>​
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- You can override this to have a custom pattern --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><property</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"CONSOLE_LOG_PATTERN"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">value</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Appender to log to console --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"console"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.ConsoleAppender"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><filter</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.classic.filter.ThresholdFilter"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Minimum logging level to be presented in the console logs--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><level></span>DEBUG<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></level></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></filter></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>${CONSOLE_LOG_PATTERN}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><charset></span>utf8<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></charset></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></appender></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Appender to log to file --></span>​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"flatfile"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><file></span>${LOG_FILE}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></file></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><rollingPolicy</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.TimeBasedRollingPolicy"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileNamePattern></span>${LOG_FILE}.%d{yyyy-MM-dd}.gz<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileNamePattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><maxHistory></span>7<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></maxHistory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></rollingPolicy></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>${CONSOLE_LOG_PATTERN}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><charset></span>utf8<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></charset></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></appender></span>
|
|
​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Appender to log to file in a JSON format --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"logstash"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><file></span>${LOG_FILE}.json<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></file></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><rollingPolicy</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.TimeBasedRollingPolicy"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileNamePattern></span>${LOG_FILE}.json.%d{yyyy-MM-dd}.gz<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileNamePattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><maxHistory></span>7<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></maxHistory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></rollingPolicy></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><encoder</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><providers></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><timestamp></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><timeZone></span>UTC<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></timeZone></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></timestamp></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>
|
|
{
|
|
"severity": "%level",
|
|
"service": "${springAppName:-}",
|
|
"trace": "%X{X-B3-TraceId:-}",
|
|
"span": "%X{X-B3-SpanId:-}",
|
|
"parent": "%X{X-B3-ParentSpanId:-}",
|
|
"exportable": "%X{X-Span-Export:-}",
|
|
"pid": "${PID:-}",
|
|
"thread": "%thread",
|
|
"class": "%logger{40}",
|
|
"rest": "%message"
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></providers></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></appender></span>
|
|
​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><root</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">level</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"INFO"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender-ref</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">ref</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"console"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- uncomment this to have also JSON logs --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!--<appender-ref ref="logstash"/>--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!--<appender-ref ref="flatfile"/>--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></root></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you’re using a custom <code class="literal">logback-spring.xml</code> then you have to pass the <code class="literal">spring.application.name</code> in
|
|
<code class="literal">bootstrap</code> instead of <code class="literal">application</code> property file. Otherwise your custom logback file won’t read the property properly.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_propagating_span_context" href="#_propagating_span_context"></a>1.2.6 Propagating Span Context</h3></div></div></div><p>The span context is the state that must get propagated to any child Spans across process boundaries.
|
|
Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context.
|
|
Baggage is an optional part.</p><p>Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace
|
|
and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP
|
|
header is prefixed with <code class="literal">baggage-</code> and for messaging it starts with <code class="literal">baggage_</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>There’s currently no limitation of the count or size of baggage items. However, keep in mind that
|
|
too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due
|
|
to exceeding transport-level message or header capacity.</p></td></tr></table></div><p>Example of setting baggage on a span:</p><pre class="programlisting">Span initialSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.nextSpan().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"span"</span>).start();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> (Tracer.SpanInScope ws = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.withSpanInScope(initialSpan)) {
|
|
ExtraFieldPropagation.set(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>);
|
|
ExtraFieldPropagation.set(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"UPPER_CASE"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"someValue"</span>);
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_baggage_vs_span_tags" href="#_baggage_vs_span_tags"></a>Baggage vs. Span Tags</h4></div></div></div><p>Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of
|
|
baggage and will not even receive that information.</p><p>Tags are attached to a specific span - they are presented for that particular span only. However you
|
|
can search by tag to find the trace, where there exists a span having the searched tag value.</p><p>If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Remember that the span needs to be in scope!</p></td></tr></table></div><pre class="programlisting">initialSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>,
|
|
ExtraFieldPropagation.get(initialSpan.context(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>));
|
|
initialSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"UPPER_CASE"</span>,
|
|
ExtraFieldPropagation.get(initialSpan.context(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"UPPER_CASE"</span>));</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_adding_to_the_project" href="#_adding_to_the_project"></a>1.3 Adding to the project</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>To ensure that your application name is properly displayed in Zipkin
|
|
set the <code class="literal">spring.application.name</code> property in <code class="literal">bootstrap.yml</code>.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_only_sleuth_log_correlation" href="#_only_sleuth_log_correlation"></a>1.3.1 Only Sleuth (log correlation)</h3></div></div></div><p>If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add
|
|
the <code class="literal">spring-cloud-starter-sleuth</code> module to your project.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO1-1" href="#CO1-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO1-2" href="#CO1-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-sleuth<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code></p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO2-1" href="#CO2-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies { <a name="CO2-2" href="#CO2-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-sleuth"</span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO2-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO2-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sleuth_with_zipkin_via_http" href="#_sleuth_with_zipkin_via_http"></a>1.3.2 Sleuth with Zipkin via HTTP</h3></div></div></div><p>If you want both Sleuth and Zipkin just add the <code class="literal">spring-cloud-starter-zipkin</code> dependency.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO3-1" href="#CO3-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO3-2" href="#CO3-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-zipkin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO3-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO3-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-zipkin</code></p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO4-1" href="#CO4-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies { <a name="CO4-2" href="#CO4-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-zipkin"</span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO4-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO4-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-zipkin</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sleuth_with_zipkin_via_rabbitmq_or_kafka" href="#_sleuth_with_zipkin_via_rabbitmq_or_kafka"></a>1.3.3 Sleuth with Zipkin via RabbitMQ or Kafka</h3></div></div></div><p>If you want to use RabbitMQ or Kafka instead of http, add the <code class="literal">spring-rabbit</code> or <code class="literal">spring-kafka</code>
|
|
dependencies. The default destination name is <code class="literal">zipkin</code>.</p><p><span class="emphasis"><em>Note: <code class="literal">spring-cloud-sleuth-stream</code> is deprecated and incompatible with these destinations</em></span></p><p>If you want Sleuth over RabbitMQ add the <code class="literal">spring-cloud-starter-zipkin</code> and <code class="literal">spring-rabbit</code>
|
|
dependencies.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO5-1" href="#CO5-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO5-2" href="#CO5-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-zipkin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO5-3" href="#CO5-3"></a><span><img src="images/callouts/3.png" alt="3" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.amqp<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-zipkin</code> - that way all dependent dependencies will be downloaded</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-3"><span><img src="images/callouts/3.png" alt="3" border="0"></span></a> </p></td><td valign="top" align="left"><p>To automatically configure rabbit, simply add the spring-rabbit dependency</p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO6-1" href="#CO6-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-zipkin"</span> <a name="CO6-2" href="#CO6-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.amqp:spring-rabbit"</span> <a name="CO6-3" href="#CO6-3"></a><span><img src="images/callouts/3.png" alt="3" border="0"></span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-zipkin</code> - that way all dependent dependencies will be downloaded</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-3"><span><img src="images/callouts/3.png" alt="3" border="0"></span></a> </p></td><td valign="top" align="left"><p>To automatically configure rabbit, simply add the spring-rabbit dependency</p></td></tr></table></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_additional_resources" href="#_additional_resources"></a>2. Additional resources</h1></div></div></div><p><span class="strong"><strong>Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin</strong></span></p><p><a class="link" href="https://www.youtube.com/watch?v=eQV71Mw1u1c" target="_top">click here to see the video</a></p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_features" href="#_features"></a>3. Features</h1></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">Adds trace and span ids to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator. Example logs:</p><pre class="screen">2016-02-02 15:30:57.902 INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
|
|
2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
|
|
2016-02-02 15:31:01.936 INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...</pre><p class="simpara">notice the <code class="literal">[appname,traceId,spanId,exportable]</code> entries from the MDC:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><span class="strong"><strong>spanId</strong></span> - the id of a specific operation that took place</li><li class="listitem"><span class="strong"><strong>appname</strong></span> - the name of the application that logged the span</li><li class="listitem"><span class="strong"><strong>traceId</strong></span> - the id of the latency graph that contains the span</li><li class="listitem"><span class="strong"><strong>exportable</strong></span> - whether the log should be exported to Zipkin or not. When would you like the span not to be
|
|
exportable? In the case in which you want to wrap some operation in a Span and have it written to the logs
|
|
only.</li></ul></div></li><li class="listitem">Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations,
|
|
key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible.</li><li class="listitem"><p class="simpara">Sleuth records timing information to aid in latency analysis. Using sleuth, you can pinpoint causes of
|
|
latency in your applications. Sleuth is written to not log too much, and to not cause your production application to crash.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">propagates structural data about your call-graph in-band, and the rest out-of-band.</li><li class="listitem">includes opinionated instrumentation of layers such as HTTP</li><li class="listitem">includes sampling policy to manage volume</li><li class="listitem">can report to a Zipkin system for query and visualization</li></ul></div></li><li class="listitem">Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints,
|
|
rest template, scheduled actions, message channels, zuul filters, feign client).</li><li class="listitem">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
|
|
<code class="literal">SpanInjector</code> and <code class="literal">SpanExtractor</code> implementations.</li><li class="listitem">Sleuth gives you the possibility to propagate context (also known as baggage) between processes. That means that if you set on a Span
|
|
a baggage element then it will be sent downstream either via HTTP or messaging to other processes.</li><li class="listitem">Provides a way to create / continue spans and add tags and logs via annotations.</li><li class="listitem"><p class="simpara">If <code class="literal">spring-cloud-sleuth-zipkin</code> is on the classpath then the app will generate and collect Zipkin-compatible traces.
|
|
By default it sends them via HTTP to a Zipkin server on localhost (port 9411).
|
|
Configure the location of the service using <code class="literal">spring.zipkin.baseUrl</code>.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">If you depend on <code class="literal">spring-rabbit</code> or <code class="literal">spring-kafka</code> your app will send traces to a broker instead of http.</li><li class="listitem">Note: <code class="literal">spring-cloud-sleuth-stream</code> is deprecated and should no longer be used.</li></ul></div></li><li class="listitem">Spring Cloud Sleuth is <a class="link" href="http://opentracing.io/" target="_top">OpenTracing</a> compatible</li></ul></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If using Zipkin, configure the percentage of spans exported using <code class="literal">spring.sleuth.sampler.percentage</code>
|
|
(default 0.1, i.e. 10%). <span class="strong"><strong>Otherwise you might think that Sleuth is not working cause it’s omitting some spans.</strong></span></p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>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
|
|
<code class="literal">logging.pattern.level</code> set to <code class="literal">%5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}]</code>
|
|
(this is a Spring Boot feature for logback users).
|
|
<span class="strong"><strong>This means that if you’re not using SLF4J this pattern WILL NOT be automatically applied</strong></span>.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_introduction_to_brave" href="#_introduction_to_brave"></a>3.1 Introduction to Brave</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Starting with version <code class="literal">2.0.0</code> Spring Cloud Sleuth uses
|
|
<a class="link" href="https://github.com/openzipkin/brave" target="_top">Brave</a> as the tracing library.
|
|
For your convenience we’re embedding part of the Brave’s docs here.</p></td></tr></table></div><p>Brave is a library used to capture and report latency information about
|
|
distributed operations to Zipkin. Most users won’t use Brave directly,
|
|
rather libraries or frameworks than employ Brave on their behalf.</p><p>This module includes tracer creates and joins spans that model the
|
|
latency of potentially distributed work. It also includes libraries to
|
|
propagate the trace context over network boundaries, for example, via
|
|
http headers.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_tracing" href="#_tracing"></a>3.1.1 Tracing</h3></div></div></div><p>Most importantly, you need a <code class="literal">brave.Tracer</code>, configured to [report to Zipkin]
|
|
(<a class="link" href="https://github.com/openzipkin/zipkin-reporter-java" target="_top">https://github.com/openzipkin/zipkin-reporter-java</a>).</p><p>Here’s an example setup that sends trace data (spans) to Zipkin over
|
|
http (as opposed to Kafka).</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Tracer tracer;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Tracer will be autowired</span>
|
|
MyClass(Tracer tracer) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer = tracer;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> doSth() {
|
|
Span span = tracer.newTrace().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"encode"</span>).start();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
}
|
|
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If your span contains a name greater than 50 chars, then that name will
|
|
be truncated to 50 chars. Your names have to be explicit and concrete. Big names lead to
|
|
latency issues and sometimes even thrown exceptions.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_tracing_2" href="#_tracing_2"></a>3.1.2 Tracing</h3></div></div></div><p>The tracer creates and joins spans that model the latency of potentially
|
|
distributed work. It can employ sampling to reduce overhead in process
|
|
or to reduce the amount of data sent to Zipkin.</p><p>Spans returned by a tracer report data to Zipkin when finished, or do
|
|
nothing if unsampled. After starting a span, you can annotate events of
|
|
interest or add tags containing details or lookup keys.</p><p>Spans have a context which includes trace identifiers that place it at
|
|
the correct spot in the tree representing the distributed operation.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_local_tracing" href="#_local_tracing"></a>3.1.3 Local Tracing</h3></div></div></div><p>When tracing local code, just run it inside a span.</p><pre class="programlisting">Span span = tracer.newTrace().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"encode"</span>).start();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
doSomethingExpensive();
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
span.finish();
|
|
}</pre><p>In the above example, the span is the root of the trace. In many cases,
|
|
you will be a part of an existing trace. When this is the case, call
|
|
<code class="literal">newChild</code> instead of <code class="literal">newTrace</code></p><pre class="programlisting">Span span = tracer.newChild(root.context()).name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"encode"</span>).start();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
doSomethingExpensive();
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
span.finish();
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_customizing_spans" href="#_customizing_spans"></a>3.1.4 Customizing spans</h3></div></div></div><p>Once you have a span, you can add tags to it, which can be used as lookup
|
|
keys or details. For example, you might add a tag with your runtime
|
|
version.</p><pre class="programlisting">span.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"clnt/finagle.version"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"6.36.0"</span>);</pre><p>When exposing the ability to customize spans to third parties, prefer
|
|
<code class="literal">brave.SpanCustomizer</code> as opposed to <code class="literal">brave.Span</code>. The former is simpler to
|
|
understand and test, and doesn’t tempt users with span lifecycle hooks.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> MyTraceCallback {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> request(Request request, SpanCustomizer customizer);
|
|
}</pre><p>Since <code class="literal">brave.Span</code> implements <code class="literal">brave.SpanCustomizer</code>, it is just as easy for you
|
|
to pass to users.</p><p>Ex.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> (MyTraceCallback callback : userCallbacks) {
|
|
callback.request(request, span);
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_implicitly_looking_up_the_current_span" href="#_implicitly_looking_up_the_current_span"></a>3.1.5 Implicitly looking up the current span</h3></div></div></div><p>Sometimes you won’t know if a trace is in progress or not, and you don’t
|
|
want users to do null checks. <code class="literal">brave.CurrentSpanCustomizer</code> adds to any
|
|
span that’s in progress or drops data accordingly.</p><p>Ex.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// user code can then inject this without a chance of it being null.</span>
|
|
<em><span class="hl-annotation" style="color: gray">@Autowire</span></em> SpanCustomizer span;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> userCode() {
|
|
span.annotate(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tx.started"</span>);
|
|
...
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_rpc_tracing" href="#_rpc_tracing"></a>3.1.6 RPC tracing</h3></div></div></div><p>Check for <a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation" target="_top">instrumentation written here</a>
|
|
and <a class="link" href="http://zipkin.io/pages/existing_instrumentations.html" target="_top">Zipkin’s list</a>
|
|
before rolling your own RPC instrumentation!</p><p>RPC tracing is often done automatically by interceptors. Under the scenes,
|
|
they add tags and events that relate to their role in an RPC operation.</p><p>Here’s an example of a client span:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// before you send a request, add metadata that describes the operation</span>
|
|
span = tracer.newTrace().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"get"</span>).type(CLIENT);
|
|
span.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"clnt/finagle.version"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"6.36.0"</span>);
|
|
span.tag(TraceKeys.HTTP_PATH, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/api"</span>);
|
|
span.remoteEndpoint(Endpoint.builder()
|
|
.serviceName(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"backend"</span>)
|
|
.ipv4(<span class="hl-number">127</span> << <span class="hl-number">24</span> | <span class="hl-number">1</span>)
|
|
.port(<span class="hl-number">8080</span>).build());
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when the request is scheduled, start the span</span>
|
|
span.start();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// if you have callbacks for when data is on the wire, note those events</span>
|
|
span.annotate(Constants.WIRE_SEND);
|
|
span.annotate(Constants.WIRE_RECV);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when the response is complete, finish the span</span>
|
|
span.finish();</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_one_way_tracing" href="#_one_way_tracing"></a>One-Way tracing</h4></div></div></div><p>Sometimes you need to model an asynchronous operation, where there is a
|
|
request, but no response. In normal RPC tracing, you use <code class="literal">span.finish()</code>
|
|
which indicates the response was received. In one-way tracing, you use
|
|
<code class="literal">span.flush()</code> instead, as you don’t expect a response.</p><p>Here’s how a client might model a one-way operation</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// start a new span representing a client request</span>
|
|
oneWaySend = tracer.newSpan(parent).kind(Span.Kind.CLIENT);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Add the trace context to the request, so it can be propagated in-band</span>
|
|
tracing.propagation().injector(Request::addHeader)
|
|
.inject(oneWaySend.context(), request);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// fire off the request asynchronously, totally dropping any response</span>
|
|
request.execute();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// start the client side and flush instead of finish</span>
|
|
oneWaySend.start().flush();</pre><p>And here’s how a server might handle this..</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// pull the context out of the incoming request</span>
|
|
extractor = tracing.propagation().extractor(Request::getHeader);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// convert that context to a span which you can name and add tags to</span>
|
|
oneWayReceive = nextSpan(tracer, extractor.extract(request))
|
|
.name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"process-request"</span>)
|
|
.kind(SERVER)
|
|
... add tags etc.
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// start the server side and flush instead of finish</span>
|
|
oneWayReceive.start().flush();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you should not modify this span anymore as it is complete. However,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you can create children to represent follow-up work.</span>
|
|
next = tracer.newSpan(oneWayReceive.context()).name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"step2"</span>).start();</pre><p><span class="strong"><strong>Note</strong></span> The above propagation logic is a simplified version of our [http handlers](<a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server" target="_top">https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server</a>).</p><p>There’s a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java).</p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_sampling" href="#_sampling"></a>4. Sampling</h1></div></div></div><p>Sampling may be employed to reduce the data collected and reported out
|
|
of process. When a span isn’t sampled, it adds no overhead (noop).</p><p>Sampling is an up-front decision, meaning that the decision to report
|
|
data is made at the first operation in a trace, and that decision is
|
|
propagated downstream.</p><p>By default, there’s a global sampler that applies a single rate to all
|
|
traced operations. <code class="literal">Tracer.Builder.sampler</code> is how you indicate this,
|
|
and it defaults to trace every request.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_declarative_sampling" href="#_declarative_sampling"></a>4.1 Declarative sampling</h2></div></div></div><p>Some need to sample based on the type or annotations of a java method.</p><p>Most users will use a framework interceptor which automates this sort of
|
|
policy. Here’s how they might work internally.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// derives a sample rate from an annotation on a java method</span>
|
|
DeclarativeSampler<Traced> sampler = DeclarativeSampler.create(Traced::sampleRate);
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Around("@annotation(traced)")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Object traceThing(ProceedingJoinPoint pjp, Traced traced) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Throwable {
|
|
Span span = tracing.tracer().newTrace(sampler.sample(traced))...
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> pjp.proceed();
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
span.finish();
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_sampling" href="#_custom_sampling"></a>4.2 Custom sampling</h2></div></div></div><p>You may want to apply different policies depending on what the operation
|
|
is. For example, you might not want to trace requests to static resources
|
|
such as images, or you might want to trace all requests to a new api.</p><p>Most users will use a framework interceptor which automates this sort of
|
|
policy. Here’s how they might work internally.</p><pre class="programlisting">Span newTrace(Request input) {
|
|
SamplingFlags flags = SamplingFlags.NONE;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (input.url().startsWith(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/experimental"</span>)) {
|
|
flags = SamplingFlags.SAMPLED;
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (input.url().startsWith(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/static"</span>)) {
|
|
flags = SamplingFlags.NOT_SAMPLED;
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> tracer.newTrace(flags);
|
|
}</pre><p>Note: the above is the basis for the built-in <a class="link" href="https://github.com/openzipkin/sleuth/tree/master/instrumentation/http" target="_top">http sampler</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_sampling_in_spring_cloud_sleuth" href="#_sampling_in_spring_cloud_sleuth"></a>4.3 Sampling in Spring Cloud Sleuth</h2></div></div></div><p>Spring Cloud Sleuth by default sets all spans to non-exportable.
|
|
That means that you will see traces in logs, but not in any remote store.
|
|
For testing the default is often enough, and it probably is all you need
|
|
if you are only using the logs (e.g. with an ELK aggregator). If you are
|
|
exporting span data to Zipkin, there is also an <code class="literal">Sampler.ALWAYS_SAMPLE</code>
|
|
that exports everything and a <code class="literal">ProbabilityBasedSampler</code> that samples a
|
|
fixed fraction of spans.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">ProbabilityBasedSampler</code> is the default if you are using
|
|
<code class="literal">spring-cloud-sleuth-zipkin</code>. You can
|
|
configure the exports using <code class="literal">spring.sleuth.sampler.probability</code>. The passed
|
|
value needs to be a double from <code class="literal">0.0</code> to <code class="literal">1.0</code>.</p></td></tr></table></div><p>A sampler can be installed just by creating a bean definition, e.g:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Sampler defaultSampler() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Sampler.ALWAYS_SAMPLE;
|
|
}</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>You can set the HTTP header <code class="literal">X-B3-Flags</code> to <code class="literal">1</code> or when doing messaging you can
|
|
set <code class="literal">spanFlags</code> header to <code class="literal">1</code>. Then the current span will be forced to be exportable
|
|
regardless of the sampling decision.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_propagation" href="#_propagation"></a>5. Propagation</h1></div></div></div><p>Propagation is needed to ensure activity originating from the same root
|
|
are collected together in the same trace. The most common propagation
|
|
approach is to copy a trace context from a client sending an RPC request
|
|
to a server receiving it.</p><p>For example, when an downstream Http call is made, its trace context is
|
|
sent along with it, encoded as request headers:</p><pre class="screen"> Client Span Server Span
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ │ │ │
|
|
│ TraceContext │ Http Request Headers │ TraceContext │
|
|
│ ┌──────────────┐ │ ┌───────────────────┐ │ ┌──────────────┐ │
|
|
│ │ TraceId │ │ │ X─B3─TraceId │ │ │ TraceId │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ │ ParentSpanId │ │ Extract │ X─B3─ParentSpanId │ Inject │ │ ParentSpanId │ │
|
|
│ │ ├─┼─────────>│ ├────────┼>│ │ │
|
|
│ │ SpanId │ │ │ X─B3─SpanId │ │ │ SpanId │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ │ Sampled │ │ │ X─B3─Sampled │ │ │ Sampled │ │
|
|
│ └──────────────┘ │ └───────────────────┘ │ └──────────────┘ │
|
|
│ │ │ │
|
|
└──────────────────┘ └──────────────────┘</pre><p>The names above are from <a class="link" href="https://github.com/openzipkin/b3-propagation" target="_top">B3 Propagation</a>,
|
|
which is built-in to Brave and has implementations in many languages and
|
|
frameworks.</p><p>Most users will use a framework interceptor which automates propagation.
|
|
Here’s how they might work internally.</p><p>Here’s what client-side propagation might look like</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// configure a function that injects a trace context into a request</span>
|
|
injector = tracing.propagation().injector(Request.Builder::addHeader);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// before a request is sent, add the current span's context to it</span>
|
|
injector.inject(span.context(), request);</pre><p>Here’s what server-side propagation might look like</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// configure a function that extracts the trace context from a request</span>
|
|
extracted = tracing.propagation().extractor(Request::getHeader);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when a server receives a request, it joins or starts a new trace</span>
|
|
span = tracer.nextSpan(extracted, request);</pre><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_propagating_extra_fields" href="#_propagating_extra_fields"></a>5.1 Propagating extra fields</h2></div></div></div><p>Sometimes you need to propagate extra fields, such as a request ID or an alternate trace context.
|
|
For example, if you are in a Cloud Foundry environment, you might want to pass the request ID:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when you initialize the builder, define the extra field you want to propagate</span>
|
|
tracingBuilder.propagationFactory(
|
|
ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-vcap-request-id"</span>)
|
|
);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// later, you can tag that request ID or use it in log correlation</span>
|
|
requestId = ExtraFieldPropagation.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-vcap-request-id"</span>);</pre><p>You may also need to propagate a trace context you aren’t using. For example, you may be in an
|
|
Amazon Web Services environment, but not reporting data to X-Ray. To ensure X-Ray can co-exist
|
|
correctly, pass-through its tracing header like so.</p><pre class="programlisting">tracingBuilder.propagationFactory(
|
|
ExtraFieldPropagation.newFactory(B3Propagation.FACTORY, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-amzn-trace-id"</span>)
|
|
);</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_prefixed_fields" href="#_prefixed_fields"></a>5.1.1 Prefixed fields</h3></div></div></div><p>You can also prefix fields, if they follow a common pattern. For example, the following will
|
|
propagate the field "x-vcap-request-id" as-is, but send the fields "country-code" and "user-id"
|
|
on the wire as "x-baggage-country-code" and "x-baggage-user-id" respectively.</p><p>Setup your tracing instance with allowed fields:</p><pre class="programlisting">tracingBuilder.propagationFactory(
|
|
ExtraFieldPropagation.newFactoryBuilder(B3Propagation.FACTORY)
|
|
.addField(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-vcap-request-id"</span>)
|
|
.addPrefixedFields(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"baggage-"</span>, Arrays.asList(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country-code"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user-id"</span>))
|
|
.build()
|
|
);</pre><p>Later, you can call below to affect the country code of the current trace context</p><pre class="programlisting">ExtraFieldPropagation.set(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country-code"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FO"</span>);
|
|
String countryCode = ExtraFieldPropagation.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country-code"</span>);</pre><p>Or, if you have a reference to a trace context, use it explicitly</p><pre class="programlisting">ExtraFieldPropagation.set(span.context(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country-code"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FO"</span>);
|
|
String countryCode = ExtraFieldPropagation.get(span.context(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country-code"</span>);</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>In comparison to previous versions of Sleuth, with
|
|
Brave it’s required to pass the list of baggage keys.
|
|
There are two properties to achieve this. Via the <code class="literal">spring.sleuth.baggage-keys</code> you set keys
|
|
that will get prefixed with <code class="literal">baggage-</code> for http calls and <code class="literal">baggage_</code> for messaging. You can also pass
|
|
a list of prefixed keys that will be whitelisted without any prefix via
|
|
<code class="literal">spring.sleuth.propagation-keys</code> property.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_extracting_a_propagated_context" href="#_extracting_a_propagated_context"></a>5.1.2 Extracting a propagated context</h3></div></div></div><p>The <code class="literal">TraceContext.Extractor<C></code> reads trace identifiers and sampling status
|
|
from an incoming request or message. The carrier is usually a request object
|
|
or headers.</p><p>This utility is used in standard instrumentation like [HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java),
|
|
but can also be used for custom RPC or messaging code.</p><p><code class="literal">TraceContextOrSamplingFlags</code> is usually only used with <code class="literal">Tracer.nextSpan(extracted)</code>, unless you are
|
|
sharing span IDs between a client and a server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sharing_span_ids_between_client_and_server" href="#_sharing_span_ids_between_client_and_server"></a>5.1.3 Sharing span IDs between client and server</h3></div></div></div><p>A normal instrumentation pattern is creating a span representing the server
|
|
side of an RPC. <code class="literal">Extractor.extract</code> might return a complete trace context when
|
|
applied to an incoming client request. <code class="literal">Tracer.joinSpan</code> attempts to continue
|
|
the this trace, using the same span ID if supported, or creating a child span
|
|
if not. When span ID is shared, data reported includes a flag saying so.</p><p>Here’s an example of B3 propagation:</p><pre class="screen"> ┌───────────────────┐ ┌───────────────────┐
|
|
Incoming Headers │ TraceContext │ │ TraceContext │
|
|
┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │
|
|
│ X─B3-TraceId │─────────┼─┼> TraceId │ │──────┼─┼> TraceId │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ X─B3-ParentSpanId │─────────┼─┼> ParentSpanId │ │──────┼─┼> ParentSpanId │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ X─B3-SpanId │─────────┼─┼> SpanId │ │──────┼─┼> SpanId │ │
|
|
└───────────────────┘ │ │ │ │ │ │ │ │
|
|
│ │ │ │ │ │ Shared: true │ │
|
|
│ └───────────────┘ │ │ └───────────────┘ │
|
|
└───────────────────┘ └───────────────────┘</pre><p>Some propagation systems only forward the parent span ID, detected when
|
|
<code class="literal">Propagation.Factory.supportsJoin() == false</code>. In this case, a new span ID is
|
|
always provisioned and the incoming context determines the parent ID.</p><p>Here’s an example of AWS propagation:</p><pre class="screen"> ┌───────────────────┐ ┌───────────────────┐
|
|
x-amzn-trace-id │ TraceContext │ │ TraceContext │
|
|
┌───────────────────┐(extract)│ ┌───────────────┐ │(join)│ ┌───────────────┐ │
|
|
│ Root │─────────┼─┼> TraceId │ │──────┼─┼> TraceId │ │
|
|
│ │ │ │ │ │ │ │ │ │
|
|
│ Parent │─────────┼─┼> SpanId │ │──────┼─┼> ParentSpanId │ │
|
|
└───────────────────┘ │ └───────────────┘ │ │ │ │ │
|
|
└───────────────────┘ │ │ SpanId: New │ │
|
|
│ └───────────────┘ │
|
|
└───────────────────┘</pre><p>Note: Some span reporters do not support sharing span IDs. For example, if you
|
|
set <code class="literal">Tracing.Builder.spanReporter(amazonXrayOrGoogleStackdrive)</code>, disable join
|
|
via <code class="literal">Tracing.Builder.supportsJoin(false)</code>. This will force a new child span on
|
|
<code class="literal">Tracer.joinSpan()</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_implementing_propagation" href="#_implementing_propagation"></a>5.1.4 Implementing Propagation</h3></div></div></div><p><code class="literal">TraceContext.Extractor<C></code> is implemented by a <code class="literal">Propagation.Factory</code> plugin. Internally, this code
|
|
will create the union type <code class="literal">TraceContextOrSamplingFlags</code> with one of the following:
|
|
* <code class="literal">TraceContext</code> if trace and span IDs were present.
|
|
* <code class="literal">TraceIdContext</code> if a trace ID was present, but not span IDs.
|
|
* <code class="literal">SamplingFlags</code> if no identifiers were present</p><p>Some <code class="literal">Propagation</code> implementations carry extra data from point of extraction (ex reading incoming
|
|
headers) to injection (ex writing outgoing headers). For example, it might carry a request ID. When
|
|
implementations have extra data, here’s how they handle it.
|
|
* If a <code class="literal">TraceContext</code> was extracted, add the extra data as <code class="literal">TraceContext.extra()</code>
|
|
* Otherwise, add it as <code class="literal">TraceContextOrSamplingFlags.extra()</code>, which <code class="literal">Tracer.nextSpan</code> handles.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_current_tracing_component" href="#_current_tracing_component"></a>6. Current Tracing Component</h1></div></div></div><p>Brave supports a "current tracing component" concept which should only
|
|
be used when you have no other means to get a reference. This was made
|
|
for JDBC connections, as they often initialize prior to the tracing
|
|
component.</p><p>The most recent tracing component instantiated is available via
|
|
<code class="literal">Tracing.current()</code>. You there’s also a shortcut to get only the tracer
|
|
via <code class="literal">Tracing.currentTracer()</code>. If you use either of these methods, do
|
|
noot cache the result. Instead, look them up each time you need them.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_current_span" href="#_current_span"></a>7. Current Span</h1></div></div></div><p>Brave supports a "current span" concept which represents the in-flight
|
|
operation. <code class="literal">Tracer.currentSpan()</code> can be used to add custom tags to a
|
|
span and <code class="literal">Tracer.nextSpan()</code> can be used to create a child of whatever
|
|
is in-flight.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_setting_a_span_in_scope_manually" href="#_setting_a_span_in_scope_manually"></a>7.1 Setting a span in scope manually</h2></div></div></div><p>When writing new instrumentation, it is important to place a span you
|
|
created in scope as the current span. Not only does this allow users to
|
|
access it with <code class="literal">Tracer.currentSpan()</code>, but it also allows customizations
|
|
like SLF4J MDC to see the current trace IDs.</p><p><code class="literal">Tracer.withSpanInScope(Span)</code> facilitates this and is most conveniently
|
|
employed via the try-with-resources idiom. Whenever external code might
|
|
be invoked (such as proceeding an interceptor or otherwise), place the
|
|
span in scope like this.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> (SpanInScope ws = tracer.withSpanInScope(span)) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> inboundRequest.invoke();
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// note the scope is independent of the span</span>
|
|
span.finish();
|
|
}</pre><p>In edge cases, you may need to clear the current span temporarily. For
|
|
example, launching a task that should not be associated with the current
|
|
request. To do this, simply pass null to <code class="literal">withSpanInScope</code>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> (SpanInScope cleared = tracer.withSpanInScope(null)) {
|
|
startBackgroundThread();
|
|
}</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_instrumentation" href="#_instrumentation"></a>8. Instrumentation</h1></div></div></div><p>Spring Cloud Sleuth instruments all your Spring application
|
|
automatically, so you shouldn’t have to do anything to activate
|
|
it. The instrumentation is added using a variety of technologies
|
|
according to the stack that is available, e.g. for a servlet web
|
|
application we use a <code class="literal">Filter</code>, and for Spring Integration we use
|
|
<code class="literal">ChannelInterceptors</code>.</p><p>You can customize the keys used in span tags. To limit the volume of
|
|
span data, by default an HTTP request will be tagged only with a
|
|
handful of metadata like the status code, host and URL. You can add
|
|
request headers by configuring <code class="literal">spring.sleuth.keys.http.headers</code> (a
|
|
list of header names).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Remember that tags are only collected and exported if there is a
|
|
<code class="literal">Sampler</code> that allows it (by default there is not, so there is no
|
|
danger of accidentally collecting too much data without configuring
|
|
something).</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_span_lifecycle" href="#_span_lifecycle"></a>9. Span lifecycle</h1></div></div></div><p>You can do the following operations on the Span by means of <span class="strong"><strong>brave.Tracer</strong></span>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="#creating-and-finishing-spans" title="9.1 Creating and finishing spans">start</a> - when you start a span its name is assigned and start timestamp is recorded.</li><li class="listitem"><a class="link" href="#creating-and-finishing-spans" title="9.1 Creating and finishing spans">close</a> - the span gets finished (the end time of the span is recorded) and if
|
|
the span is <span class="strong"><strong>sampled</strong></span> then it will be eligible for collection to e.g. Zipkin.</li><li class="listitem"><a class="link" href="#continuing-spans" title="9.2 Continuing spans">continue</a> - a new instance of span will be created whereas it will be a copy of the
|
|
one that it continues.</li><li class="listitem"><a class="link" href="#continuing-spans" title="9.2 Continuing spans">detach</a> - the span doesn’t get stopped or closed. It only gets removed from the current thread.</li><li class="listitem"><a class="link" href="#creating-spans-with-explicit-parent" title="9.3 Creating spans with an explicit parent">create with explicit parent</a> - you can create a new span and set an explicit parent to it</li></ul></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Spring Cloud Sleuth creates the instance of <code class="literal">Tracer</code> for you. In order to use it,
|
|
all you need is to just autowire it.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creating-and-finishing-spans" href="#creating-and-finishing-spans"></a>9.1 Creating and finishing spans</h2></div></div></div><p>You can manually create spans by using the <span class="strong"><strong>Tracer</strong></span>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Start a span. If there was a span present in this thread it will become</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the `newSpan`'s parent.</span>
|
|
Span newSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.nextSpan().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> (Tracer.SpanInScope ws = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.withSpanInScope(newSpan.start())) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can tag a span</span>
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxValue"</span>, taxValue);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can log an event on a span</span>
|
|
newSpan.annotate(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxCalculated"</span>);
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Once done remember to finish the span. This will allow collecting</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the span to send it to Zipkin</span>
|
|
newSpan.finish();
|
|
}</pre><p>In this example we could see how to create a new instance of span. Assuming that there already
|
|
was a span present in this thread then it would become the parent of that span.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Always clean after you create a span! Don’t forget to finish a span if you want to send it to Zipkin.</p></td></tr></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If your span contains a name greater than 50 chars, then that name will
|
|
be truncated to 50 chars. Your names have to be explicit and concrete. Big names lead to
|
|
latency issues and sometimes even thrown exceptions.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="continuing-spans" href="#continuing-spans"></a>9.2 Continuing spans</h2></div></div></div><p>Sometimes you don’t want to create a new span but you want to continue one. Example of such a
|
|
situation might be (of course it all depends on the use-case):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>AOP</strong></span> - If there was already a span created before an aspect was reached then you might not want to create a new span.</li><li class="listitem"><span class="strong"><strong>Hystrix</strong></span> - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact
|
|
only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being.</li></ul></div><p>To continue a span you can use <span class="strong"><strong>brave.Tracer</strong></span>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// let's assume that we're in a thread Y and we've received</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the `initialSpan` from thread X</span>
|
|
Span continuedSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.joinSpan(newSpan.context());
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can tag a span</span>
|
|
continuedSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxValue"</span>, taxValue);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can log an event on a span</span>
|
|
continuedSpan.annotate(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxCalculated"</span>);
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Once done remember to flush the span. That means that</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// it will get reported but the span itself is not yet finished</span>
|
|
continuedSpan.flush();
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creating-spans-with-explicit-parent" href="#creating-spans-with-explicit-parent"></a>9.3 Creating spans with an explicit parent</h2></div></div></div><p>There is a possibility that you want to start a new span and provide an explicit parent of that span.
|
|
Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread.
|
|
In Brave, whenever you call <code class="literal">nextSpan()</code>, it’s creating one in reference
|
|
to the span being currently in scope. It’s enough to just put
|
|
the span in scope and then call <code class="literal">nextSpan()</code>, as presented in the example below:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// let's assume that we're in a thread Y and we've received</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the `initialSpan` from thread X. `initialSpan` will be the parent</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// of the `newSpan`</span>
|
|
Span newSpan = null;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> (Tracer.SpanInScope ws = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.withSpanInScope(initialSpan)) {
|
|
newSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.nextSpan().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateCommission"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can tag a span</span>
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"commissionValue"</span>, commissionValue);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can log an event on a span</span>
|
|
newSpan.annotate(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"commissionCalculated"</span>);
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Once done remember to finish the span. This will allow collecting</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the span to send it to Zipkin. The tags and events set on the</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// newSpan will not be present on the parent</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (newSpan != null) {
|
|
newSpan.finish();
|
|
}
|
|
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>After having created such a span remember to finish it, otherwise it will not get
|
|
reported to e.g. Zipkin</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_naming_spans" href="#_naming_spans"></a>10. Naming spans</h1></div></div></div><p>Picking a span name is not a trivial task. Span name should depict an operation name. The name should
|
|
be low cardinality (e.g. not include identifiers).</p><p>Since there is a lot of instrumentation going on some of the span names will be
|
|
artificial like:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">controller-method-name</code> when received by a Controller with a method name <code class="literal">conrollerMethodName</code></li><li class="listitem"><code class="literal">async</code> for asynchronous operations done via wrapped <code class="literal">Callable</code> and <code class="literal">Runnable</code>.</li><li class="listitem"><code class="literal">@Scheduled</code> annotated methods will return the simple name of the class.</li></ul></div><p>Fortunately, for the asynchronous processing you can provide explicit naming.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="__spanname_annotation" href="#__spanname_annotation"></a>10.1 @SpanName annotation</h2></div></div></div><p>You can name the span explicitly via the <code class="literal">@SpanName</code> annotation.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpanName("calculateTax")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TaxCountingRunnable <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> Runnable {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// perform logic</span>
|
|
}
|
|
}</pre><p>In this case, when processed in the following manner:</p><pre class="programlisting">Runnable runnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceRunnable(tracer, spanNamer, errorParser,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TaxCountingRunnable());
|
|
Future<?> future = executorService.submit(runnable);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ... some additional logic ...</span>
|
|
future.get();</pre><p>The span will be named <code class="literal">calculateTax</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_tostring_method" href="#_tostring_method"></a>10.2 toString() method</h2></div></div></div><p>It’s pretty rare to create separate classes for <code class="literal">Runnable</code> or <code class="literal">Callable</code>. Typically one creates an anonymous
|
|
instance of those classes. You can’t annotate such classes thus to override that, if there is no <code class="literal">@SpanName</code> annotation present,
|
|
we’re checking if the class has a custom implementation of the <code class="literal">toString()</code> method.</p><p>So executing such code:</p><pre class="programlisting">Runnable runnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceRunnable(tracer, spanNamer, errorParser, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Runnable() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// perform logic</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String toString() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>;
|
|
}
|
|
});
|
|
Future<?> future = executorService.submit(runnable);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ... some additional logic ...</span>
|
|
future.get();</pre><p>will lead in creating a span named <code class="literal">calculateTax</code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_managing_spans_with_annotations" href="#_managing_spans_with_annotations"></a>11. Managing spans with annotations</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rationale" href="#_rationale"></a>11.1 Rationale</h2></div></div></div><p>The main arguments for this features are</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">api-agnostic means to collaborate with a span</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">use of annotations allows users to add to a span with no library dependency on a span api.
|
|
This allows Sleuth to change its core api less impact to user code.</li></ul></div></li><li class="listitem"><p class="simpara">reduced surface area for basic span operations.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">without this feature one has to use the span api, which has lifecycle commands that
|
|
could be used incorrectly. By only exposing scope, tag and log functionality, users can
|
|
collaborate without accidentally breaking span lifecycle.</li></ul></div></li><li class="listitem"><p class="simpara">collaboration with runtime generated code</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">with libraries such as Spring Data / Feign the implementations of interfaces are generated
|
|
at runtime thus span wrapping of objects was tedious. Now you can provide annotations
|
|
over interfaces and arguments of those interfaces</li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_creating_new_spans" href="#_creating_new_spans"></a>11.2 Creating new spans</h2></div></div></div><p>If you really don’t want to take care of creating local spans manually you can profit from the
|
|
<code class="literal">@NewSpan</code> annotation. Also we give you the <code class="literal">@SpanTag</code> annotation to add tags in an automated
|
|
fashion.</p><p>Let’s look at some examples of usage.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod();</pre><p>Annotating the method without any parameter will lead to a creation of a new span whose name
|
|
will be equal to annotated method name.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan("customNameOnTestMethod4")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod4();</pre><p>If you provide the value in the annotation (either directly or via the <code class="literal">name</code> parameter) then
|
|
the created span will have the name as the provided value.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// method declaration</span>
|
|
<em><span class="hl-annotation" style="color: gray">@NewSpan(name = "customNameOnTestMethod5")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod5(<em><span class="hl-annotation" style="color: gray">@SpanTag("testTag")</span></em> String param);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and method execution</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.testBean.testMethod5(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"test"</span>);</pre><p>You can combine both the name and a tag. Let’s focus on the latter. In this case whatever the value of
|
|
the annotated method’s parameter runtime value will be - that will be the value of the tag. In our sample
|
|
the tag key will be <code class="literal">testTag</code> and the tag value will be <code class="literal">test</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan(name = "customNameOnTestMethod3")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod3() {
|
|
}</pre><p>You can place the <code class="literal">@NewSpan</code> annotation on both the class and an interface. If you override the
|
|
interface’s method and provide a different value of the <code class="literal">@NewSpan</code> annotation then the most
|
|
concrete one wins (in this case <code class="literal">customNameOnTestMethod3</code> will be set).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_continuing_spans" href="#_continuing_spans"></a>11.3 Continuing spans</h2></div></div></div><p>If you want to just add tags and annotations to an existing span it’s enough
|
|
to use the <code class="literal">@ContinueSpan</code> annotation as presented below. Note that in contrast
|
|
with the <code class="literal">@NewSpan</code> annotation you can also add logs via the <code class="literal">log</code> parameter:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// method declaration</span>
|
|
<em><span class="hl-annotation" style="color: gray">@ContinueSpan(log = "testMethod11")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod11(<em><span class="hl-annotation" style="color: gray">@SpanTag("testTag11")</span></em> String param);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// method execution</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.testBean.testMethod11(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"test"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.testBean.testMethod13();</pre><p>That way the span will get continued and:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">logs with name <code class="literal">testMethod11.before</code> and <code class="literal">testMethod11.after</code> will be created</li><li class="listitem">if an exception will be thrown a log <code class="literal">testMethod11.afterFailure</code> will also be created</li><li class="listitem">tag with key <code class="literal">testTag11</code> and value <code class="literal">test</code> will be created</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_more_advanced_tag_setting" href="#_more_advanced_tag_setting"></a>11.4 More advanced tag setting</h2></div></div></div><p>There are 3 different ways to add tags to a span. All of them are controlled by the <code class="literal">SpanTag</code> annotation.
|
|
Precedence is:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">try with the bean of <code class="literal">TagValueResolver</code> type and provided name</li><li class="listitem">if one hasn’t provided the bean name, try to evaluate an expression. We’re searching for a <code class="literal">TagValueExpressionResolver</code> bean.
|
|
The default implementation uses SPEL expression resolution.</li><li class="listitem">if one hasn’t provided any expression to evaluate just return a <code class="literal">toString()</code> value of the parameter</li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_custom_extractor" href="#_custom_extractor"></a>11.4.1 Custom extractor</h3></div></div></div><p>The value of the tag for following method will be computed by an implementation of <code class="literal">TagValueResolver</code> interface.
|
|
Its class name has to be passed as the value of the <code class="literal">resolver</code> attribute.</p><p>Having such an annotated method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> getAnnotationForTagValueResolver(<em><span class="hl-annotation" style="color: gray">@SpanTag(key = "test", resolver = TagValueResolver.class)</span></em> String test) {
|
|
}</pre><p>and such a <code class="literal">TagValueResolver</code> bean implementation</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean(name = "myCustomTagValueResolver")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> TagValueResolver tagValueResolver() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> parameter -> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Value from myCustomTagValueResolver"</span>;
|
|
}</pre><p>Will lead to setting of a tag value equal to <code class="literal">Value from myCustomTagValueResolver</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_resolving_expressions_for_value" href="#_resolving_expressions_for_value"></a>11.4.2 Resolving expressions for value</h3></div></div></div><p>Having such an annotated method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> getAnnotationForTagValueExpression(<em><span class="hl-annotation" style="color: gray">@SpanTag(key = "test", expression = "length() + ' characters'")</span></em> String test) {
|
|
}</pre><p>and no custom implementation of a <code class="literal">TagValueExpressionResolver</code> will lead to evaluation of the SPEL expression and a tag with value <code class="literal">4 characters</code> will be set on the span.
|
|
If you want to use some other expression resolution mechanism you can create your own implementation
|
|
of the bean.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_using_tostring_method" href="#_using_tostring_method"></a>11.4.3 Using toString method</h3></div></div></div><p>Having such an annotated method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> getAnnotationForArgumentToString(<em><span class="hl-annotation" style="color: gray">@SpanTag("test")</span></em> Long param) {
|
|
}</pre><p>if executed with a value of <code class="literal">15</code> will lead to setting of a tag with a String value of <code class="literal">"15"</code>.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_customizations" href="#_customizations"></a>12. Customizations</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_integration" href="#_spring_integration"></a>12.1 Spring Integration</h2></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http" href="#_http"></a>12.2 HTTP</h2></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_tracefilter" href="#_tracefilter"></a>12.3 TraceFilter</h2></div></div></div><p>You can also modify the behaviour of the <code class="literal">TraceFilter</code> - the component that is responsible
|
|
for processing the input HTTP request and adding tags basing on the HTTP response. You can customize
|
|
the tags, or modify the response headers by registering your own instance of the <code class="literal">TraceFilter</code> bean.</p><p>In the following example we will register the <code class="literal">TraceFilter</code> bean and we will add the
|
|
<code class="literal">ZIPKIN-TRACE-ID</code> response header containing the current Span’s trace id. Also we will
|
|
add to the Span a tag with key <code class="literal">custom</code> and a value <code class="literal">tag</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Component</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Order(TraceFilter.ORDER + 1)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyFilter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> GenericFilterBean {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Tracer tracer;
|
|
|
|
MyFilter(Tracer tracer) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer = tracer;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> doFilter(ServletRequest request, ServletResponse response,
|
|
FilterChain chain) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException, ServletException {
|
|
Span currentSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.currentSpan();
|
|
then(currentSpan).isNotNull();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// for readability we're returning trace id in a hex form</span>
|
|
((HttpServletResponse) response)
|
|
.addHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"ZIPKIN-TRACE-ID"</span>,
|
|
currentSpan.context().traceIdString());
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// we can also add some custom tags</span>
|
|
currentSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"custom"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tag"</span>);
|
|
chain.doFilter(request, response);
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_service_name" href="#_custom_service_name"></a>12.4 Custom service name</h2></div></div></div><p>By default Sleuth assumes that when you send a span to Zipkin, you want the span’s service name
|
|
to be equal to <code class="literal">spring.application.name</code> value. That’s not always the case though. There
|
|
are situations in which you want to explicitly provide a different service name for all spans coming
|
|
from your application. To achieve that it’s enough to just pass the following property
|
|
to your application to override that value (example for <code class="literal">foo</code> service name):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.service.name</span>: foo</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customization_of_reported_spans" href="#_customization_of_reported_spans"></a>12.5 Customization of reported spans</h2></div></div></div><p>Before reporting spans to e.g. Zipkin you can be interested in modifying that span in some way.
|
|
You can achieve that by using the <code class="literal">SpanAdjuster</code> interface.</p><p>In Sleuth we’re generating spans with a fixed name. Some users want to modify the name depending on values
|
|
of tags. Implementation of the <code class="literal">SpanAdjuster</code> interface can be used to alter that name. Example:</p><p>Example. If you register two beans of <code class="literal">SpanAdjuster</code> type:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em> SpanAdjuster adjusterOne() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> span -> span.toBuilder().name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>).build();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em> SpanAdjuster adjusterTwo() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> span -> span.toBuilder().name(span.name() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">" bar"</span>).build();
|
|
}</pre><p>This will lead in changing the name of the reported span to <code class="literal">foo bar</code>, just before it gets reported (e.g. to Zipkin).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_host_locator" href="#_host_locator"></a>12.6 Host locator</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>This section is about defining <span class="strong"><strong>host</strong></span> from service discovery. It’s <span class="strong"><strong>NOT</strong></span>
|
|
about finding Zipkin in service discovery.</p></td></tr></table></div><p>In order to define the host that is corresponding to a particular span we need to resolve the host name
|
|
and port. The default approach is to take it from server properties. If those for some reason are not set
|
|
then we’re trying to retrieve the host name from the network interfaces.</p><p>If you have the discovery client enabled and prefer to retrieve the host address from the registered
|
|
instance in a service registry then you have to set the property (it’s applicable for both HTTP and
|
|
Stream based span reporting).</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.locator.discovery.enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_sending_spans_to_zipkin" href="#_sending_spans_to_zipkin"></a>13. Sending spans to Zipkin</h1></div></div></div><p>By default if you add <code class="literal">spring-cloud-starter-zipkin</code> as a dependency to your project,
|
|
when the span is closed, it will be sent to Zipkin over HTTP. The communication
|
|
is asynchronous. You can configure the URL by setting the <code class="literal">spring.zipkin.baseUrl</code>
|
|
property as follows:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.baseUrl</span>: http://<span class="hl-number">192.168</span>.<span class="hl-number">99.100</span>:<span class="hl-number">9411</span>/</pre><p>If you want to find Zipkin via service discovery it’s enough to pass the
|
|
Zipkin’s service id inside the URL (example for <code class="literal">zipkinserver</code> service id)</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.baseUrl</span>: http://zipkinserver/</pre><p>If you have web, rabbit or kafka together on the classpath, you might need
|
|
to pick the means by which you would like to send spans to zipkin. To do that
|
|
just set either <code class="literal">web</code>, <code class="literal">rabbit</code> or <code class="literal">kafka</code> to the <code class="literal">spring.zipkin.sender.type</code> property.
|
|
Example for <code class="literal">web</code>:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.sender.type</span>: web</pre></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_zipkin_stream_span_consumer" href="#_zipkin_stream_span_consumer"></a>14. Zipkin Stream Span Consumer</h1></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>The suggested approach is to use the Zipkin’s
|
|
native support for message based span sending. Starting from
|
|
Edgware Zipkin Stream server is deprecated and in Finchley
|
|
it got removed.</p></td></tr></table></div><p>Please refer to the <a class="link" href="http://cloud.spring.io/spring-cloud-static/Dalston.SR4/multi/multi__span_data_as_messages.html#_zipkin_consumer" target="_top">Dalston Documentaion</a>
|
|
on how to create a Stream Zipkin server.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_integrations" href="#_integrations"></a>15. Integrations</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_opentracing" href="#_opentracing"></a>15.1 OpenTracing</h2></div></div></div><p>Spring Cloud Sleuth is <a class="link" href="http://opentracing.io/" target="_top">OpenTracing</a> compatible. If you have
|
|
OpenTracing on the classpath we will automatically register the OpenTracing
|
|
<code class="literal">Tracer</code> bean. If you wish to disable this just set <code class="literal">spring.sleuth.opentracing.enabled</code> to <code class="literal">false</code></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_runnable_and_callable" href="#_runnable_and_callable"></a>15.2 Runnable and Callable</h2></div></div></div><p>If you’re wrapping your logic in <code class="literal">Runnable</code> or <code class="literal">Callable</code> it’s enough to wrap those classes in their Sleuth representative.</p><p>Example for <code class="literal">Runnable</code>:</p><pre class="programlisting">Runnable runnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Runnable() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// do some work</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String toString() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spanNameFromToStringMethod"</span>;
|
|
}
|
|
};
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Manual `TraceRunnable` creation with explicit "calculateTax" Span name</span>
|
|
Runnable traceRunnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceRunnable(tracer, spanNamer, errorParser,
|
|
runnable, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Wrapping `Runnable` with `Tracing`. That way the current span will be available</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// in the thread of `Runnable`</span>
|
|
Runnable traceRunnableFromTracer = tracing.currentTraceContext().wrap(runnable);</pre><p>Example for <code class="literal">Callable</code>:</p><pre class="programlisting">Callable<String> callable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Callable<String>() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String call() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> someLogic();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String toString() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spanNameFromToStringMethod"</span>;
|
|
}
|
|
};
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Manual `TraceCallable` creation with explicit "calculateTax" Span name</span>
|
|
Callable<String> traceCallable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceCallable<>(tracer, spanNamer, errorParser,
|
|
callable, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Wrapping `Callable` with `Tracing`. That way the current span will be available</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// in the thread of `Callable`</span>
|
|
Callable<String> traceCallableFromTracer = tracing.currentTraceContext().wrap(callable);</pre><p>That way you will ensure that a new Span is created and closed for each execution.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_hystrix" href="#_hystrix"></a>15.3 Hystrix</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_custom_concurrency_strategy" href="#_custom_concurrency_strategy"></a>15.3.1 Custom Concurrency Strategy</h3></div></div></div><p>We’re registering a custom <a class="link" href="https://github.com/Netflix/Hystrix/wiki/Plugins#concurrencystrategy" target="_top"><code class="literal">HystrixConcurrencyStrategy</code></a>
|
|
that wraps all <code class="literal">Callable</code> instances into their Sleuth representative -
|
|
the <code class="literal">TraceCallable</code>. The strategy either starts or continues a span depending on the fact whether tracing was already going
|
|
on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the <code class="literal">spring.sleuth.hystrix.strategy.enabled</code> to <code class="literal">false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_manual_command_setting" href="#_manual_command_setting"></a>15.3.2 Manual Command setting</h3></div></div></div><p>Assuming that you have the following <code class="literal">HystrixCommand</code>:</p><pre class="programlisting">HystrixCommand<String> hystrixCommand = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HystrixCommand<String>(setter) {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> String run() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> someLogic();
|
|
}
|
|
};</pre><p>In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the <code class="literal">HystrixCommand</code> which is the
|
|
<code class="literal">TraceCommand</code>:</p><pre class="programlisting">TraceCommand<String> traceCommand = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceCommand<String>(tracer, traceKeys, setter) {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doRun() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> someLogic();
|
|
}
|
|
};</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rxjava" href="#_rxjava"></a>15.4 RxJava</h2></div></div></div><p>We’re registering a custom <a class="link" href="https://github.com/ReactiveX/RxJava/wiki/Plugins#rxjavaschedulershook" target="_top"><code class="literal">RxJavaSchedulersHook</code></a>
|
|
that wraps all <code class="literal">Action0</code> instances into their Sleuth representative -
|
|
the <code class="literal">TraceAction</code>. The hook either starts or continues a span depending on the fact whether tracing was already going
|
|
on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the <code class="literal">spring.sleuth.rxjava.schedulers.hook.enabled</code> to <code class="literal">false</code>.</p><p>You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list
|
|
of regular expressions in the <code class="literal">spring.sleuth.rxjava.schedulers.ignoredthreads</code> property.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http_integration" href="#_http_integration"></a>15.5 HTTP integration</h2></div></div></div><p>Features from this section can be disabled by providing the <code class="literal">spring.sleuth.web.enabled</code> property with value equal to <code class="literal">false</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_http_filter" href="#_http_filter"></a>15.5.1 HTTP Filter</h3></div></div></div><p>Via the <code class="literal">TraceFilter</code> all sampled incoming requests result in creation of a Span. That Span’s name is <code class="literal">http:</code> + the path to which
|
|
the request was sent. E.g. if the request was sent to <code class="literal">/foo/bar</code> then the name will be <code class="literal">http:/foo/bar</code>. You can configure which URIs you would
|
|
like to skip via the <code class="literal">spring.sleuth.web.skipPattern</code> property. If you have <code class="literal">ManagementServerProperties</code> on classpath then
|
|
its value of <code class="literal">contextPath</code> gets appended to the provided skip pattern. If you want to reuse the
|
|
Sleuth’s default skip patterns and just append your own, pass those patterns via
|
|
the <code class="literal">spring.sleuth.web.additionalSkipPattern</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_handlerinterceptor" href="#_handlerinterceptor"></a>15.5.2 HandlerInterceptor</h3></div></div></div><p>Since we want the span names to be precise we’re using a <code class="literal">TraceHandlerInterceptor</code> that either wraps an
|
|
existing <code class="literal">HandlerInterceptor</code> or is added directly to the list of existing <code class="literal">HandlerInterceptors</code>. The
|
|
<code class="literal">TraceHandlerInterceptor</code> adds a special request attribute to the given <code class="literal">HttpServletRequest</code>. If the
|
|
the <code class="literal">TraceFilter</code> doesn’t see this attribute set it will create a "fallback" span which is an additional
|
|
span created on the server side so that the trace is presented properly in the UI. Seeing that most likely
|
|
signifies that there is a missing instrumentation. In that case please file an issue in Spring Cloud Sleuth.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_async_servlet_support" href="#_async_servlet_support"></a>15.5.3 Async Servlet support</h3></div></div></div><p>If your controller returns a <code class="literal">Callable</code> or a <code class="literal">WebAsyncTask</code> Spring Cloud Sleuth will continue the existing span instead of creating a new one.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_webflux_support" href="#_webflux_support"></a>15.5.4 WebFlux support</h3></div></div></div><p>Via the <code class="literal">TraceWebFilter</code> all sampled incoming requests result in creation of a Span. That Span’s name is <code class="literal">http:</code> + the path to which
|
|
the request was sent. E.g. if the request was sent to <code class="literal">/foo/bar</code> then the name will be <code class="literal">http:/foo/bar</code>. You can configure which URIs you would
|
|
like to skip via the <code class="literal">spring.sleuth.web.skipPattern</code> property. If you have <code class="literal">ManagementServerProperties</code> on classpath then
|
|
its value of <code class="literal">contextPath</code> gets appended to the provided skip pattern. If you want to reuse the
|
|
Sleuth’s default skip patterns and just append your own, pass those patterns via
|
|
the <code class="literal">spring.sleuth.web.additionalSkipPattern</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http_client_integration" href="#_http_client_integration"></a>15.6 HTTP client integration</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_synchronous_rest_template" href="#_synchronous_rest_template"></a>15.6.1 Synchronous Rest Template</h3></div></div></div><p>We’re injecting a <code class="literal">RestTemplate</code> interceptor that ensures that all the tracing information is passed to the requests. Each time a
|
|
call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous <code class="literal">RestTemplate</code> features
|
|
just set <code class="literal">spring.sleuth.web.client.enabled</code> to <code class="literal">false</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>You have to register <code class="literal">RestTemplate</code> as a bean so that the interceptors will get injected.
|
|
If you create a <code class="literal">RestTemplate</code> instance with a <code class="literal">new</code> keyword then the instrumentation WILL NOT work.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_asynchronous_rest_template" href="#_asynchronous_rest_template"></a>15.6.2 Asynchronous Rest Template</h3></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Starting with Sleuth <code class="literal">2.0.0</code> we no longer register
|
|
a bean of <code class="literal">AsyncRestTemplate</code> type. It’s up to you to create such
|
|
a bean. Then we will instrument it.</p></td></tr></table></div><p>To block the <code class="literal">AsyncRestTemplate</code> features set <code class="literal">spring.sleuth.web.async.client.enabled</code> to <code class="literal">false</code>.
|
|
To disable creation of the default <code class="literal">TraceAsyncClientHttpRequestFactoryWrapper</code> set <code class="literal">spring.sleuth.web.async.client.factory.enabled</code>
|
|
to <code class="literal">false</code>. If you don’t want to create <code class="literal">AsyncRestClient</code> at all set <code class="literal">spring.sleuth.web.async.client.template.enabled</code> to <code class="literal">false</code>.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_multiple_asynchronous_rest_templates" href="#_multiple_asynchronous_rest_templates"></a>Multiple Asynchronous Rest Templates</h4></div></div></div><p>Sometimes you need to use multiple implementations of Asynchronous Rest Template. In the following snippet you
|
|
can see an example of how to set up such a custom <code class="literal">AsyncRestTemplate</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Config {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean(name = "customAsyncRestTemplate")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> AsyncRestTemplate traceAsyncRestTemplate() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AsyncRestTemplate(asyncClientFactory(), clientHttpRequestFactory());
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ClientHttpRequestFactory clientHttpRequestFactory() {
|
|
ClientHttpRequestFactory clientHttpRequestFactory = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomClientHttpRequestFactory();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//CUSTOMIZE HERE</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> clientHttpRequestFactory;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> AsyncClientHttpRequestFactory asyncClientFactory() {
|
|
AsyncClientHttpRequestFactory factory = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomAsyncClientHttpRequestFactory();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//CUSTOMIZE HERE</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> factory;
|
|
}
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_webclient" href="#_webclient"></a>15.6.3 WebClient</h3></div></div></div><p>We inject a <code class="literal">ExchangeFilterFunction</code> implementation that creates a span and via on success and on
|
|
error callbacks takes care of closing client side spans.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>You have to register <code class="literal">WebClient</code> as a bean so that the tracing instrumention gets applied.
|
|
If you create a <code class="literal">WebClient</code> instance with a <code class="literal">new</code> keyword then the instrumentation WILL NOT work.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_traverson" href="#_traverson"></a>15.6.4 Traverson</h3></div></div></div><p>If you’re using the <a class="link" href="http://docs.spring.io/spring-hateoas/docs/current/reference/html/#client.traverson" target="_top">Traverson</a> library
|
|
it’s enough for you to inject a <code class="literal">RestTemplate</code> as a bean into your Traverson object. Since <code class="literal">RestTemplate</code>
|
|
is already intercepted, you will get full support of tracing in your client. Below you can find a pseudo code
|
|
of how to do that:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Autowired</span></em> RestTemplate restTemplate;
|
|
|
|
Traverson traverson = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Traverson(URI.create(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://some/address"</span>),
|
|
MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// use Traverson</span></pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_feign" href="#_feign"></a>15.7 Feign</h2></div></div></div><p>By default Spring Cloud Sleuth provides integration with feign via the <code class="literal">TraceFeignClientAutoConfiguration</code>. You can disable it entirely
|
|
by setting <code class="literal">spring.sleuth.feign.enabled</code> to false. If you do so then no Feign related instrumentation will take place.</p><p>Part of Feign instrumentation is done via a <code class="literal">FeignBeanPostProcessor</code>. You can disable it by providing the <code class="literal">spring.sleuth.feign.processor.enabled</code> equal to <code class="literal">false</code>.
|
|
If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation
|
|
however will be still there.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_asynchronous_communication" href="#_asynchronous_communication"></a>15.8 Asynchronous communication</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__async_annotated_methods" href="#__async_annotated_methods"></a>15.8.1 @Async annotated methods</h3></div></div></div><p>In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads.
|
|
You can disable this behaviour by setting the value of <code class="literal">spring.sleuth.async.enabled</code> to <code class="literal">false</code>.</p><p>If you annotate your method with <code class="literal">@Async</code> then we’ll automatically create a new Span with the following characteristics:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">if the method is annotated with <code class="literal">@SpanName</code> then the value of the annotation will be the Span’s name</li><li class="listitem">if the method is <span class="strong"><strong>not</strong></span> annotated with <code class="literal">@SpanName</code> the Span name will be the annotated method name</li><li class="listitem">the Span will be tagged with that method’s class name and the method name too</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__scheduled_annotated_methods" href="#__scheduled_annotated_methods"></a>15.8.2 @Scheduled annotated methods</h3></div></div></div><p>In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour
|
|
by setting the value of <code class="literal">spring.sleuth.scheduled.enabled</code> to <code class="literal">false</code>.</p><p>If you annotate your method with <code class="literal">@Scheduled</code> then we’ll automatically create a new Span with the following characteristics:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">the Span name will be the annotated method name</li><li class="listitem">the Span will be tagged with that method’s class name and the method name too</li></ul></div><p>If you want to skip Span creation for some <code class="literal">@Scheduled</code> annotated classes you can set the
|
|
<code class="literal">spring.sleuth.scheduled.skipPattern</code> with a regular expression that will match the fully qualified name of the
|
|
<code class="literal">@Scheduled</code> annotated class.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you are using <code class="literal">spring-cloud-sleuth-stream</code> and <code class="literal">spring-cloud-netflix-hystrix-stream</code> together, Span will be created for
|
|
each Hystrix metrics and sent to Zipkin. This may be annoying. You can prevent this by setting
|
|
<code class="literal">spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_executor_executorservice_and_scheduledexecutorservice" href="#_executor_executorservice_and_scheduledexecutorservice"></a>15.8.3 Executor, ExecutorService and ScheduledExecutorService</h3></div></div></div><p>We’re providing <code class="literal">LazyTraceExecutor</code>, <code class="literal">TraceableExecutorService</code> and <code class="literal">TraceableScheduledExecutorService</code>. Those implementations
|
|
are creating Spans each time a new task is submitted, invoked or scheduled.</p><p>Here you can see an example of how to pass tracing information with <code class="literal">TraceableExecutorService</code> when working with <code class="literal">CompletableFuture</code>:</p><pre class="programlisting">CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// perform some logic</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">1</span>_<span class="hl-number">000</span>_<span class="hl-number">000L</span>;
|
|
}, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceableExecutorService(beanFactory, executorService,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// 'calculateTax' explicitly names the span - this param is optional</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>));</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Sleuth doesn’t work with <code class="literal">parallelStream()</code> out of the box. If you want
|
|
to have the tracing information propagated through the stream you have to use the
|
|
approach with <code class="literal">supplyAsync(...)</code> as presented above.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_customization_of_executors" href="#_customization_of_executors"></a>Customization of Executors</h4></div></div></div><p>Sometimes you need to set up a custom instance of the <code class="literal">AsyncExecutor</code>. In the following snippet you
|
|
can see an example of how to set up such a custom <code class="literal">Executor</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAsync</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomExecutorConfig <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> AsyncConfigurerSupport {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> BeanFactory beanFactory;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Executor getAsyncExecutor() {
|
|
ThreadPoolTaskExecutor executor = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ThreadPoolTaskExecutor();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// CUSTOMIZE HERE</span>
|
|
executor.setCorePoolSize(<span class="hl-number">7</span>);
|
|
executor.setMaxPoolSize(<span class="hl-number">42</span>);
|
|
executor.setQueueCapacity(<span class="hl-number">11</span>);
|
|
executor.setThreadNamePrefix(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"MyExecutor-"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// DON'T FORGET TO INITIALIZE</span>
|
|
executor.initialize();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> LazyTraceExecutor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.beanFactory, executor);
|
|
}
|
|
}</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_messaging" href="#_messaging"></a>15.9 Messaging</h2></div></div></div><p>Spring Cloud Sleuth integrates with <a class="link" href="http://projects.spring.io/spring-integration/" target="_top">Spring Integration</a>. It creates spans for publish and
|
|
subscribe events. To disable Spring Integration instrumentation, set <code class="literal">spring.sleuth.integration.enabled</code> to false.</p><p>You can provide the <code class="literal">spring.sleuth.integration.patterns</code> pattern to explicitly
|
|
provide the names of channels that you want to include for tracing. By default all channels
|
|
are included.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>When using the <code class="literal">Executor</code> to build a Spring Integration <code class="literal">IntegrationFlow</code> remember to use the <span class="strong"><strong>untraced</strong></span> version of the <code class="literal">Executor</code>.
|
|
Decorating Spring Integration Executor Channel with <code class="literal">TraceableExecutorService</code> will cause the spans to be improperly closed.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_zuul" href="#_zuul"></a>15.10 Zuul</h2></div></div></div><p>We’re instrumenting the Zuul Ribbon integration by enriching the Ribbon requests with tracing information.
|
|
To disable Zuul support set the <code class="literal">spring.sleuth.zuul.enabled</code> property to <code class="literal">false</code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_running_examples" href="#_running_examples"></a>16. Running examples</h1></div></div></div><p>You can find the running examples deployed in the <a class="link" href="https://run.pivotal.io/" target="_top">Pivotal Web Services</a>. Check them out in the following links:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://docssleuth-zipkin-server.cfapps.io/" target="_top">Zipkin for apps presented in the samples to the top</a></li><li class="listitem"><a class="link" href="http://docsbrewing-zipkin-server.cfapps.io/" target="_top">Zipkin for Brewery on PWS</a>, its <a class="link" href="https://github.com/spring-cloud-samples/brewery" target="_top">Github Code</a></li></ul></div></div></div></body></html> |