<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<refentry id="cockpit-metrics">
  <refnamediv>
    <refname>cockpit.js: Metrics</refname>
    <refpurpose>Reading and streaming metric data</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para>Metrics about the system can be retrieved from several sources using
      <link linkend="cockpit-metrics"><code>cockpit.metrics()</code></link> metrics channels.
      The metrics are made available as series data, and can be used with the
      <link linkend="cockpit-series"><code>cockpit.series()</code></link> and
      <link linkend="cockpit-grid"><code>cockpit.grid()</code></link> facilities.</para>
  </refsynopsisdiv>

  <refsection id="cockpit-metrics-function">
    <title>cockpit.metrics()</title>
<programlisting>
metrics = cockpit.metrics(interval, options, cache)
</programlisting>

    <para>Opens a new metrics channel. The data retrieved will be available in the
      <link linkend="cockpit-metrics-series"><code>metrics.series</code></link> series sink, and can
      be used together with <link linkend="cockpit-grid"><code>cockpit.grid()</code></link> objects.</para>

    <para>The <code>interval</code> is in milliseconds, and is the granularity of the series data
      retrieved. Any grids consuming the data must have the same interval.</para>

    <para>The <code>cache</code> 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.</para>

    <para>The <code>options</code> argument is either a javascript
      plain object, or an array of those.  Each object can have the
      following fields.</para>

    <variablelist>
      <varlistentry>
        <term><code>"metrics"</code></term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"source"</code></term>
        <listitem><para>The source to use for real-time data.  This
          is used by the <code>follow</code> method, see below.  Set
          to <code>"internal"</code> to retrieve internal metrics read
          by the bridge. If set to <code>"direct"</code> or
          <code>"pmcd"</code> then data will be retrieved from <ulink
          url="https://pcp.io">PCP</ulink>if it is available. The
          default is <code>"internal"</code>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><code>"archive_source"</code></term>
        <listitem><para>The source to use for retrieving historical
          data.  This is used by the <code>fetch</code> method, see
          below.  Set to <code>"pcp-archive"</code> to retrieve data
          from PCP archives.  The default is not to try to retrieve
          historical data.</para></listitem>
      </varlistentry>
    </variablelist>

    <para>When the <code>options</code> 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 <code>fetch</code> and
      <code>follow</code> might use different entries from the
      list.</para>
  </refsection>

  <refsection id="cockpit-metrics-fetch">
    <title>metrics.fetch()</title>
<programlisting>
metrics.fetch(beg, end)
</programlisting>

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

  <refsection id="cockpit-metrics-follow">
    <title>metrics.follow()</title>
<programlisting>
metrics.follow()
</programlisting>

    <para>Start retrieving live metrics data as it become available.</para>
  </refsection>

  <refsection id="cockpit-metrics-close">
    <title>metrics.close()</title>
<programlisting>
metrics.close()
</programlisting>

    <para>Stop the retrieval of metrics and release resources.</para>
  </refsection>

  <refsection id="cockpit-metrics-series">
    <title>metrics.series</title>
    <para>The series sink where data retrieved data will be processed.</para>
  </refsection>

  <refsection id="cockpit-metrics-meta">
    <title>metrics.meta</title>
    <para>The metrics meta data last received.</para>
  </refsection>

  <refsection id="cockpit-metrics-onchanged">
    <title>metrics.onchanged</title>
<programlisting>
metrics.onchanged = function() { }
</programlisting>
    <para>An event triggered when one of the properties on this metrics object changes.</para>
  </refsection>

</refentry>
