Wavefront OpenTracing Java SDK
Clone or download
sushantdewan123 and vikramraman generate metrics from spans (#36)
* Initial commit

* Fix broken test

* fixed broken test

* fixed review comments

* improved the tests to not sleep

* added total_time counter

* minor naming change

* Addressing review comments
Latest commit dc58a75 Jan 15, 2019

README.md

wavefront-opentracing-sdk-java build status Released Version OpenTracing Badge

The Wavefront by VMware OpenTracing SDK for Java is a library that provides open tracing support for Wavefront.

Maven

If you are using Maven, add the following maven dependency to your pom.xml:

<dependency>
  <groupId>com.wavefront</groupId>
  <artifactId>wavefront-opentracing-sdk-java</artifactId>
  <version>$releaseVersion</version>
</dependency>

Replace $releaseVersion with the latest version available on maven.

Set Up a Tracer

Tracer is an OpenTracing interface for creating spans and propagating them across arbitrary transports.

This SDK provides a WavefrontTracer for creating spans and sending them to Wavefront. The steps for creating a WavefrontTracer are:

  1. Create an ApplicationTags instance, which specifies metadata about your application.
  2. Create a WavefrontSender for sending trace data to Wavefront.
  3. Create a WavefrontSpanReporter for reporting trace data to Wavefront.
  4. Create the WavefrontTracer instance.

The following code sample creates a Tracer. For the details of each step, see the sections below.

Tracer createWavefrontTracer(String application, String service) throws IOException {
  // Step 1. Create ApplicationTags. 
  ApplicationTags applicationTags = new ApplicationTags.Builder(application, service).build();
  
  // Step 2. Create a WavefrontSender for sending trace data via a Wavefront proxy.
  //         Assume you have installed and started the proxy on <proxyHostname>.
  WavefrontSender wavefrontSender = new WavefrontProxyClient.Builder(<proxyHostname>).
        metricsPort(2878).tracingPort(30000).build();
        
  // Step 3. Create a WavefrontSpanReporter for reporting trace data that originates on <sourceName>.
  Reporter wfSpanReporter = new WavefrontSpanReporter.Builder().
        withSource(<sourceName>).build(wavefrontSender);
        
  // Step 4. Create the WavefrontTracer.
  return new WavefrontTracer.Builder(wfSpanReporter, applicationTags).build();
}

1. Set Up Application Tags

Application tags determine the metadata (span tags) that are included with every span reported to Wavefront. These tags enable you to filter and query trace data in Wavefront.

You encapsulate application tags in an ApplicationTags object. See Instantiating ApplicationTags for details.

2. Set Up a WavefrontSender

A WavefrontSender object implements the low-level interface for sending data to Wavefront. You can choose to send data using either the Wavefront proxy or direct ingestion.

  • If you have already set up a WavefrontSender for another SDK that will run in the same JVM, use that one. (For details about sharing a WavefrontSender instance, see Share a WavefrontSender.)

  • Otherwise, follow the steps in Set Up a WavefrontSender.

3. Reporter

You must create a WavefrontSpanReporter to report trace data to Wavefront. You can optionally create a CompositeReporter to send data to Wavefront and to print to the console.

Create a WavefrontSpanReporter

To build a WavefrontSpanReporter, you must specify a WavefrontSender. You can optionally specify a string that represents the source for the reported spans. If you omit the source, the host name is automatically used.

To create a WavefrontSpanReporter:

// Create a WavefrontProxyClient or WavefrontDirectIngestionClient
WavefrontSender sender = buildWavefrontSender(); // pseudocode; see above

Reporter wfSpanReporter = new WavefrontSpanReporter.Builder().
  withSource("wavefront-tracing-example"). // optional nondefault source name
  build(sender);

//  To get the number of failures observed while reporting
int totalFailures = wfSpanReporter.getFailureCount();

Note: After you initialize the WavefrontTracer with the WavefrontSpanReporter (below), completed spans will automatically be reported to Wavefront. You do not need to start the reporter explicitly.

Create a CompositeReporter (Optional)

A CompositeReporter enables you to chain a WavefrontSpanReporter to another reporter, such as a ConsoleReporter. A console reporter is useful for debugging.

// Create a console reporter that reports span to stdout
Reporter consoleReporter = new ConsoleReporter(<sourceName>); // Specify the same source you used for the WavefrontSpanReporter

// Instantiate a composite reporter composed of a console reporter and a WavefrontSpanReporter
Reporter compositeReporter = new CompositeReporter(wfSpanReporter, consoleReporter);

4. Create a WavefrontTracer

To create a WavefrontTracer, you pass the ApplicationTags and Reporter instances you created above to a Builder:

ApplicationTags appTags = buildTags(); // pseudocode; see above
Reporter wfSpanReporter = buildReporter();  // pseudocode; see above
WavefrontTracer.Builder wfTracerBuilder = new WavefrontTracer.Builder(wfSpanReporter, appTags);
// Optionally add multi-valued span tags before building
Tracer tracer = wfTracerBuilder.build();

Multi-valued Span Tags (Optional)

You can optionally add metadata to OpenTracing spans in the form of multi-valued tags. The WavefrontTracer builder supports different methods to add those tags.

// Construct WavefrontTracer.Builder instance
WavefrontTracer.Builder wfTracerBuilder = new WavefrontTracer.Builder(...);

// Add individual tag key value
wfTracerBuilder.withGlobalTag("env", "Staging");

// Add a map of tags
wfTracerBuilder.withGlobalTags(new HashMap<String, String>() {{ put("severity", "sev-1"); }});

// Add a map of multivalued tags since Wavefront supports repeated tags
wfTracerBuilder.withGlobalMultiValuedTags(new HashMap<String, Collection<String>>() {{
     put("location", Arrays.asList("SF", "NY", "LA")); }});

// Construct Wavefront opentracing Tracer
Tracer tracer = wfTracerBuilder.build();

Close the Tracer

Always close the tracer before exiting your application to flush all buffered spans to Wavefront.

tracer.close();

Cross Process Context Propagation

See the context propagation documentation for details on propagating span contexts across process boundaries.