html5 api

[ doc ]

    - html5 api references

[ frontend ]

    - embed popup

    - hover flyoouts for button bar in sql editor "Refresh, Change View and use CTRL+enter"

FnordMetric HTML5 API Reference

===============================

_The HTML5 API is still a Work In Progress — Pull Requests welcome!_

### Introduction

The FnordMetric UI HTML5 API allows you to plugin real-time data and

charts into any website without having to write code. This is achieved

by including a JavaScript library and using data-* attributes on html

elements to declare the widgets.

The javascript library `fnordmetric-ui.js` is bundled with FnordMetric

Classic and FnordMetric Enterprise, but you can [download a copy here](http://github.com/paulasmuth/fnordmetric/tree/master/fnordmetric-ui) if you want to include it in your project.

charts into any website without having to write any JavaScript code. This is

achieved by including a JavaScript library and using the FnordMetric HTML5

components.

FnordMetric UI requires jQuery 1.6.2+

The JavaScript library `fnordmetric.js` is bundled with FnordMetric Server, to

include it put this line into your HTML file:

    <script src='fnordmetric-ui.js' type='text/javascript'></script>

    <link href='fnordmetric-ui.css' type='text/css' rel='stylesheet' />

    <!-- include fnordmetric.js from fnordmetric-server-host:port -->

    <script src='http://fnordmetric-server-host:port/s/fnordmetric.js' type='text/javascript'></script>

    <!-- example: include fnordmetric.js from localhost:8080 -->

    <script src='http://localhost:8080/s/fnordmetric.js' type='text/javascript'></script>

### Reference: Counters

Counters are span or div elements. They are updated to contain the value of

the gauge at one point in time as plain text. Example:

### Component: \<fm-chart\>

    <span

      data-fnordetric="counter"

      data-gauge="my_gauge"

      data-at="now"

      >0</span>

The `\<fm-chart\>` tag executes a ChartSQL query and displays the result as a chart.

For Example:

If the value of `my_gauge` this element is updated to:

    <fm-chart style="width: 800px;">

      DRAW LINECHART

          AXIS BOTTOM;

    <span data-fnordmetric... >23</span>

      SELECT

          time AS x, value AS y FROM ...;

    </fm-chart>

These are the valid html attributes for counters:

These are the valid html attributes for `\<fm-chart\>` tags:

<table>

  <tr>

    <th>data-fnordmetric <i>(mandatory)</i></th>

    <td>

      must be "counter"

    </td>

  </tr>

  <tr>

    <th>data-gauge <i>(mandatory)</i></th>

    <td>

      name of the gauge to be displayed

    </td>

  </tr>

  <tr>

    <th>data-at</th>

    <td>

      display this value at a certain time, may be a unix timestamp,

      a time definition like `-3hours` (3 hours ago), `-45m` (45m ago)

      or `-3600` (3600 seconds = 1 hour ago).

      <p>You can also get a sum of the last x measurements by setting this to

      e.g. "sum(-3hours)" which will give you the sum of the last three hours.</p>

      <p>You can also get a average of the last x measurements by setting this to

      e.g. "avg(-3hours)" which will give you the average of the last three hours.</p>

      The Default is "now". You can find the <a href="/documentation/enterprise_api_reference"/>full documentation for this time format here</a>

    </td>

  </tr>

  <tr>

    <th>data-scale-by</th>

    <td>

      multiply the value with a constant before displaying it (e.g. if you are reporting data

      as cents, but want to display them as dollar/euro, use `data-scale-by="0.01"`

    </td>

  </tr>

  <tr>

    <th>data-round-to</th>

    <td>

      force rounding this value to the specified precision. e.g. 0 for integer / no floating point and 3 for three digits after the dot/comma.

    </td>

  </tr>

  <tr>

    <th>data-autoupdate</th>

    <td>

      refresh this value every N seconds

    </td>

  </tr>

  <tr>

    <th>data-unit</th>

    <td>

      display the value with a unit (e.g. € or ms)

      refresh the chart every N seconds

    </td>

  </tr>

</table>

<br />

### Reference: Timeseries

Timeseries widgets are div elements. They act as container elements for timeseries

charts. The chart will auto-size itself to the width of the container div, but the

height has to be configured manually (default is 240px):

    <div

      data-fnordetric="timeseries"

      data-gauges="my_gauge"

      data-since="-2hours"

      data-until="now"

      ></div>

These are the valid html attributes:

<table>

  <tr>

    <th>data-fnordmetric <i>(mandatory)</i></th>

    <td>

      must be "timeseries"

    </td>

  </tr>

  <tr>

    <th>data-gauges <i>(mandatory)</i></th>

    <td>

      comma separated list of gauges to be dispalyed (mandatory)

    </td>

  </tr>

  <tr>

    <th>data-since,<br />data-until <i>(mandatory)</i></th>

    <td>

      these attributes specify the time range to be displayed. they may be a

      unix timestamp, a time definition like "-3hours" (3 hours ago), "-45m"

      (45m ago) or "-3600" (3600 seconds = 1 hour ago) or "now". To e.g. display

      the last two hours of data use: data-since="-2hours" data-until="now".

      You can find the <a href="/documentation/enterprise_api_reference"/>full documentation for this time format here</a>

    </td>

  </tr>

  <tr>

    <th>data-colors</th>

    <td>

      comma separated list of series / gauge colors (optional)

    </td>

  </tr>

  <tr>

    <th>data-height</th>

    <td>

    height of the chart (default is 240px)

    </td>

  </tr>

  <tr>

    <th>data-y-max</th>

    <td>

    highest value on the y axis (default is none)

    </td>

  </tr>

  <tr>

    <th>data-chart-style</th>

    <td>

    render style (either line, area or flow), default is "line"

    </td>

  </tr>

  <tr>

    <th>data-legend</th>

    <td>

    display a legend? (values are "on" or "off"), default is "on"

    </td>

  </tr>

  <tr>

    <th>data-cardinal</th>

    <td>

    use cardinal splines (values are "on" or "off"), default is "off"

    </td>

  </tr>

  <tr>

    <th>data-autoupdate</th>

    <td>

      refresh this chart every N seconds, default is no autorefresh

    </td>

  </tr>

</table>

<br />

### Refreshing / Resizing

FnordMetric UI offers two JavaScript methods: `refresh` and `resize`.

**FnordMetric#refresh**

You are allowed manipulate the data-* attributes at runtime. You could use this to build

e.g. a custom date picker. After changing the data-* attributes, you should tell FnordMetric

to refresh this widget.

Example: Refresh element "my_graph"

    FnordMetric.refresh($("#my_graph"));

**FnordMetric#resize**

Resizes all widgets but does not redraw (you can use this to build responsive layouts)

Example: Resize all widgets

    FnordMetric.resize();

### JavaScript API

FnordMetric UI provides a JavaScript API to retrieve metric values.

**FnordMetric#value_at(metrics, time, callback)**

Retrieves the measured value of a metric at a specific point in time. [See here](/documentation/enterprise_api_reference)

for more information about the time format.

    >> FnordMetric.value_at(["response_time-mean-30"], "now", function(){ console.log(this); })

    << {value: 2122.55581}

**FnordMetric#values_in(metrics, since, until, callback)**

Retrieves all measured values of a metric in a specific time interval. [See here](/documentation/enterprise_api_reference)

for more information about the time format.

    >> FnordMetric.values_in(["response_time-mean-30"], "-2h", "now", function(){ console.log(this); })

    << { "response_time-mean-30": {1363188688: "2036.83876", 1363188718: "2049.7485", 1363188748: "2283.37632"} }