This website uses cookies to give you the best experience on our website. Using this website means you are okay with this but you can find out more here.

Metric Types

Statful has built Clients for some of our favourite frameworks/programming languages and made them available on GitHub.
See the full list of official and community Clients here.

To support your own development while accessing Statful’s server, we’ve packed the Clients with predefined methods. These methods are subjective to framework and metric type.

Nevertheless, they are customisable for you to fine-tune in your own way and send metrics to Statful with little to no extra effort required.

Default Configurations

Instead of returning a result from a single intake of metrics, you can return computed data (from a finite set), that is then stored in Statful. Your aggregated data is calculated within the time period you specify and applying any of the following:

  • Counter - as the name implies, its default aggregation “counts” - it will increment a numeric attribute, considering the interval that is given. This value is meant to only increase, much like a number of completed tasks, of website visitors, errors in your app, etc.
    A direct advantage of using the counter is an easy extrapolation of its value when a sample rate is specified.

  • Gauge - this metric has a single numerical value in time that could arbitrarily go up or down. Typically the gauge relies on “last” value aggregation, which could not be used to extrapolate a value considering a sample rate since the numbers are random.
    You can use gauges, e.g., as instant memory usage, running processes, etc.

  • Timer - to reduce load but sample up events that get through, you could set up a timer. This method applies the 90th percentile aggregation on your metrics, measuring an occurrence, taking the average of duration of an event for the time interval you define, and provide the “count” of execution. That’s why a tag unit:ms is always associated with this call.

  • Put or Custom Metrics - this option is open-ended, so it doesn’t have a preeminent aggregation. Statful will simply store data from data points correlated with a timestamp.

Whenever omitted, the methods assume default values for the optional parameters. Learn more about these values on the table below.

OptionDescriptionDefault for CounterDefault for GaugeDefault for TimerDefault for Custom Metric
aggregationsDefines the aggregations to be executed. These aggregations are merged with the ones configured globally, including method defaults.

Valid Aggregations: AVG, COUNT, SUM, FIRST, LAST, P90, P95, P99 MIN, MAX
aggFreqDefines the aggregation frequency in seconds. It overrides the global aggregation frequency configuration.

Valid Aggregation Frequencies: 10, 30, 60, 120, 180, 300
namespaceDefines the namespace of the metric. It overrides the global namespace configuration.applicationapplicationapplicationapplication
tagsDefines the tags of the metric. These tags are merged with the ones configured globally, including method defaults.nonenoneunit: 'ms'none
timestampDefines the timestamp of the metric. This timestamp is a UNIX Epoch time, represented in seconds.current timestampcurrent timestampcurrent timestampcurrent timestamp

For more information about the aggregations and options presented in the table, please refer to the documentation here.


You will often find these methods available for use with non-aggregated and aggregated metrics. The latter responds to the need for ingestion of already aggregated metrics into Statful (for example, from AWS CloudWatch).

Non-aggregated metrics receive a metric name and a metric value as arguments and send a counter, gauge, timer, or custom metric.

Here’s an example call for each method, as seen in the Java Client:

//non-aggregated metrics
client.counter("testCounter", 1).send();
client.gauge("testGauge", 10).send();
client.timer("testTimer", 200).send();

Note that the above methods are sent with its metric type alone. An example of a fine-tuned non-aggregated metric is:

client.counter("testCounter", 1).with().aggregations(SUM).send();
client.gauge("testGauge", 10).with().tag("host", "localhost").send();
client.timer("testTimer", 200).with().namespace("sandbox").send();

Aggregated metrics receive a metric name and value, an aggregation and an aggregation frequency (the one used beforehand to aggregate the metric) as arguments, and send a counter, a gauge, a timer or a custom metric.

The call to these metrics is depicted here:

//aggregated metrics
client.aggregatedGauge("testGauge", 10, Aggregation.AVG, AggregationFreq.FREQ_120).send();
client.aggregatedTimer("testTimer", 100, Aggregation.AVG, AggregationFreq.FREQ_10).send();
client.aggregatedCounter("testCounter", 1, Aggregation.SUM, AggregationFreq.FREQ_10).send();
client.aggregatedPut("testCustomMetric", Aggregation.COUNT, AggregationFreq.FREQ_180).send();