This is an automated email from the ASF dual-hosted git repository.
ningjiang pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/incubator-servicecomb-website.git
The following commit(s) were added to refs/heads/master by this push:
new 20299b7 SCB-172 add how to upgrade to zipkin2 post
20299b7 is described below
commit 20299b784491d9cbfdcdedae448580c15e6ef67a
Author: Yang, Bo <yangb...@huawei.com>
AuthorDate: Wed Jan 10 15:56:44 2018 +0800
SCB-172 add how to upgrade to zipkin2 post
This howto describes the changes between zipkin and zipkin2 and how Java
Chassis upgraded to zipkin2.
---
_data/authors.yml | 5 +
_posts/2018-01-10-howto-upgrade-to-zipkin-v2.md | 238 ++++++++++++++++++++++++
2 files changed, 243 insertions(+)
diff --git a/_data/authors.yml b/_data/authors.yml
index 463f3da..badee2f 100644
--- a/_data/authors.yml
+++ b/_data/authors.yml
@@ -35,3 +35,8 @@ Wang Lei:
uri: "https://wldandan.github.io";
email: "wanglei...@huawei.com"
bio: "Happy Coding, Happy Life"
+Yang Bo:
+ name: "Yang Bo"
+ email: "yangb...@huawei.com"
+ bio: "Simplicity is beauty"
+
diff --git a/_posts/2018-01-10-howto-upgrade-to-zipkin-v2.md
b/_posts/2018-01-10-howto-upgrade-to-zipkin-v2.md
new file mode 100644
index 0000000..5e68e3a
--- /dev/null
+++ b/_posts/2018-01-10-howto-upgrade-to-zipkin-v2.md
@@ -0,0 +1,238 @@
+---
+title: "Howto Upgrade to Zipkin2"
+lang: en
+ref: howto-upgrade-topzipkin2
+permalink: /docs/howto-upgrade-topzipkin2/
+excerpt: "Changes between v1 and v2 of zipkin and how Java Chassis upgraded to
zipkin2"
+last_modified_at: 2018-01-11T10:26:28+08:00
+author: Yang Bo
+tags: [zipkin]
+redirect_from:
+ - /theme-setup/
+---
+
+## Background
+
+Java Chassis uses zipkin as the default tracing implementation.
+
+Zipkin introduced [v2 http api](http://zipkin.io/zipkin-api/#/) in version
1.31 which simplifies data types. There are also various other improvements and
new features added to the zipkin libraries, so it seems a good time for us to
follow the upstream and upgrade to zipkin2.
+
+### Version matrix
+
+| module | current | target | supports v2 since |
+|---|---|---|---|
+| zipkin | 1.24.0 | 2.4.2 | 2.0.0 |
+| brave | 4.13.1 | 4.13.1 | 4.7.1 |
+| reporter | 0.10.0 | 2.2.2 | 2.0.0 |
+
+## What's changed
+
+Zipkin did a very good job on maintaining backward compatibility. All the
changes that breaks compatiblity are packaged into a new group(`io.zipkin.java`
-> `io.zipkin.zipkin2`, `io.zipkin.reporter` -> `io.zipkin.reporter2`). And
v1/v2 libraries can coexist.
+
+The zipkin2 library can use both v1 and v2 api to communicate with server.
+
+The `zipkin2.Span` class changed a bit from the old `zipkin.Span` class. The
public fields are refactored to methods. And the `BinaryAnnotation` class is
removed along with `zipkin.Span.binaryAnnotaions` field. It's functionality is
replaced by `zipkin2.Span.tags()` method which return a `Map<String,String>`.
+
+## Upgrade to zipkin2 for Java Chassis
+
+### Modify the maven dependencies to use the target version of related
libraries.
+Change the group `io.zipkin.java` and `io.zipkin.reporter` to
`io.zipkin.zipkin2` and `io.zipkin.reporter2` respectively.
+
+``` diff
+java-chassis-dependencies/pom.xml
+@@ -50,8 +50,8 @@
+ <cxf.version>3.1.6</cxf.version>
+ <logback.version>1.1.7</logback.version>
+ <brave.version>4.13.1</brave.version>
+- <zipkin.version>1.24.0</zipkin.version>
+- <zipkin-reporter.version>0.10.0</zipkin-reporter.version>
++ <zipkin.version>2.4.2</zipkin.version>
++ <zipkin-reporter.version>2.2.2</zipkin-reporter.version>
+ </properties>
+
+ <dependencyManagement>
+@@ -646,7 +646,7 @@
+
+ <!-- zipkin dependencies -->
+ <dependency>
+- <groupId>io.zipkin.java</groupId>
++ <groupId>io.zipkin.zipkin2</groupId>
+ <artifactId>zipkin</artifactId>
+ <version>${zipkin.version}</version>
+ </dependency>
+@@ -661,7 +661,7 @@
+ <version>${brave.version}</version>
+ </dependency>
+ <dependency>
+- <groupId>io.zipkin.reporter</groupId>
++ <groupId>io.zipkin.reporter2</groupId>
+ <artifactId>zipkin-sender-okhttp3</artifactId>
+ <version>${zipkin-reporter.version}</version>
+ </dependency>
+
+handlers/handler-tracing-zipkin/pom.xml
+@@ -50,7 +50,7 @@
+ <artifactId>brave</artifactId>
+ </dependency>
+ <dependency>
+- <groupId>io.zipkin.reporter</groupId>
++ <groupId>io.zipkin.reporter2</groupId>
+ <artifactId>zipkin-sender-okhttp3</artifactId>
+ </dependency>
+ <dependency>
+
+```
+
+
+### Make brave to use zipkin2 instead of zipkin
+
+Change the zipkin.xxx import to zipkin2.xxx on imports, and most importantly,
use `spanReporter()` instead of `reporter()` for generating reporter for brave,
change the api path to /api/v2/xxx when creating sender.
+
+``` diff
+handlers/handler-tracing-zipkin/src/main/java/io/servicecomb/tracing/zipkin/TracingConfiguration.java
+@@ -31,11 +31,11 @@
+ import brave.http.HttpTracing;
+ import brave.propagation.CurrentTraceContext;
+ import io.servicecomb.config.DynamicProperties;
+-import zipkin.Span;
+-import zipkin.reporter.AsyncReporter;
+-import zipkin.reporter.Reporter;
+-import zipkin.reporter.Sender;
+-import zipkin.reporter.okhttp3.OkHttpSender;
++import zipkin2.Span;
++import zipkin2.reporter.AsyncReporter;
++import zipkin2.reporter.Reporter;
++import zipkin2.reporter.Sender;
++import zipkin2.reporter.okhttp3.OkHttpSender;
+
+ @Configuration
+ class TracingConfiguration {
+@@ -56,14 +56,15 @@ Sender sender(DynamicProperties dynamicProperties) {
+ return AsyncReporter.builder(sender).build();
+ }
+
++
+ @Bean
+ Tracing tracing(Reporter<Span> reporter, DynamicProperties
dynamicProperties,
+ CurrentTraceContext currentTraceContext) {
+ return Tracing.newBuilder()
+
.localServiceName(dynamicProperties.getStringProperty(CONFIG_QUALIFIED_MICROSERVICE_NAME_KEY,
+ DEFAULT_MICROSERVICE_NAME))
+ .currentTraceContext(currentTraceContext) // puts trace IDs into logs
+- .reporter(reporter)
++ .spanReporter(reporter)
+ .build();
+ }
+```
+
+**Note**:
+
+In the [brave release
notes](https://github.com/openzipkin/brave/releases/tag/4.7.1), it's stated
that we need to use `create()` instead of `builder()`
+
+``` diff
+
+ /** Configuration for how to buffer spans into messages for Zipkin */
+- @Bean Reporter<Span> reporter() {
+- return AsyncReporter.builder(sender()).build();
++ @Bean Reporter<Span> spanReporter() {
++ return AsyncReporter.create(sender()).build();
+ }
+```
+
+
+But this will not work. In `zipkin2.Reporter`, the `create(sender)` is
actually equivalent to `builder(sender).build()`
+
+``` java
+ public static AsyncReporter<Span> create(Sender sender) {
+ return (new AsyncReporter.Builder(sender)).build();
+ }
+
+ public static AsyncReporter.Builder builder(Sender sender) {
+ return new AsyncReporter.Builder(sender);
+ }
+```
+
+
+### Make changes according to the changes of zipkin.Span and zipkin2.Span.
+
+We do not use zipkin.Span in our production code, but we do use it in our
tests. Those changes are quite straight forward, we just change the accessing
of fields to calling methods as described in the What's Changed section.
+
+``` diff
+tracing/tracing-zipkin/src/test/java/io/servicecomb/tracing/zipkin/ZipkinSpanAspectTest.java
+@@ -45,7 +45,7 @@
+ import io.servicecomb.tracing.zipkin.app.ZipkinSpanTestApplication;
+ import
io.servicecomb.tracing.zipkin.app.ZipkinSpanTestApplication.CustomSpanTask;
+ import
io.servicecomb.tracing.zipkin.app.ZipkinSpanTestApplication.SomeSlowTask;
+-import zipkin.Span;
++import zipkin2.Span;
+
+ @RunWith(SpringRunner.class)
+ @SpringBootTest(classes = {ZipkinSpanTestApplication.class,
TracingConfig.class})
+@@ -74,8 +74,8 @@ public void reportedSpanContainsAnnotatedMethodInfo() throws
Exception {
+
+ await().atMost(2, SECONDS).until(() -> !spans.isEmpty());
+
+- zipkin.Span span = spans.poll();
+- assertThat(span.name, is("crawl"));
++ zipkin2.Span span = spans.poll();
++ assertThat(span.name(), is("crawl"));
+ assertThat(tracedValues(span),
contains(SomeSlowTask.class.getMethod("crawl").toString()));
+ }
+
+@@ -84,17 +84,17 @@ public void reportCustomSpanInfomation() throws Exception {
+ customSpanTask.invoke();
+ await().atMost(2, SECONDS).until(() -> !spans.isEmpty());
+
+- zipkin.Span span = spans.poll();
+- assertThat(span.name, is("transaction1"));
++ zipkin2.Span span = spans.poll();
++ assertThat(span.name(), is("transaction1"));
+ assertThat(tracedValues(span), contains("startA"));
+
+ }
+
+- private List<String> tracedValues(zipkin.Span spans) {
+- return spans.binaryAnnotations.stream()
+- .filter(span -> CALL_PATH.equals(span.key) ||
"error".equals(span.key))
+- .filter(span -> span.value != null)
+- .map(annotation -> new String(annotation.value))
++ private List<String> tracedValues(zipkin2.Span spans) {
++ return spans.tags().entrySet().stream()
++ .filter(span -> CALL_PATH.equals(span.getKey()) ||
"error".equals(span.getKey()))
++ .filter(span -> span.getValue() != null)
++ .map(annotation -> new String(annotation.getValue()))
+ .distinct()
+ .collect(Collectors.toList());
+ }
+@@ -110,7 +110,7 @@ public void reportCustomSpanInfomation() throws Exception {
+ Tracing tracing(Queue<Span> spans) {
+ return Tracing.newBuilder()
+ .currentTraceContext(new StrictCurrentTraceContext())
+- .reporter(spans::add)
++ .spanReporter(spans::add)
+ .build();
+ }
+ }
+```
+
+
+### Support both v1 and v2 api of zipkin server.
+
+Our customers may be still running a zipkin server prior to 1.31 which does
not support the v2 http api. So we added an option to let them specify the
server api version.
+
+Supporting v1 api is built into zipkin2, so we do not need to rely on the v1
libraries. Just use the `SpanBytesEncoder.JSON_V1` when building reporter and
change the sender api path.
+
+``` java
+sender = URLConnectionSender.create("http://localhost:9411/api/v1/spans";)
+reporter = AsyncReporter.builder(sender)
+ .build(SpanBytesEncoder.JSON_V1);
+```
+
+
+That's all, for the complete changes, please refer the [pull
request](https://github.com/apache/incubator-servicecomb-java-chassis/pull/488)
for the complete changes.
+
+## References
+
+* [Zipkin 2.0.0 release
notes](https://github.com/openzipkin/zipkin/releases/tag/2.0.0)
+* [Brave 4.7.1 release
notes](https://github.com/openzipkin/brave/releases/tag/4.7.1)
+* [Brave API V4](https://github.com/openzipkin/brave/tree/master/brave)
--
To stop receiving notification emails like this one, please contact
['"commits@servicecomb.apache.org" <commits@servicecomb.apache.org>'].
