Skip to content
Python Shell Makefile
Latest commit 930f02c @drio drio Merge pull request #110 from librato/chore/new_release_0.8.6
Update changelog and others.


Build Status

A Python wrapper for the Librato Metrics API.


In your shell:

$ easy_install librato-metrics


$ pip install librato-metrics

From your application or script:

import librato


We first use our credentials to connect to the API. I am assuming you have a librato account for Metrics. Go to your account settings page and save your username (email address) and token (long hexadecimal string).

  api = librato.connect(user, token)

When creating your connection you may choose to provide a sanitization function. This will be applied to any metric name you pass in. For example we provide a sanitization function that will ensure your metrics are legal librato names. This can be set as such

  api = librato.connect(user, token, sanitizer=librato.sanitize_metric_name)

By default no sanitization is done.

Basic Usage

To iterate over your metrics:

  for m in api.list_metrics():

or use list_all_metrics() to iterate over all your metrics with transparent pagination.

Let's now create a Metric:

  api.submit("temperature", 10, description="temperature at home")

By default submit() will create a gauge metric. The metric will be created automatically by the server if it does not exist. We can remove it:


For creating a counter metric, we can:

  api.submit("connections", 20, type='counter', description="server connections")

And again to remove:


To iterate over your metrics:

  for m in api.list_metrics():
    print "%s: %s" % (, m.description)

To retrieve a specific metric:

  gauge   = api.get("temperature")
  counter = api.get("connections")

To retrieve a composite metric:

  # Get average temperature in all cities for last 8 hours
  compose = 'mean(s("temperature", "*", {function: "mean", period: "3600"}))'
  start_time = int(time.time()) - 8 * 3600
  resp = api.get_composite(compose, start_time=start_time)
  # [
  #   {u'measure_time': 1421744400, u'value': 41.23944444444444},
  #   {u'measure_time': 1421748000, u'value': 40.07611111111111},
  #   {u'measure_time': 1421751600, u'value': 38.77444444444445},
  #   {u'measure_time': 1421755200, u'value': 38.05833333333333},
  #   {u'measure_time': 1421758800, u'value': 37.983333333333334},
  #   {u'measure_time': 1421762400, u'value': 38.93333333333333},
  #   {u'measure_time': 1421766000, u'value': 40.556666666666665}
  # ]

For sending more measurements:

  for temp in [20, 21, 22]:
    api.submit('temperature', temp)
  for num_con in [100, 200, 300]:
    api.submit('connections', num_con, type='counter')

To create a composite metric:

  api.create_composite('humidity', 'sum(s("all.*", "*"))', description="a test composite")

Let's now iterate over the measurements of our Metrics:

  metric = api.get("temperature", count=100, resolution=1)
  for m in metric.measurements['unassigned']:
    print "%s: %s" % (m['value'], m['measure_time'])

Notice a couple of things here. First, we are using the key unassigned since we have not associated our measurements to any source. Read more about it in the API documentation. In addition, notice how we are passing the count and resolution parameters to make sure the API returns measurements in its answer and not only the metric properties. Read more about them here.

Sending measurements in batch mode

Sending a measurement in a single HTTP request is inefficient. The overhead both at protocol and backend level is very high. That's why we provide an alternative method to submit your measurements. The idea is to send measurements in batch mode. We push measurements that are stored and when we are ready, they will be submitted in an efficient manner. Here is an example:

api = librato.connect(user, token)
q   = api.new_queue()
q.add('temperature', 22.1, source='upstairs')
q.add('temperature', 23.1, source='dowstairs')
q.add('num_requests', 100, type='counter', source='server1')
q.add('num_requests', 102, type='counter', source='server2')

Queues can also be used as context managers. Once the context block is complete the queue is submitted automatically. This is true even if an exception interrupts flow. In the example below if potentially_dangerous_operation causes an exception the queue will submit the first measurement as it was the only one successfully added. If the operation succeeds both measurements will be submitted.

api = librato.connect(user, token)
with api.new_queue() as q:
    q.add('temperature', 22.1, source='upstairs')
    q.add('num_requests', 100, type='counter', source='server1')

Queues by default will collect metrics until they are told to submit. You may create a queue that autosubmits based on metric volume.

api = librato.connect(user, token)
# Submit when the 400th metric is queued
q = api.new_queue(auto_submit_count=400)

Client-side Aggregation

You can aggregate measurements before submission using the Aggregator class. Optionally, specify a measure_time to submit that timestamp to the API. You may also optionally specify a period to floor the timestamp to a particular interval. If period is specified without a measure_time, the current timestamp will be used, and floored to period. Specifying an optional source allows the aggregated measurement to report a source name.

Aggregator instances can be sent immediately by calling submit() or added to a Queue by calling queue.add_aggregator().

from librato.aggregator import Aggregator

api = librato.connect(email, token)

a = Aggregator(api)
a.add("foo", 42)
a.add("foo", 5)
# count=2, min=5, max=42, sum=47 (value calculated by API = mean = 23.5), source=unassigned

a = Aggregator(api, source='my.source', period=60)
a.add("foo", 42)
a.add("foo", 5)
# count=2, min=5, max=42, sum=47 (value calculated by API = mean = 23.5), source=my.source
# measure_time = <now> - (<now> % 60)

a = Aggregator(api, period=60, measure_time=1419302671)
a.add("foo", 42)
a.add("foo", 5)
# count=2, min=5, max=42, sum=47 (value calculated by API = mean = 23.5), source=unassigned
# measure_time = <now> - (<now> % 60) = 1419302640

a = Aggregator(api, measure_time=1419302671)
a.add("foo", 42)
a.add("foo", 5)
# count=2, min=5, max=42, sum=47 (value calculated by API = mean = 23.5), source=unassigned
# measure_time = 1419302671

# You can also add an Aggregator instance to a queue
q = librato.queue.Queue(api)

Updating Metrics

You can update the information for a metric by using the update method, for example:

api = librato.connect(user, token)
for metric in api.list_metrics():
  gauge = api.get(
  attrs = gauge.attributes
  attrs['display_units_long'] = 'ms'
  api.update(, attributes=attrs)


List Annotation all annotation streams:

for stream in api.list_annotation_streams
print "%s:%s" % (,stream.display_name)

View the metadata on a named annotation stream:

print stream

Retrieve all of the events inside a named annotation stream, by adding a start_time parameter to the get_annotation_stream() call:

for source in
    print source[source]
    for event in events:
        print event['id']
        print event['title']
        print event['description']

Submit a new annotation to a named annotation stream (creates the stream if it doesn't exist). Title is a required parameter, and all other parameters are optional


api.post_annotation("TravisCI",title="build %s"%travisBuildID,
                     description="Application %s, Travis build %s"%(appName,travisBuildID),
                     links=[{'rel': 'travis', 'href': ''}])

Delete a named annotation stream:



List all alerts:

for alert in api.list_alerts():

Create alerts with an above condition:

alert = api.create_alert(name)
alert.add_condition_for('metric_name').above(1) # immediately
alert.add_condition_for('metric_name').above(1).duration(60) # duration of the threshold to trigger the alert
alert.add_condition_for('metric_name').above(1, 'sum') # custom summary function

Create alerts with a below condition:

alert.add_condition_for('metric_name').below(1) # the same syntax from above conditions

Create alerts with an absent condition:

alert.add_condition_for('metric_name').stops_reporting_for(1) # duration of the threshold to trigger the alert



Timeouts are provided by the underlying http client. By default we timeout at 10 seconds. You can change that by using api.set_timeout(timeout).


Do you want to contribute? Do you need a new feature? Please open a ticket.


The original version of python-librato was conceived/authored/released by Chris Moyer (AKA @kopertop). He's graciously handed over maintainership of the project to us and we're super-appreciative of his efforts.

Thanks also to @Bachmann1234 for continually improving this library.


Copyright (c) 2011-2014 Librato Inc. See LICENSE for details.

Something went wrong with that request. Please try again.