.. _statistics_and_graphing:

Statistics and Graphing
=======================

Eww supports two statistic primitives:

* Counters
* Graphs

We'll cover each one separately.

Counters
--------

Counters provide simple integer storage.  You don't need to define or declare a counter, just call one of the methods provided by Eww and the correct thing will happen.

They can be manipulated with three different methods::

    eww.incr('foo')  # Increments counter 'foo' by 1
    eww.incr('foo', 2)  # Increments 'foo' by 2

    eww.put('foo', 5)  # Sets 'foo' to 5, ignoring any previous value

    eww.decr('foo')  # Decrements 'foo' by 1
    eww.decr('foo', 2)  # Decrements 'foo' by 2

Graphs
------

Like counters, graphs do not need to be defined or declared.  Just start using them::

    eww.graph('foo', (0, 0))
    eww.graph('foo', (1, 5))
    eww.graph('foo', (2, 10))

The passed points should be a tuple, and are interpreted as X, Y coordinates.

Accessing Stats
---------------

Stats are accessed by connecting to the Eww console and using the `stats` command::

    (eww) stats
    Counters:
      bar:1
    Graphs:
      foo:1
    (eww)

The counters section is formatted as :code:`<name>:<value>`.  Graphs are formatted as :code:`<name>:<number of points>`.

SVG graphs of Graph data can be generated by running :code:`stats -g foo`.

Additional usage details for the :code:`stats` command can be found by running :code:`help stats`.

Limits
------

By default, Eww will only store the 500 most recent graph datapoints.  This is to prevent the memory usage of busy applications from ballooning.  You can change this limit when embedding Eww like so::

    eww.embed(max_datapoints=1000)

``max_datapoints`` is a per-name limit.  That is, if ``max_datapoints`` is 1000, then each unique graph name can have up to 1000 entries.