NAV
cURL Ruby Python

Introduction

API Libraries

There are many collection agents and language bindings for Librato. This guide covers documentation for the Ruby and Python libraries.

Quick Start

This example covers submitting and retrieving measurements from a specific metric. View the Metrics section for more information on metric measurements and metadata.

How to submit a measurement for the gauge metric cpu_temp:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'gauges[0][name]=cpu_temp' \
  -d 'gauges[0][value]=75' \
  -d 'gauges[0][source]=us-west' \
  -X POST \
  https://metrics-api.librato.com/v1/metrics
require "librato/metrics"
Librato::Metrics.authenticate ENV['LIBRATO_USERNAME'], ENV['LIBRATO_TOKEN']
Librato::Metrics.submit cpu_temp: {source: 'us-west', value: 75}
import librato
api = librato.connect(<user>, <token>)
api.submit("cpu_temp", 75, source='us-west')

How to retrieve the last 4 measurements from the metric cpu_temp at a resolution of 60 seconds. This will return measurement data along with metric’s metadata.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/cpu_temp?count=4&resolution=60'
require "librato/metrics"
Librato::Metrics.authenticate ENV['LIBRATO_USERNAME'], ENV['LIBRATO_TOKEN']
metric = Librato::Metrics.get_metric :cpu_temp, count: 4, resolution: 60
puts metric["measurements"]
import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu_temp", count=4, resolution=60)
print(metric.measurements)

Welcome to the official reference for Librato’s Application Programming Interface (API).

Librato is committed to enabling our user community to manage their services configurations through first-class REST APIs. Librato’s own clients (web, command line, etc) are built upon these APIs.

Detailed documentation for authentication and each individual API call can be accessed through the menu. We invite suggestions, feature requests or problem reports at our support forum.

Authentication

A user with an email address example@librato.com and an API token of 75AFDB82 will use the following command:

curl -u example@librato.com:75AFDB82 https://metrics-api.librato.com/v1/metrics
require "librato/metrics"
Librato::Metrics.authenticate example@librato.com, 75AFDB82
import librato
api = librato.connect('email', 'token')

Or you may include the credentials in the URL (see the note about URL Encoding below):

curl https://example%40librato.com:75AFDB82@metrics-api.librato.com/v1/metrics

Note: API Tokens have been shortened for the purposes of this documentation. Your real API token will be longer.

The API requires HTTP basic authentication for every request. All requests must be sent over HTTPS.

Authentication is accomplished with a user and token pair. User is the email address that you used to create your Librato Metrics account and token is the API token that can be found on your account page.

URL Encoding

To use URL encoding, use the following format:

https://user:token@metrics-api.librato.com/v1/metrics

Because the user value is an email address, it has to be escaped in order to form a valid URL. The @ sign is represented by the %40 entity. For example:

https://example%40librato.com:apitoken@metrics-api.librato.com/v1/metrics

Note: cURL automatically converts the @ to a %40 if you use the -u option, but not if you put authentication in the URL directly.

You can also include your user and token credentials in the URL with most clients.

Response Codes & Errors

HTTP Status Codes

The Librato API returns one of the following status codes for every request.

Error Code Meaning Definition
200 OK The request was processed successfully and the information is returned in the body in the desired format. This code gets returned after GET requests or PUT requests (if the PUT resulted in data being generated and returned). In case of a search (e.g. for metrics) without search results, a 200 still gets returned.
201 Created The request was processed successfully. The resource was created and the Location variable in the header points to the resource. This code gets returned after POST requests only.
204 No Content The request was processed successfully. Since this code gets returned after PUT or DELETE requests only, there is no need for returning information in the response body.
400 Bad Request The request could not be parsed or the parameters were not valid. The request should be modified before resubmitting.
401 Unauthorized Challenges the user to provide authentication credentials.
403 Forbidden The request was not encrypted via SSL or the account is rate limited.
404 Not Found The request refers to a resource that either does not exist or the user does not have permissions to access (due to security through obscurity). If a search request gets sent, it will however not return a 404 if the API did not find resources matching the search query.
415 Incorrect Content-Type Content type was not application/json.
422 Entity Already Exists An attempt was made to create a new entity that matched an existing one. The request should be modified to use unique parameters (e.g., a different container name) or a PUT request should be made instead to modify the existing entity.
429 Rate Limited Request was rate limited (it’s possible some data was permitted, need to verify response body).

If creating a measurement, this error returns when it can not parse the basic format of the payload to identify measurements.
503 Service Unavailable In the rare occasion that we must put the API into maintenance mode for a service upgrade, the API can return a 503 error code. The API should be available again shortly so it is advised that you resubmit your request later.

Error Messages

Example of a request type error message.

{
  "errors": {
    "request": [
      "Please use secured connection through https!",
      "Please provide credentials for authentication."
    ]
  }
}

The API reports errors in a JSON format which makes it easier to parse and evaluate them.

Error Message Structure

There are three types of errors: params, request, and system.

Type Description
params Errors related to parameters are reported based on the attribute the error occurred on.
requests Errors related to the request itself are reported in an array structure with the key request.
system Service errors due to maintenance periods, for example, are reported in an array structure with the key system.

Metrics

Metrics are custom measurements stored in Librato’s Metrics service. These measurements are created and may be accessed programmatically through a set of RESTful API calls. There are currently two types of metrics that may be stored in Librato Metrics, gauges and counters.

Gauges

Gauges capture a series of measurements where each measurement represents the value under observation at one point in time. The value of a gauge typically varies between some known minimum and maximum. Examples of gauge measurements include the requests/second serviced by an application, the amount of available disk space, the current value of $AAPL, etc.

Counters

Counters track an increasing number of occurrences of some event. A counter is unbounded and always monotonically increasing in any given run. A new run is started anytime that counter is reset to zero. Examples of counter measurements include the number of connections made to an app, the number of visitors to a website, the number of a times a write operation failed, etc.

Metric Properties

Some common properties are supported across all types of metrics:

Property Definition
name Each metric has a name that is unique to its class of metrics e.g. a gauge name must be unique among gauges. The name identifies a metric in subsequent API calls to store/query individual measurements and can be up to 255 characters in length. Valid characters for metric names are A-Za-z0-9.:-_. The metric namespace is case insensitive.
period The period of a metric is an integer value that describes (in seconds) the standard reporting period of the metric. Setting the period enables Metrics to detect abnormal interruptions in reporting and aids in analytics.
description The description of a metric is a string and may contain spaces. The description can be used to explain precisely what a metric is measuring, but is not required. This attribute is not currently exposed in the Librato UI.
display_name More descriptive name of the metric which will be used in views on the Metrics website. Allows more characters than the metric name, including spaces, parentheses, colons and more.
attributes The attributes hash configures specific components of a metric’s visualization.
source_lag This property sets a “look back” further in the data stream when rendering a composite metric for the purposes of alerting. The default is 120, meaning we look back 2 minutes when rendering, which should normally be enough time for the appropriate sources to have reported their data.

Measurement Properties

Each individual metric corresponds to a series of individual measurements. Some common properties are supported across all measurements.

Property Definition
measure_time The epoch time at which an individual measurement occurred with a maximum resolution of seconds.
value The numeric value of an individual measurement. Multiple formats are supported (e.g. integer, floating point, etc) but the value must be numeric.
source Source is an optional property that can be used to subdivide a common gauge/counter among multiple members of a population. For example the number of requests/second serviced by an application could be broken up among a group of server instances in a scale-out tier by setting the hostname as the value of source.

Source names can be up to 255 characters in length and must be composed of the characters A-Za-z0-9.:-_. The word all is a reserved word and cannot be used as a user source. The source namespace is case insensitive.

Measurement Restrictions

Internally all floating point values are stored in double-precision format. However, Librato Metrics places the following restrictions on very large or very small floating point exponents:

Create a Metric

How to create 3 new measurements: Two counter measurements (conn_servers and write_fails) and one gauge measurement (cpu_temp).

The gauge measurement specifies an explicit measure_time and source that overrides the global ones while the counter measurements default to the global measure_time and source.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'measure_time=1234567950' \
  -d 'source=prod-us-west' \
  -d 'counters[0][name]=conn_servers' \
  -d 'counters[0][value]=5' \
  -d 'counters[1][name]=write_fails' \
  -d 'counters[1][value]=3' \
  -d 'gauges[0][name]=cpu_temp' \
  -d 'gauges[0][value]=88.4' \
  -d 'gauges[0][source]=prod-us-east' \
  -d 'gauges[0][measure_time]=1234567949' \
  -X POST \
  https://metrics-api.librato.com/v1/metrics
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
queue = Librato::Metrics::Queue.new
queue.add :conn_servers => {:type => :counter, :measure_time => 1234567950, :value => 5}
queue.add :write_fails => {:type => :counter, :measure_time => 1234567950, :value => 3}
queue.add :cpu_temp => {:measure_time => 1234567949, :value => 88.4}
queue.submit
import librato
api = librato.connect(<user>, <token>)
q  = api.new_queue()
q.add('conn_servers', 5, type='counter', source='prod-us-west')
q.add('write_fails', 3, type='counter', source='prod-us-west')
q.add('cpu_temp', 88.4, type='gauge', source='prod-us-east')
q.submit()

Response Code:

200 Success

HTTP Request

POST https://metrics-api.librato.com/v1/metrics

This action allows you to create metrics and submit measurements for new or existing metrics. You can submit measurements for multiple metrics in a single request.

For each counter and gauge measurement in the request, a new measurement is created and associated with the appropriate metric. If any of the metrics in the submitted set do not currently exist, they will be created.

For truly large numbers of measurements (e.g. 20 metrics x 500 sources) we suggest batching into multiple concurrent requests. Currently a POST with ~300 distinct measurements takes roughly 600ms, so we recommend this as an initial guideline for a cap on request size. As we continue to tune the system this suggested cap will be updated.

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Measurement Parameters

The request must include at least one gauge or counter measurement. It may include multiple counter or gauge measurements or a combination of multiple measurement types.

Gauge measurements are collated under the top-level parameter gauges. Similarly, counter measurements are collated under the top-level parameter key counters. Each measurement is a hash of measurement parameters as described below:

Parameter Definition
name The unique identifying name of the property being tracked. The metric name is used both to create new measurements and query existing measurements. Must be 255 or fewer characters, and may only consist of ‘A-Za-z0-9.:-_’. Depending on the submission format the location of the name parameter may vary, see examples below in “Measurement Formats”. The metric namespace is case insensitive.
value The numeric value of a single measured sample.
measure_time
optional
The integer value of the unix timestamp of the measurement. If not specified will default to time the measurement is received.
source
optional
A string which describes the originating source of a measurement when that measurement is tracked across multiple members of a population. Examples: foo.bar.com, user-123, 77025.

Sources must be composed of 'A-Za-z0-9.:-’ and can be up to 255 characters in length. The word all is reserved and cannot be used as user source. The source namespace is case insensitive.

source and measure_time can also be specified as a parameters outside of the gauges and counters measurement hashes. In this case the given source and measure_time values will be applied to all values submitted unless those measurements have another source or `measure
time` specified in their sub-hashes.

NOTE: The optional parameters listed in the metrics PUT operation can be used with POST operations, but they will be ignored if the metric already exists. To update existing metrics, please use the PUT operation.

Gauge Specific Parameters

Gauges support an optional, more complex parameter set which you can use to report multi-sample measurements:

Parameter Definition
count Indicates the request corresponds to a multi-sample measurement. This is useful if measurements are taken very frequently in a closed loop and the metric value is only periodically reported. If count is set, then sum must also be set in order to calculate an average value for the recorded metric measurement. Additionally min, max, and sum_squares may also be set when count is set. The value parameter should not be set if count is set.
sum If count was set, sum must be set to the summation of the individual measurements. The combination of count and sum are used to calculate an average value for the recorded metric measurement.
max If count was set, max can be used to report the largest individual measurement among the averaged set.
min If count was set, min can be used to report the smallest individual measurement among the averaged set.
sum_squares If count was set, sum_squares report the summation of the squared individual measurements. If sum_squares is set, a standard deviation can be calculated for the recorded metric measurement.

Measurement Formats

The individual gauge and counter measurements can be specified in one of several formats:

Hashed by Name

The JSON payload below creates a gauge measurement for the gauge login-delay with a value 3.5:

{
  "gauges": {
    "login-delay": {
      "value": 3.5,
      "source": "foo.bar.com"
    }
  }
}

Each metric name is a hash to the measurement values.

Multiple measurements with the same name

How to create two measurements for the gauge login-delay: one with the source foo1.bar.com and a second with foo2.bar.com:

{
  "gauges": {
    "0": {
      "name": "login-delay",
      "value": 3.5,
      "source": "foo1.bar.com"
    },
    "1": {
      "name": "login-delay",
      "value": 2.6,
      "source": "foo2.bar.com"
    }
  }
}

If you would like to specify two measurements for the same gauge (maybe to specify two different sources), you can specify a name parameter within the measurement that overrides the hash key name.

Array format (JSON only)

The following JSON payload will create the same measurements as the previous example:

{
  "gauges": [
    {
      "name": "login-delay",
      "value": 3.5,
      "source": "foo1.bar.com"
    },
    {
      "name": "login-delay",
      "value": 2.6,
      "source": "foo2.bar.com"
    }
  ]
}

If the submission Content-Type is JSON, you can also specify the measurement parameters in an array format. This is only supported in JSON formats since the URL-encoded-form content type does not support an array format.

Retrieve a Metric

The Librato API lets you search for metric metadata and measurements within the system. For example, you could query a list of all available metrics in the system or those matching a specific naming pattern. When retrieving the measurements of a specific metric you can specify a specific time range or limit the amount of data points returned.

Metric Measurement Queries

Retrieve all metrics containing request in the metric name:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics?name=request'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.metrics name:'request'
import librato
api = librato.connect(<user>, <token>)
api.list_metrics(name="request")

Response (when one of the two metrics measure requests):

{
  "query": {
    "found": 1,
    "length": 1,
    "offset": 0,
    "total": 2
  },
  "metrics": [
    {
      "name": "app_requests",
      "display_name": "app_requests",
      "description": "HTTP requests serviced by the app per-minute",
      "period": 60,
      "type": "counter",
      "attributes": {
        "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
        "display_max": null,
        "display_min": 0,
        "display_stacked": true,
        "display_transform": null,
        "display_units_long": "Requests",
        "display_units_short": "reqs"
      }
    }
  ]
}

In order to retrieve measurements from a specific metric, include the name parameter along with the metric name you wish to view measurement data from.

https://metrics-api.librato.com/v1/metrics?name=metric_name

Retrieve a Metric by Name

How to retrieve the metadata for the metric cpu_temp:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/cpu_temp'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_metric :cpu_temp
import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu_temp")
print(metric.attributes)

Response Body:

{
  "name": "cpu_temp",
  "display_name": "cpu_temp",
  "description": "Current CPU temperature in Fahrenheit",
  "period": 60,
  "type": "gauge",
  "attributes": {
    "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
    "display_max": null,
    "display_min": 0,
    "display_stacked": true,
    "display_transform": null,
    "display_units_long": "Fahrenheit",
    "display_units_short": "°F"
  }
}

How to return the metric cpu_temp with up to four measurements at resolution 60:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/cpu_temp?count=4&resolution=60'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_metric :cpu_temp, count: 4, resolution: 60
import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu_temp", count=4, resolution=60)
print(metric.measurements)

Response Body:

{
  "resolution": 60,
  "measurements": {
    "server1.acme.com": [
      {
        "measure_time": 1234567890,
        "value": 84.5,
        "count": 1
      },
      {
        "measure_time": 1234567950,
        "value": 86.7,
        "count": 1
      },
      {
        "measure_time": 1234568010,
        "value": 84.6,
        "count": 1
      },
      {
        "measure_time": 1234568070,
        "value": 89.7,
        "count": 1
      }
    ]
  },
  "name": "cpu_temp",
  "display_name": "cpu_temp",
  "description": "Current CPU temperature in Fahrenheit",
  "period": 60,
  "type": "gauge",
  "attributes": {
    "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
    "display_max": null,
    "display_min": 0,
    "display_stacked": true,
    "display_transform": null,
    "display_units_long": "Fahrenheit",
    "display_units_short": "°F"
  }
}

Returns information for a specific metric. If time interval search parameters are specified will also include a set of metric measurements for the given time span.

HTTP Request

GET https://metrics-api.librato.com/v1/metrics/:name

Measurement Search Parameters

How to return the metric cpu_temp with measurements from the source server*:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/cpu_temp?source=server*&count=4&resolution=60'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_metric :cpu_temp, source: :server, count: 4, resolution:60
import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu_temp", source="server*", count=4, resolution=60)
print(metric.measurements)

Response Body:

{
  "resolution": 60,
  "measurements": {
    "server1.acme.com": [
      {
        "measure_time": 1234567890,
        "value": 84.5,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 86.7,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 84.6,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 89.7,
        "count": 1
      }
    ],
    "server2.acme.com": [
      {
        "measure_time": 1234567890,
        "value": 94.5,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 96.7,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 94.6,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 99.7,
        "count": 1
      }
    ]
  },
  "name": "cpu_temp",
  "display_name": "cpu_temp",
  "description": "Current CPU temperature in Fahrenheit",
  "period": 60,
  "type": "gauge",
  "attributes": {
    "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
    "display_max": null,
    "display_min": 0,
    "display_stacked": true,
    "display_transform": null,
    "display_units_long": "Fahrenheit",
    "display_units_short": "°F"
  }
}

Return the metric cpu_temp with measurements from an array of sources, including server1.acme.com or server2.acme.com:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/cpu_temp?sources%5B%5D=server1.acme.com&sources%5B%5D=server2.acme.com&count=4&resolution=60'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_metric :cpu_temp, sources: ['server1.acme.com', 'server2.acme.com'], count: 4, resolution: 60
import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu_temp", sources=['server1.acme.com', 'server2.acme.com'], count=4, resolution=60)
print(metric.measurements)

Response Body:

{
  "resolution": 60,
  "measurements": {
    "server1.acme.com": [
      {
        "measure_time": 1234567890,
        "value": 84.5,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 86.7,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 84.6,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 89.7,
        "count": 1
      }
    ],
    "server2.acme.com": [
      {
        "measure_time": 1234567890,
        "value": 94.5,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 96.7,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 94.6,
        "count": 1
      },
      {
        "measure_time": 1234567890,
        "value": 99.7,
        "count": 1
      }
    ]
  },
  "name": "cpu_temp",
  "display_name": "cpu_temp",
  "description": "Current CPU temperature in Fahrenheit",
  "period": 60,
  "type": "gauge",
  "attributes": {
    "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
    "display_max": null,
    "display_min": 0,
    "display_stacked": true,
    "display_transform": null,
    "display_units_long": "Fahrenheit",
    "display_units_short": "°F"
  }
}

If optional time interval search parameters are specified, the response includes the set of metric measurements covered by the time interval. Measurements are listed by their originating source name if one was specified when the measurement was created. All measurements that were created without an explicit source name are listed with the source name unassigned.

Search Parameter Definition
source If source is specified, the response is limited to measurements from the given source name or pattern.
sources If sources is specified, the response is limited to measurements from those sources. The sources parameter should be specified as an array of source names. The response is limited to the set of sources specified in the array.
summarize_time If summarize_time is specified, then the individual measurements over the covered time period will be aggregated into a single summarized record for each source. In this case, the measurements array for each source will contain a single summarized record.

The measure_time in each of the summarized measurements will be set to the first measure_time in the period covered by the time interval search parameters.

If the metric is a counter, then the summarized record will be a gauge that represents the summarization of the deltas of the counter values for each source.
summarize_sources If summarize_sources is specified, a source name all is included in the list of measurements. This special source name will include all measurements summarized across all the sources for each point in time. For each unique point in time within the covered time interval search, there will be a single record in the all measurements list.

If multiple sources published a measurement at the same time, the record in the all list will be a summarized record of all the individual source measurements at that point in time. If combined with the summarize_time parameter, then the all list will be summarized across sources and across time, implying it will be a list with a single record.

If the metric is a counter, then the summarized record will be a gauge that represents the summarization of the deltas of the counter values for each source.
breakout_sources When summarize_sources is specified with multiple sources (and the all series is generated) by default the individual source series are also included in the response. Setting breakout_sources to false will reduce the response to only the all series. This reduces resource consumption when the individual series are not needed.
group_by When querying a gauge and specifying multiple sources with the sources parameter the group_by parameter optionally specifies a statistical function used to generate an aggregated time series across sources identified in the response with the special source name all. The acceptable values for group_by are: min, max, mean, sum, count.

Each entry in the all series contains a set of summary statistics, each of which represents the result of applying the group_by function across that summary statistic in the corresponding entry in each the individual sources. For example when group_by is set to max, each entry in the all series specifies the minimum of the maximums as min, the maximum of the maximums as max, the maximum of the sums as sum, etc.

Regardless of the function specified for group_by each entry in all also includes a field named summarized that communicates how many individual source series were grouped at that point in time and a field named count that contains the total number of samples aggregated across all sources at that point in time.

Setting the group_by option implies both summarize_sources=true (required) and breakout_sources=false (can be optionally overridden).

Composite Metric Queries

Execute a composite query to derive the idle collectd CPU time for a given host:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics?compose=derive(s("collectd.cpu.*.idle","boatman*45"))&start_time=1432931007&resolution=60'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_composite 'derive(s("collectd.cpu.*.idle","boatman*45"))', start_time: Time.now.to_i - 60*60, resolution: 60
import librato
api = librato.connect(<user>, <token>)
compose = 'derive(s("collectd.cpu.*.idle", "boatman*45", {period: "60"}))'
import time
start_time = 1432931007
resp = api.get_composite(compose, start_time=start_time)
resp['measurements'][0]['series']

Response (the result of the derive() function over the idle CPU time):

{
  "compose": "derive(s(\"collectd.cpu.*.idle\",\"boatman*19\"))",
  "measurements": [
    {
      "metric": {
        "attributes": {
          "aggregate": false,
          "created_by_ua": "Collectd-Librato.py/0.0.8 (Linux; x86_64) Python-Urllib2/2.7",
          "display_max": null,
          "display_min": null,
          "display_stacked": true,
          "display_transform": null,
          "display_units_long": "Units",
          "gap_detection": true
        },
        "description": null,
        "display_name": null,
        "name": "collectd.cpu.0.cpu.idle",
        "period": 60,
        "type": "counter"
      },
      "period": 60,
      "query": {
        "metric": "collectd.cpu.*.idle",
        "source": "boatman*19"
      },
      "series": [
        {
          "measure_time": 1395802200,
          "value": 5831.0
        },
        {
          "measure_time": 1395802620,
          "value": 5748.0
        }
      ],
      "source": {
        "display_name": null,
        "name": "boatman-stg_19"
      }
    }
  ],
  "resolution": 60
}

This route will also execute a composite metric query string when the following parameter is specified. Metric pagination is not performed when executing a composite metric query.

Parameter Definition
compose A composite metric query string to execute. If this parameter is specified it must be accompanied by time interval parameters.

NOTE: start_time and resolution are required. The end_time parameter is optional. The count parameter is currently ignored. When specified, the response is a composite metric query response.

Time Intervals

Librato tracks and stores several different types of measurements as time-series data. Each measurement corresponds to a particular point in time. Queries are typically made to request the values over some time interval that is a subset of the entire series e.g. the last hour, last Monday, etc. The search parameters described below may be used in different combinations to specify a time interval when making queries against metrics.

Time Interval Parameters

If an explicit interval (i.e. start_time to end_time) is specified, the response contains all measurements that fall within the interval. In this scenario the parameter start_time must be set, while end_time may be set or left to default to the current time.

An interval can also be implicitly specified through a count parameter. If count is set to N alongside with either (but not both) start_time or end_time, the response covers the time interval that covers N measurements. The value of end_time always defaults to the current time, so a request for the last N measurements only requires the count parameter set to N.

Request Parameter Definition
start_time The unix timestamp indicating the start time of the desired interval.
end_time The unix timestamp indicating the end time of the desired interval. If left unspecified it defaults to the current time.
count The number of measurements desired. When specified as N in conjunction with start_time, the response contains the first N measurements after start_time. When specified as N in conjunction with end_time, the response contains the last N measurements before end_time.
resolution A resolution for the response as measured in seconds. If the original measurements were reported at a higher resolution than specified in the request, the response contains averaged measurements.

Pagination

Return the metric librato.cpu.percent.idle with the start_time of 1303252025 (unix time):

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/librato.cpu.percent.idle?resolution=60&start_time=1303252025'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_metric :librato.cpu.percent.idle, start_time: 1303252025, resolution: 60
import librato
api = librato.connect(<user>, <token>)
metric = api.get("librato.cpu.percent.idle", start_time="1303252025", resolution=60)
print(metric.measurements)

If the response includes the following query section with next_time it implies there are more points and that start_time should be set to 1305562061 to retrieve the next matching elements.

"query" : {
    "next_time" : 1305562061
}

Note: In order to receive a next_time value, ensure you aren’t including a count value in your request.

If a request does not include an explicit count and the matched data range includes more points than the maximum return size, then the response will include a pagination hint. In this case the response will include a parameter next_time in the query top-level response section. The next_time will be set to the epoch second start time of the next matching element of the original request. This hint serves two purposes:

1) It indicates there are more matching elements, but that the original request was truncated due to the response limit, and

2) It provides the start_time value that should be used in a subsequent request. If the original request is resubmitted with the start_time set to the returned next_time the response will include the next set of matching elements in the set. It may require multiple requests to page through the entire set if the number of matching elements is large.

Request Parameters

The response is paginated, so the request supports our generic Pagination Parameters. Specific to metrics, the default and only permissible value of the orderby pagination parameter is name.

Parameter Definition
name A search parameter that limits the results to metrics whose names contain a matching substring. The search is not case-sensitive.

Update a Metric

HTTP Request

PUT https://metrics-api.librato.com/v1/metrics

Set the period and display_min for metrics cpu, servers and reqs:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names=cpu&names=servers&names=reqs&period=60&display_min=0' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metrics names: ["cpu", "servers", "reqs"], period: 60, display_min: 0
import librato
api = librato.connect(<user>, <token>)
for name in ['cpu', 'servers', 'reqs']:
  gauge = api.get(name)
  attrs['period'] = '60'
  attrs['display_min'] = '0'
  api.update(name, attributes=attrs)

Set the display_units_short for all metrics that end with .time:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names=*.time&display_units_short=ms' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metrics names: ["*.time"] , display_units_short: "ms"
Not available

Response Code

204 No Content OR 202 Accepted

Response Headers

Location: <job-checking URI>  # issued only for 202

Update the properties and/or attributes of a set of metrics at the same time.

This route accepts either a list of metric names OR a single pattern which includes wildcards (*).

If attributes are included which are specific to gauge metrics and the set of metrics provided includes counter metrics, those attributes will be applied only to the gauge metrics in the set.

There are two potential success states for this action, either a 204 No Content (all changes are complete) or a 202 Accepted.

A 202 will be issued when the metric set is large enough that it cannot be operated on immediately. In those cases a Location: response header will be included which identifies a Job resource which can be monitored to determine when the operation is complete and if it has been successful.

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Update a Metric by Name

Update the existing metric temp by setting the display_name and the minimum display attribute.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'display_name=Temperature in Celsius&attributes[display_min]=0' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics/temp'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :temp, name: "Temperature in Celsius", attributes: { display_min: '0' }
import librato
api = librato.connect(<user>, <token>)
for metric in api.list_metrics(name="temp"):
  gauge = api.get(metric.name)
  attrs = gauge.attributes
  attrs['display_name'] = 'Temperature in Celsius'
  attrs['display_min'] = '0'
  api.update(metric.name, attributes=attrs)

Response Code

204 No Content

Create a gauge metric named queue_len (this assumes the metric does not exist):

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'type=gauge&description=Length of app queue&display_name=num. elements' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics/queue_len'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :queue_len, type: :gauge, display_name: "num. elements", period: 15
import librato
api = librato.connect(<user>, <token>)
api.submit("queue_len", 10)

Response Code

201 Created

Response Headers

Location: /v1/metrics/queue_len

Response Body

{
  "name": "queue_len",
  "description": "Length of app queue",
  "display_name": "num. elements",
  "type": "gauge",
  "period": null,
  "attributes": {
    "created_by_ua": "curl/7.24.0 (x86_64-redhat-linux-gnu) libcurl/7.24.0 NSS/3.13.5.0 zlib/1.2.5 libidn/1.24 libssh2/1.4.1"
  }
}

HTTP Request

PUT https://metrics-api.librato.com/v1/metrics/:name

Updates or creates the metric identified by name. If the metric already exists, it performs an update of the metric’s properties.

If the metric name does not exist, then the metric will be created with the associated properties. Normally metrics are created the first time a measurement is sent to the collated POST route, after which their properties can be updated with this route. However, sometimes it is useful to set the metric properties before the metric has received any measurements so this will create the metric if it does not exist. The property type must be set if the metric is to be created.

Creating Persisted Composite Metrics

With this route you can also create and update persisted composite metrics. This allows you to save and use a composite definition as if it was a normal metric. To create a persisted composite set the type to composite and provide a composite definition in the composite parameter. A named metric will be created that can be used on instruments or alerts, similar to how you would use a regular metric.

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Create Parameters

Parameter Definition
type Type of metric to create (gauge, counter, or composite).
display_name
optional
Name which will be used for the metric when viewing the Metrics website.
description
optional
Text that can be used to explain precisely what the gauge is measuring.
period
optional
Number of seconds that is the standard reporting period of the metric. Setting the period enables Metrics to detect abnormal interruptions in reporting and aids in analytics. For gauge metrics that have service-side aggregation enabled, this option will define the period that aggregation occurs on.
attributes
optional
The attributes hash configures specific components of a metric’s visualization.
composite
optional
The composite definition. Only used when type is composite.

Delete a Metric

HTTP Request

DELETE https://metrics-api.librato.com/v1/metrics

Delete the metrics cpu, servers and reqs:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names%5B%5D=cpu&names%5B%5D=servers&names%5B%5D=reqs' \
  -X DELETE \
  'https://metrics-api.librato.com/v1/metrics'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.delete_metrics :cpu, :servers, :reqs
import librato
api = librato.connect(<user>, <token>)
api.delete(names=['cpu', 'servers', 'reqs'])

Delete all metrics that start with cpu and end with .90:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names=cpu*.90' \
  -X DELETE \
  'https://metrics-api.librato.com/v1/metrics'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.delete_metrics names: ["cpu*.90"]
Not available

Response Code

204 No Content OR 202 Accepted

Response Headers

Location: <job-checking URI>  # issued only for 202

Batch-delete a set of metrics. Both the metrics and all of their measurements will be removed. All data deleted will be unrecoverable, so use this with care.

This route accepts either a list of metric names OR a single pattern which includes wildcards (*).

If you post measurements to a metric name after deleting the metric, that metric will be re-created as a new metric with measurements starting from that point.

There are two potential success states for this action, either a 204 No Content (all changes are complete) or a 202 Accepted.

A 202 will be issued when the metric set is large enough that it cannot be operated on immediately. In those cases a Location: response header will be included which identifies a Job resource which can be monitored to determine when the operation is complete and if it has been successful.

Delete a Metric by Name

HTTP Request

DELETE https://metrics-api.librato.com/v1/metrics/:name

Delete the metric named app_requests.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/metrics/app_requests'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.delete_metrics :app_requests
import librato
api = librato.connect(<user>, <token>)
api.delete("app_requests")

Response Code

204 No Content

Delete the metric identified by :name. This will delete both the metric and all of its measurements.

If you post measurements to a metric name after deleting the metric, that metric will be re-created as a new metric with measurements starting from that point.

If you have attempted to DELETE a metric but it is still in your metric list, ensure that you are not continuing to submit measurements to the metric you are trying to delete.

List All Metrics

HTTP Request

GET https://metrics-api.librato.com/v1/metrics

Metric Metadata Queries

List all metrics:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.metrics
import librato
api = librato.connect(<user>, <token>)
api.list_metrics()

Response Code

200 OK

Response (when there are two total):

{
  "query": {
    "found": 2,
    "length": 2,
    "offset": 0,
    "total": 2
  },
  "metrics": [
    {
      "name": "app_requests",
      "display_name": "app_requests",
      "description": "HTTP requests serviced by the app per-minute",
      "period": 60,
      "type": "counter",
      "attributes": {
        "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
        "display_max": null,
        "display_min": 0,
        "display_stacked": true,
        "display_transform": null,
        "display_units_long": "Requests",
        "display_units_short": "reqs"
      }
    },
    {
      "name": "cpu_temp",
      "display_name": "cpu_temp",
      "description": "Current CPU temperature in Fahrenheit",
      "period": 60,
      "type": "gauge",
      "attributes": {
        "created_by_ua": "librato-metrics/0.7.4 (ruby; 1.9.3p194; x86_64-linux) direct-faraday/0.8.4",
        "display_max": null,
        "display_min": 0,
        "display_stacked": true,
        "display_transform": null,
        "display_units_long": "Fahrenheit",
        "display_units_short": "°F"
      }
    }
  ]
}

The endpoint above returns metadata containing all of the available metrics recorded in your account.

Metric Attributes

Each metric instance can be configured past the basic name and description through a set of key/values pairs called attributes. These display attributes are particularly useful for configuring the metric visualization. The attributes described below are supported across all metric types.

Each metric supports a top-level parameter on PUT operations named attributes that comprises a set of key/value pairs.

The following sections list the available metric attributes.

Display Attributes

Display Attribute Definition
color Sets a default color to prefer when visually rendering the metric. Must be a seven character string that represents the hex code of the color e.g. #52D74C.
display_max If a metric has a known theoretical maximum value, set display_max so that visualizations can provide perspective of the current values relative to the maximum value.
display_min If a metric has a known theoretical minimum value, set display_min so that visualizations can provide perspective of the current values relative to the minimum value.
display_units_long A string that identifies the unit of measurement e.g. Microseconds. Typically the long form of display_units_short and used in visualizations e.g. the Y-axis label on a graph.
display_units_short A terse (usually abbreviated) string that identifies the unit of measurement e.g. uS (Microseconds). Typically the short form of display_units_long and used in visualizations e.g. the tooltip for a point on a graph.
display_stacked A boolean value indicating whether or not multiple sources for a metric should be aggregated in a visualization (e.g. stacked graphs). By default counters have display_stacked enabled while gauges have it disabled.
display_transform A linear formula that is run on each measurement prior to visualization. Useful for translating between different units (e.g. Fahrenheit -> Celsius) or scales (e.g. Microseconds -> Milliseconds). The formula may only contain: numeric characters, whitespace, parentheses, the letter x, and approved mathematical operators (’+’, ’-’, ’’, ’/’). The regular expression used is `/^[\dxp()+-\/ ]+$/`.

The formula is run on each measurement by substituting x with a given measurement’s value and p (if present) with the number of seconds in the period the measurement covers. Although you could technically circumvent the lack of an exponential operator by multiplying x by itself (e.g. x*x), YOU SHOULD NOT DO THIS. Non-linear functions will not apply correctly against the automatically generated aggregate values meaning any visualization at a resolution other than the raw data stream would be at best garbage and at worst misleading.

Gauge-only attributes

The following example demonstrates how to set the metric attribute display_max on the metric temperature.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'attributes[display_max]=150' \
  -X PUT \
  https://metrics-api.librato.com/v1/metrics/temperature
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :temperature, attributes: { display_max: '150' }

For aggregate, the following example demonstrates how to enable SSA for the metric speed.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'attributes[aggregate]=true' \
  -X PUT \
  https://metrics-api.librato.com/v1/metrics/speed
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :speed, attributes: { aggregate: 'true' }
Gauge Attribute Definition
summarize_function Determines how to calculate values when rolling up from raw values to higher resolution intervals. Must be one of: ‘average’, 'sum’, 'count’, 'min’, 'max’. If summarize_function is not set the behavior defaults to average.

If the values of the measurements to be rolled up are: 2, 10, 5:

* average: 5.67
* sum: 17
* count: 3
* min: 2
* max: 10
aggregate Enable service-side aggregation for this gauge. When enabled, measurements sent using the same source name will be aggregated into single measurements on an interval defined by the period of the metric. If there is no period defined for the metric then all measurements will be aggregated on a 60-second interval.

This option takes a value of true or false. If this option is not set for a metric it will default to false.

Pagination

Many of the resources accessible through the Metrics REST APIs can contain large numbers of results when an INDEX operation is requested. To enable faster page load times and simple browsing of large result sets the APIs support pagination in a consistent fashion across resources.

Request Parameters

Request which returns the 2nd 10 metrics (would equal to page 2 where each page displays 10 metrics):

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  'https://metrics-api.librato.com/v1/metrics?offset=10&length=10'
Not available
# pagination not available, use list_metrics() for all metrics
for m in api.list_metrics():
    print m.name

Response Code:

200

Response Body:

{
  "query":{
    "found": 200,
    "length": 10,
    "offset": 10,
    "total": 200
  },
  "metrics": [{
    "name": "api",
    "display_name": null,
    "type": "gauge",
    "attributes": {
      "summarize_function": "average",
      "display_units_long": "Request Latency (mS)",
      "display_units_short": "mS",
      "display_min": 0,
      "created_by_ua": "librato-metrics/0.7.4",
      "display_transform": "x/p",
      "display_stacked": false,
      "gap_detection": false,
      "aggregate": true
      },
    "description":null,
    "period":300,
    "source_lag":null
    },
    // 9 more metrics...
  ]
}

There are several request parameters that you can use to control the pagination of the results. These apply in a consistent fashion across all paginated resources. All of the following request parameters have default values and are therefore optional:

Request Parameter Definition
offset
optional
Specifies how many results to skip for the first returned result. Defaults to 0.
length
optional
Specifies how many resources should be returned. The maximum permissible (and the default) length is 100.
orderby
optional
Order by the specified attribute. Permissible set of orderby attributes and the default value varies with resource type.
sort
optional
The sort order in which the results should be ordered. Permissible values are asc (ascending) and desc (descending). Defaults to asc.

Response Parameters

Request to get the third page for the query “api” where each page has a length of 10 metrics.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  https://metrics-api.librato.com/v1/metrics?name=api&offset=20&limit=10
Not available
# pagination not available, use list_metrics() for all metrics
for m in api.list_metrics():
    print m.name

Response Code:

200

Response Body:

{
  "query":{
    "found": 50,
    "length": 10,
    "offset": 20,
    "total": 200
  },
  "metrics": [{
    "name": "api",
    "display_name": null,
    "type": "gauge",
    "attributes": {
      "summarize_function": "average",
      "display_units_long": "Request Latency (mS)",
      "display_units_short": "mS",
      "display_min": 0,
      "created_by_ua": "librato-metrics/0.7.4",
      "display_transform": "x/p",
      "display_stacked": false,
      "gap_detection": false,
      "aggregate": true
      },
    "description":null,
    "period":300,
    "source_lag":null
    },
    // 9 more metrics...
  ]
}

All paginated JSON responses contain a top-level element query that contains the following standard response parameters in addition to any additional response parameters specific to that request:

Response Parameter Definition
length The maximum number of resources to return in the response.
offset The index into the entire result set at which the current response begins. E.g. if a total of 20 resources match the query, and the offset is 5, the response begins with the sixth resource.
total The total number of resources owned by the user.
found The number of resources owned by the user that satisfy the specified query parameters. found will be less than or equal to total. Additionally if length is less than found, the response is a subset of the resources matching the specified query parameters.

Measurements Beta

Measurements represent the individual time-series samples sent to the Librato service. They are associated with a metric, one or more tag pairs, and a point in time.

Each measurement has a value that represents an observation at one point in time. The value of a measurement will typically vary between some minimum or maximum value (ex. CPU usage moving from 0% to 100%).

Measurement Properties

The general properties of a measurement are described below. The documentation on submitting measurements includes a full overview of all acceptable parameters.

Property Definition
name The unique identifying name of the property being tracked. The metric name is used both to create new measurements and query existing measurements.
tags A set of key/value pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. Examples include the region a server is located in, the size of a cloud instance or the country a user registers from. The full set of unique tag pairs defines a single data stream.
value The numeric value of a single measured sample.
time Unix Time (epoch seconds). This defines the time that a measurement is recorded at. It is useful when sending measurements from multiple sources to align them on a given time boundary, eg. time=floor(Time.now, 60) to align samples on a 60 second tick.
period Define the period for the metric. This will be persisted for new metrics and used as the metric period for metrics marked for Service-Side Aggregation.

Create a Measurement

Create a new measurement AWS.EC2.DiskWriteBytes with the tag region : "us-east-1":

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "region": "us-east-1"
    },
    "measurements": [
      {
        "name": "AWS.EC2.DiskWriteBytes",
        "value": 65
      }
    ]
  }' \
  -X POST \
  https://metrics-api.librato.com/v1/measurements
Not yet available
Not yet available

HTTP Request

POST https://metrics-api.librato.com/v1/measurements

This action allows you to submit measurements for new or existing metric data streams. You can submit measurements for multiple metrics in a single request.

If the metric referenced by the name property of a measurement does not exist, it will be created prior to saving the measurements. Any metric properties included in the request will be used when creating this initial metric. However, if the metric already exists the properties will not update the given metric.

For truly large numbers of measurements we suggest batching into multiple concurrent requests. It is recommended that you keep batch requests under 1,000 measurements/post. As we continue to tune the system this suggested cap will be updated.

Headers

The only permissible content type is JSON at the moment. All requests must include the following header:

Content-Type: application/json

Measurement Parameters

Top-Level Tags

The following payload demonstrates submitting tags at the top-level of the payload. This may be common for a collection agent that tags all metrics the same based on the identification of the collection host parameters.

This will result in two data streams, cpu and memory. Both metrics will contain the tags region=us-west and name=web-prod-3.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "region": "us-west",
      "name": "web-prod-3"
    },
    "measurements": [
      {
        "name": "cpu",
        "value": 4.5
      },
      {
        "name": "memory",
        "value": 10.5
      }
    ]
  }' \
-X POST \
https://metrics-api.librato.com/v1/measurements
Not yet available
Not yet available

Embedded Measurement Tags

The following example payload demonstrates mixing top-level tags with per-measurement tags.

This will result in the data streams, cpu and memory. The cpu metric strips the name tag from the data stream while the memory metric actually adds two additional tag names.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "region": "us-west",
      "name": "web-prod-3"
    },
    "measurements": [
      {
        "name": "cpu",
        "value": 4.5,
        "tags": {
          "name": null
        }
      },
      {
        "name": "memory",
        "sum": 34.5,
        "count": 5,
        "tags": {
          "az": "g",
          "db": "db-prod-1"
        }
      }
    ]
  }' \
-X POST \
https://metrics-api.librato.com/v1/measurements
Not yet available
Not yet available

Full Measurement Sample

How to submit a single measurement that contains a full summary statistics fields. This includes embedded tag names and the metric attribute (which specifies not to enable SSA) that is saved when the initial metric (cpu) is created.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [
      {
        "name": "cpu",
        "time": 1421530163,
        "period": 60,
        "attributes": {
          "aggregate": false
        },
        "sum": 35.0,
        "count": 3,
        "min": 4.5,
        "max": 6.7,
        "last": 2.5,
        "stddev": 1.34,
        "tags": {
          "region": "us-east-1",
          "az": "b",
          "role": "kafka",
          "environment": "prod",
          "instance": "3"
        }
      }
    ]
  }' \
-X POST \
https://metrics-api.librato.com/v1/measurements
Not yet available
Not yet available

Individual Sample Parameters

The request must include at least one measurement. Measurements are collated under the top-level parameter measurements. The minimum required fields for a measurement are:

Parameter Definition
name The unique identifying name of the property being tracked. The metric name is used both to create new measurements and query existing measurements. Must be 255 or fewer characters, and may only consist of ‘A-Za-z0-9.:-_’. The metric namespace is case insensitive.
value The numeric value of a single measured sample.

Global or per-sample parameters

In addition, the following parameters can be specified to further define the measurement sample. They may be set at the individual measurement level or at the top-level. The top-level value is used unless the same parameter is set at an individual measurement.

Parameter Definition
time Unix Time (epoch seconds). This defines the time that a measurement is recorded at. It is useful when sending measurements from multiple sources to align them on a given time boundary, eg. time=floor(Time.now, 60) to align samples on a 60 second tick.
tags A set of key/value pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. Examples include the region a server is located in, the size of a cloud instance or the country a user registers from. The full set of unique tag pairs defines a single data stream.

Tags are merged between the top-level tags and any per-measurement tags, see the section Tag Merging for details.

If no tag pairs are specified in the payload, a default tag pair of source=unassigned will be applied.
period Define the period for the metric. This will be persisted for new metrics and used as the metric period for metrics marked for Service-Side Aggregation.

Summary fields

Measurements can contain a single floating point value or they can support samples that have been aggregated prior to submission (eg. with statsd) with the following summary fields:

Parameter Definition
count Indicates the request corresponds to a multi-sample measurement. This is useful if measurements are taken very frequently in a closed loop and the metric value is only periodically reported. If count is set, then sum must also be set in order to calculate an average value for the recorded metric measurement. Additionally min, max, and stddev/stddev_m2 may also be set when count is set. The value parameter should not be set if count is set.
sum If count was set, sum must be set to the summation of the individual measurements. The combination of count and sum are used to calculate an average value for the recorded metric measurement.
max If count was set, max can be used to report the largest individual measurement amongst the averaged set.
min If count was set, min can be used to report the smallest individual measurement amongst the averaged set.
last Represents the last value seen in the interval. Useful when tracking derivatives over points in time.
stddev Represents the standard deviation of the sample set. If the measurement represents an aggregation of multiple samples, standard deviation can be calculated and included with the sample. Standard deviations are averaged when downsampling multiple samples over time.
stddev_m2 Represents the current mean value when aggregating samples using the alternative standard deviation method. The current mean value allows an accurate standard deviation calculation when aggregating multiple samples over time. Only one of stddev and stddev_m2 may be set.

Optional Parameters

NOTE: The optional parameters listed in the metrics PUT operation can be used with POST operations, but they will be ignored if the metric already exists. To update existing metrics, please use the PUT operation.

Tag Merging

A given payload can mix tag definitions at the top-level tags parameter or tags can be specified per measurement (and eventually event). A tag with the same name in the measurement block will override any value set at the top-level. Any tag defined at the top-level, but not included in the measurement tag block will be merged with the measurement tags. To unset or clear a tag at the top-level, the tag name can be set to the JSON “null” value in the measurement block.

Rate Limiting

Every response will include headers that define the current API limits related to the request made, the current usage of the account towards this limit, the total capacity of the limit and when the API limit will be reset.

Measurement Restrictions

Name Restrictions

Metric names must be 255 or fewer characters, and may only consist of A-Za-z0-9.:-_. The metric namespace is case insensitive.

Tag names must match the regular expression /\A[-.:_\w]+\z/{1,64}. Tag names are always converted to lower case.

Tag values must match the regular expression /\A[-.:_\w]+\z/{1, 256}. Tag values are always converted to lower case.

Data streams have a default limit of 10 tag names per measurement.

Accounts have a default limit of 100 unique tag names.

Metrics have a maximum permitted cardinality for tag values. This maximum will be enforced as both a create rate limit and total cardinality limit.

Float Restrictions

Internally all floating point values are stored in double-precision format. However, Librato places the following restrictions on very large or very small floating point exponents:

If the base-10 exponent of any floating point value is larger than 1 x 10^126, the request will be aborted with a 400 status error code.

If the base-10 exponent of any floating point value is smaller than 1 x 10^-130, the value will be truncated to zero (0.0).

Retrieve a Measurement

Retrieve Measurements by Matching Tags

How to retrieve the measurement AWS.EC2.DiskWriteBytes with the tags matching region=us* and name=prod:

Note: When using cURL you will need to utilize URL encoding for the tag brackets (%5B and %5D)

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/measurements/AWS.EC2.DiskWriteBytes?resolution=60&duration=86400&tags%5Bregion%5D=us-*&tags%5Bname%5D=prod'
Not yet available
Not yet available

Response:

{
  "series":[
    {
      "tags":{
         "name":"prod",
         "region":"us-east"
      },
      "measurements":[
         {
            "time":1476218700,
            "value":753.0
         },
         {
            "time":1476219840,
            "value":25.0
         },
         {
            "time":1476219900,
            "value":758.0
         }
      ]
    },
    {
      "tags":{
         "name":"prod",
         "region":"us-west"
      },
      "measurements":[
        {
           "time":1476218700,
           "value":496.0
        }
      ]
    }
  ],
  "resolution":60,
  "name":"AWS.EC2.DiskWriteBytes"
}

How to retrieve the measurements AWS.EC2.DiskWriteBytes with the tags matching region=us-east OR region=us-west AND name=prod (also group by region):

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/measurements/AWS.EC2.DiskWriteBytes?resolution=60&duration=86400&tags%5Bregion%5D=us-*&tags%5Bname%5D=prod&group_by=region&group_by_function=sum'
Not yet available
Not yet available

Response:

{
  "series":[
    {
      "tags":{
         "region":"us-east"
      },
      "measurements":[
        {
           "time":1476218700,
           "value":753.0
        },
        {
           "time":1476219840,
           "value":25.0
        },
        {
           "time":1476219900,
           "value":758.0
        }
      ]
    },
    {
      "tags":{
         "region":"us-west"
      },
      "measurements":[
        {
           "time":1476218700,
           "value":496.0
        }
      ]
    }
  ],
  "resolution":60,
  "name":"AWS.EC2.DiskWriteBytes"
}

Retrieve Measurements Using tags_search

How to use the tags_search parameter to retrieve measurements for memory which match the tags region=us-east* and db=prod.

In cURL you will need to apply URL encoding to the parameter tags_search=region=us-east* and db=*prod*.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/measurements/memory?resolution=60&duration=86400&tags_search=region%3Dus-east*%20and%20db%3D*prod*'
Not yet available
Not yet available

Response:

{
  "series":[
   {
     "tags":{
       "name":"prod",
       "region":"us-east",
       "db":"db-prod-1"
     },
     "measurements":[
       {
          "time":1476227520,
          "value":6.9
       }
     ]
   }
  ],
  "links":[],
  "resolution":60,
  "name":"memory"
}

HTTP Request

GET https://metrics-api.librato.com/v1/measurements/:measurement

This route returns streams of measurements for a given metric. The streams returned are based on the combination of time search and tag filter/aggregation parameters specified.

HTTP Response

In the response payload the top-level measurements key is replaced with the series keyword, similar to composite responses. The series are no longer keyed by source name, instead series is an array of measurement objects. Each measurement object contains either the grouping tag name/value or a set of tag/value pairs (depends if they use the group_by option).

Measurements are flattened to a single pair. The time is the Unix Time of the sample, which will be floored to the requested resolution. The value is based on the combination of the aggregation performed using the summary_function and group_by function parameters.

By default the series will be sorted by the ordering of their tag pairs.

Time search parameters

The following parameters control the period of time that is returned from a given query and the period of the individual samples.

Property Definition
start_time Unix Time of where to start the time search from. This parameter is optional if duration is specified.
end_time Unix Time of where to end the search. This parameter is optional and defaults to current wall time.
duration How far back to look in time, measured in seconds. This parameter can be used in combination with endtime to set a starttime N seconds back in time. It is an error to set starttime, endtime and duration.
resolution
required
Defines the resolution to return the data to in seconds. The returned data will be downsampled to this resolution and loaded from the appropriate underlying rollup resolution. An error will be returned if the requested resolution is not available during the requested time interval. The max value will be one week (604800 seconds).

Tag Search Parameters

The returned data streams can be filtered on the set of tags included on the original data streams.

Property Definition
tags A map of tag search patterns that limit the returned set of streams by simple wildcard patterns against tag values. Only streams matching the provided tag name/values are returned. Tags can be searched by AND, OR, and NOT conditions on their tag values. Specifying the same tag name multiple times with different values is an OR. Specifying different tag names performs an AND and prefixing a tag value search pattern with “!” negates the match.

A negation requires that the particular tag name is set on the data stream. It will not match streams that do not have the particular tag name set. See section below for how negation is handled.

Only tag values can be wildcard matches, tag names must be fully specified. It is not possible to perform wildcard matches against tag names.
tags_search The tag_search parameter, which may NOT be specified with the tags parameter, defines a complex search query over a set of tags. It is provided to allow a more complex query pattern over the set of tag values than the tags parameter can provide. The grammar should be properly form-encoded to escape fields not appropriate for URL query parameters.

Tag Negation

When using the tags property you can perform two operations:

eg. region=!us-east

eg. !host

Aggregation parameters

By default all matching data streams are returned in the response. The following parameters control how to aggregate data streams based on the tag values.

Property Definition
group_by Defines one or more tag names to group the returned results by. Any measurements with the same tag value for the given group_by tag names are aggregated using the group_by_func aggregation function. Each returned stream will include the grouped tags. If group_by is not specified, all streams are returned broken out by their tag values.

The group_by tags also define a filter for the returned results. Only streams that contain all of the group by tags are returned.

The special format of group_by=* will return all data streams aggregated together to a single stream. The response will not include any tag information.

Examples: group_by=region, group_by=region,az, group_by=*
group_by_function Defines the aggregation function to group results by. This parameter is required if group_by is set. Options are: sum, min, max, & mean. Future: cardinality of aggregated streams.
summary_function Defines the property of the metric to query. A metric has properties like: sum, count, min, max; this parameter defines which of the properties to read and represent in the payload.

Acceptable values are: sum, min, max, count, mean, derivative, stddev, & all. This parameter falls back to the persisted summary function of the metric, which by default is mean. If the parameter is set to all then the api will, instead of returning just one summarization, return multiple summarizations for each returned measure.

The summary function also defines the function used when downsampling data to a coarser granularity. The downsampling function is chosen as following given a summary function.

Note: If summary_function = all, group_by may not be specified.

Measurement Pagination

Response if more results are available for pagination:

{
  "series": [

  ],
  "links": [
    {
      "rel": "next",
      "href": "https://metrics-api.librato.com/v1/measurements/foo?start_time=1234&resolution=3"
    }
  ]
}

Response if there are no more results:

{
  "series": [

  ],
  "links": [

  ]
}

When retrieving measurements, the response payload includes a pagination href if more results are available. This href will define how to invoke the API again to query the next set of data corresponding to the current query. The href may include an opaque “session key” as a parameter that will allow the API to store session data (like running accumulators) to continue a query without loss of data.

The response payload will have a top-level member called links that will contain a link member with a relative value of next. If there are no more results, the links section will not contain an entry for next.

Future iterations may add different components to the links list, so the consumer should check for the next entry specifically.

Spaces

Spaces contain a collection of charts that graph one or more metrics in real time. The API allows you to view details on Spaces associated with an account. The API allows you to create, modify, and delete Spaces by referencing the name or id of the Space.

Space Properties

Property Definition
id Each space has a unique numeric ID
name Unique name for space
tags Boolean: Enable space for Tags. Only available in the Tags Beta.

Pagination Parameters

The response is paginated, so the request supports our generic Pagination Parameters. Specific to spaces, the default value of the orderby pagination parameter is name, and the permissible values of the orderby pagination parameter are: name.

Parameter Definition
name Search by name of the space.

Create a Space

Create a space with name CPUs:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=CPUs' \
  -X POST \
  'https://metrics-api.librato.com/v1/spaces'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.create_space("CPUs")
print("Created '%s'" % space.name)

Using JSON

{
  "name": "CPUs"
}

Response Code

201 Created

Response Headers

Location: /v1/spaces/129

Response Body

{
  "id": 129,
  "name": "CPUs"
}

HTTP Request

POST https://metrics-api.librato.com/v1/spaces

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Retrieve a Space

Return the details of a Space with ID 129:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/spaces/129'
Not available
import librato
api = librato.connect(<user>, <token>)
space_info = api.get_space(129)
print space_info.chart_ids

Response Code

200 OK

Response Body

{
  "name": "CPUs",
  "id": 129,
  "charts": [
    {
      "id": 915
    },
    {
      "id": 1321
    },
    {
      "id": 47842
    },
    {
      "id": 922
    }
  ]
}

Returns the details of a specific space.

HTTP Request

GET https://metrics-api.librato.com/v1/spaces/:id

Update a Space

Change the name of the space to MEMORY:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=MEMORY' \
  -X PUT \
  'https://metrics-api.librato.com/v1/spaces/:id'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.find_space('CPUs')
space.name = "MEMORY"
space.save()

Using JSON

{
  "name": "MEMORY"
}

Response Code

204 No Content

Modifies a space by changing its name.

HTTP Request

PUT https://metrics-api.librato.com/v1/spaces/:id

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Delete Space

Delete the space with ID 129:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/spaces/129'
Not available
import librato
api = librato.connect(<user>, <token>)
api.delete_space(129)

Response Code

204 No Content

Delete the space identified by :id.

HTTP Request

DELETE https://metrics-api.librato.com/v1/spaces/:id

List all Spaces

HTTP Request

GET https://metrics-api.librato.com/v1/spaces

Retrieve all spaces:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/spaces'
Not available
import librato
api = librato.connect(<user>, <token>)
spaces = api.list_spaces()
for s in spaces:
  print s.name

Return all spaces owned by the user, with name matching ops:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/spaces?name=ops'
Not available
import librato
api = librato.connect(<user>, <token>)
spaces = api.list_spaces(name="ops")
for s in spaces:
  print(s.name)

Response Code

200 OK

Response Body

{
  "query": {
    "found": 1,
    "length": 1,
    "offset": 0,
    "total": 15
  },
  "spaces": [
    {
      "id": 4,
      "name": "staging_ops"
    }
  ]
}

Returns all spaces created by the user.

Charts

A charts graphs one or more metrics in real time. In order to create a chart you will first need to build a Space. Each Space accommodates multiple charts.

Create a Chart

Create a line chart with various metric streams including their source(s) and group/summary functions:

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-d 'type=line' \
-d 'name=Server Temperature' \
-d 'streams[0][metric]=server_temp' \
-d 'streams[0][source]=app1' \
-d 'streams[1][metric]=environmental_temp' \
-d 'streams[1][source]=*' \
-d 'streams[1][group_function]=breakout' \
-d 'streams[1][summary_function]=average' \
-d 'streams[2][metric]=server_temp' \
-d 'streams[2][source]=%' \
-d 'streams[2][group_function]=average' \
-X POST \
'https://metrics-api.librato.com/v1/spaces/:id/charts'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.get_space(123)
chart = api.create_chart(
    'Server Temperature',
    space,
    type='line',
    streams=[
        {'metric': 'server_temp', 'source': 'app1'},
        {'metric': 'environmental_temp', 'source': '*',
        'group_function': 'average'},
        {'metric': 'server_temp', 'source': '%'}])

Response Code

201 Created

Response Headers

Location: /v1/spaces/123

Response Body

{
  "id": 123,
  "name": "Server Temperature",
  "type": "line",
  "streams": [
    {
      "metric": "server_temp",
      "source": "app1",
      "type": "gauge"
    },
    {
      "metric": "environmental_temp",
      "source": "*",
      "type": "gauge",
      "group_function": "average"
    },
    {
      "metric": "server_temp",
      "source": "%",
      "type": "gauge"
    }
  ]
}

How to add a composite metric to a chart

NOTE: This will replace existing streams within the specified chart

curl \
  -u  $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'type=line' \
  -d 'streams[0][composite]=divide([sum(s("memory_total","prod.web*")),sum(s("memory_used","prod.web*"))])' \
  -X PUT \
  'https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.get_space(123)
charts = space.chart_ids
chart = api.get_chart(charts[0], space.id)
chart.new_stream(composite='divide([
  sum(s("memory_total","prod.web*")),
  sum(s("memory_used","prod.web*"))])')
chart.save()

Response Code

204 No Content

You can create a new chart with specified metrics or update an existing chart with new metrics to override the chart’s existing metrics.

HTTP Request

POST https://metrics-api.librato.com/v1/spaces/:id/charts

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
name Title of the chart when it is displayed.
streams An array of hashes describing the metrics and sources to use for data in the chart.
type Indicates the type of chart. Must be one of line, stacked, or bignumber (default to line)
min The minimum display value of the chart’s Y-axis
max The maximum display value of the chart’s Y-axis
label The Y-axis label
related_space The ID of another space to which this chart is related

Stream Properties

Parameter Definition
metric Name of metric
source Name of source or * to include all sources. This field will also accept specific wildcard entries. For example us-west–app* will match us-west-21-app but not us-west-12-db. Use % to specify a dynamic source that will be provided after the instrument or dashboard has loaded, or in the URL.
composite A composite metric query string to execute when this stream is displayed. This can not be specified with a metric, source or group_function.
group_function How to process the results when multiple sources will be returned. Value must be one of: average, sum, min, max, breakout. If average, sum, min, or max, a single line will be drawn representing the function applied over all sources. If the function is breakout, a separate line will be drawn for each source. If this property is not supplied, the behavior will default to average.
summary_function When visualizing complex measurements or a rolled-up measurement, this allows you to choose which statistic to use. If unset, defaults to “average”. Valid options are one of: [max, min, average, sum, count].
downsample_function This allows you to choose which statistic to use during roll-ups (for composite metrics only). If unset, defaults to “average”. Valid options are one of: [max, min, average, sum, count].
color Sets a color to use when rendering the stream. Must be a seven character string that represents the hex code of the color e.g. #52D74C.
name A display name to use for the stream when generating the tooltip.
units_short Unit value string to use as the tooltip label.
units_long String value to set as they Y-axis label. All streams that share the same units_long value will be plotted on the same Y-axis.
min Theoretical minimum Y-axis value.
max Theoretical maximum Y-axis value.
transform_function Linear formula to run on each measurement prior to visualization.
period An integer value of seconds that defines the period this stream reports at. This aids in the display of the stream and allows the period to be used in stream display transforms.

Retrieve a Chart

Return chart by id and space id.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id'
Not available
import librato
api = librato.connect(<user>, <token>)
chart = api.get_chart(chart_id, space_id)
for s in chart.streams:
  print(s.metric, s.source, s.group_function, s.summary_function)

Response Code

200 OK

Response Body

{
  "id": 6637,
  "name": "CPU Usage",
  "type": "line",
  "streams": [
    {
      "id": 386291,
      "metric": "collectd.cpu.0.cpu.user",
      "type": "counter",
      "source": "*",
      "group_function": "average",
      "summary_function": "derivative"
    }
  ]
}

Returns a specific chart by its id and space id.

HTTP Request

GET https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id

Update a Chart

Update a chart name to Temperature:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=Temperature' \
  -X PUT \
  'https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.get_space(123)
charts = space.chart_ids
chart = api.get_chart(charts[0], space.id)
chart.name = 'Temperature'
chart.save()

Response Code

200 OK

Response Body

{
  "id": 1,
  "name": "Temperature",
  "type": "line",
  "streams": [
    {
      "id": 1,
      "metric": "temperature",
      "type": "gauge",
      "source": "*",
      "group_function": "average"
    }
  ]
}

Updates attributes of a specific chart. In order to update the metrics associated with a chart you will need to view the example under Create a Chart, which demonstrates overwriting an existing chart with new metrics.

HTTP Request

PUT https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
name Title of the chart when it is displayed.
streams An array of hashes describing the metrics and sources to use for data in the chart.
type Indicates the type of chart. Must be one of line or stacked (default to line)
min The minimum display value of the chart’s Y-axis
max The maximum display value of the chart’s Y-axis
label The Y-axis label
related_space The ID of another space to which this chart is related

Stream Properties

Property Definition
metric Name of metric
source Name of source or * to include all sources. This field will also accept specific wildcard entries. For example us-west–app* will match us-west-21-app but not us-west-12-db. Use % to specify a dynamic source that will be provided after the instrument or dashboard has loaded, or in the URL.
composite A composite metric query string to execute when this stream is displayed. This can not be specified with a metric, source or group_function.
group_function How to process the results when multiple sources will be returned. Value must be one of: average, sum, min, max, breakout. If average, sum, min, or max, a single line will be drawn representing the function applied over all sources. If the function is breakout, a separate line will be drawn for each source. If this property is not supplied, the behavior will default to average.
summary_function When visualizing complex measurements or a rolled-up measurement, this allows you to choose which statistic to use. If unset, defaults to “average”. Valid options are one of: [max, min, average, sum, count].
downsample_function This allows you to choose which statistic to use during roll-ups (for composite metrics only). If unset, defaults to “average”. Valid options are one of: [max, min, average, sum, count].
color Sets a color to use when rendering the stream. Must be a seven character string that represents the hex code of the color e.g. #52D74C.
name A display name to use for the stream when generating the tooltip.
units_short Unit value string to use as the tooltip label.
units_long String value to set as they Y-axis label. All streams that share the same units_long value will be plotted on the same Y-axis.
min Theoretical minimum Y-axis value.
max Theoretical maximum Y-axis value.
transform_function Linear formula to run on each measurement prior to visualization.
period An integer value of seconds that defines the period this stream reports at. This aids in the display of the stream and allows the period to be used in stream display transforms.

Delete a Chart

Delete the chart ID 123.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.get_space(123)
charts = space.chart_ids
chart = api.get_chart(charts[0], space_id)
chart.delete()

Response Code

204 No Content

Delete the specified chart.

HTTP Request

DELETE https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id

List all Charts in Space

List all charts in a Space with ID 129.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/spaces/129/charts'
Not available
import librato
api = librato.connect(<user>, <token>)
space = api.get_space(129)
charts = space.chart_ids
for c in charts:
   i = api.get_chart(c, space.id)
   for s in i.streams:
       print(s.id, s.metric, s.source, s.group_function, s.summary_function)

Response Code

200 OK

Response Body

[
  {
    "id": 6637,
    "name": "CPU Usage",
    "type": "line",
    "streams": [
      {
        "id": 386291,
        "metric": "collectd.cpu.0.cpu.user",
        "type": "counter",
        "source": "*",
        "group_function": "average",
        "summary_function": "derivative"
      }
    ]
  },
  {
    "id": 6638,
    "name": "Free Memory",
    "type": "line",
    "streams": [
      {
        "id": 386292,
        "metric": "collectd.memory.memory.free",
        "type": "gauge",
        "source": "*",
        "group_function": "average",
        "summary_function": "average"
      }
    ]
  }
]

Return charts for a given space.

HTTP Request

GET https://metrics-api.librato.com/v1/spaces/:id/charts

Annotations

Annotations are used to record external events (e.g. a deployment) that typically occur at non-uniform times, yet may impact the behavior of monitored metrics. Each annotation event has an associated time and metadata description. When a set of annotation events are added to a graph, each event is plotted as a single vertical line. This permits a user to correlate operational or business actions to observed metrics.

Every annotation event is associated with a single named annotation stream, analogous to how multiple measurements are associated with the named metric they belong to. For example, you might have an annotation stream named ux-app-deploys to track deployments to your UX application and another annotation stream api-app-deploys to track deploys to your API application. Multiple annotation events can be added to a graph by selecting the name of the annotation stream, similar to selecting a metric name.

An annotation event can also include an end time to represent an event that spanned a duration of time. For example, a batch job that ran for five minutes would set the annotation event’s start time when the job started and update the annotation event with an end time when the job completed. Annotation events that include an end time will be displayed with their start and end times as connected vertical lines on graphs.

Annotation Streams

Annotation streams group related annotation events into a single timeline. Annotation streams are referenced by their name and are automatically created when an annotation event is POSTed to a new annotation stream name.

Annotation Stream Properties

Annotation Property Definition
name Name of the annotation stream.
display_name The string used to display this annotation stream.

Annotation Events

An annotation event records a single point in time when an external action (like a deployment) occurred. Annotation events can include metadata that describe the particular event in more detail or reference an external site.

Annotation Event Properties

Annotation Property Definition
id Each annotation event has a unique numeric ID.
title The title of an annotation is a string and may contain spaces. The title should be a short, high-level summary of the annotation e.g. v45 Deployment. The title is a required parameter to create an annotation.
source A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population. Examples: foo3.bar.com, user-123, 77025.
description The description contains extra metadata about a particular annotation. The description should contain specifics on the individual annotation e.g. Deployed 9b562b2: shipped new feature foo! A description is not required to create an annotation.
links An optional list of references to resources associated with the particular annotation. For example, these links could point to a build page in a CI system or a changeset description of an SCM. Each link has a tag that defines the link’s relationship to the annotation. See the link documentation for details on available parameters.
start_time The unix timestamp indicating the the time at which the event referenced by this annotation started. By default this is set to the current time if not specified.
end_time The unix timestamp indicating the the time at which the event referenced by this annotation ended. For events that have a duration, this is a useful way to annotate the duration of the event. This parameter is optional and defaults to null if not set.

Create an Annotation

Create an annotation event in the app-deploys stream:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=Deployed v56&source=foo3.bar.com&description=v56 - Fixed typo in page titles' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/app-deploys'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.annotate :'app-deploys', 'Deployed v56', source: 'foo3.bar.com',
    description: 'v56 - Fixed typo in page titles'
import librato
api = librato.connect(<user>, <token>)
api.post_annotation("app-deploys",
  title="Deployed v56",
  source="foo3.bar.com",
  description="v56 - Fixed typo in page titles")

Create an annotation event at a specific timestamp:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=My Annotation&description=Joe deployed v29 to metrics&start_time=1234567890' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.annotate :'app-deploys', 'My Annotation', source: 'foo3.bar.com',
    start_time: 1234567890, description: 'Joe deployed v29 to metrics'
import librato
api = librato.connect(<user>, <token>)
api.post_annotation("app-deploys",
  title="My Annotation",
  source="foo3.bar.com",
  start_time="1234567890",
  description="Joe deployed v29 to metrics")

Create an annotation event with a link:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=My Annotation&description=Joe deployed v29 to metrics&start_time=1234567890' \
  -d 'links[0][label]=Metrics Gem' \
  -d 'links[0][href]=https://github.com/librato/librato-metrics' \
  -d 'links[0][rel]=github' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.annotate :'app-deploys', 'My Annotation', source: 'foo3.bar.com',
    start_time: 1234567890, description: 'Joe deployed v29 to metrics',
    links: [label: 'Metrics Gem', href: 'https://github.com/librato/librato-metrics', rel: 'github']
import librato
api = librato.connect(<user>, <token>)
api.post_annotation("app-deploys",
  title="My Annotation",
  source="foo3.bar.com",
  start_time="1234567890",
  description="Joe deployed v29 to metrics",
  links=[{'rel': 'github', 'href': 'https://github.com/librato/librato-metrics'}])

Response Code

201 Created

Response Headers

Location: /v1/annotations/api-deploys/123

Response Body

{
  "id": 123,
  "title": "My Annotation",
  "description": "Joe deployed v29 to metrics",
  "source": null,
  "start_time": 1234567890,
  "end_time": null,
  "links": [

  ]
}

Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically.

HTTP Request

POST https://metrics-api.librato.com/v1/annotations/:name

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameter Definition
title The title of an annotation is a string and may contain spaces. The title should be a short, high-level summary of the annotation e.g. v45 Deployment. The title is a required parameter to create an annotation.
source
optional
A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population. Examples: foo3.bar.com, user-123, 77025.
description
optional
The description contains extra metadata about a particular annotation. The description should contain specifics on the individual annotation e.g. Deployed 9b562b2: shipped new feature foo! A description is not required to create an annotation.
links
optional
An optional list of references to resources associated with the particular annotation. For example, these links could point to a build page in a CI system or a changeset description of an SCM. Each link has a tag that defines the link’s relationship to the annotation. See the link documentation for details on available parameters.
start_time
optional
The unix timestamp indicating the the time at which the event referenced by this annotation started. By default this is set to the current time if not specified.
end_time
optional
The unix timestamp indicating the the time at which the event referenced by this annotation ended. For events that have a duration, this is a useful way to annotate the duration of the event. This parameter is optional and defaults to null if not set.

Retrieve an Annotation

Return details of the annotation stream name api-deploys.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.list name: ('api-deploys')
import librato
api = librato.connect(<user>, <token>)
stream = api.get_annotation_stream("api-deploys", start_time="1234500000")
for source in stream.events:
   print source
   events = stream.events[source]
   for event in events:
       print event['id']
       print event['title']
       print event['description']

Specifying a set of time interval search parameters will return a list of all annotation events for a stream. For example, to return the set of annotation events on the annotation stream blog-posts between two timestamps and limited to sources db1.acme and db2.acme:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/annotations/blog-posts?start_time=1234500000&end_time=1234600000&sources%5B%5D=db1.acme&sources%5B%5D=db2.acme'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.fetch :'blog-posts', start_time: 1234500000, end_time: 1234600000, sources: ['db1.acme', 'db2.acme']
import librato
api = librato.connect(<user>, <token>)
stream = api.get_annotation_stream("blog-posts",
  start_time="1234500000",
  end_time="1234600000",
  sources=['db1.acme', 'db2.acme'])
print(stream.events)

Response Code

200 OK

Response Body

An annotation stream from multiple sources:

{
  "name": "api-deploys",
  "display_name": "Deploys to API",
  "events": [
    {
      "unassigned": [
        {
          "id": 45,
          "title": "Deployed v91",
          "description": null,
          "start_time": 1234567890,
          "end_time": null,
          "source": null,
          "links": [
            {
              "label": "Github commit",
              "rel": "github",
              "href": "http://github.com/org/app/commit/01beaf"
            },
            {
              "label": "Jenkins CI build job",
              "rel": "jenkins",
              "href": "http://ci.acme.com/job/api/34"
            }
          ]
        }
      ],
      "foo3.bar.com": [
        {
          "id": 123,
          "title": "My Annotation",
          "description": null,
          "start_time": 1234567890,
          "end_time": null,
          "source": "foo3.bar.com",
          "links": [

          ]
        },
        {
          "id": 1098,
          "title": "Chef run finished",
          "description": "Chef migrated up to SHA 44a87f9",
          "start_time": 1234567908,
          "end_time": 1234567958,
          "source": "foo3.bar.com",
          "links": [

          ]
        }
      ]
    }
  ]
}

Return a list of annotations associated with given stream name.

HTTP Request

GET https://metrics-api.librato.com/v1/annotations/:name

Annotation Search Parameters

If optional time interval search parameters are specified, the response includes the set of annotation events with start times that are covered by the time interval. Annotation events are always returned in order by their start times.

Annotation events are grouped by their originating source name if one was specified when the annotation event was created. All annotation events that were created without an explicit source name are listed with the source name unassigned.

Annotation events can be further restricted by the following search parameters:

Search Parameter Definition
sources An array of source names to limit the search to. Can include source name wildcards like db-* to show annotations from all db sources.

Retrieve an Annotation Event

Lookup the annotation event 189 in the annotation stream api-deploys:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/annotations/api-deploys/189'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.fetch :'api-deploys', start_time: (Time.now.to_i-3600)
Not available

Response Code

200 OK

Response Body

{
  "id": 189,
  "title": "Deployed v91",
  "description": null,
  "start_time": 1234567890,
  "end_time": null,
  "source": null,
  "links": [
    {
      "label": "Github commit",
      "rel": "github",
      "href": "http://github.com/org/app/commit/01beaf"
    },
    {
      "label": "Jenkins CI build job",
      "rel": "jenkins",
      "href": "http://ci.acme.com/job/api/34"
    }
  ]
}

Return annotation event details associated with given stream name.

HTTP Request

GET https://metrics-api.librato.com/v1/annotations/:name/:id

Update an Annotation

Add a link to github to the annotation event 198 in the app-deploys stream:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'rel=github&label=Github Commit&href=https://github.com/acme/app/commits/01beaf' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/198/links'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.fetch :'app-deploys', start_time: (Time.now.to_i-3600), end_time: (Time.now.to_i), sources: ['db1.acme', 'db2.acme']
Not available

Response Code

201 Created

Response Headers

Location: /v1/annotations/app-deploys/198/links/github

Response Body

{
  "rel": "github",
  "label": "Github Commit",
  "href": "https://github.com/acme/app/commits/01beaf"
}

Add a link to a specific annotation event.

HTTP Request

POST https://metrics-api.librato.com/v1/annotations/:name/:id/links

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
rel Defines the relationship of the link. A link’s relationship must be unique within a single annotation event.
href The link URL.
label
optional
A display label for the link.

Update an Annotation Stream Attributes

Update the display name of the annotation stream api-deploys:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'display_name=Deploys to API' \
  -X PUT \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'
Not available
Not available

Response Code

204 No Content

Update the attributes of an annotation stream.

HTTP Request

PUT https://metrics-api.librato.com/v1/annotations/:name

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Annotation Stream Parameters

Parameter Definition
display_name Name used to display the annotation stream.

Update Annotation Event Metadata

Update the description of the annotation 143 in the stream app-deploys:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'description=Deployed git SHA 601060a68ff2e' \
  -X PUT \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/143'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.update_event :app-deploys, 143, description: 'Deployed git SHA 601060a68ff2e'
Not available

Response Code

204 No Content

Update the metadata of an annotation event.

HTTP Request

PUT https://metrics-api.librato.com/v1/annotations/:name/:id

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Annotation Event Parameters

The following parameters can be updated.

Parameter Definition
title Short description of annotation event.
description Long description of annotation event.
end_time Sets an end time for annotation events that occurred over a duration.
links An optional list of references to resources associated with the particular annotation. For example, these links could point to a build page in a CI system or a changeset description of an SCM. Each link has a tag that defines the link\’s relationship to the annotation.

Delete an Annotation

Delete the annotation stream api-deploys

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.delete :api-deploys
import librato
api = librato.connect(<user>, <token>)
api.delete_annotation_stream("api-deploys")

Response Code

204 No Content

Delete an annotation stream. This will delete all annotation events associated with the stream.

HTTP Request

DELETE https://metrics-api.librato.com/v1/annotations/:name

Delete an Annotation Event

Delete the annotation event 123 in the annotation stream app-deploys:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/123'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.delete_event :api-deploys, 123
Not available

Response Code

204 No Content

Delete an annotation event.

HTTP Request

DELETE https://metrics-api.librato.com/v1/annotations/:name/:id

Delete the link with the relationship github from the annotation event 189 in the annotation stream app-deploys:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/189/links/github'
Not available
Not available

Response Code

204 No Content

Delete a link from an annotation event.

HTTP Request

DELETE https://metrics-api.librato.com/v1/annotations/:name/:id/links/:link

List all Annotations

Return all annotation streams:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/annotations'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.list
import librato
api = librato.connect(<user>, <token>)
for stream in api.list_annotation_streams():
  print(stream.name)

Return all annotation streams matching the name api:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/annotations?name=api'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.list name: ('api')
import librato
api = librato.connect(<user>, <token>)
for stream in api.list_annotation_streams(name="api"):
  print(stream.name)

Response Code

200 OK

Response Body (all annotation streams)

{
  "query": {
    "found": 2,
    "length": 2,
    "offset": 0,
    "total": 2
  },
  "annotations": [
    {
      "name": "api-deploys",
      "display_name": "Deploys to API"
    },
    {
      "name": "app-deploys",
      "display_name": "Deploys to UX app"
    }
  ]
}

Return a list of annotation streams.

HTTP Request

GET https://metrics-api.librato.com/v1/annotations

Pagination Parameters

The response is paginated, so the request supports our generic Pagination Parameters. Specific to annotation streams, the default value of the orderby pagination parameter is name, and the permissible values of the orderby pagination parameter are: name.

Alerts

Alerts are used to build actionable responses to changes in metric measurements. Alerts define conditions on the input measurements and are triggered when the value(s) of the input measurements cross a threshold or stop reporting. For example, an alert could be used to notify an administrator that response time for a given service is elevated above an acceptable range.

The Alert Object

Alerts Properties

Alert Property Definition
id Each alert has a unique numeric ID.
name A unique name used to identify the alert. Must be 255 or fewer characters, and may only consist of A-Za-z0-9.:-. Dotted decimal notation (e.g. production.web.frontend.responsetime) is recommended.
version Optional. Identifies the alert as v1 or v2. Defaults to ‘2’. For v1 alerts (deprecated) this must be submitted as '1’.
conditions An array of conditions hashes (properties described in the overview). NOTE: conditions are required for PUT operations.
services An array of services to notify for this alert (sent as list of IDs).
attributes A key-value hash of metadata for the alert (described in alert attributes).
description A string describing this alert.
active Boolean: identifies whether the alert is active (can be triggered). Defaults to true.
rearm_seconds Specifies the minimum amount of time between sending alert notifications, in seconds. A notification will be sent once the alert is triggered, and then will not be sent again until the rearm timer has elapsed, even if more measurements are received that would trigger the alert. Required to be a multiple of 60, and when unset or null will default to 600 (10 minutes).

Alert Conditions

Each alert can have multiple alert conditions, each of which specifies a state which must be met for the alert to fire. Note an alert will fire when ALL alert conditions are met, not when a single condition is met.

We currently support three alert condition types:

Condition Definition
above Condition is met when the stream (metric/source pair) goes above the specified threshold.
absent Condition is met when the stream does not send a measurement for duration seconds.
below Condition is met when the stream goes below the specified threshold.

All alert conditions have the following properties:

Property Definition
type One of above, absent, or below.
metric_name The name of the metric this alert condition applies to.
source
optional
A source expression which identifies which sources for the given metric to monitor. If not specified all sources will be monitored. Wildcards can be used here (e.g. prod-* will include all sources that begin with prod-).
detect_reset boolean: If the summary_function is “derivative”, this toggles the method used to calculate the delta from the previous sample. When set to “false” (default), the delta is calculated as simple subtraction of current - previous.

If “true” only increasing (positive) values will be reported. Any time the current value is less than the previous it is considered a reset of the counter and a derivative of zero is reported. This field is ignored for any setting of summary_function other than “derivative”.

Additional properties for the 'above’ alert condition type:

Property Definition
threshold float: measurements over this number will fire the alert.
summary_function
optional
string: Indicates which statistic of an aggregated measurement to alert on.

For gauge metrics will default to “average”, which is also the “value” of non-complex or un-aggregated measurements. If set, must be one of: [min, max, average, sum, count, derivative]. See Instrument Stream Property summary_function for more details.

For counter metrics will default to “derivative”, which is the delta between the most recent measurement and the one before it. If set, must be one of: [derivative, absolute_value].
duration integer: Number of seconds that data for the specified metric/source combination must be above the threshold for before the condition is met. All data points within the given duration must be above the threshold to meet this condition. This avoids a single spike from triggering the condition.

If unset, a single sample above the threshold will trigger the condition. The tracking duration begins with samples received after the alert condition is created or updated. Must be >= 60 seconds and <= 3600 seconds.

Additional properties for the 'absent’ alert condition type:

Alert Property Definition
duration integer: How many seconds data for the specified metric/source combination must not be missing before the condition is met. This will only trigger for a given metric/source combination after a measurement has been seen at least once. Must be >= 60 seconds and <= 3600 seconds. (Required)

Additional properties for the 'below’ alert condition type:

Alert Property Definition
threshold float: measurements below this number will fire the alert. (Required)
summary_function string: Indicates which statistic of an aggregated measurement to alert on.

For gauge metrics will default to “average”, which is also the “value” of non-complex or un-aggregated measurements. If set, must be one of: [min, max, average, sum, count, derivative]. See Instrument Stream Property summary_function for more details.

For counter metrics will default to “derivative”, which is the delta between the most recent measurement and the one before it. If set, must be one of: [derivative, absolute_value].
duration integer: Number of seconds that data for the specified metric/source combination must be below the threshold for before the condition is met. All data points within the given duration must be below the threshold to meet this condition. This avoids a single drop from triggering the condition.

If unset, a single sample below the threshold will trigger the condition. The tracking duration begins with samples received after the alert condition is created or updated. Must be >= 60 seconds and <= 3600 seconds.

Alert Attributes

The attributes field on the alert accepts an optional map of key-value pairs and allows metadata to be associated with the alert. Some keys are used for special behavior:

Attribute Definition
runbook_url a URL for the runbook to be followed when this alert is firing. Used in the Librato UI if set.

Attributes can be unset by excluding their key when updating an alert.

Create an Alert

Create an alert named production.web.frontend.response_time with one condition which monitors the metric web.nginx.response_time and alerts whenever the value goes over 200.

When the alert is triggered, the service identified by ID 849 (a Slack channel in this case) will be notified.

Not available
import librato
api = librato.connect(<user>, <token>)
alert = api.create_alert("production.web.frontend.response_time")
alert.add_condition_for('web.nginx.response_time').above(200)
alert.add_service("849")
alert.save()

#alternatively (trigger if max value is over 200 for 5min):
alert = api.create_alert(
    name="production.web.frontend.response_time",
    description="Web Response Time",
    version=2,
    services=["849"],
    attributes={"runbook_url":"http://mydomain.com/wiki/whattodo"},
    conditions=[
        {"metric_name":'web.nginx.response_time',
        "condition_type":'above',
        "threshold":200,
        "summary_function":'max',
        "duration":300}])

JSON Request used to create alert:

{
  "name": "production.web.frontend.response_time",
  "conditions": [
    {
      "type": "above",
      "threshold": 200,
      "metric_name": "web.nginx.response_time"
    }
  ],
  "services": [
    849
  ],
  "attributes": {
    "runbook_url": "http://myco.com/runbooks/response_time"
  },
  "version": 2
}

Response Code

201 Created

Response Headers

Location: /v1/alerts/123

Response Body

{
  "id": 123,
  "name": "production.web.frontend.response_time",
  "conditions": [
    {
      "type": "above",
      "threshold": 200,
      "metric_name": "web.nginx.response_time"
    }
  ],
  "services": [
    {
      "id": 849,
      "title": "Notify Slack Channel",
      "name": "slack"
    }
  ],
  "attributes": {
    "runbook_url": "http://myco.com/runbooks/response_time"
  },
  "active": true,
  "version": 2
}

Create an alert by setting the condition array parameters by providing a metric_name, threshold, and condition type.

HTTP Request

POST https://metrics-api.librato.com/v1/alerts

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
name A unique name used to identify the alert. Must be 255 or fewer characters, and may only consist of 'A-Za-z0-9.:-’. Dotted decimal notation (e.g. production.web.frontend.responsetime) is recommended.
version Optional. Can be set to 1 or 2 and dictates whether to return v1 (deprecated) or v2 alerts. If unspecified, v2 alerts will be returned.
conditions An array of conditions hashes (properties described in the overview).

NOTE: Conditions are required for PUT operations.
services An array of services to notify for this alert (sent as list of IDs).
attributes
optional
A key-value hash of metadata for the alert (described in alert attributes).
description
optional
A string describing this alert.
active
optional
Boolean: identifies whether the alert is active (can be triggered). Defaults to true.
rearm_seconds
optional
Specifies the minimum amount of time between sending alert notifications, in seconds. A notification will be sent once the alert is triggered, and then will not be sent again until the rearm timer has elapsed, even if more measurements are received that would trigger the alert. Required to be a multiple of 60, and when unset or null will default to 600 (10 minutes).

Retrieve an Alert

Return alert with the id 123

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/alerts/123'
Not available
import librato
api = librato.connect(<user>, <token>)
alerts = api.list_alerts(id="123")
for a in alerts:
  print(a.name)

Response Code

200 OK

Response Body

{
  "id": 123,
  "name": "production.web.frontend.response_time",
  "conditions": [
    {
      "type": "above",
      "threshold": 200,
      "metric_name": "web.nginx.response_time"
    }
  ],
  "services": [
    {
      "id": 849,
      "title": "Notify Slack Channel",
      "name": "slack"
    }
  ],
  "attributes": {
    "runbook_url": "http://myco.com/runbooks/response_time"
  },
  "active": true,
  "version": 2
}

Return all alerts owned by the user with production in the name:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/alerts?name=production'
Not available
import librato
api = librato.connect(<user>, <token>)
alerts = api.list_alerts(name="production")
for a in alerts:
  print(a.name)

Response Code

200 OK

Response Body

{
  "query": {
    "found": 1,
    "length": 1,
    "offset": 0,
    "total": 1
  },
  "alerts": [
    {
      "id": 123,
      "name": "production.web.frontend.response_time",
      "conditions": [
        {
          "type": "above",
          "threshold": 200,
          "metric_name": "web.nginx.response_time"
        }
      ],
      "services": [
        {
          "id": 849,
          "title": "Notify Slack Channel",
          "name": "slack"
        }
      ],
      "attributes": {
        "runbook_url": "http://myco.com/runbooks/response_time"
      },
      "active": true,
      "version": 2
    }
  ]
}

Return the details of an alert (or group of alerts) by providing the id or name.

Retrieve Status of Specific Alert

Return the status for alert ID 120:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/alerts/120/status'
Not available
Not available

Response for an alert that is triggered:

{
    "alert": {
        "id": 120
    },
    "status": "triggered"
}

Response for an alert that is not triggered:

{
    "alert": {
        "id": 121
    },
    "status": "ok"
}

Returns the status for a particular alert, specified by ID.

HTTP Request

GET https://metrics-api.librato.com/v1/alerts/:alert_id/status

Update an Alert

NOTE: This method requires the conditions hash. If conditions is not included in the payload, the alert conditions will be removed.

To disable an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"active": false, "name": "my.alert.name", "description": "Process went down", "conditions": [{"type": "absent", "metric_name": "service.alive", "source": "*", "duration": 900}]}' \
"https://metrics-api.librato.com/v1/alerts/123"
Not available
import librato
api = librato.connect(<user>, <token>)
alert = api.get_alert("my.alert.name")
alert.active = "false"
alert.save()

To enable an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"active": true, "name": "my.alert.name", "description": "Process went down", "conditions": [{"type": "absent", "metric_name": "service.alive", "source": "*", "duration": 900}]}' \
"https://metrics-api.librato.com/v1/alerts/123"
Not available
import librato
api = librato.connect(<user>, <token>)
alert = api.get_alert("my.alert.name")
alert.active = "true"
alert.save()

Update the description of an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"description": "A new description", "name": "my.alert.name", "conditions": [{"type": "absent", "metric_name": "service.alive", "source": "*", "duration": 900}], "active": true}' \
"https://metrics-api.librato.com/v1/alerts/123"
Not available
import librato
api = librato.connect(<user>, <token>)
alert = api.get_alert("my.alert.name")
alert.description = "A new description"
alert.save()

Update the runbook URL for an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"attributes": {"runbook_url": "http://google.com"}, "name": "my.alert.name", "description": "A process went down.", "conditions": [{"type": "absent", "metric_name": "service.alive", "source": "*", "duration": 900}], "active": true}' \
"https://metrics-api.librato.com/v1/alerts/123"
Not available
Not available

Response Code

204 No Content

Update the specified alert.

HTTP Request

PUT https://metrics-api.librato.com/v1/alerts/:id

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
name A unique name used to identify the alert. Must be 255 or fewer characters, and may only consist of A-Za-z0-9.:-. Dotted decimal notation (e.g. production.web.frontend.responsetime) is recommended.
version Optional. Identifies the alert as v1 or v2. Defaults to '2’. For v1 alerts (deprecated) this must be submitted as '1’.
conditions An array of conditions hashes (properties described in the overview). NOTE: conditions are required for PUT operations.
services An array of services to notify for this alert (sent as list of IDs).
attributes
optional
A key-value hash of metadata for the alert (described in alert attributes).
description
optional
A string describing this alert.
active
optional
Boolean: identifies whether the alert is active (can be triggered). Defaults to true.
rearm_seconds
optional
Specifies the minimum amount of time between sending alert notifications, in seconds. A notification will be sent once the alert is triggered, and then will not be sent again until the rearm timer has elapsed, even if more measurements are received that would trigger the alert. Required to be a multiple of 60, and when unset or null will default to 600 (10 minutes).

Notification Services

Librato provides many notification services to alert your team by when an alert is triggered. At least one (but not lmiited to one) service must be tied to each alert.

Associate a Service with an Alert

Add the service identified by ID 290 to the alert “my.alert.name” (ID 45). When the alert is triggered, the service 290 will be notified.

Note: To get a list of created services, view the section on Retrieving all services.

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'service=290' \
  -X POST \
  'https://metrics-api.librato.com/v1/alerts/45/services'
Not available
Not available
alert = api.get_alert("my.alert.name")
alert.add_service("290")
alert.save()

Response Code

201 Created

Headers

Location: /v1/alerts/45/services/209

Associates a single service with the alert identified by :alert_id.

HTTP Request

POST https://metrics-api.librato.com/v1/alerts/:id/services

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

This route accepts a single parameter service that should be set to the ID of the service to associate with this alert.

Remove a Service from an Alert

HTTP Request

DELETE https://metrics-api.librato.com/v1/alerts/:alert_id/services/:id

Remove service 209 from alert 123. From then on when alert 123 is triggered, the service 209 will no longer be triggered.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/alerts/123/services/209'
Not available
Not available

Response Code

204 No Content

Remove the service identified by :id from the alert identified by :alert_id.

Resolve an Alert

Resolve alert ID 120:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X POST \
  'https://metrics-api.librato.com/v1/alerts/120/clear'
Not available
Not available

Response Code

204 No Content

Clears the alert specified using the alert id.

HTTP Request

POST https://metrics-api.librato.com/v1/alerts/:alert_id/clear

Delete Alert

Delete the alert id 123

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/alerts/123'
Not available
import librato
api = librato.connect(<user>, <token>)
api.delete_alert("alert_name")

Response Code

204 No Content

Delete an alert by specifying a unique id or name.

HTTP Request

DELETE https://metrics-api.librato.com/v1/alerts/:id

List all Alerts

List the status of all alerts:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/alerts/status'
Not available
Not available

Response Body

{
    "cleared": [
        {
            "cleared_at": 1454108320,
            "id": 127
        }
    ],
    "firing": [
        {
            "id": 106,
            "triggered_at": 1413328283
        },
        {
            "id": 129,
            "triggered_at": 1444934147
        }
    ]
}

Returns a list of alert ids, grouped by those belonging to alerts which are in a triggered state and by those that have recently cleared.

HTTP Request

GET https://metrics-api.librato.com/v1/alerts

Pagination Parameters

The response is paginated, so the request supports our generic Pagination Parameters. Specific to alerts, the default value of the orderby pagination parameter is updated_at, and the permissible values of the orderby pagination parameter are: updated_at.

Other Parameters

Parameter Definition
version Optional. Can be set to 1 or 2 and dictates whether to return v1 (deprecated) or v2 alerts. If unspecified, v2 alerts will be returned.
name A search parameter that limits the results to metrics whose names contain a matching substring. Search is case-insensitive.

API Tokens

API Tokens are used for authenticating with the API. They are used in combination with your normal login as part of a standard HTTP Basic Auth payload. See Authentication for more details on how to authenticate to the API with a token.

You may have as many API Tokens as you like to help limit your exposure to single compromised token. If you happen to accidentally lose control of a token by emailing it or pasting it on a website, it is convenient to deactivate or delete that token, rendering it inoperable for authentication, without interfering with the operation of other agents or clients using other tokens. We recommend having as many API Tokens as is convenient for each client or group of clients to have their own.

API Token Properties

Property Definition
name A name for the API Token. There is no limit on length or uniqueness, so use whatever naming scheme makes it easiest for you to keep them organized. Name may be null for any legacy or auto generated tokens, but it is required for any new tokens created.
token A long random string of characters to be used as the “password” segment of the basic auth header. This is auto-generated, and any attempt to set it will be ignored.
active A true/false value indicating the ability of a Token to be used for authentication. Attempting to authenticate using a token that has active set to false will result in a 401 response.
role The name of the role that encapsulates the permissions this token has. Must be one of: “admin”, “recorder”, or “viewer”. See the Knowledge Base Article for more details.

Create a Token

HTTP Request

POST https://metrics-api.librato.com/v1/api_tokens

Create a new API Token by specifying the name and role:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=My New Token&role=admin' \
  -X POST \
  'https://metrics-api.librato.com/v1/api_tokens'
Not available

Using JSON

{
  "name": "My New Token",
  "role": "admin"
}

Response Code

201 Created

Response Headers

Location: /v1/api_tokens/28

Response Body

{
  "name": "My New Token",
  "token": "24f9fb2134399595b91da1dcac39cb6eafc68a07fa08ad3d70892b7aad10e1cf",
  "active": true,
  "role": "admin",
  "href": "http://api.librato.dev/v1/api_tokens/28",
  "created_at": "2013-02-01 18:53:38 UTC",
  "updated_at": "2013-02-01 18:53:38 UTC"
}

Creates a new API Token.

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Retrieve a Token

Retrieve a token that contains the word “token” within the name parameter:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/api_tokens?name=*token*'

Response Code

200 OK

Response Body

{
  "api_tokens": [
    {
      "name": "Token for collectors",
      "token": "24f9fb2134399595b91da1dcac39cb6eafc68a07fa08ad3d70892b7aad10e1cf",
      "active": true,
      "role": "recorder",
      "href": "http://metrics-api.librato.com/v1/api_tokens/28",
      "created_at": "2013-02-01 18:53:38 UTC",
      "updated_at": "2013-02-01 18:53:38 UTC"
    },
    {
      "name": "Token that has been disabled",
      "active": false,
      "role": "viewer",
      "href": "http://metrics-api.librato.com/v1/api_tokens/29",
      "token": "d1ffbbbe327c6839a71023c2a8c9ba921207e32e427a49fb221843d74d63f7b8",
      "created_at": "2013-02-01 18:54:28 UTC",
      "updated_at": "2013-02-01 18:54:28 UTC"
    }
  ],
    "query": {
        "found": 2,
        "length": 2,
        "offset": 0,
        "total": 2
    }
}

Returns the details for API Tokens that match a name. Supports wildcards, e.g. ? name=*token*. Omitting a wild card will automatically add them, so querying ?name=foo.bar will return foo.bar and foo.bar.bazzle.

HTTP Request

GET https://metrics-api.librato.com/v1/api_tokens/:name

Retrieve a Token by ID

Retrieve the token with the id 28:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/api_tokens/28'

Response Code

200 OK

Response Body

{
  "name": "My New Token",
  "token": "24f9fb2134399595b91da1dcac39cb6eafc68a07fa08ad3d70892b7aad10e1cf",
  "active": true,
  "role": "admin",
  "href": "http://api.librato.dev/v1/api_tokens/28",
  "created_at": "2013-02-01 18:53:38 UTC",
  "updated_at": "2013-02-01 18:53:38 UTC"
}

Returns the details for a specific API Token by providing the id of the token. The id can be found in the URL of the href parameter provided when listing all API tokens.

HTTP Request

GET https://metrics-api.librato.com/v1/api_tokens/:id

Update a Token

Update the token associated with the id 28:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=New Token Name&active=false&role=admin' \
  -X PUT \
  'https://metrics-api.librato.com/v1/api_tokens/28'
Not available
Not available

Response Code

200 OK

Response Body

{
  "name": "New Token Name",
  "token": "24f9fb2134399595b91da1dcac39cb6eafc68a07fa08ad3d70892b7aad10e1cf",
  "active": false,
  "role": "admin",
  "href": "http://api.librato.dev/v1/api_tokens/28",
  "created_at": "2013-02-01 18:53:38 UTC",
  "updated_at": "2013-02-01 19:51:22 UTC"
}

Modify an API Token, such as changing the name, or flagging as active/inactive.

HTTP Request

PUT https://metrics-api.librato.com/v1/api_tokens/:id

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Delete a Token

Delete the API token with ID 28:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/api_tokens/28'
Not available

Response Code

204 No Content

Delete the API Token identified by :id.

HTTP Request

DELETE https://metrics-api.librato.com/v1/api_tokens/:id

List all Tokens

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/api_tokens'
Not available

Response Code

200 OK

Response Body

{
  "query": {
    "found": 3,
    "length": 3,
    "offset": 0,
    "total": 3
  },
  "api_tokens": [
    {
      "name": null,
      "token": "9b593b3dff7cef442268c3056625981b92d5feb622cfe23fef8d716d5eecd2c3",
      "active": true,
      "role": "admin",
      "href": "http://metrics-api.librato.com/v1/api_tokens/2",
      "created_at": "2013-01-22 18:08:15 UTC",
      "updated_at": "2013-01-22 18:08:15 UTC"
    },
    {
      "name": "Token for collectors",
      "token": "24f9fb2134399595b91da1dcac39cb6eafc68a07fa08ad3d70892b7aad10e1cf",
      "active": true,
      "role": "recorder",
      "href": "http://metrics-api.librato.com/v1/api_tokens/28",
      "created_at": "2013-02-01 18:53:38 UTC",
      "updated_at": "2013-02-01 18:53:38 UTC"
    },
    {
      "name": "Token that has been disabled",
      "active": false,
      "role": "viewer",
      "href": "http://metrics-api.librato.com/v1/api_tokens/29",
      "token": "d1ffbbbe327c6839a71023c2a8c9ba921207e32e427a49fb221843d74d63f7b8",
      "created_at": "2013-02-01 18:54:28 UTC",
      "updated_at": "2013-02-01 18:54:28 UTC"
    }
  ]
}

Returns all API Tokens.

HTTP Request

GET https://metrics-api.librato.com/v1/api_tokens

Jobs

Some resources in the Librato API allow you to make requests which will take longer to complete than is reasonable for a single request-response cycle. These resources will respond with a job which you can use to follow progress and final state of the request.

Requests which start jobs will respond with an HTTP status code of 202 Accepted. They will also include the URI to query for job status as a Location: response header.

Job Properties

Jobs can be queried for their current state and other status information. They have the following properties:

Property Definition
id Each job has a unique numeric ID.
state Reflects the current status of the job, will be one of queued, working, complete failed, or canceled.
progress
optional
a floating point number from 0.0-100.0 reflecting how close to completion the job is currently.
output
optional
if the job results in output it will be available in this field.
errors
optional
if the job results in any errors they will be available in this field.

Retrieve a Job

Check status for job qith the id 123456:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/jobs/123456'
Not available

Response properties may vary depending on the state of the job. Some jobs may only report id and state, so you are encouraged to consider state authoritative rather than relying on the presence of other properties (errors or progress for example).

Job in progress:

{
  "id": 123456,
  "state": "working",
  "progress": 31.56
}

Job which has completed successfully:

{
  "id": 123456,
  "state": "complete",
  "progress": 100.0
}

A queued job which has not started yet:

{
  "id": 123456,
  "state": "queued"
}

A job that has failed:

{
  "id": 123456,
  "state": "failed",
  "errors": {
    "name": [
      "is invalid"
    ]
  }
}

Returns information for a specific job. All jobs will return their id and state. Some jobs may also return one or more optional properties.

HTTP Request

GET https://metrics-api.librato.com/v1/jobs/:id

About Jobs

Jobs are spawned by other resources in the Librato API when an operation will take longer to complete than is allowed by a single request-response cycle.

Snapshots

Snapshots provide the ability to capture a point-in-time image of a given chart as a PNG file to share with collaborators via email and/or chat applications such as Slack, Campfire, HipChat, and Flowdock.

Snapshot Properties

Property Definition
href A link to the representation of the snapshot.
job_href A link to the representation of the background job created to process the snapshot.
image_href A link to the PNG file of the snapshot. Initially null until background job has processed rendering.
duration Time interval of the snapshot, in seconds.
end_time Time indicating the end of the interval.
created_at Time the snapshot was created.
updated_at Time the snapshot was updated.
subject The subject chart of the snapshot.

Create a Snapshot

Create a snapshot of a stacked chart associated with the id of 1:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'subject[chart][id]=1&subject[chart][source]=*&subject[chart][type]=stacked' \
  -X POST \
  'https://metrics-api.librato.com/v1/snapshots'
Not available

Response Code

202 Accepted

Response Headers

Location: /v1/snapshots/:id

Response Body

{
  "href": "https://metrics-api.librato.com/v1/snapshots/1",
  "job_href": "https://metrics-api.librato.com/v1/jobs/123456",
  "image_href": "http://snapshots.librato.com/chart/tuqlgn1i-71569.png",
  "duration": 3600,
  "end_time": "2016-02-20T01:18:46Z",
  "created_at": "2016-02-20T01:18:46Z",
  "updated_at": "2016-02-20T01:18:46Z",
  "subject": {
    "chart": {
      "id": 1,
      "sources": [
        "*"
      ],
      "type": "stacked"
    }
  }
}

Create a new snapshot by providing the subject parameters (associated with the chart). The parameters of the chart array include id, source, and chart type.

HTTP Request

POST https://metrics-api.librato.com/v1/snapshots

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
subject The subject chart of the snapshot, e.g., {"chart":{"id": 1, "source": "*", "type": "stacked"}}.
duration
optional
Time interval over which to take the snapshot, in seconds. Defaults to 3600 (1 hour).
end_time
optional
Time indicating the end of the interval. Defaults to present.

Subject Parameters

Parameter Definition
id Each chart has a unique numeric ID.
source Indicates the source of data for the chart. Wildcard * to include all sources.
type Indicates the type of chart. One of line, stacked or bignumber.

Retrieve a Snapshot

Return the snapshot with the id 1.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/snapshots/1'
Not available

Response Code

200 OK

Response Body

{
  "href": "https://metrics-api.librato.com/v1/snapshots/1",
  "job_href": "https://metrics-api.librato.com/v1/jobs/123456",
  "image_href": "http://snapshots.librato.com/chart/tuqlgn1i-71569.png",
  "duration": 3600,
  "end_time": "2016-02-20T01:18:46Z",
  "created_at": "2016-02-20T01:18:46Z",
  "updated_at": "2016-02-20T01:18:46Z",
  "subject": {
    "chart": {
      "id": 1,
      "sources": [
        "*"
      ],
      "type": "stacked"
    }
  }
}

Returns a specific snapshot associated with an id.

HTTP Request

GET https://metrics-api.librato.com/v1/snapshots/:id

Services

Services define the actions that are taken when an alert is triggered. Example actions might include: sending an email, notifying a real-time chat room, or hitting an external web hook with a POST.

A single service can be shared across multiple alerts. This allows for a single service to be configured and reused on multiple alerts without having to copy the service details. Similarly, a single alert can notify multiple services of the same type. For example, a single alert could notify multiple real-time chat rooms.

Each service is chosen from a set of supported back end services. The supported services are implemented in the Librato Services Github repository. Users are encouraged to contribute new services.

Service Properties

Property Definition
id Each service has a unique numeric ID.
type The service type (e.g. Campfire, Pagerduty, mail, etc.). See an extensive list of services here.
settings Hash of settings specific to the service type.
title Display title for the service.

Pagination Parameters

The response is paginated, so the request supports our generic Pagination Parameters. Specific to services, the default value of the orderby pagination parameter is title, and the permissible values of the orderby pagination parameter are: title and updated_at.

Create a Service

Create a service that notifies the campfire room Ops:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=Notify Ops Room&type=campfire&settings%5Btoken%5D=1234567890ABCDEF&settings%5Broom%5D=Ops&settings%5Bsubdomain%5D=acme' \
  -X POST \
  'https://metrics-api.librato.com/v1/services'
Not available
Not available

Response Code

201 Created

Response Headers

Location: /v1/services/145

Response Body

{
  "id": "145",
  "type": "campfire",
  "settings": {
    "room": "Ops",
    "token": "1234567890ABCDEF",
    "subdomain": "acme"
  },
  "title": "Notify Ops Room"
}

Creates a notification service for alerts to notify by when triggered. View the support documentation for a full list of supported services. Once created you will need to associate a service with an alert in order for an alert to trigger it.

HTTP Request

POST https://metrics-api.librato.com/v1/services

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
title Display title for the service.
type The service type (e.g. Campfire, Pagerduty, mail, etc.). See an extensive list of services here.
settings Hash of settings specific to the service type.

Retrieve a Service

Return the service 156:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/services/156'
Not available
Not available

Response Code

200 OK

Response Body

{
  "id": "156",
  "type": "mail",
  "settings": {
    "addresses": "george@example.com,fred@example.com"
  },
  "title": "Email ops team"
}

Returns the specific service associated to the provided service id.

HTTP Request

GET https://metrics-api.librato.com/v1/services/:id

Update a Service

Update the title for service 145:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=Notify Ops Chatroom' \
  -X PUT \
  'https://metrics-api.librato.com/v1/services/145'
Not available
Not available

Response Code

204 No Content

Updates a service by specifying the service id.

HTTP Request

PUT https://metrics-api.librato.com/v1/services/:id

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameter Definition
title Display title for the service.
type The service type (e.g. Campfire, Pagerduty, mail, etc.). See an extensive list of services here.
settings Hash of settings specific to the service type.

Delete a Service

Delete the service 145:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/services/145'
Not available
Not available

Response Code

204 No Content

Delete the service referenced by :id. It will automatically be removed from any alert that is currently using it.

HTTP Request

DELETE https://metrics-api.librato.com/v1/services/:id

List all Services

Return all services:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/services'
Not available
import librato
api = librato.connect(<user>, <token>)
services = api.list_services()
for s in services:
  print(s._id, s.title, s.settings)

Response Code

200 OK

Response Body

All services (when there are two total):

{
  "query": {
    "found": 2,
    "length": 2,
    "offset": 0,
    "total": 2
  },
  "services": [
    {
      "id": "145",
      "type": "campfire",
      "settings": {
        "room": "Ops",
        "token": "1234567890ABCDEF",
        "subdomain": "acme"
      },
      "title": "Notify Ops Room"
    },
    {
      "id": "156",
      "type": "mail",
      "settings": {
        "addresses": "george@example.com,fred@example.com"
      },
      "title": "Email ops team"
    }
  ]
}

Returns a list of outbound services that are created within the user’s account.

HTTP Request

GET https://metrics-api.librato.com/v1/services

Sources

When submitting a measurement to Librato, in addition to specifying the metric name you can optionally specify a source name as additional metadata. This is useful when you are tracking the same metrics across a set of homogeneous entities.

For example, you can specify the server instances in a cluster (source name => hostname) or sensors in a grid (source name => MAC address).

For more information on sources and how they can be leveraged, check out this knowledge base article.

Source Properties

Properties Definition
name The name of the source.
display_name Human readable name to use in place of the actual source name. Maximum length 255 characters.

Create a Source

Update an existing source i-d32d61af by setting the display_name to web-frontend-0:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'display_name=web-frontend-0' \
  -X PUT \
  'https://metrics-api.librato.com/v1/sources/i-d32d61af'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_source "i-d32d61af", display_name: "web-frontend-0"

Response Code

204 No Content

Create a source name foo.bar.com (assumes this source does not exist):

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'display_name=FooBar' \
  -X PUT \
  'https://metrics-api.librato.com/v1/sources/foo.bar.com'
Not available

Response Code

201 Created

Response Headers

Location: /v1/sources/foo.bar.com

Response Body

{
  "name": "foo.bar.com",
  "display_name": "FooBar"
}

Creates or updates the source identified by :name. If the source name does not exist, the source will be created with the associated properties. If the source already exists, properties will be updated.

Typically sources are created the first time a measurement for a given source is sent to the collated POST route.

HTTP Request

PUT https://metrics-api.librato.com/v1/sources/:name

Headers

This specifies the format of the data sent to the API.

For HTML (default):

Content-Type: application/x-www-form-urlencoded

For JSON:

Content-Type: application/json

Parameters

Parameter Definition
name Each metric has a name that is unique to its class of metrics e.g. a gauge name must be unique amongst gauges. The name identifies a metric in subsequent API calls to store/query individual measurements and can be up to 255 characters in length. Valid characters for metric names are A-Za-z0-9.:-_. The metric namespace is case insensitive.
display_name
optional
Human readable name to use in place of the actual source name. Maximum length 255 characters.

Retrieve a Source

Return the source named foo.bar.com:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/sources/foo.bar.com'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_source "foo.bar.com"

Response Code

200 OK

Response Body

{
  "name": "foo.bar.com",
  "display_name": "FooBar"
}

Returns the current representation of the source identifed by name.

HTTP Request

GET https://metrics-api.librato.com/v1/sources/:name

List all Sources

Return all sources:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/sources'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.sources

Return all sources owned by the user with name matching example:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/sources?name=example'
require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.sources name: "example"

Response Code

200 OK

Response Body

{
  "query": {
    "found": 4,
    "length": 4,
    "offset": 0,
    "total": 15
  },
  "sources": [
    {
      "name": "prod.example.com",
      "display_name": null
    },
    {
      "name": "stg1.example.com",
      "display_name": "Staging 1"
    },
    {
      "name": "stg2.example.com",
      "display_name": "Staging 2"
    },
    {
      "name": "foo.bar.com",
      "display_name": "Example Source"
    }
  ]
}

Returns all sources created by the user.

HTTP Request

GET https://metrics-api.librato.com/v1/sources

Pagination Parameters

The response is paginated, so the request supports our generic Pagination Parameters. Specific to sources, the default value of the orderby pagination parameter is name, and the permissible values of the orderby pagination parameter are: name.

Parameter Definition
name Searches both the names and display_names of the source. Case-insensitive.