System.Metrics.RRDTool

Simple API for passing ekg monitoring statistics to a round-robin database (RRD) using rrdtool.

Basic Types

type IntervalSeconds = Int

Intervals in seconds (e.g. heartbeats and step size)

type SourceValue = Int64

Counters, gauges etc. in ekg have this type

Data Sources

data DataSource

A data source in a round-robin database.

Constructors

DataSource

Fields

dsName :: Text

The name of the metric in the database. Maximum 19 characters and contains letters, digits and underscores only.

dsMetric :: Text

The name of the metric in the ekg Store.

dsType :: DataSourceType

The type of the metric.

dsHeartBeat :: IntervalSeconds

After this length of time with no updates, consider the value to be 'unknown'.

dsMin :: Maybe SourceValue

Values less than this should be interpreted as 'unknown'.

dsMax :: Maybe SourceValue

Values greater than this should be interpreted as 'unknown'.

Instances

Eq DataSource

Show DataSource

data DataSourceType

Types of data source in a round-robin database.

Constructors

DsGauge

Metrics whose current value is tracked. This is appropriate for Gauge metrics and creates a GAUGE DS.

DsDerive

Metrics that are monotonically increasing and whose rate-of-change is tracked. This is appropriate for Counter metrics and creates a DERIVE DS.

Instances

Bounded DataSourceType

Enum DataSourceType

Eq DataSourceType

Show DataSourceType

gcSources

Arguments

:: IntervalSeconds

The heartbeat for these metrics, in seconds.

-> [DataSource]

Pre-defined data sources for tracking GHC's GC metrics. See registerGcMetrics or GCStats for more details. Clients must run registerGcMetrics to register these metrics once the RRD is created.

Round Robin Archives

data ConsolidationFunction

Defines how multiple primary data points (PDPs) are turned into a consolidated data point (CDP) for storage in a RoundRobinArchive.

Constructors

CFLast

Keep the last point only.

CFAverage

Take the mean of the points.

CFMin

Take the minimum point.

CFMax

Take the maximum point.

Instances

Eq ConsolidationFunction

Show ConsolidationFunction

data RoundRobinArchive

A sequence of consolidated data points (CDPs).

Constructors

RoundRobinArchive

Fields

rraCf :: ConsolidationFunction

How to consolidate PDPs to get each CDP.

rraXff :: Double

The 'Xfiles factor' - if more than this proportion of PDPs is unknown then the CDP is unknown.

rraPdpCount :: Int

The number of PDPs to use to calculate each CDP.

rraRecordCount :: Int

The number of CDPs to store in the archive.

Instances

Eq RoundRobinArchive

Show RoundRobinArchive

Round Robin Databases

data RoundRobinDatabase

A round-robin database (RRD), which is a file on disk that stores time series data from a number of sources.

newRRD

Arguments

:: FilePath

The name of the database file.

-> IntervalSeconds

The update interval in seconds.

-> Maybe FilePath

A path to the rrdtool binary, or Nothing to simply call rrdtool.

-> [RoundRobinArchive]

Round-robin archives that define how data is stored.

-> [DataSource]

Data sources to define in the database.

-> IO RoundRobinDatabase

Create a new RoundRobinDatabase. Creates the database file on disk if not already present. Metrics must subsequently be registered in the store associated with the RoundRobinDatabase, which can be obtained with rrdStore. Throws an IOException if there was a problem running rrdtool.

rrdStore :: RoundRobinDatabase -> Store

Get the Store associated with this RoundRobinDatabase in order to register metrics.

Monitoring Thread

data MonitorThread

The monitoring thread for a round robin database, which can be created with runMonitor and killed with killMonitor.

runMonitor :: RoundRobinDatabase -> IO MonitorThread

Run a monitoring thread for the given database, which samples the metrics and updates the database at the chosen frequency. Failed updates are ignored.

killMonitor :: MonitorThread -> IO ()

Kills the monitoring thread.

nullMonitor :: MonitorThread

A do-nothing MonitorThread, for use if monitoring is disabled.