README.md

Wavefront Jersey SDK

The Wavefront for VMware Jersey SDK for Java is a library that collects out-of-the-box metrics, histograms and (optionally) traces from your Jersey-based microservices application, and reports the data to Wavefront. You can analyze the data in Wavefront to better understand how your application is performing in production.

You use this SDK for applications that use Jersey-compliant frameworks such as Dropwizard, Spring Boot, etc.

Maven

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

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

Replace $releaseVersion with the latest version available on maven.

Setup Steps

Choose the setup option that best fits your use case.

• Option 1: Quickstart - Use configuration files, plus a few code changes, to quickly instrument the Jersey framework and the JVM in your microservice. Default settings are used.

• Option 2: Custom Setup - Instantiate helper objects in your code for control over all settable aspects of instrumentation. Appropriate for Wavefront power users.

Quickstart

Follow the steps below to quickly set up a WavefrontJerseyFilter for collecting HTTP request/response metrics, histograms, and trace data. See the Jersey documentation to understand how filters work.

For each service that uses a Jersey-compliant framework, add the dependency if you have not already done so, and then perform the following steps:

1. Configure a set of application tags to describe your application to Wavefront.
2. Configure how to report out-of-the-box metrics, histograms and trace data to Wavefront.
3. Create and register a WavefrontJerseyFilter object.
4. Optional. Create and register a WavefrontJaxrsClientFilter object.

For the details of each step, see the sections below.

1. Configure Application Tags

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

For each web service in your Jersey application:

1. Create a application-tags.yaml configuration file.

2. Edit the file to add properties and values such as the following:

   application: "beachshirts"
   cluster: "us-west"
   service: "styling"
   shard: "primary"
   customTags:
     location: "Palo-Alto"
     env: "production"
   

   Notes:

   YAML Property	Description
   application	Required. Name that identifies your application. Use the same value for all microservices in the same application.
   service	Required. Name that identifies the microservice within your application. Use a unique value for each microservice.
   cluster	Optional. Name of a group of related hosts that serves as a cluster or region in which the application will run.
   shard	Optional. Name of a subgroup of hosts within a cluster.
   customTags	Optional. Tags specific to your application.

2. Configure Wavefront Reporting

You can choose to report out-of-the-box metrics, histograms, and traces to Wavefront using one of the following techniques:

• Use direct ingestion to send the data directly to the Wavefront service. This is the simplest way to get up and running quickly. See Option 1.
• Use a Wavefront proxy, which then forwards the data to the Wavefront service. This is the recommended choice for a large-scale deployment that needs resilience to internet outages, control over data queuing and filtering, and more. See Option 2.

Option 1 - Send Data Directly to Wavefront

For each web service in your Jersey application:

1. Create a wf-reporting-config.yaml configuration file.

2. Edit the file to add properties and values such as the following:

   # Reporting through direct ingestion
   reportingMechanism: "direct"
   server: "<replace-with-wavefront-url>"
   token: "<replace-with-wavefront-api-token>"
   source: "<replace-with-reporting-source>"
   reportTraces: true
   

   Notes:

   YAML Property	Value
   reportingMechanism	direct
   server	URL for your Wavefront instance, typically https://myCompany.wavefront.com
   token	String produced by obtaining an API token. You must have Direct Data Ingestion permission when you obtain the token.
   source	String that represents where the data originates -- typically the host name of the machine running the microservice.
   reportTraces	true to include trace data. false to suppress trace data.

Option 2 - Send Data to a Wavefront Proxy

Note: Before your application can send data, you must set up a Wavefront proxy on a host that the application can access.

For each web service in your Jersey application:

1. Create a wf-reporting-config.yaml configuration file.

2. Edit the file to add properties and values such as the following:

   # Reporting with a Wavefront proxy
   reportingMechanism: "proxy"
   proxyHost: "<replace-with-wavefront-proxy-hostname>"
   proxyMetricsPort: 2878
   proxyDistributionsPort: 40000
   proxyTracingPort: 30000
   source: "<replace-with-reporting-source>"
   reportTraces: true
   

   Notes:
   When you set up a Wavefront proxy on the specified proxy host, you specify the port it will listen to for each type of data to be sent. The proxy port properties in the YAML file must specify the same port numbers as the corresponding properties in the proxy configuration file (wavefront.conf):

   YAML Property	Value
   reportingMechanism	proxy
   proxyHost	String name or IP address of the host on which you set up the Wavefront proxy.
   proxyMetricsPort	Proxy port to send metrics to. Default is 2878. Must match the value set for pushListenerPorts= in wavefront.conf.
   proxyDistributionsPort	Proxy port to send histograms to. Recommended value is 40000. Must match the value set for histogramDistListenerPorts= in wavefront.conf.
   proxyTracingPort	Proxy port to send trace data to. Recommended value is 30000. Must match the value set for traceListenerPorts= in wavefront.conf.
   source	String that represents where the data originates -- typically, the host name of the machine running the microservice.
   reportTraces	true to include trace data. false to suppress trace data.

3. Create and Register a WavefrontJerseyFilter

In the code for each web service in your Jersey application:

1. Instantiate a WavefrontJerseyFactory. Pass in the path names of the configuration files you created above.

   // Instantiate the WavefrontJerseyFactory
   WavefrontJerseyFactory wavefrontJerseyFactory = new WavefrontJerseyFactory(
       applicationTagsYamlFile, wfReportingConfigYamlFile);

2. Use the factory to create a WavefrontJerseyFilter:

   // Create the WavefrontJerseyFilter
   WavefrontJerseyFilter wavefrontJerseyFilter
       wavefrontJerseyFactory.getWavefrontJerseyFilter();

3. Register the WavefrontJerseyFilter according to the framework used by the service:
   • Dropwizard registration steps
   • Spring Boot registration steps

4. Create and Register a WavefrontJaxrsClientFilter (Optional)

Ignore this section if you are collecting only metrics and histograms (without trace data) from your application.

In the code for each web service that is a JAX-RS-based client:

1. Use the factory you built in the previous section to create a WavefrontJaxrsClientFilter:

   // Instantiate the WavefrontJaxrsClientFilter
   WavefrontJaxrsClientFilter wavefrontJaxrsClientFilter = wavefrontJerseyFactory.
       getWavefrontJaxrsClientFilter();

2. Register the WavefrontJaxrsClientFilter:

   // Assumes a JAX-RS-compliant ClientBuilder instance
   clientBuilder.register(filter);

Notes:

• The WavefrontJaxrsClientFilter enables an instrumented client service to propagate trace information when sending a request to another service.
• The WavefrontJaxrsClientFilter supplements the WavefrontJerseyFilter, which creates server-side trace data, but not client-side trace data.

Metrics and Histograms Sent From Jersey Operations

See the metrics documentation for details on the out of the box metrics and histograms collected by this SDK and reported to Wavefront.