NAV
cURL Ruby Python

Introduction

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

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

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

Authentication

Example Request

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(example@librato.com, 75AFDB82)

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.

Partner Admin Access

Example Request

curl -u <user email>:<partner admin token> https://metrics-api.librato.com/v1/metrics

To administrate a user account created via the partner API, select the user’s email address and use your partner admin user’s token as the API token.

See the Managing Users section of the partner API for more information.

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 (eg. 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.
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.
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

Error Message Structure

Errors related to parameters are reported based on the attribute the error occurred on.

{
  "errors": {
    "params": {
      "name":["is not present"],
      "start_time":["is not a number"]
    }
  }
}

Errors related to the request itself are reported in an array structure with the key request.

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

Service errors due to maintenance periods, for example, are reported in an array structure with the key system:

{
  "errors": {
    "system": [
      "The API is currently down for maintenance. It'll be back shortly."
    ]
  }
}

The API reports errors in a the JSON format which makes it easier to parse and evaluate them. As of now, there are two kinds of errors: params and request.

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

Example Request

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

curl \
  -u <user>:<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:

Code: 200
Headers: not applicable

Response Body:

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

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

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

Response Parameters

Example Request

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

curl \
  -u <user>:<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:

Code: 200
Headers: not applicable

Response Body:

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

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

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

Metrics

Overview

Metrics are custom measurements stored in Librato’s Metrics service. These measurements are created and may be accessed programatically 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 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.
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 amongst multiple members of a population. For example the number of requests/second serviced by an application could be broken up amongst 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:

Retrieve Metrics

Definition

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

Example Request

Retrieve all metrics:

curl \
  -i \
  -u <user>:<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()

Retrieve all metrics pertaining to a request:

curl \
  -i \
  -u <user>:<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")

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

curl \
  -i \
  -u <user>:<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 Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body for all metrics (when there are two total):

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

Metrics corresponding to requests (when one of the two metrics measure requests):

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

Composite query results for displaying the result of the derive() function over the idle CPU time.

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

Composite Metric Query Execution

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.

Retrieve Metric by Name

Definition

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

Example Request: Return metadata for the metric cpu_temp:

curl \
  -i \
  -u <user>:<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 Code:

200 OK

Response Headers:

** NOT APPLICABLE **

Response Body:

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

Example Request

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

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

Response Body:

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

Example Request

Return the metric cpu_temp with measurements from the source server*:

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

Response Body:

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

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

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

Response Body:

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

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.

Measurement Search Parameters

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 identifed 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 maxiums 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).

Pagination

Example Request

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

curl \
  -i \
  -u <user>:<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.

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.

Submit Metrics

Definition

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

Example Request

This creates a total of three 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.

Default measure_time and source:

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

Response Code:

200 Success

Response Body:

** NOT APPLICABLE **

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

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

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Measurement Parameters

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

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

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

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

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

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

Gauge Specific Parameters

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

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

Example Request:

The example 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

For example:

{
  "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)

For example, the following JSON message 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.

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

Update Metric

Definition

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

Example Request

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

curl \
  -u <user>:<token> \
  -d 'names%5B%5D=cpu&names%5B%5D=servers&names%5B%5D=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)

Example Request

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

curl \
  -u <user>:<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

Response Body

** NOT APPLICABLE **

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 Metric by Name

Definition

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

Example Request

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

curl \
  -u <user>:<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

Response Body

** NOT APPLICABLE **

Example Request

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

curl \
  -u <user>:<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"
  }
}

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 Metric

Definition

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

Example Request

Delete the metrics cpu, servers and reqs:

curl \
  -u <user>:<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 <user>:<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

Response Body

** NOT APPLICABLE **

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 wilcards (*).

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 Metric by Name

Definition

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

Example Request

Delete the metric named app_requests.

curl \
  -i \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

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.

Metric Attributes

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

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

The following sections list the available metric attributes.

Display Attributes

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

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

Gauge-only attributes

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

curl \
  -u <user>:<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 <user>:<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.

Spaces

Overview

Spaces contain a collection of charts that graph one or more metrics in real time.

Space Properties

Property Definition
id Each space has a unique numeric ID
name Unique name for space

Retrieve All Spaces

Definition

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

Retrieve all spaces.

curl \
  -i \
  -u <user>:<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 <user>:<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.

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.

Retrieve Details of Space

Definition

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

Return the details of a Space with ID 129:

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

Response Body

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

Returns the details of a specific space.

Create a Space

Definition

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

Example Request

Create a space with name CPUs:

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

Using JSON

{
  "name": "CPUs"
}

Response Code

201 Created

Response Headers

Location: /v1/spaces/129

Response Body

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

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

Modify a Space

Definition

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

Example Request

Change the name of the space to MEMORY:

curl \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Modifies a space by changing its 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

Delete Space

Definition

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

Example Request

Delete the space with ID 129:

curl \
  -i \
  -u <user>:<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

Response Body

** NOT APPLICABLE **

Delete the space identified by :id.

Charts

Overview

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 accomodates multiple charts.

Retrieve Chart by ID

Definition

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

Return chart by id and space id.

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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.

Retrieve Charts in Space

Definition

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

List all charts in a Space with ID 129.

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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.

Create a Chart

Definition

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

Example Request

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

curl \
-u <user>:<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, 
    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"
    }
  ]
}

Example Request

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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

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

Update Chart Attributes

Definition

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

Example Request

Update a chart name to Temperature:

curl \
  -u <user>:<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

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Updates attributes of a specific chart.

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 visualizaton.
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 Chart

Definition

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

Delete the chart ID 123.

curl \
  -i \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Delete the specified chart.

Annotations

Overview

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 meta-data 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 streams have the following 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 meta-data that describe the particular event in more detail or reference an external site.

Annotation events have the following 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 meta-data 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.

Retrieve Annotations

Definition

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

Example Request

All annotation streams:

curl \
  -i \
  -u <user>:<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)

All annotation streams matching the name api:

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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.

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.

Retrieve Annotations by Name

Definition

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

Example Request

Return details of the annotation stream name api-deploys.

curl \
  -i \
  -u <user>:<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 <user>:<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 Headers

** NOT APPLICABLE **

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.

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 Annotation Event

Definition

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

Example Request

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

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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.

Create Annotations

Definition

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

Example Request

Create an annotation event in the app-deploys stream

curl \
  -u <user>:<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 <user>:<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 <user>:<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.

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 meta-data 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.

Definition

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

Example Request

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

curl \
  -u <user>:<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.

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 Attributes

Definition

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

Example Request

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

curl \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Update the attributes of an annotation stream.

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
display_name Name used to display the annotation stream.

Update Meta-Data

Definition

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

Example Request

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

curl \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Update the meta-data of an annotation event.

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

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 Annotation Stream

Definition

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

Example Request

Delete the annotation stream api-deploys

curl \
  -i \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

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

Delete Annotation Event

Definition

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

Example Request

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

curl \
  -i \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Delete an annotation event.

Definition

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

Example Request

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

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/189/links/github'
Not available
Not available

Response Code

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Delete a link from an annotation event.

Alerts

Overview

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.

Alerts

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

Retrieve All Alerts

Definition

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

Example Request

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

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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 Campfire Room",
          "name": "campfire"
        }
      ],
      "attributes": {
        "runbook_url": "http://myco.com/runbooks/response_time"
      },
      "active": true,
      "version": 2
    }
  ]
}

Returns all alerts created by the user.

Pagination Parameters

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

Other Parameters

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

Retrieve Alert by ID

Example Request: Return alert ID 123

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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 Campfire Room",
      "name": "campfire"
    }
  ],
  "attributes": {
    "runbook_url": "http://myco.com/runbooks/response_time"
  },
  "active": true,
  "version": 2
}

Returns a specific alert.

Retrieve Status of Alerts

Definition

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

Example Request

curl \
  -i \
  -u <user>:<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.

Retrieve Status of Specific Alert

Definition

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

Example Request

Return the status for alert ID 120:

curl \
  -i \
  -u <user>:<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.

Create an Alert

Definition

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

Example

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 campfire room 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()

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 Campfire Room",
      "name": "campfire"
    }
  ],
  "attributes": {
    "runbook_url": "http://myco.com/runbooks/response_time"
  },
  "active": true,
  "version": 2
}

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 recieved 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 & Attributes

See details in the alert overview.

Associate Service with Alert

Definition

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

Example Request

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 <user>:<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

Response Body

** NOT APPLICABLE **

Associates a single service with the alert identified by :alert_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

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

Modify Alert

Definition

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

Examples

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

Disable an alert:

curl \
  -u <user>:<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()

Enable an alert:

curl \
  -u <user>:<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 <user>:<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 <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Update the specified alert.

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 recieved 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 & Attributes

See details in the alert overview.

Resolve an Alert

Definition

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

Example Request

Resolve alert ID 120:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  '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.

Delete Alert

Definition

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

Example Request

Delete the alert ID 123

curl \
  -i \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Delete the specified alert.

Remove Service from Alert

Definition

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

Example Request

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 <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/alerts/123/services/209'
Not available
Not available

Response Code

204 No Content

Response Headers

not applicable

Response Body

not applicable

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

API Tokens

Overview

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

Retrieve Tokens

Definition

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

Example Request

curl \
  -i \
  -u <user>:<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.

Retrieve Specific Token

Definition

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

Example Request

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/api_tokens/28'

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

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.

Create Token

Definition

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

Example Request

Create a new API Token:

curl \
  -u <user>:<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

Modify API Token

Definition

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

Example Request

curl \
  -u <user>:<token> \
  -d 'name=New Token Name&active=false&role=admin' \
  -X PUT \
  'https://metrics-api.librato.com/v1/api_tokens/:id'
Not available

Using JSON

{
  "name": "New Token Name",
  "active": false,
  "role": "admin"
}

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

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.

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 API Token

Definition

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

Example Request

Delete the API token with ID 28:

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/api_tokens/28'
Not available

Response Code

204 No Content

Response Body

** NOT APPLICABLE **

Delete the API Token identified by :id.

Chart Tokens

Overview

Chart tokens allow you to make graphs for selected resources viewable to the public. Accessing a graph resource via a chart token does not require authentication. You may create chart tokens for Instruments and Dashboards.

Chart Token Properties

All tokens have the following three properties:

Property Definition
token The randomly generated string which is used to identify the chart token.
entity_type The type of resource the chart token refers to. This may be either instrument or dashboard.
entity_id The ID of the entity that the chart token refers to. This would either be the intrument’s or dashboard’s ID.

Retrieve Chart Tokens

Definition

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

Example Request: Retrieve all chart tokens

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/charts'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

All chart tokens (when there are 3 total):

{
  "query": {
    "found": 3,
    "length": 3,
    "offset": 0,
    "total": 3
  },
  "charts": [
    {
      "token": "conrhpsk",
      "entity_id": 34,
      "entity_type": "instrument"
    },
    {
      "token": "jdqs9ki9",
      "entity_id": 89,
      "entity_type": "dashboard"
    },
    {
      "token": "1psp35gj",
      "entity_id": 23,
      "entity_type": "instrument"
    }
  ]
}

Returns a listing of available chart tokens.

Pagination Parameters

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

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

Retrieve Specific Chart Token

Definition

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

Example Request: Return the chart token with token irhjoz9f

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/charts/irhjoz9f'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

{
  "token": "irhjoz9f",
  "entity_id": 1848,
  "entity_type": "instrument"
}

Returns a specific chart token.

Create Chart Token

Definition

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

Example Request: Create a chart token for the instrument with ID 1848

curl \
  -u <user>:<token> \
  -d 'entity_type=instrument&entity_id=1848' \
  -X POST \
  'https://metrics-api.librato.com/v1/charts'
Not available

Response Code

201 Created

Response Headers

Location: /v1/charts/irhjoz9f

Response Body

{
  "token": "irhjoz9f",
  "entity_id": 1848,
  "entity_type": "instrument"
}

Creates a new chart 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

Parameters

Parameter Definition
entity_type The type of resource the chart token refers to. This may be either instrument or dashboard.
entity_id The ID of the entity that the chart token refers to. This would either be the intrument’s or dashboard’s ID.

Delete Chart Token

Definition

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

Example Request

Delete the chart token conrhpsk.

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/charts/conrhpsk'
Not available

Response Code

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Delete the specified chart token, revoking public access to the referenced entity. This will only delete access to the referenced entity via this chart token; it does affect the referenced entity.

Jobs

Overview

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 cancelled.
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 Job Information

Definition

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

Example Request

Check status for job 123456:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/jobs/123456'
Not available

Response Body Response Examples 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
}

Queued job which has not started yet:

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

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.

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

Overview

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.

Retrieve Specific Snapshot

Definition

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

Example Request

Return the snapshot 1.

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/snapshots/1'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

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.

Create a Snapshot

Definition

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

Create a snapshot.

curl \
  -u <user>:<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"
    }
  }
}

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 Properties

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

Services

Overview

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

Retrieve All Services

Definition

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

Example Request

Return all services:

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

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.

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.

Retrieve Specific Service

Definition

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

Example Request

Return the service 156.

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/services/156'
Not available
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

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

Returns a specific service.

Create a Service

Definition

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

Create a service that notifies the campfire room Ops.

curl \
  -u <user>:<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"
}

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.

Modify a Service

Definition

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

Example Request

Update the title for service 145:

curl \
  -u <user>:<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

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

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

Definition

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

Example Request

Delete the service 145:

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/services/145'
Not available
Not available

Response Code

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

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

Sources

Overview

When submitting a measurement to Librato, in addition to specifying the metric name you can optionally specify a source name as additional meta-data. This is useful when you are tracking the same metrics across a set of homogenous entities e.g. 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.

Retrieve all Sources

Definition

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

Example Request

Return all sources:

curl \
  -i \
  -u <user>:<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 <user>:<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.

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.

Retrieve Source by Name

Definition

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

Example Request

Return the source named foo.bar.com:

curl \
  -i \
  -u <user>:<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 Headers

** NOT APPLICABLE **

Response Body

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

Returns the current representation of the source identifed by name.

Create or update a Source

Definition

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

Example Request

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

curl \
  -u <user>:<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

Response Body

** NOT APPLICABLE **

Example Request

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

curl \
  -u <user>:<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.

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.

Users

Overview

The users API enables third party IaaS and PaaS vendors to create and manage user accounts on behalf of their customers.

Managing Users

If you are a third-party partner that has the ability to manage your users, then it is easy to access the API as a particular user. Access is provided by swapping the user context of the authentication credentials for each request.

In the API, to operate in the context of one of your users, simply select the email address of the user you would like to access as the user field of the authentication credentials. For the token credential, use the API token of your assigned partner admin user account.

User Properties

Property Definition
id Each user has a unique ID.
email Each user has a unique email address.
password Each user has a password. Partners receive an initial password when a user is created and have the ability to reset it at any point in the future. Passwords may not be retrieved as they are never stored in plain text.
api_token Each user has a unique API token. These tokens are used to authenticate access to Librato’s API. This token should be handled securely and only shared with the associated user.
reference The reference uniquely identifies a user within the partner’s application.
name An optional field that stores the user’s name.
company An optional field that stores the company that employs the user.
time_zone An optional field that stores the time zone where the user resides.
created_at When was the account created.
updated_at When was the account last updated.

Retrieve All Users

Definition

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

Example Request

Return all users:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/users'
Not available

The user identified in the partner’s application by 67523:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/users?reference=67523'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

{
  "query": {
    "found": 1,
    "length": 1,
    "offset": 0,
    "total": 1
  },
  "users": [
    {
      "id": 123,
      "email": "foobar@baz.com",
      "api_token": "fda61ef1b4303d5ca8200630afcf90666d779afb79317c471403bfd31985d5d6",
      "reference": "67523",
      "name": "Foo Bar",
      "company": "Baz, Inc.",
      "country": "US",
      "time_zone": "America/Los_Angeles",
      "created_at": "2010-05-17 04:34:55",
      "updated_at": "2011-06-02 18:50:11"
    }
  ]
}

Returns all users managed by the partner.

Parameters

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

Parameter Definition
email A unique email address that identifies the user. It is recommended that you namespace user emails according to a partner associated domain name. For example: user145@partner-domain.com. This field is used as the credential for metric collectors, so changes to it should be made with caution as to not break existing collectors.
reference A string that can be used to store a reference ID to this user in your partner database. The contents can be any string, but it must be unique for each user created in your partner account. If you do not require a reference, you can simply set this to the unique email address.

Retrieve User

Definition

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

Example Request

Return user ID 123:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/users/123'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

{
  "id": 123,
  "email": "foobar@baz.com",
  "api_token": "fda61ef1b4303d5ca8200630afcf90666d779afb79317c471403bfd31985d5d6",
  "reference": "67523",
  "name": "Foo Bar",
  "company": "Baz, Inc.",
  "country": "US",
  "time_zone": "America/Los_Angeles",
  "created_at": "2010-05-17 04:34:55",
  "updated_at": "2011-06-02 18:50:11"
}

Return a specific user.

Create User

Definition

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

Example Request

Create a new user:

curl \
  -u <user>:<token> \
  -d 'email=foobar@baz.com&reference=5267&country=US' \
  -X POST \
  'https://metrics-api.librato.com/v1/users'
Not available

Response Code

201 Created

Response Headers

Location: /v1/users/123

Response Body

{
  "id": 123,
  "email": "foobar@baz.com",
  "api_token": "fda61ef1b4303d5ca8200630afcf90666d779afb79317c471403bfd31985d5d6",
  "reference": "67523",
  "name": "Foo Bar",
  "company": "Baz, Inc.",
  "country": "US",
  "time_zone": "America/Los_Angeles",
  "created_at": "2010-05-17 04:34:55",
  "updated_at": "2011-06-02 18:50:11",
  "password": "5ca7002b72be700b"
}

Create a new Librato user account.

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
email A unique email address that identifies the user. It is recommended that you namespace user emails according to a partner associated domain name. For example: user145@partner-domain.com. This field is used as the credential for metric collectors, so changes to it should be made with caution as to not break existing collectors.
reference A string that can be used to store a reference ID to this user in your partner database. The contents can be any string, but it must be unique for each user created in your partner account. If you do not require a reference, you can simply set this to the unique email address.
name
optional
A full name for this user, e.g. John Smith.
company
optional
Company this user works for.
country
optional
Country this user is from. Defaults to US.
time_zone
optional
The time zone this user is from, e.g. UTC.

Update a User

Definition

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

Example Request

Update a user:

curl \
  -u <user>:<token> \
  -d 'company=NewCompany' \
  -X PUT \
  'https://metrics-api.librato.com/v1/users/123'
Not available

Generate random password for user:

curl \
  -u <user>:<token> \
  -d 'password_reset=1' \
  -X PUT \
  'https://metrics-api.librato.com/v1/users/156'
Not available

Note that password and password_reset must not be set at the same time.

Response

200 OK
204 No Content

Headers

not applicable

Response Body

If password_reset was not provided, a 204 No Content is returned and the body is empty.

A successful password_reset will return a 200 OK with the new password:

{
  "password": "69d07dbd7cb7302b"
}

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
email A unique email address that identifies the user. It is recommended that you namespace user emails according to a partner associated domain name. For example: user145@partner-domain.com. This field is used as the credential for metric collectors, so changes to it should be made with caution as to not break existing collectors.
reference A string that can be used to store a reference ID to this user in your partner database. The contents can be any string, but it must be unique for each user created in your partner account. If you do not require a reference, you can simply set this to the unique email address.
name A full name for this user, e.g. John Smith.
company Company this user works for.
country Country this user is from. Defaults to US.
time_zone The time zone this user is from, e.g. UTC.

Password Management Parameters

The following optional parameters can be used to update the user’s password. Only one of these options can be specified at a time. Specifying both of these options will return an error status code of 400.

Parameter Definition
password_reset Setting this option (set to a value of 1) will instruct the API to reset the user’s password to a randomly generated string. If the reset is successful, the API will respond with a status of 200 OK and the body will contain the new password.
password Resets the user’s password to this value. The new password must be at least six characters long. Unless you require strict control over passwords, the password_reset option is preferred over this option to ensure secure passwords.

Delete User

Definition

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

Example Request

Delete the user 672:

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/users/672'
Not available

Response Code

204 No Content

Response Body

** NOT APPLICABLE **

Delete a user by ID.

Dashboards

Overview

Dashboards contain a stacked collection of instruments that graph one or more metrics in real time. Dashboards can be projected on large-screen displays to easily observe many metrics side-by-side.

Dashboard Properties

Property Definition
id Each dashboard has a unique numeric ID
name Unique name for dashboard
instruments Array of objects containing the IDs of the instruments to be included, in order

Retrieve All Dashboards

Definition

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

Example Request

Return all dashboards owned by the user with name matching ops:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/dashboards?name=ops'
Not available

Response Code

200 OK

Response Body

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

Returns all dashboards created by the user.

Pagination Parameters

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

Parameter Definition
name Search by name of the dashboard.

Retrieve Specific Dashboard

Definition

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

Example Request

Return the dashboard id 129.

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/dashboards/129'

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

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

Returns the details of a specific dashboard.

Create a Dashboard

Definition

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

Example Request

Create a dashboard with name CPUs containing the instruments identified by IDs 4, 87, and 9, in that order:

curl \
  -u <user>:<token> \
  -d 'name=CPUs&instruments%5B%5D=4&instruments%5B%5D=87&instruments%5B%5D=9' \
  -X POST \
  'https://metrics-api.librato.com/v1/dashboards'
Not available

Using JSON

{
  "name": "CPUs",
  "instruments": [
    {
      "id": 4
    },
    {
      "id": 87
    },
    {
      "id": 9
    }
  ]
}

Response Code

201 Created

Response Headers

Location: /v1/dashboards/129

Response Body

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

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

Modify a Dashboard

Definition

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

Example Request

If we have a dashboard with instruments [42, 7, 16], and we want to swap 42 and 7, remove 16, and add 99. Submit the instruments field with the new IDs, in the order you want them to appear.

curl \
  -u <user>:<token> \
  -d 'name=CPUs&instruments%5B%5D=7&instruments%5B%5D=42&instruments%5B%5D=99' \
  -X PUT \
  'https://metrics-api.librato.com/v1/dashboards/:id'
Not available

Using JSON

{
  "name": "CPUs",
  "instruments": [
    {
      "id": 7
    },
    {
      "id": 42
    },
    {
      "id": 99
    }
  ]
}

Response Code

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Modify a dashboard, such as changing the name, or adding, deleting or reordering instruments.

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 Dashboard

Definition

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

Example Request

Delete the dashboard with ID 145:

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/dashboards/145'
Not available

Response Code

204 No Content

Response Body

** NOT APPLICABLE **

Delete the dashboard identified by :id.

Instruments

Overview

Instruments are the data representations of graphs of one or more metrics that you use to visualize and correlate behavior. Instruments can be placed on dashboards for viewing.

Instrument Properties

Property Definition
id Each instrument has a unique numeric ID.
name Title of the instrument when it is displayed.
streams An array of hashes describing the metrics and sources to use for data in the instrument.
attributes The attributes hash configures specific components of an instruments’s visualization.

Stream Properties

Instrument streams have the following properties. Many of the stream properties are the same attributes that can be set on individual metrics and they will override the specific metric attributes. See the metric attributes documentation for more info on what the attributes mean.

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, breakout. If average or sum, a single line will be drawn representing the average or sum (respectively) of all sources. If the group_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].
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 visualizaton.
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.

Attribute Properties

Property Definition
display_stacked Boolean indicating whether to render the instrument as a stacked area chart.
display_integral Boolean indicating whether do display the integral of each series as an explicit number.

Retrieve Instruments

Definition

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

Example Request

Return all instruments owned by the user:

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/instruments'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

{
  "query": {
    "found": 1,
    "length": 1,
    "offset": 0,
    "total": 15
  },
  "instruments": [
    null
  ]
}

Returns instruments created by the user.

Pagination Parameters

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

Retrieve Instrument Details

Definition

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

Example Request: Return instrument ID 123

curl \
  -i \
  -u <user>:<token> \
  -X GET \
  'https://metrics-api.librato.com/v1/instruments/123'
Not available

Response Code

200 OK

Response Headers

** NOT APPLICABLE **

Response Body

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

Returns the details of a specific instrument.

Create an Instrument

Definition

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

Example Request

Create an instrument named Server Temperature which will display the internal server temperature (metric=server_temp) for application server 1 (source=app1) in the same graph as the average external temperature in the datacenter for all sources (source=*) and a ‘dynamic source’ to be specified by the user after the graph has loaded, or on the URL. (source=%). The literal % needs to be % encoded for it to be handled properly, hence %25.

curl \
  -u <user>:<token> \
  -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]=average' \
  -d 'streams[2][metric]=server_temp' \
  -d 'streams[2][source]=%25' \
  -d 'attributes[display_integral]=true' \
  -X POST \
  https://metrics-api.librato.com/v1/instruments
Not available

POST Request Body (JSON)

{
  "name": "Server Temperature",
  "streams": [
    {
      "metric": "server_temp",
      "source": "app1"
    },
    {
      "metric": "environmental_temp",
      "source": "*",
      "group_function": "breakout",
      "summary_function": "average"
    },
    {
      "metric": "server_temp",
      "source": "%",
      "group_function": "average"
    }
  ],
  "attributes": {
    "display_integral": true
  }
}

Response Code

201 Created

Response Headers

Location: /v1/instruments/123

Response Body

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

POST Request Body - Composite Streams (JSON)

{
  "name": "Server Temperature",
  "streams": [
    {
      "composite": "s(\"server_t*\", \"app*\")",
      "display_min": 0
    },
    {
      "composite": "s(\"*temp*\", \"%\", {function: \"mean\", period: \"3600\"})"
    }
  ]
}

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 instrument when it is displayed.
streams An array of hashes describing the metrics and sources to use for data in the instrument.
attributes The attributes hash configures specific components of an instruments’s visualization.

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, breakout. If average or sum, a single line will be drawn representing the average or sum (respectively) of all sources. If the group_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].
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 visualizaton.
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.

Attribute Properties

Property Definition
display_stacked Boolean indicating whether to render the instrument as a stacked area chart.
display_integral Boolean indicating whether do display the integral of each series as an explicit number.

Update an Instrument

Definition

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

Example Request

Add a new data stream (metric server_temp from source app3) to an instrument which currently displays server temp for app1 and the average environmental temperature. Instrument streams are always overwritten, so to add a stream you must the entire new list of streams.

curl \
  -u <user>:<token> \
  -d 'streams[0][metric]=server_temp' \
  -d 'streams[0][source]=app1' \
  -d 'streams[1][metric]=server_temp' \
  -d 'streams[1][source]=app3' \
  -d 'streams[2][metric]=environmental_temp' \
  -d 'streams[2][source]=*' \
  -d 'streams[2][group_function]=average' \
  -d 'attributes[display_integral]=true' \
  -X PUT \
  https://metrics-api.librato.com/v1/instruments/129
Not available

PUT Request Body (JSON)

{
  "name": "Server Temperature",
  "streams": [
    {
      "metric": "server_temp",
      "source": "app1"
    },
    {
      "metric": "server_temp",
      "source": "app3"
    },
    {
      "metric": "environmental_temp",
      "source": "*",
      "group_function": "average"
    }
  ],
  "attributes": {
    "display_integral": true
  }
}

PUT Request Body - Composite Streams (JSON)

{
  "name": "Server Temperature",
  "streams": [
    {
      "composite": "s(\"server_t*\", \"app*\")",
      "display_min": 0
    },
    {
      "composite": "s(\"*temp*\", \"%\", {function: \"mean\", period: \"3600\"})"
    }
  ]
}

Response Code

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

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 instrument when it is displayed.
streams An array of hashes describing the metrics and sources to use for data in the instrument.
attributes The attributes hash configures specific components of an instruments’s visualization.

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, breakout. If average or sum, a single line will be drawn representing the average or sum (respectively) of all sources. If the group_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].
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 visualizaton.
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 an Instrument

Definition

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

Example Request

Delete the instrument ID 123:

curl \
  -i \
  -u <user>:<token> \
  -X DELETE \
  'https://metrics-api.librato.com/v1/instruments/123'
Not available

Response Code

204 No Content

Response Headers

** NOT APPLICABLE **

Response Body

** NOT APPLICABLE **

Delete the specified instrument.