isabella232 / wavefront-dropwizard-metrics-sdk-java

Send Dropwizard Metrics to Wavefront

Wavefront Dropwizard Metrics SDK

Table of Content

• Prerequisites
• Set Up a DropwizardMetricsReporter
  • Step 1: Create a Builder for a DropwizardMetricsReporter
  • Step 2: Configure the DropwizardMetricsReporter (Optional)
  • Step 3: Set Up a WavefrontSender
  • Step 4: Create a DropwizardMetricsReporter
• Start the DropwizardMetricsReporter
• Stop the DropwizardMetricsReporter
• Types of Data You Can Report to Wavefront
• Monitoring the SDK
• License
• How to Contribute

Welcome to the Wavefront Dropwizard Metrics SDK

The Tanzu Observability by Wavefront Dropwizard Metrics SDK for Java is a library that supports reporting Dropwizard metrics, delta counters, and histograms to Wavefront.

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

Note:
This is the Tanzu Observability by Wavefront Metrics SDK for the Java Dropwizard Framework! If this SDK is not what you were looking for, see the table given below.

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

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

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

Replace $releaseVersion with the latest version available on maven.

Set Up a DropwizardMetricsReporter

This SDK provides a DropwizardMetricsReporter to report metrics and histograms to Wavefront.

To create a DropwizardMetricsReporter, follow these steps:

1. Create a DropwizardMetricsReporter.Builder instance.
2. Optionally, use the builder to configure the DropwizardMetricsReporter.
3. Create a WavefrontSender to send data to Wavefront.
4. Use the builder to create a DropwizardMetricsReporter with the WavefrontSender.

For details of each step, see the sections below.

Step 1: Create a Builder for a DropwizardMetricsReporter

The DropwizardMetricsReporter object reports any metrics, delta counters, and histograms you register in a MetricRegistry. This step creates a builder that supports configuring the metrics reporter.

// Create a registry
MetricRegistry metricRegistry = new MetricRegistry();

// Create a builder instance for the registry
DropwizardMetricsReporter.Builder builder = DropwizardMetricsReporter.forRegistry(metricRegistry);

Step 2: Configure the DropwizardMetricsReporter (Optional)

You can use the DropwizardMetricsReporter builder to specify various optional properties.

Basic Properties

// Optional: Set a nondefault source for your metrics, delta counters, and histograms.
// Defaults to hostname if omitted
builder.withSource("mySource");

// Add individual reporter-level point tags for your metrics, delta counters, and histograms
// The point tags are sent with every metric and histogram reported to Wavefront.
builder.withReporterPointTag("env", "staging");  // Example - replace values!
builder.withReporterPointTag("location", "SF");  // Example - replace values!

// Optional: Add application tags, which are propagated as point tags with the reported metric.
// See https://github.com/wavefrontHQ/wavefront-sdk-java/blob/master/docs/apptags.md for details.
builder.withApplicationTags(new ApplicationTags.Builder("OrderingApp", "Inventory").
       cluster("us-west-1").
       shard("primary").build());   // Example - replace values!

// Optional: Report your metrics, delta counters, and histograms with the specified prefix.
builder.prefixedWith("myPrefix");   // Example - replace value!

// Optional: Report JVM metrics for your Java application.
builder.withJvmMetrics();

// Optional: Report minute bin Wavefront histograms.
builder.reportMinuteDistribution();

// Optional: Report hour bin Wavefront histograms.
builder.reportHourDistribution();

// Optional: Report day bin Wavefront histograms.
builder.reportDayDistribution();

Advanced Properties

// Optional: Explicitly set the clock to override default behavior
builder.withClock(new Clock() {
  @Override
  public long getTick() {
    return System.currentTimeMillis();
  }
});

// Optional: Set a filter to report metrics only if they begin with 'my*'
builder.filter(MetricFilter.startsWith("my"));

// Optional: Don't report stddev and m15
builder.disabledMetricAttributes(ImmutableSet.<MetricAttribute>builder().
    add(MetricAttribute.STDDEV).
    add(MetricAttribute.M15_RATE).
    build());

Step 3: Set Up a WavefrontSender

The WavefrontSender object implements the low-level interface to send data to Wavefront.

• 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, follow the steps in Set Up a WavefrontSender to send data using either the Wavefront proxy or direct ingestion.

Step 4: Create a DropwizardMetricsReporter

Use the configured builder to create the DropwizardMetricsReporter. You must first specify the WavefrontSender object (see above).

// Create a DropwizardMetricsReporter instance
WavefrontSender wavefrontSender = buildWavefrontSender(); // pseudocode
DropwizardMetricsReporter dropwizardMetricsReporter = builder.build(wavefrontSender);

Start the DropwizardMetricsReporter

You need to explicitly start the DropwizardMetricsReporter to start reporting any metrics, delta counters, or histograms you create. Reporting continues until you stop the DropwizardMetricsReporter (see below).

The DropwizardMetricsReporter reports metrics/delta counters/histograms at regular intervals. Specify the length of the reporting interval to control how often you send data to the WavefrontSender. The reporting interval determines the timestamps on the data sent to Wavefront.

// Start the reporter to report metrics/delta counters/histograms at regular interval (example: 30s)
dropwizardMetricsReporter.start(30, TimeUnit.SECONDS);

Stop the DropwizardMetricsReporter

You must explicitly stop the DropwizardMetricsReporter before shutting down your application.

// Get total failure count reported by this reporter
int totalFailures = dropwizardMetricsReporter.getFailureCount();

// stop the reporter
dropwizardMetricsReporter.stop();

Types of Data You Can Report to Wavefront

The Dropwizard metrics library supports various metric types. This Wavefront SDK additionally provides a DeltaCounter type and a WavefrontHistogram type.

After you have created and started the DropwizardMetricsReporter, the metrics/delta counters/histograms you create are automatically reported to Wavefront.

// Assume a DropwizardMetricsReporter that is configured with the filter shown in Advanced Properties, above.

// Raw Counters
// Counter name begins with 'my*', so it's reported.
Counter counter = metricRegistry.counter("myCounter");
// Counter name does not begin with 'my*', so it's ignored.
Counter notReported = metricRegistry.counter("notMyCounter");

// Wavefront Delta Counter
DeltaCounter deltaCounter = DeltaCounter.get(metricRegistry, "myDeltaCounter");

// Gauge
AtomicInteger bufferSize = new AtomicInteger();
Gauge gauge = metricRegistry.register("myGauge", () -> bufferSize.get());

// Meter
Meter meter = metricRegistry.meter("myMeter");

// Timer
Timer timer = metricRegistry.timer("myTimer");

// Default Dropwizard Histogram
Histogram dropwizardHistogram = metricRegistry.histogram("myDropwizardHistogram");

// WavefrontHistogram
WavefrontHistogram wavefrontHistogram = WavefrontHistogram.get(metricRegistry, "myWavefrontHistogram");

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.
• If you didn't find the information you are looking for in our Wavefront Documentation, create a GitHub issue or PR.