This page provides custom steps for setting up the Wavefront by VMware Jersey SDK in your application. With custom setup, you instantiate helper objects explicitly in your code instead of using the configuration files shown with Quickstart setup.
Custom setup gives you control over all settable aspects of instrumenting the Jersey framework in a microservice. You should use custom setup if you want to tune performance through the WavefrontSender
, or if you want to implement your own configuration-file mechanism.
Follow the steps below to 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:
- Create an
ApplicationTags
instance, which specifies metadata about your application. - Create a
WavefrontSender
for sending data to Wavefront. - Create a
WavefrontJerseyReporter
for reporting Jersey metrics and histograms to Wavefront. - Optional. Create a
WavefrontTracer
for reporting trace data from Jersey APIs to Wavefront. - Create and register a
WavefrontJerseyFilter
. - If you created a
WavefrontTracer
in step 4, create and register aWavefrontJaxrsClientFilter
.
For the details of each step, see the sections below.
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.
You encapsulate application tags in an ApplicationTags
object. See Instantiating ApplicationTags for details.
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 aWavefrontSender
instance, see Share a WavefrontSender.) -
Otherwise, follow the steps in Set Up a WavefrontSender.
The WavefrontSender
is used by both the WavefrontJerseyReporter
and the optional WavefrontTracer
.
A WavefrontJerseyReporter
object reports metrics and histograms to Wavefront.
To build a WavefrontJerseyReporter
, you must specify:
You can optionally specify:
- A nondefault source for the reported data. If you omit the source, the host name is automatically used.
- A nondefault reporting interval, which controls how often data is reported to the WavefrontSender. The reporting interval determines the timestamps on the data sent to Wavefront. If you omit the reporting interval, data is reported once a minute.
ApplicationTags applicationTags = buildTags(); // pseudocode; see above
// Create WavefrontJerseyReporter.Builder using applicationTags.
WavefrontJerseyReporter.Builder wfJerseyReporterBuilder = new WavefrontJerseyReporter.Builder(applicationTags);
// Optionally set a nondefault source name for your metrics and histograms. Omit this statement to use the host name.
wfJerseyReporterBuilder.withSource("mySource");
// Optionally change the reporting interval to 30 seconds. Default is 1 minute
wfJerseyReporterBuilder.reportingIntervalSeconds(30);
// Create a WavefrontJerseyReporter with a WavefronSender
WavefrontJerseyReporter wfJerseyReporter = wfJerseyReporterBuilder.build(wavefrontSender);
You can optionally configure the WavefrontTracer
to create and send trace data from your Jersey application to Wavefront.
To build a WavefrontTracer
, you must specify:
- The
ApplicationTags
object (see above). - A
WavefrontSpanReporter
for reporting trace data to Wavefront. See Create a WavefrontSpanReporter for details. Note: When you create theWavefrontSpanReporter
, you should instantiate it with the same source name andWavefrontSender
that you used to create theWavefrontJerseyReporter
earlier on this page.
ApplicationTags applicationTags = buildTags(); // pseudocode; see above
Reporter wavefrontSpanReporter = buildSpanReporter(); // pseudocode
Tracer wavefrontTracer = new WavefrontTracer.Builder(wavefrontSpanReporter, applicationTags).build();
A WavefrontJerseyFilter
collects HTTP request/response metrics, histograms, and server-side trace data.
-
Build a
WavefrontJerseyFilter
. Specify theApplicationTags
,WavefrontSpanReporter
, and optionalWavefrontTracer
objects you created above:// Use the WavefrontJerseyReporter and ApplicationTags to create a builder WavefrontJerseyFilter.Builder wfJerseyFilterBuilder = new WavefrontJerseyFilter.Builder(wfJerseyReporter, applicationTags); // Configure the builder with the WavefrontTracer, if you set one up. // Omit this call if you only want to collect metrics and histograms. wfJerseyFilterBuilder.withTracer(wavefrontTracer); // Create the WavefrontJerseyFilter WavefrontJerseyFilter wfJerseyFilter = wfJerseyFilterBuilder.build();
-
Register the
WavefrontJerseyFilter
. Follow the steps for the framework used by the service:
Ignore this section if you want to collect only metrics and histograms (no trace data).
A WavefrontJaxrsClientFilter
enables an instrumented client-side 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.
Note: As an alternative to using a WavefrontJaxrsClientFilter
, you can propagate trace information between services explicitly.
-
Build the
WavefrontJaxrsClientFilter
. Specify theWavefrontSender
,ApplicationTags
andWavefrontTracer
you created above, and use the same source name you specified to theWavefrontJerseyReporter
.sourceName = "mySource"; // Example - Replace value! WavefrontJaxrsClientFilter wfClientFilter = new WavefrontJaxrsClientFilter(wavefrontSender, applicationTags, sourceName, wavefrontTracer);
-
Register the
WavefrontJaxrsClientFilter
:// Assumes a JAX-RS-compliant ClientBuilder instance clientBuilder.register(wfClientFilter);
After you instantiate the WavefrontJerseyReporter
and WaveFrontJerseyFilter
, you must explicitly start the Jersey reporter.
// Start the reporter
wfJerseyReporter.start();
Before you shut down your Jersey application, you must explicitly stop the Jersy reporter.
// Stop the reporter
wfJerseyReporter.stop();
See the metrics documentation for details on the out of the box metrics and histograms collected by this SDK and reported to Wavefront.
See the tracing documentation for details on propagating span contexts across process boundaries.