wavefrontHQ/wavefront-opentracing-sdk-java

Wavefront OpenTracing Java SDK

wavefront-opentracing-sdk-java

We are deprecating the OpenTracing repositories, and they are no longer supported. To migrate from OpenTracing to OpenTelemetry, see the migration steps in our documentation

Contact our support team if you have any questions (support@wavefront.com). Thank you!

Table of Content

• Prerequisites
• Usage
  • Application Tags
  • WavefrontSender
  • Reporter
  • WavefrontTracer
• Span Logs
• Cross Process Context Propagation
• RED Metrics
• Monitoring the SDK
• License
• How to Contribute

Welcome to Wavefront's OpenTracing Java SDK

This is the Wavefront by VMware OpenTracing SDK for Java that provides distributed tracing support for Wavefront.

The Wavefront OpenTracing SDK for Java automatically reports JVM metrics, custom trace data, and derived metrics. You can display the JVM metrics in a chart using the query ts(app-agent.jvm.*).

Before you start implementing, let us make sure you are using the correct SDK!

Note:

• This is the Wavefront by VMware OpenTracing SDK for Java! If this SDK is not what you were looking for, see the table given below.
• Don't want to write code to instrument your application? Use the Wavefront Java Tracing Agent.
• See instrument your application for tracing for more information.

Wavefront SDKs

SDK Type	SDK Description	Supported Languages
OpenTracing SDK	Implements the OpenTracing specification. Lets you define, collect, and report custom trace data from any part of your application code. Automatically derives Rate Errors Duration (RED) metrics from the reported spans.	Java: OpenTracing SDK | Tracing Agent Python: OpenTracing SDK Go: OpenTracing SDK .Net/C#: OpenTracing SDK
Metrics SDK	Implements a standard metrics library. Lets you define, collect, and report custom business metrics and histograms from any part of your application code.	Java: Dropwizard | JVM Python: Pyformance SDK Go: Go Metrics SDK .Net/C#: App Metrics SDK
Framework SDK	Reports predefined traces, metrics, and histograms from the APIs of a supported app framework. Lets you get started quickly with minimal code changes.	Java: Dropwizard | gRPC | JAX-RS | Jersey .Net/C#: ASP.Net core
Sender SDK	Lets you send raw values to Wavefront for storage as metrics, histograms, or traces, e.g., to import CSV data into Wavefront.	Java: Sender SDK Python: Sender SDK Go: Sender SDK .Net/C#: Sender SDK C++: Sender SDK

Prerequisites

• Java 8 or above.
• If you are using Maven, add the following maven dependency to your pom.xml file:

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

  Replace $releaseVersion with the latest version available on maven.

Usage

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

This SDK provides a WavefrontTracer to create spans and send them to Wavefront. The WavefrontTracer also automatically generates and reports RED metrics from your spans.

Follow these steps to create a WavefrontTracer:

1. Create an ApplicationTags instance, to specify metadata about your application.
2. Create a WavefrontSender instance to send trace data to Wavefront.
3. Create a WavefrontSpanReporter instance to report trace data to Wavefront.
4. Create the WavefrontTracer instance.

The following code sample creates a Tracer. For details on 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 and configure it to send data via a Wavefront proxy. WavefrontClientFactory is used to send data to multiple Wavefront services, such as the metrics port and the distribution port.
  // Assume you have installed and started the proxy on <proxyHostname>.
  WavefrontClientFactory wavefrontClientFactory = new WavefrontClientFactory();
    // Add a client to send metrics and distributions data to Wavefront. The default port is 2878
    // From proxy version 9.0 onwards, you can send metrics and spans using port 2878.
    wavefrontClientFactory.addClient("http://<proxy_hostname>:2878/");
    // Add a client to send traces and spans to Wavefront. The default port is 30000
    wavefrontClientFactory.addClient("http://<proxy_hostname>:30000/");
  WavefrontSender wavefrontSender = wavefrontClientFactory.getClient();

  // 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 describe the structure of your application. They are included with every span reported to Wavefront and are associated with span tags that you can use 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 the Wavefront proxy or direct ingestion.

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

• Otherwise, set up a WavefrontSender.

3. Set Up a Reporter

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

Create a WavefrontSpanReporter

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

Example: 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 are automatically 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 configure sampling and add multi-valued span tags before building
Tracer tracer = wfTracerBuilder.build();

Sampling (Optional)

Optionally, you can apply one or multiple sampling strategies to the WavefrontTracer. See the sampling documentation for details.

Multi-valued Span Tags (Optional)

Optionally, you can 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();

Add Custom Span-Level RED metrics

Optionally, you can add custom span-level tags to propagate RED metrics. See Custom Span-Level Tags for RED Metrics for details.

wfTracerBuilder.redMetricsCustomTagKeys(new HashSet<String>(Arrays.asList("env", "location")));

Close the Tracer

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

tracer.close();

Span Logs

Note: Span logs are disabled by default and require Wavefront proxy version 5.0 or later. Contact support@wavefront.com to enable the feature.

You can instrument your application to emit logs or events with spans, and examine them from the Wavefront Tracing UI.

Use the OpenTracing Span object’s log() method in your application.

Cross Process Context Propagation

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

RED Metrics

See the RED metrics documentation for details on the out-of-the-box metrics and histograms that are provided.

Monitoring the SDK

See the diagnostic metrics documentation for details on the internal metrics that this SDK collects and reports to Wavefront.

License

Apache 2.0 License.

How to Contribute

• Reach out to us on our public Slack channel.
• If you run into any issues, let us know by creating a GitHub issue.