WavefrontSender

March 29, 2021 ยท View on GitHub

Table of Content

Overview

You can send metrics, histograms, delta counters, or trace data from your application to the Wavefront service using a Wavefront proxy or direct ingestion.

  • 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.
  • Use direct ingestion to send the data directly to the Wavefront service. This is the simplest way to get up and running quickly.

Let's create a WavefrontClient to send data to Wavefront either via Wavefront proxy or directly over HTTP.

Deprecated implementations: WavefrontDirectIngestionClient and WavefrontProxyClient are deprecated from Wavefront proxy version 7.0 onwards. We recommend all new applications to use WavefrontClient.

  • Use WavefrontClientFactory to create a WavefrontClient instance, which can send data directly to a Wavefront service or send data using a Wavefront proxy.
  • The WavefrontClientFactory supports multiple client bindings. If more than one client configuration is specified, you can create a WavefrontMultiClient to send data to multiple Wavefront services.

Option 1: Sending Data via the Wavefront proxy

Prerequisites

Initialize the WavefrontClient

You initialize a WavefrontClient as shown in the examples below.

Optionally, you can call factory methods to tune the following ingestion properties:

  • Max queue size - Internal buffer capacity of the WavefrontSender. Data that exceeds this size is dropped.
  • Flush interval - Interval for flushing data from the WavefrontSender directly to Wavefront.
  • Batch size - Amount of data to send to Wavefront in each flush interval.

Together, the batch size and flush interval control the maximum theoretical throughput of the WavefrontSender.

Note: Override the default values only when you want to set higher values.

Example: Use a factory class to create a WavefrontClient and send data to Wavefront via Wavefront proxy.

// Add a client with the following URL format: "proxy://<your.proxy.load.balancer.com>:<port>" or "http://<host>:<port>/"
// to send data to proxies
WavefrontClientFactory wavefrontClientFactory = new WavefrontClientFactory();
wavefrontClientFactory.addClient(wavefrontURL);

WavefrontSender wavefrontSender = wavefrontClientFactory.getClient();

Example: Use a builder to create a WavefrontClient and send data to Wavefront via Wavefront proxy.

// Using the WavefrontClient.Builder directly with a url in the form of "http://<your.proxy.load.blanacer>:<port>"
// to send data to proxies.
WavefrontClient.Builder wfClientBuilder = new WavefrontClient.Builder(proxyURL);

// This is the size of internal buffer beyond which data is dropped
// Optional: Set this to override the default max queue size of 50,000
wfClientBuilder.maxQueueSize(100_000);

// This is the max batch of data sent per flush interval
// Optional: Set this to override the default batch size of 10,000
wfClientBuilder.batchSize(20_000);

// Together with batch size controls the max theoretical throughput of the sender
// Optional: Set this to override the default flush interval value of 1 second
wfClientBuilder.flushIntervalSeconds(2);

WavefrontSender wavefrontSender = wfClientBuilder.build();

Option 2: Sending Data via Direct Ingestion

Prerequisites

  • Verify that you have the Direct Data Ingestion permission. For details, see Examine Groups, Roles, and Permissions.
  • The HTTP URL of your Wavefront instance. This is the URL you connect to when you log in to Wavefront, typically something like http://<domain>.wavefront.com.
  • Obtain the API token.

Initialize the WavefrontClient

You initialize a WavefrontClient by building it with the information you obtained in the Prerequisites section.

Optionally, you can call factory methods to tune the following ingestion properties:

  • Max queue size - Internal buffer capacity of the WavefrontSender. Data that exceeds this size is dropped.
  • Flush interval - Interval for flushing data from the WavefrontSender directly to Wavefront.
  • Batch size - Amount of data to send to Wavefront in each flush interval.

Together, the batch size and flush interval control the maximum theoretical throughput of the WavefrontSender.

Note: Override the default values only when you want to set higher values.

Example: Use a factory class to create a WavefrontClient and send data to Wavefront via direct ingestion.

// Create a factory and add a client with the following URL format: "http://TOKEN@DOMAIN.wavefront.com"
// and a Wavefront API token with direct ingestion permission
WavefrontClientFactory wavefrontClientFactory = new WavefrontClientFactory();

// Add a new client that sends data directly to Wavefront services 
wavefrontClientFactory.addClient(wavefrontURL);

WavefrontSender wavefrontSender = wavefrontClientFactory.getClient();

Example: Use a builder to create a WavefrontClient and send data to Wavefront via direct ingestion.

// Using the WavefrontClient.Builder directly with a url in the form of "https://DOMAIN.wavefront.com"
// and a Wavefront API token with direct ingestion permission
WavefrontClient.Builder wfClientBuilder = new WavefrontClient.Builder(wavefrontURL, token);

// This is the size of internal buffer beyond which data is dropped
// Optional: Set this to override the default max queue size of 50,000
wfClientBuilder.maxQueueSize(100_000);

// This is the max batch of data sent per flush interval
// Optional: Set this to override the default batch size of 10,000
wfClientBuilder.batchSize(20_000);

// Together with batch size controls the max theoretical throughput of the sender
// Optional: Set this to override the default flush interval value of 1 second
wfClientBuilder.flushIntervalSeconds(2);

WavefrontSender wavefrontSender = wfClientBuilder.build();

Share a WavefrontSender

If you are using multiple Wavefront Java SDKs within the same JVM process, you can instantiate the WavefrontSender just once and share it among the SDKs.

For example, the following snippet shows how to use the same WavefrontSender when setting up the wavefront-opentracing-sdk-java and wavefront-dropwizard-metrics-sdk-java SDKs.


// Create a WavefrontSender
WavefrontSender wavefrontSender = buildWavefrontClient(); // pseudocode

// Create a WavefrontSpanReporter for the OpenTracing SDK
Reporter spanReporter = new WavefrontSpanReporter.Builder().
   withSource("wavefront-tracing-example").
   build(wavefrontSender);

// Create a Wavefront reporter for the Dropwizard Metrics SDK
MetricRegistry registry = new MetricRegistry();
DropwizardMetricsReporter.Builder builder =   
DropwizardMetricsReporter metricsReporter =
   DropwizardMetricsReporter.forRegistry(registry).
   build(wavefrontSender);
...

Note: If you use SDKs in different JVM processes, you must instantiate one WavefrontSender instance per JVM process.

Where to Go Next

To continue, select one of the Wavefront Java SDK links in the table below.

SDK Type SDK Description Java SDKs
OpenTracing SDK Implements the OpenTracing specification. Lets you define, collect, and report custom trace data from any part of your application code.
Automatically derives RED metrics from the reported spans.
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.
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.
Sender SDK Lets you send raw values to Wavefront for storage as metrics, histograms, or traces, e.g., to import CSV data into Wavefront.