Introduction

API Libraries

There are many collection agents and language bindings for Librato. This guide includes examples 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.

Submit a measurement for the gauge metric cpu:

JSON

curl -H "Content-Type: application/json" \
     -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
     -d $'
     {
       "gauges": [
         {
           "name": "cpu",
           "value": 75,
           "source": "my.machine"
         }
       ]
     }' \
    -X POST \
    https://metrics-api.librato.com/v1/metrics

Form Encoded

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'gauges[0][name]=cpu' \
  -d 'gauges[0][value]=75' \
  -d 'gauges[0][source]=my.machine' \
  -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: {source: 'my.machine', value: 75}

import librato
api = librato.connect(<user>, <token>)
api.submit("cpu", 75, source='my.machine')

Retrieve the last 5 measurements from the metric cpu at a resolution of 60 seconds. This will return measurement data along with metric metadata.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/metrics/cpu?count=5&resolution=60'

require "librato/metrics"
Librato::Metrics.authenticate ENV['LIBRATO_USERNAME'], ENV['LIBRATO_TOKEN']
metric = Librato::Metrics.get_metric :cpu, count: 5, resolution: 60
puts metric["measurements"]

import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu", count=5, resolution=60)
print(metric.measurements)

Welcome to the official reference for the Librato Application Programming Interface (API). Detailed documentation for authentication and each individual API call can be accessed through the menu.

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:

• 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).

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.

JSON

curl -H "Content-Type: application/json" \
     -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
     -d $'
     {
       "measure_time": 1481637660,
       "source": "my.app",
       "gauges": [
         {
           "name": "my.metric",
           "value": 42
         },
         {
           "name": "my.other.metric",
           "value": 43
         },
         {
           "name": "cpu",
           "value": 88.4,
           "source": "my.machine",
           "measure_time": 1481637540
         }
       ]
     }' \
    -X POST \
    https://metrics-api.librato.com/v1/metrics

Form Encoded

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'measure_time=1481637660' \
  -d 'source=my.app' \
  -d 'gauges[0][name]=my.metric' \
  -d 'gauges[0][value]=42' \
  -d 'gauges[1][name]=my.other.metric' \
  -d 'gauges[1][value]=43' \
  -d 'gauges[2][name]=cpu' \
  -d 'gauges[2][value]=88.4' \
  -d 'gauges[2][source]=my.machine' \
  -d 'gauges[2][measure_time]=1481637540' \
  -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 `measuretime` 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_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_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_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_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_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_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_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_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.

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_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_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.

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. Set this to false

if working with sources on the legacy version.

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' \
  -d 'tags=false' \
  -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 Link From Annotation Event

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 alert names matching the 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.