Recording Custom Java Metrics

Retrace supports the monitoring of custom metrics for Java web applications.  Metrics are reported to Stackify once a minute. They are only reported if you log a value within that minute time frame. See advanced settings below about overriding that default behavior. All metrics have a category and metric name. It is recommended to group similar metrics under a single category so they show together in the UI.

Also visit the Stackify Github Page to view the source code and learn more.

Installation

Add it as a maven dependency:

<dependency>
	<groupId>com.stackify</groupId>
	<artifactId>stackify-metrics</artifactId>         
	<version>INSERT_LATEST_MAVEN_CENTRAL_VERSION</version>
</dependency>

Usage

There are four different types of metrics:

• Gauge: Keeps track of the last value that was set in the current minute
• Counter: Calculates the rate per minute
• Average: Calculates the average of all values in the current minute
• Timer: Calculates the average elapsed time for an operation in the current minute
• CounterAndTimer: Composite of the Counter and Timer metrics for convenience

All metrics are identified with a category and name. We will group metrics with the same category when they are displayed in Stackify. Use the MetricFactory to get different types of metrics. See below for more details on the operations available for each type of metric.

Gauge gauge = MetricFactory.getGauge("MyCategory", "MyGauge");

Be sure to properly shutdown to flush any queued metrics and shutdown the background thread:

MetricManager.shutdown();

Configuration

You need a stackify-api.properties file on your classpath that defines the configuration required for the Metrics API:

stackify.apiKey=YOUR_API_KEY
stackify.application=YOUR_APPLICATION_NAME
stackify.environment=YOUR_ENVIRONMENT

Note: If you are logging from a device that has the stackify-agent installed, the environment setting is optional. We will use the environment associated to your device in Stackify.

Programmatic Configuration (Optional)

Instead of providing a properties file in your classpath, you can configure the Metrics API programmatically:

ApiConfiguration.Builder builder = ApiConfiguration.newBuilder();
builder.apiKey("YOUR_API_KEY");
builder.application("YOUR_APPLICATION_NAME");
builder.environment("YOUR_ENVIRONMENT");
ApiConfiguration config = builder.build();
		
MetricManager.configure(config);

This needs to be done at application startup before any other interactions with the Metrics API.

Note: If you are logging from a device that has the stackify-agent installed, the environment setting is optional. We will use the environment associated to your device in Stackify.

Gauge Metric

// Get a Gauge metric
Gauge gauge = MetricFactory.getGauge("MyCategory", "MyGauge");

// Set the value of the metric to v
gauge.set(v);

// Adds v to the current value of the metric
gauge.add(v);

// Subtracts v from the current value of the metric
gauge.subtract(v);

// Automatically report 0 for the value of the metric if not set
gauge.autoReportZeroValue();

// Automatically report the last value for this metric if not set
gauge.autoReportLastValue();

Counter Metric

// Get a Counter metric
Counter counter = MetricFactory.getCounter("MyCategory", "MyCounter");

// Adds 1 to the current value of the metric
counter.increment();

// Adds v to the current value of the metric
counter.increment(v);

// Subtracts 1 from the current value of the metric
counter.decrement();

// Subtracts v from the current value of the metric
counter.decrement(v);

// Adds v to the current value of the metric
counter.add(v);

// Subtracts v from the current value of the metric
counter.subtract(v);

//Automatically report 0 for the value of the metric if not set
counter.autoReportZeroValue();

Average Metric

// Get a Average metric
Average average = MetricFactory.getAverage("MyCategory", "MyAverage");

// Adds a value to the average metric
average.addValue(v);

// Automatically report 0 for the value of the metric if not set
average.autoReportZeroValue();

// Automatically report the last value for this metric if not set
average.autoReportLastValue();

Timer Metric

// Get a Timer metric
Timer timer = MetricFactory.getTimer("MyCategory", "MyTimer");

// Calculates the time taken for this operation using the start time d (java.util.Date)
timer.start(d);

// Calculates the time taken for this operation using the start time d (milliseconds)
timer.startMs(d);

// Sets the time taken for this operation to d (milliseconds)
timer.durationMs(d);

// Automatically report 0 for the value of the metric if not set
timer.autoReportZeroValue();

CounterAndTimer Metric

// Get a CounterAndTimer metric (composite of a Counter metric and Timer metric)
CounterAndTimer counterAndTimer = MetricFactory.getCounterAndTimer("MyCategory", "MyCounterAndTimer");

// Counter: Adds 1 to the current value of the metric
// Timer: Calculates the time taken for this operation using the start time d (java.util.Date)
counterAndTimer.start(d);

// Counter: Adds 1 to the current value of the metric
// Timer: Calculates the time taken for this operation using the start time d (milliseconds)
counterAndTimer.startMs(d);

// Counter: Adds 1 to the current value of the metric
// Timer: Sets the time taken for this operation to d (milliseconds)
counterAndTimer.durationMs(d);

// Automatically report 0 for the value of the metric if not set
counterAndTimer.autoReportZeroValue();