Usage

Use the metric shortcut to start recording metrics.

from redis_metrics import metric

# Increment the metric by one
metric('new-user-signup')

# Increment the metric by some other number
metric('new-user-signup', 4)

Metrics can also be categorized. To record a metric and add it to a category, specify a category keyword parameter

# Increment the metric, and add it to a category
metric('new-user-signup', category="User Metrics")

Metrics can also expire after a specified number of seconds

# The 'foo' metric will expire in 5 minutes
metric('foo', expire=300)

You can also reset a metric with the set_metric function. This will replace any existing values for the metric, rather than incrementing them. It’s api is similar to metric‘s.

from redis_metrics import set_metric

# Reset the Download count.
set_metric("downloads", 0)

Gauges

There are also gauge‘s. A gauge is great for storing a cumulative value, and when you don’t care about keeping a history for the metric. In other words, a gauge gives you a snapshot of some current value.

from redis_metrics import gauge

# Create a gauge
gauge('total-downloads', 0)

# Update the gauge
gauge('total-downloads', 9999)

The R class

There’s also an R class which is a lightweight wrapper around redis. You can use it directly to set metrics or gauges and to retrieve data.

>>> from redis_metrics.models import R
>>> r = R()
>>> r.metric('new-user-signup')
>>> r.get_metric('new-user-signup')
{
    'second': 0,
    'minute': 0,
    'hour': 1,
    'day': '29',
    'month': '29',
    'week': '29',
    'year': '29'
}

# list the slugs you've used to create metrics
>>> r.metric_slugs()
set(['new-user-signup', 'user-logins'])

# Get metrics for multiple slugs
>>> r.get_metrics(['new-user-signup', 'user-logins'])
[
    {'new-user-signup': {
        'second': '0', 'minute': '0', 'hour': '1',
        'day': '7', 'month': '7', 'week': '7', 'year': '7'}},
    {'user-logins':
        'second': '0', 'minute': '0', 'hour': '1',
        'day': '7', 'month': '7', 'week': '7', 'year': '7'}},
]

# Delete a metric
>>> r.delete_metric("app-errors")

Templatetags

Viewing your data is possible with the built-in views, but these all make use of a number of templatetags to display metric data and history.

  • metrics_since(slugs, years, link_type="detail", granularity=None) Renders a template with a menu to view a metric (or a list of metrics) for a given number of years. For example:

    {% metrics_since "downloads" 5 %}  {# downloads for the last 5 years #}
    
  • gauge(slug, maximum=9000, size=200): Includes a donut chart for the specified gauge. The maximum represents the largest possible value for the gague, while the size is the size of the chart in pixels.:

    {% gauge "tasks-completed" 10 %}
    
  • metric_list generates a list of all metrics.

  • metric_detail(slug, with_data_table=False) displays a metric’s current details. This tag will also generate a table of raw data if the with_data_table option is True.

  • metric_history(slug, granularity="daily", since=None, with_data_table=False) displays a given metric’s history. The granularity option defines the granularity displayed, since is a string or datetime object that specifies how much data to show, and with_data_table controls wether or not raw data is displayed in a table. Examples:

    {% metric_history "signups" "daily" "2015-01-01" %}
    
    {% metric_history "signups" "monthly" this_year %}
    
  • aggregate_detail(slug_list, with_data_table=False) is much like metric_detail, but displayes more than one metric on the chart. The slug_list parameter should be a list of metric slugs that you want to display.

  • aggregate_history(slug_list, granularity="daily", since=None, with_data_table=False) is similarly like metric_history, but for multiple metrics on once chart. but displayes more than one metric on the chart. The slug_list parameter should be a list of metric slugs that you want to display.