Crate dipstick

Crate dipstick

Expand description

A quick, modular metrics toolkit for Rust applications.

Macros§

labels: Create Labels from a list of key-value pairs Adapted from the hashmap!() macro in the maplit crate.
lazy_static
metrics: Metrics can be used from anywhere (public), does not need to declare metrics in this block.
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§

AppLabel: Handle metric labels for the whole application (globals). App scope labels have the lowest lookup priority and serve as a fallback to other scopes.
AtomicBucket: Central aggregation structure. Maintains a list of metrics for enumeration when used as source.
Attributes: Attributes common to metric components. Not all attributes used by all components.
CancelGuard: A guard canceling the inner handle when dropped.
CancelHandle: A handle to cancel a scheduled task if required.
Counter: A counter of absolute observed values (non-negative amounts). Used to count things that cannot be undone:
Gauge: A non-cumulative counter for immediate observation of resource usage.
Graphite: Graphite Input holds a socket to a graphite server. The socket is shared between scopes opened from the Input.
GraphiteMetric: Key of a graphite metric.
GraphiteScope: Graphite Input
GraphiteUdp: GraphiteUdp Input holds a socket to a graphite server. The socket is shared between scopes opened from the Input.
GraphiteUdpMetric: Key of a graphite metric.
GraphiteUdpScope: GraphiteUdp Input
InputMetric: A metric is actually a function that knows to write a metric value to a metric output.
InputQueue: Wrap new scopes with an asynchronous metric write & flush dispatcher.
InputQueueScope: A metric scope wrapper that sends writes & flushes over a Rust sync channel. Commands are executed by a background thread.
Labels: Base structure to carry metric labels from the application to the metric backend(s). Can carry both one-off labels and exported context labels (if async metrics are enabled). Used in applications through the labels!() macro.
Level: A counter of fluctuating resources accepting positive and negative values. Can be used as a stateful Gauge or as a Counter of possibly decreasing amounts.
LineTemplate: An sequence of print commands, embodying an output strategy for a single metric.
Log: Buffered metrics log output.
LogScope: A scope for metrics log output.
Marker: A monotonic counter metric. Since value is only ever increased by one, no value parameter is provided, preventing programming errors.
MetricId: A metrics identifier
MetricName: The name of a metric, including the concatenated possible namespaces in which it was defined.
MultiInput: Opens multiple scopes at a time from just as many outputs.
MultiInputScope: Dispatch metric values to a list of scopes.
NameParts: A double-ended vec of strings constituting a metric name or a future part thereof.
ObserveWhen: When to observe a recurring task.
OnFlushCancel: A handle to cancel a flush observer.
Prometheus: Prometheus Input holds a socket to a Prometheus server. The socket is shared between scopes opened from the Input.
PrometheusScope: Prometheus Input
Proxy: A dynamic proxy for app and lib metrics. Decouples metrics definition from backend configuration. Allows defining metrics before a concrete type is configured. Allows replacing metrics backend on the fly at runtime.
SimpleFormat: A simple metric output format of “MetricName {Value}”
StatsMapScope: A BTreeMap wrapper to receive metrics or stats values. Every received value for a metric replaces the previous one (if any).
Statsd: Statsd Input holds a datagram (UDP) socket to a statsd server. The socket is shared between scopes opened from the Input.
StatsdMetric: Key of a statsd metric.
StatsdScope: Statsd Input
Stream: Buffered metrics text Input.
TextScope: A scope for text metrics.
ThreadLabel: Handle metric labels for the current thread. App scope labels have the lowest lookup priority and serve as a fallback to other scopes.
TimeHandle: A handle to the start time of a counter. Wrapped so it may be changed safely later.
Timer: A timer that sends values to the metrics backend Timers can record time intervals in multiple ways :
Void: Discard metrics Input.

Enums§

Buffering: A metrics buffering strategy. All strategies other than Unbuffered are applied as a best-effort, meaning that the buffer may be flushed at any moment before reaching the limit, for any or no reason in particular.
InputKind: Used to differentiate between metric kinds in the backend.
LabelOp: Print commands are steps in the execution of output templates.
LineOp: Print commands are steps in the execution of output templates.
Sampling: The actual distribution (random, fixed-cycled, etc.) depends on selected sampling method.
ScoreType: Possibly aggregated scores.

Traits§

Buffered: Determine scope buffering strategy, if supported by output. Changing this only affects scopes opened afterwards. Buffering is done on best effort, meaning flush will occur if buffer capacity is exceeded.
CachedInput: Wrap an input with a metric definition cache. This can provide performance benefits for metrics that are dynamically defined at runtime on each access. Caching is useless if all metrics are statically declared or instantiated programmatically in advance and referenced by a long living variable.
Cancel: A deferred, repeatable, background action that can be cancelled.
Flush: Both InputScope and OutputScope share the ability to flush the recorded data.
Formatting: Format output config support.
Input: A function trait that opens a new metric capture scope.
InputDyn: A function trait that opens a new metric capture scope.
InputScope: InputScope Define metrics, write values and flush them.
LazyStatic: Support trait for enabling a few common operation on lazy static values.
LineFormat: Forges metric-specific printers
Observe: Schedule a recurring task
OnFlush: Register and notify scope-flush listeners
Prefixed: Name operations support.
QueuedInput: Wrap this output behind an asynchronous metrics dispatch queue. This is not strictly required for multi threading since the provided scopes are already Send + Sync but might be desired to lower the latency
Sampled: Apply statistical sampling to collected metrics data.
ScheduleFlush: Enable background periodical publication of metrics
WithAttributes: This trait should not be exposed outside the crate.
__Deref: Used for immutable dereferencing operations, like *v.

Functions§

initialize: Takes a shared reference to a lazy static and initializes it if it has not been already.
stats_all: 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.
stats_average: A predefined export strategy reporting the average value for every non-marker metric. Marker metrics export their hit count instead. Since there is only one stat per metric, there is no risk of collision and so exported stats copy their metric’s name.
stats_summary: A predefined single-stat-per-metric export strategy:

Type Aliases§

MetricValue: Base type for recorded metric values.