From fd25dd05bd30effdf2e2020d14315a9062ea09a7 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 14 Jun 2018 04:38:11 +0200 Subject: [PATCH 1/2] Add content for Java's Tracers. --- content/guides/java/tracers.md | 68 ++++++++++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/content/guides/java/tracers.md b/content/guides/java/tracers.md index b01b85f3b..ab5972136 100644 --- a/content/guides/java/tracers.md +++ b/content/guides/java/tracers.md @@ -2,7 +2,67 @@ title: "Java: Tracers" --- -* Setting up your tracer -* Using the Global Tracer -* Accessing the Active Span -* Accessing tracer specific features. \ No newline at end of file +#### Setting up your Tracer + +Different **Tracer** implementations vary in how and what parameters they receive at initialization time, such as: + +* Component name for this application's traces. +* Tracing endpoint. +* Tracing credentials. +* Sampling strategy. + + +For example, initializing the **Tracer** implementation of `Jaeger` looks like this: + +```java + import io.opentracing.Tracer; + + SamplerConfiguration samplerConfig = new SamplerConfiguration("const", 1); + ReporterConfiguration reporterConfig = new ReporterConfiguration(true, null, null, null, null); + Configuration config = new Configuration(service, samplerConfig, reporterConfig); + + // Get the actual OpenTracing-compatible Tracer. + Tracer tracer = config.getTracer(); +``` + +One a **Tracer** instance is obtained, it can be used to manually create **Span**, or pass it to existing instrumentation for frameworks and libraries: + +```java + // OpenTracing Redis client. It can be *any* OT-compatible tracer. + Tracer tracer = ...; + new TracingJedis(tracer); +``` + +#### Global Tracer + +In order to not force the user to keep around a **Tracer**, the **io.opentracing.util** artifact includes a helper **GlobalTracer** class implementing the **io.opentracing.Tracer**, which, as the name implies, acts as as a global instance that can be used from anywhere. It works by forwarding all operations to another underlying **Tracer**, that will get registered at some future point. + +By default, the underlying **Tracer** is a no-nop implementation. + +```java + import io.opentracing.util.GlobalTracer; + + // As part of initialization, pass it as an actual Tracer + // to code that will create Spans in the future. + new TracingJedis(GlobalTracer.get()); + + // Eventually register it, so all the calls to GlobalTracer.get() + // are forwarded to this object. Registration can happen only once. + Tracer tracer = new CustomTracer(...); + GlobalTracer.register(tracer); + ... + + // Create a Span as usually. This Span creation will happen + // using your CustomTracer. + Span span = GlobalTracer.get().buildSpan("foo").start(); +``` + +#### Using Tracer specific features + +For using **Tracer**-specific features, the instance needs to be casted back to the original type: + +```java + ((CustomTracer)tracer).customFeature(100); +``` + +**GlobalTracer** does not expose the original **Tracer**, and thus is not possible to use **Tracer**-specific features through it. From 77c80975b6626baccb077c4ea59fb2b3b4503adb Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 19 Jun 2018 00:32:11 +0200 Subject: [PATCH 2/2] Improvement pass. --- content/guides/java/tracers.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/content/guides/java/tracers.md b/content/guides/java/tracers.md index ab5972136..e2695a93b 100644 --- a/content/guides/java/tracers.md +++ b/content/guides/java/tracers.md @@ -4,6 +4,8 @@ title: "Java: Tracers" #### Setting up your Tracer +A **Tracer** is the actual implementation that will record the **Span**s and publish them somewhere. How your application handles the actual **Tracer** is up to you: either consume it directly throughout your application or store it in the **GlobalTracer** for easier usage with instrumented frameworks. + Different **Tracer** implementations vary in how and what parameters they receive at initialization time, such as: * Component name for this application's traces. @@ -12,7 +14,7 @@ Different **Tracer** implementations vary in how and what parameters they receiv * Sampling strategy. -For example, initializing the **Tracer** implementation of `Jaeger` looks like this: +For example, initializing the **Tracer** implementation of `Jaeger` might look like this: ```java import io.opentracing.Tracer; @@ -25,7 +27,13 @@ For example, initializing the **Tracer** implementation of `Jaeger` looks like t Tracer tracer = config.getTracer(); ``` -One a **Tracer** instance is obtained, it can be used to manually create **Span**, or pass it to existing instrumentation for frameworks and libraries: +If your **Tracer** supports it, the [TracerResolver](https://github.com/opentracing-contrib/java-tracerresolver) can also be used. With this approach, there's no **Tracer**-specific initialization code in your application: + +```java + Tracer tracer = TracerResolver.resolveTracer(); +``` + +Once a **Tracer** instance is obtained, it can be used to manually create **Span**, or pass it to existing instrumentation for frameworks and libraries: ```java // OpenTracing Redis client. It can be *any* OT-compatible tracer. @@ -35,7 +43,7 @@ One a **Tracer** instance is obtained, it can be used to manually create **Span* #### Global Tracer -In order to not force the user to keep around a **Tracer**, the **io.opentracing.util** artifact includes a helper **GlobalTracer** class implementing the **io.opentracing.Tracer**, which, as the name implies, acts as as a global instance that can be used from anywhere. It works by forwarding all operations to another underlying **Tracer**, that will get registered at some future point. +In order to not force the user to keep around a **Tracer**, the **io.opentracing.util** artifact includes a helper **GlobalTracer** class implementing the **io.opentracing.Tracer** interface, which, as the name implies, acts as as a global instance that can be used from anywhere. It works by forwarding all operations to another underlying **Tracer**, that will get registered at some future point. By default, the underlying **Tracer** is a no-nop implementation.