24 lines
18 KiB
HTML
24 lines
18 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>155. Spring Cloud Sleuth</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="multi_spring-cloud.html" title="Spring Cloud"><link rel="up" href="multi_spring-cloud-gcp-reference.html" title="Part XVIII. Spring Cloud GCP"><link rel="prev" href="multi__spring_cloud_stream_2.html" title="154. Spring Cloud Stream"><link rel="next" href="multi__stackdriver_logging.html" title="156. Stackdriver Logging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">155. Spring Cloud Sleuth</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__spring_cloud_stream_2.html">Prev</a> </td><th width="60%" align="center">Part XVIII. Spring Cloud GCP</th><td width="20%" align="right"> <a accesskey="n" href="multi__stackdriver_logging.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_sleuth_2" href="#_spring_cloud_sleuth_2"></a>155. Spring Cloud Sleuth</h2></div></div></div><p><a class="link" href="https://cloud.spring.io/spring-cloud-sleuth/" target="_top">Spring Cloud Sleuth</a> is an instrumentation framework for Spring Boot applications.
|
|
It captures trace information and can forward traces to services like Zipkin for storage and analysis.</p><p>Google Cloud Platform provides its own managed distributed tracing service called <a class="link" href="https://cloud.google.com/trace/" target="_top">Stackdriver Trace</a>.
|
|
Instead of running and maintaining your own Zipkin instance and storage, you can use Stackdriver Trace to store traces, view trace details, generate latency distributions graphs, and generate performance regression reports.</p><p>This Spring Cloud GCP starter can forward Spring Cloud Sleuth traces to Stackdriver Trace without an intermediary Zipkin server.</p><p>Maven coordinates, using Spring Cloud GCP BOM:</p><pre class="programlisting"><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-gcp-starter-trace<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>Gradle coordinates:</p><pre class="screen">dependencies {
|
|
compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-starter-trace'
|
|
}</pre><p>You must enable Stackdriver Trace API from the Google Cloud Console in order to capture traces.
|
|
Navigate to the <a class="link" href="https://console.cloud.google.com/apis/api/cloudtrace.googleapis.com/overview" target="_top">Stackdriver Trace API</a> for your project and make sure it’s enabled.</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>If you are already using a Zipkin server capturing trace information from multiple platform/frameworks, you can also use a <a class="link" href="https://cloud.google.com/trace/docs/zipkin" target="_top">Stackdriver Zipkin proxy</a> to forward those traces to Stackdriver Trace without modifying existing applications.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_tracing_2" href="#_tracing_2"></a>155.1 Tracing</h2></div></div></div><p>Spring Cloud Sleuth uses the <a class="link" href="https://github.com/openzipkin/brave" target="_top">Brave tracer</a> to generate traces.
|
|
This integration enables Brave to use the <a class="link" href="https://github.com/openzipkin/zipkin-gcp/tree/master/propagation-stackdriver" target="_top"><code class="literal">StackdriverTracePropagation</code></a> propagation.</p><p>A propagation is responsible for extracting trace context from an entity (e.g., an HTTP servlet request) and injecting trace context into an entity.
|
|
A canonical example of the propagation usage is a web server that receives an HTTP request, which triggers other HTTP requests from the server before returning an HTTP response to the original caller.
|
|
In the case of <code class="literal">StackdriverTracePropagation</code>, first it looks for trace context in the <code class="literal">x-cloud-trace-context</code> key (e.g., an HTTP request header).
|
|
The value of the <code class="literal">x-cloud-trace-context</code> key can be formatted in three different ways:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">x-cloud-trace-context: TRACE_ID</code></li><li class="listitem"><code class="literal">x-cloud-trace-context: TRACE_ID/SPAN_ID</code></li><li class="listitem"><code class="literal">x-cloud-trace-context: TRACE_ID/SPAN_ID;o=TRACE_TRUE</code></li></ul></div><p><code class="literal">TRACE_ID</code> is a 32-character hexadecimal value that encodes a 128-bit number.</p><p><code class="literal">SPAN_ID</code> is an unsigned long.
|
|
Since Stackdriver Trace doesn’t support span joins, a new span ID is always generated, regardless of the one specified in <code class="literal">x-cloud-trace-context</code>.</p><p><code class="literal">TRACE_TRUE</code> can either be <code class="literal">0</code> if the entity should be untraced, or <code class="literal">1</code> if it should be traced.
|
|
This field forces the decision of whether or not to trace the request; if omitted then the decision is deferred to the sampler.</p><p>If a <code class="literal">x-cloud-trace-context</code> key isn’t found, <code class="literal">StackdriverTracePropagation</code> falls back to tracing with the <a class="link" href="https://github.com/openzipkin/b3-propagation" target="_top">X-B3 headers</a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_boot_starter_for_stackdriver_trace" href="#_spring_boot_starter_for_stackdriver_trace"></a>155.2 Spring Boot Starter for Stackdriver Trace</h2></div></div></div><p>Spring Boot Starter for Stackdriver Trace uses Spring Cloud Sleuth and auto-configures a <a class="link" href="https://github.com/openzipkin/zipkin-gcp/blob/master/sender-stackdriver/src/main/java/zipkin2/reporter/stackdriver/StackdriverSender.java" target="_top">StackdriverSender</a> that sends the Sleuth’s trace information to Stackdriver Trace.</p><p>All configurations are optional:</p><div class="informaltable"><table class="informaltable" style="border-collapse: collapse;border-top: 1px solid ; border-bottom: 1px solid ; "><colgroup><col class="col_1"><col class="col_2"><col class="col_3"><col class="col_4"></colgroup><tbody><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Name</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Description</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Required</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>Default value</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.enabled</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Auto-configure Spring Cloud Sleuth to send traces to Stackdriver Trace.</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">true</code></p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.project-id</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Overrides the project ID from the <a class="link" href="multi_spring-cloud-gcp-core.html" title="149. Spring Cloud GCP Core">Spring Cloud GCP Module</a></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.credentials.location</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Overrides the credentials location from the <a class="link" href="multi_spring-cloud-gcp-core.html" title="149. Spring Cloud GCP Core">Spring Cloud GCP Module</a></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.credentials.encoded-key</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Overrides the credentials encoded key from the <a class="link" href="multi_spring-cloud-gcp-core.html" title="149. Spring Cloud GCP Core">Spring Cloud GCP Module</a></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.credentials.scopes</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Overrides the credentials scopes from the <a class="link" href="multi_spring-cloud-gcp-core.html" title="149. Spring Cloud GCP Core">Spring Cloud GCP Module</a></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.num-executor-threads</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Number of threads used by the Trace executor</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"><p>4</p></td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.authority</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>HTTP/2 authority the channel claims to be connecting to.</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.compression</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Name of the compression to use in Trace calls</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.deadline-ms</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Call deadline in milliseconds</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.max-inbound-size</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Maximum size for inbound messages</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.max-outbound-size</code></p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>Maximum size for outbound messages</p></td><td style="border-right: 1px solid ; border-bottom: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="border-bottom: 1px solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 1px solid ; " align="left" valign="top"><p><code class="literal">spring.cloud.gcp.trace.wait-for-ready</code></p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p><a class="link" href="https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md" target="_top">Waits for the channel to be ready</a> in case of a transient failure</p></td><td style="border-right: 1px solid ; " align="left" valign="top"><p>No</p></td><td style="" align="left" valign="top"><p><code class="literal">false</code></p></td></tr></tbody></table></div><p>You can use core Spring Cloud Sleuth properties to control Sleuth’s sampling rate, etc.
|
|
Read <a class="link" href="https://cloud.spring.io/spring-cloud-sleuth/" target="_top">Sleuth documentation</a> for more information on Sleuth configurations.</p><p>For example, when you are testing to see the traces are going through, you can set the sampling rate to 100%.</p><pre class="screen">spring.sleuth.sampler.probability=1 # Send 100% of the request traces to Stackdriver.
|
|
spring.sleuth.web.skipPattern=(^cleanup.*|.+favicon.*) # Ignore some URL paths.</pre><p>Spring Cloud GCP Trace does override some Sleuth configurations:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Always uses 128-bit Trace IDs.
|
|
This is required by Stackdriver Trace.</li><li class="listitem">Does not use Span joins.
|
|
Span joins will share the span ID between the client and server Spans.
|
|
Stackdriver requires that every Span ID within a Trace to be unique, so Span joins are not supported.</li><li class="listitem">Uses <code class="literal">StackdriverHttpClientParser</code> and <code class="literal">StackdriverHttpServerParser</code> by default to populate Stackdriver related fields.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_integration_with_logging" href="#_integration_with_logging"></a>155.3 Integration with Logging</h2></div></div></div><p>Integration with Stackdriver Logging is available through the <a class="link" href="logging.adoc" target="_top">Stackdriver Logging Support</a>.
|
|
If the Trace integration is used together with the Logging one, the request logs will be associated to the corresponding traces.
|
|
The trace logs can be viewed by going to the <a class="link" href="https://console.cloud.google.com/traces/traces" target="_top">Google Cloud Console Trace List</a>, selecting a trace and pressing the <code class="literal">Logs → View</code> link in the <code class="literal">Details</code> section.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_sample_6" href="#_sample_6"></a>155.4 Sample</h2></div></div></div><p>A <a class="link" href="https://github.com/spring-cloud/spring-cloud-gcp/tree/master/spring-cloud-gcp-samples/spring-cloud-gcp-trace-sample" target="_top">sample application</a> and a <a class="link" href="https://codelabs.developers.google.com/codelabs/cloud-spring-cloud-gcp-trace/index.html" target="_top">codelab</a> are available.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__spring_cloud_stream_2.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="multi_spring-cloud-gcp-reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="multi__stackdriver_logging.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">154. Spring Cloud Stream </td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud.html">Home</a></td><td width="40%" align="right" valign="top"> 156. Stackdriver Logging</td></tr></table></div></body></html> |