# cockpit.js: Metrics

Metrics about the system can be retrieved from several sources using `cockpit.metrics()` metrics channels. The metrics are made available as series data, and can be used with the `cockpit.series()` and `cockpit.grid()` facilities.

## cockpit.metrics()

    metrics = cockpit.metrics(interval, options, cache)

Opens a new metrics channel. The data retrieved will be available in the `metrics.series` series sink, and can be used together with `cockpit.grid()` objects.

The `interval` is in milliseconds, and is the granularity of the series data retrieved. Any grids consuming the data must have the same interval.

The `cache` argument is a cache identifier. If specified, then this metrics channel will share data with other metrics channels of the same identifier. Make sure to use a globally unique string.

The `options` argument is either a javascript plain object, or an array of those. Each object can have the following fields.

`"metrics"`

  An array of full metric descriptions, as javascript objects. The specifics of these, and how to determine which ones to use, can unfortunately only be found in the low-level protocol documentation. This option is required.

`"source"`

  The source to use for real-time data. This is used by the `follow` method, see below. Set to `"internal"` to retrieve internal metrics read by the bridge. If set to `"direct"` or `"pmcd"` then data will be retrieved from PCPif it is available. The default is `"internal"`.

`"archive_source"`

  The source to use for retrieving historical data. This is used by the `fetch` method, see below. Set to `"pcp-archive"` to retrieve data from PCP archives. The default is not to try to retrieve historical data.

When the `options` argument is an array of javascript objects, then the metrics channel tries to use them in order until one succeeds. This way, you can prefer PCP as the source but fall back to internal metrics when PCP is not available, for example. The channel gives no indication which of the options has been used, and `fetch` and `follow` might use different entries from the list.

## metrics.fetch()

    metrics.fetch(beg, end)

Retrieve archived metrics data between `beg` and `end`. The arguments can either be numbers, in which case they are interval based offsets, or they can be javascript Date objects.

## metrics.follow()

    metrics.follow()

Start retrieving live metrics data as it become available.

## metrics.close()

    metrics.close()

Stop the retrieval of metrics and release resources.

## metrics.series

The series sink where data retrieved data will be processed.

## metrics.meta

The metrics meta data last received.

## metrics.onchanged

    metrics.onchanged = function() { }

An event triggered when one of the properties on this metrics object changes.