Crate dipstick

A quick, modular metrics toolkit for Rust applications; similar to popular logging frameworks, but with counters, markers, gauges and timers.

Dipstick builds on stable Rust with minimal dependencies and is published as a crate.

Features

• Send metrics to stdout, log, statsd or graphite (one or many)
• Synchronous, asynchronous or mixed operation
• Optional fast random statistical sampling
• Immediate propagation or local aggregation of metrics (count, sum, average, min/max)
• Periodic or programmatic publication of aggregated metrics
• Customizable output statistics and formatting
• Global or scoped (e.g. per request) metrics
• Per-application and per-output metric namespaces
• Predefined or ad-hoc metrics

Cookbook

Dipstick is easy to add to your code: rust use dipstick::*; let app_metrics = metrics(to_graphite("host.com:2003")); app_metrics.counter("my_counter").count(3);

Metrics can be sent to multiple outputs at the same time: rust let app_metrics = metrics((to_stdout(), to_statsd("localhost:8125", "app1.host."))); Since instruments are decoupled from the backend, outputs can be swapped easily.

Metrics can be aggregated and scheduled to be published periodically in the background: rust use std::time::Duration; let (to_aggregate, from_aggregate) = aggregate(); publish_every(Duration::from_secs(10), from_aggregate, to_log("last_ten_secs:"), all_stats); let app_metrics = metrics(to_aggregate); Aggregation is performed locklessly and is very fast. Count, sum, min, max and average are tracked where they make sense. Published statistics can be selected with presets such as all_stats (see previous example), summary, average.

For more control over published statistics, a custom filter can be provided: rust let (_to_aggregate, from_aggregate) = aggregate(); publish(from_aggregate, to_log("my_custom_stats:"), |metric_kind, metric_name, metric_score| match metric_score { HitCount(hit_count) => Some((Counter, vec![metric_name, ".per_thousand"], hit_count / 1000)), _ => None });

Metrics can be statistically sampled: rust let app_metrics = metrics(sample(0.001, to_statsd("server:8125", "app.sampled."))); A fast random algorithm is used to pick samples. Outputs can use sample rate to expand or format published data.

Metrics can be recorded asynchronously: rust let app_metrics = metrics(async(48, to_stdout())); The async queue uses a Rust channel and a standalone thread. The current behavior is to block when full.

Metric definitions can be cached to make using ad-hoc metrics faster: rust let app_metrics = metrics(cache(512, to_log())); app_metrics.gauge(format!("my_gauge_{}", 34)).value(44);

The preferred way is to predefine metrics, possibly in a lazy_static! block: ```rust

[macro_use] external crate lazy_static;

lazy_static! { pub static ref METRICS: GlobalMetrics = metrics(to_stdout()); pub static ref COUNTER_A: Counter = METRICS.counter("counter_a"); } COUNTER_A.count(11); ```

Timers can be used multiple ways: ```rust let timer = app_metrics.timer("my_timer"); time!(timer, {/* slow code here /} ); timer.time(|| {/ slow code here */} );

let start = timer.start(); /* slow code here */ timer.stop(start);

timer.interval_us(123_456); ```

Related metrics can share a namespace: rust let db_metrics = app_metrics.with_prefix("database."); let db_timer = db_metrics.timer("db_timer"); let db_counter = db_metrics.counter("db_counter");

Reexports

pub use error::*;

pub use core::*;

Modules

core	Dipstick metrics core types and traits. This is mostly centered around the backend. Application-facing types are in the app module.
error	Error-chain like mechanism, without the error-chain dependency.
macros	Publicly exposed metric macros are defined here. Although dipstick does not have a macro-based API, in some situations they can make instrumented code simpler.

Macros

time	A convenience macro to wrap a block or an expression with a start / stop timer. Elapsed time is sent to the supplied statsd client after the computation has been performed. Expression result (if any) is transparently returned.

Structs

Aggregator	Central aggregation structure. Since AggregateKeys themselves contain scores, the aggregator simply maintains a shared list of metrics for enumeration when used as source.
CancelHandle	A handle to cancel a scheduled task if required.
Counter	A counter that sends values to the metrics backend
Gauge	A gauge that sends values to the metrics backend
GlobalMetrics	Variations of this should also provide control of the metric recording scope.
Graphite	Key of a graphite metric.
Marker	A monotonic counter metric. Since value is only ever increased by one, no value parameter is provided, preventing programming errors.
Publisher	Define and write metrics from aggregated scores to the target channel If this is called repeatedly it can be a good idea to use the metric cache to prevent new metrics from being created every time.
QueueCommand	Carry the scope command over the queue, from the sender, to be executed by the receiver.
RetrySocket	A socket that retries
Sample	The metric sampling key also holds the sampling rate to apply to it.
ScopeCounter	A counter that sends values to the metrics backend
ScopeGauge	A gauge that sends values to the metrics backend
ScopeMarker	A monotonic counter metric. Since value is only ever increased by one, no value parameter is provided, preventing programming errors.
ScopeTimer	A timer that sends values to the metrics backend Timers can record time intervals in multiple ways : - with the time! macrohich wraps an expression or block with start() and stop() calls. - with the time(Fn) methodhich wraps a closure with start() and stop() calls. - with start() and stop() methodsrapping around the operation to time - with the interval_us() method, providing an externally determined microsecond interval
ScopedMetrics	Variations of this should also provide control of the metric recording scope.
Scoreboard	A metric that holds aggregated values. Some fields are kept public to ease publishing.
Statsd	Key of a statsd metric.
Timer	A timer that sends values to the metrics backend Timers can record time intervals in multiple ways : - with the time! macrohich wraps an expression or block with start() and stop() calls. - with the time(Fn) methodhich wraps a closure with start() and stop() calls. - with start() and stop() methodsrapping around the operation to time - with the interval_us() method, providing an externally determined microsecond interval

Enums

ScoreType

Possibly aggregated scores.

Traits

Publish	A trait to publish metrics.
ToPrimitive	A generic trait for converting a value to a number.
ToSocketAddrs	A trait for objects which can be converted or resolved to one or more SocketAddr values.

Functions

aggregate	Aggregate metrics in memory. Depending on the type of metric, count, sum, minimum and maximum of values will be tracked. Needs to be connected to a publish to be useful.
all_stats	A predefined export strategy reporting all aggregated stats for all metric types. Resulting stats are named by appending a short suffix to each metric's name.
async	Cache metrics to prevent them from being re-defined on every use. Use of this should be transparent, this has no effect on the values. Stateful sinks (i.e. Aggregate) may naturally cache their definitions.
average	A predefined export strategy reporting the average value for every non-marker metric. Marker metrics export their hit count instead.
cache	Cache metrics to prevent them from being re-defined on every use. Use of this should be transparent, this has no effect on the values. Stateful sinks (i.e. Aggregate) may naturally cache their definitions.
global_metrics	Wrap the metrics backend to provide an application-friendly interface.
prefix	Insert prefix in newly defined metrics.
sample	Perform random sampling of values according to the specified rate.
schedule	Schedule a task to run periodically. Starts a new thread for every task.
scoped_metrics	Wrap the metrics backend to provide an application-friendly interface. When reporting a value, scoped metrics also need to be passed a [Scope].
snapshot	Capture a snapshot of Dipstick's internal metrics since the last snapshot.
summary	A predefined single-stat-per-metric export strategy: - Timers and Counters each export their sums - Markers each export their hit count - Gauges each export their average
to_graphite	Send metrics to a graphite server at the address and port provided.
to_log	Write metric values to the standard log using info!.
to_statsd	Send metrics to a statsd server at the address and port provided.
to_stdout	Write metric values to stdout using println!.
to_void	Special sink that discards all metric values sent to it.

Type Definitions

Aggregate	The type of metric created by the Aggregator.
ScoreSnapshot	A snapshot of multiple scores for a single metric.