Introduction

API Libraries

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

Quick Start

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

Submit a measurement for the metric my.custom.metric:

JSON

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "region": "us-east-1",
      "az": "a"
    },
    "measurements": [
      {
        "name": "my.custom.metric",
        "value": 65
      }
    ]
  }' \
  -X POST \
  https://metrics-api.librato.com/v1/measurements

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

queue = Librato::Metrics::Queue.new
queue.add "my.custom.metric" { 
  value: 65, 
  tags: { 
    region: 'us-east-1', 
    az: 'a' 
  } 
}
queue.submit

import librato
api = librato.connect('email', 'token')

api.submit("my.custom.metric", 65, tags={'region': 'us-east-1', 'az': 'a'})

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

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/measurements/my.custom.metric?duration=300&resolution=60'

require "librato/metrics"
Librato::Metrics.authenticate ENV['LIBRATO_USERNAME'], ENV['LIBRATO_TOKEN']
query = {
  duration: 300,
  resolution: 60
}
metric = Librato::Metrics.get_series "my.custom.metric", query
puts metric[0]["measurements"]

import librato

api = librato.connect('user', 'token')

metric = api.get_tagged(
  "my.custom.metrics", 
  resolution=60, 
  duration=300
)
print(metric['series'])

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

Authentication

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

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

require "librato/metrics"
Librato::Metrics.authenticate example@librato.com, 75AFDB82

import librato
api = librato.connect('email', 'token')

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

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

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

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

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

URL Encoding

To use URL encoding, use the following format:

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

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

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

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

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

Response Codes & Errors

HTTP Status Codes

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

Error Code	Meaning	Definition
200	OK	The request was processed successfully and the information is returned in the body in the desired format. This code gets returned after GET requests or PUT requests (if the PUT resulted in data being generated and returned). In case of a search (e.g. for metrics) without search results, a 200 still gets returned.
201	Created	The request was processed successfully. The resource was created and the Location variable in the header points to the resource. This code gets returned after POST requests only.
202	Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
204	No Content	The request was processed successfully. Since this code gets returned after PUT or DELETE requests only, there is no need for returning information in the response body.
400	Bad Request	The request could not be parsed or the parameters were not valid. The request should be modified before resubmitting.
401	Unauthorized	Challenges the user to provide authentication credentials.
403	Forbidden	The request was not encrypted via SSL or the account is rate limited.
404	Not Found	The request refers to a resource that either does not exist or the user does not have permissions to access (due to security through obscurity). If a search request gets sent, it will however not return a 404 if the API did not find resources matching the search query.
415	Incorrect Content-Type	Content type was not application/json.
422	Entity Already Exists	An attempt was made to create a new entity that matched an existing one. The request should be modified to use unique parameters (e.g., a different container name) or a PUT request should be made instead to modify the existing entity.
429	Rate Limited	Request was rate limited (it’s possible some data was permitted, need to verify response body). If creating a measurement, this error returns when it can not parse the basic format of the payload to identify measurements.
503	Service Unavailable	In the rare occasion that we must put the API into maintenance mode for a service upgrade, the API can return a 503 error code. The API should be available again shortly so it is advised that you resubmit your request later.

Error Messages

Example of a request type error message.

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

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

Error Message Structure

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

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

Measurements

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

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

Measurement Properties

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

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

Create a Measurement

Create a new measurement my.custom.metric with the tag region: "us-east-1", az: "a"

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "tags": {
      "region": "us-east-1",
      "az": "a"
    },
    "measurements": [
      {
        "name": "my.custom.metric",
        "value": 65
      }
    ]
  }' \
  -X POST \
  https://metrics-api.librato.com/v1/measurements

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

queue = Librato::Metrics::Queue.new
queue.add "my.custom.metric" {
  value: 65,
  tags: {
    region: 'us-east-1',
    az: 'a'
  }
}
queue.submit

import librato
api = librato.connect('email', 'token')

api.submit("my.custom.metric", 65, tags={'region': 'us-east-1', 'az': 'a'})

HTTP Request

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

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

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

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

Headers

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

Content-Type: application/json

Measurement Parameters

Top-Level Tags

The following payload demonstrates submitting tags at the top-level of the payload. This may be common for a collection agent that tags all metrics the same based on the identification of the collection host parameters. If you add any tags to the measurement, those tags will replace the top-level tags.

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

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

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

queue = Librato::Metrics::Queue.new(
  tags: {
    region: 'us-west',
    name: 'web-prod-3'
  }
)
queue.add cpu: 4.5
queue.add memory: 10.5

queue.submit

import librato
api = librato.connect('email', 'token')

q = api.new_queue(tags={'region': 'us-west', 'name': 'web-prod-3'})
q.add('cpu', 4.5)
q.add('memory', 10.5)
q.submit()

Embedded Measurement Tags

You can override top-level tags with per-measurement tags. In the following example, the cpu metric will replace the top-level tags region:us-west and name:web-prod-3 with name:web-prod-1, while the memory metric will use the embedded tags az:e and db:db-prod-1.

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

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

queue = Librato::Metrics::Queue.new(
  tags: {
    region: 'us-west',
    name: 'web-prod-3'
  }
)
queue.add cpu: {
  value: 4.5,
  tags: {
    name: "web-prod-1"
  }
}
queue.add memory: {
  value: 34.5,
  tags: {
    az: "e",
    db: "db-prod-1"
  }
}

queue.submit

import librato
api = librato.connect('email', 'token')

q = api.new_queue(tags={'region': 'us-west', 'name': 'web-prod-3'})
q.add('cpu', 4.5, tags={'name': 'web-prod-1'})
q.add('memory', 34.5, tags={'az': 'e', 'db': 'db-prod-1'})
q.submit()

Full Measurement Sample

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

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

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

queue = Librato::Metrics::Queue.new
queue.add cpu: {
  time: 1421530163,
  period: 60,
  sum: 35,
  count: 3,
  min: 4.5,
  max: 6.7,
  last: 2.5,
  stddev: 1.34,
  attributes: {
    aggregate: false
  },
  tags: {
    region: "us-east-1",
    az: "b",
    role: "kafka",
    environment: "prod",
    instance: "3"
  }
}

queue.submit

import librato
api = librato.connect('email', 'token')

#must set the value attribute to None
api.submit(
  "my.custom.metric",
  None,
  period=60,
  sum=35,
  count=3,
  min=4.5,
  max=6.7,
  last=2.5,
  stddev=1.34,
  attributes= {
    'aggregate': False
  },
  time= 1484613483,
  tags={
    'region': 'us-east-1',
    'role': 'kafka',
    'environment': 'prod',
    'instance': '3',
    'az': 'b'
  }
)

Individual Sample Parameters

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

Parameter	Definition
name	The unique identifying name of the property being tracked. The metric name is used both to create new measurements and query existing measurements. Must be 255 or fewer characters, and may only consist of ‘A-Za-z0-9.:-_’. The metric namespace is case insensitive.
value	The numeric value of a single measured sample.
tags	A set of key/value pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. Examples include the region a server is located in, the size of a cloud instance or the country a user registers from. The full set of unique tag pairs defines a single data stream. If per-measurement tags are specified, top-level tags will not be included for that specific measurement.

Global or per-sample parameters

In addition, the following parameters can be specified to further define the measurement sample. They may be set at the individual measurement level or at the top-level. Top-level tags are only applied to a measurement if no individual tags are included. Top-level and individual tags are never merged for a measurement.

Parameter	Definition
time	Unix Time (epoch seconds). This defines the time that a measurement is recorded at. It is useful when sending measurements from multiple hosts to align them on a given time boundary, eg. time=floor(Time.now, 60) to align samples on a 60 second tick.
period	Define the period for the metric. This will be persisted for new metrics and used as the metric period for metrics marked for Service-Side Aggregation.

Summary fields

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

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

Optional Parameters

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

Overriding Top-Level Tags

Measurements with embedded tags (specified per measurement) will override and prevent any top-level tags from being recorded for the specific measurement. In order to merge both top-level and embedded tags, all tags will need to be embedded with the measurement.

Rate Limiting

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

Measurement Restrictions

Name Restrictions

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

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

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

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

Users should be mindful of the maximum cardinality of their full tag set over all measurements. Each unique set of pairs is a new unique stream and is billed as such. The full cardinality of a metric is the permutation of all possible values of tags over the billing period. For example, if you have two tags on your measurements and the first tag has 20 possible values and the second tag has 30 possible values, then your potential tag cardinality could be 20 * 30 => 600 data streams. This would be billed as 600 individual streams over the billing duration of one hour.

If you plan to have a tag cardinality over 40,000 unique tag sets per hour, please let us know ahead of time at support@librato.com. To prevent accidental cardinality explosions our API may automatically reject metrics with a cardinality exceeding this.

Float Restrictions

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

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

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

Retrieve a Measurement

Retrieve Measurements by Matching Tags

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

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

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

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

query = {
  resolution: 60,
  duration: 86400,
  tags: {
    region: "us*",
    name: "prod*"
  }
}

measurements = Librato::Metrics.get_series "AWS.EC2.DiskWriteBytes", query

import librato
api = librato.connect('email', 'token')

resp = api.get_tagged(
  "AWS.EC2.DiskWriteBytes",
  duration=86400,
  resolution=60,
  tags={
    'region': 'us*',
    'name': 'prod*'
  }
)

Response:

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

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

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

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

query = {
  resolution: 60,
  duration: 86400,
  group_by: "region",
  group_by_function: "sum",
    tags: {
    region: "us*",
    name: "prod*"
  }
}

measurements = Librato::Metrics.get_series "AWS.EC2.DiskWriteBytes", query

import librato
api = librato.connect('email', 'token')

resp = api.get_tagged(
  "AWS.EC2.DiskWriteBytes",
  duration=86400,
  resolution=60,
  group_by="region",
  group_by_function="sum",
  tags={
    'region': 'us*',
    'name': 'prod*'
  }
)

Response:

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

Retrieve Measurements Using tags_search

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

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

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

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

query = {
  resolution: 60,
  duration: 86400,
  tags_search: "region=us-east* and db=*prod*"
}

measurements = Librato::Metrics.get_series :memory, query

import librato
api = librato.connect('email', 'token')

resp = api.get_tagged(
  "AWS.EC2.DiskWriteBytes",
  duration=86400,
  resolution=60,
  tags_search="region=us-east* and db=*prod*"
)

Response:

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

HTTP Request

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

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

HTTP Response

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

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

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

Time search parameters

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

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

Tag Search Parameters

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

Property	Definition
tags	A map of tag search patterns that limit the returned set of streams by simple wildcard patterns against tag values. Only streams matching the provided tag name/values are returned. Tags can be searched by AND, OR, and NOT conditions on their tag values. Specifying the same tag name multiple times with different values is an OR. Specifying different tag names performs an AND and prefixing a tag value search pattern with “!” negates the match. A negation requires that the particular tag name is set on the data stream. It will not match streams that do not have the particular tag name set. See section below for how negation is handled. Wildcard matches can be used in place of the tag or tag value. For example, "tags":"*" (or "tags":{}) can be specified to retrieve all metric streams regardless of the tag(s) provided, and "tags":{"host":"*"} can be specified to retreive only measurements with the tag of host. note: If querying a composite metric you will need to utilize the tags_search parameter.
tags_search	The tags_search parameter, which may NOT be specified with the tags parameter, defines a complex search query over a set of tags. It is provided to allow a more complex query pattern over the set of tag values than the tags parameter can provide. The grammar should be properly form-encoded to escape fields not appropriate for URL query parameters.

Tag Negation

When using the tags property you can perform two operations:

• Negate the values of a tag: This matches any data stream that contains the tag name, but does not match the negation pattern.

eg. region=!us-east

• Negate a tag name: This matches all data streams that do not contain the particular tag name.

eg. !host

Aggregation parameters

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

Property	Definition
group_by	Defines one or more tag names to group the returned results by. Any measurements with the same tag value for the given group_by tag names are aggregated using the group_by_func aggregation function. Each returned stream will include the grouped tags. If group_by is not specified, all streams are returned broken out by their tag values. The group_by tags also define a filter for the returned results. Only streams that contain all of the group by tags are returned. The special format of group_by=* will return all data streams aggregated together to a single stream. The response will not include any tag information. Examples: group_by=region, group_by=region,az, group_by=*
group_by_function	Defines the aggregation function to group results by. This parameter is required if group_by is set. Options are: sum, min, max, & mean. Future: cardinality of aggregated streams.
summary_function	Defines the property of the metric to query. A metric has properties like: sum, count, min, max; this parameter defines which of the properties to read and represent in the payload. Acceptable values are: sum, min, max, count, mean, derivative, stddev, & all. This parameter falls back to the persisted summary function of the metric, which by default is mean. If the parameter is set to all then the api will, instead of returning just one summarization, return multiple summarizations for each returned measure. The summary function also defines the function used when downsampling data to a coarser granularity. The downsampling function is chosen as following given a summary function.

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

Measurement Pagination

Response if more results are available for pagination:

{
  "series": [

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

Response if there are no more results:

{
  "series": [

  ],
  "links": [

  ]
}

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

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

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

Composite Metric Queries

Execute a composite query to derive the the read disk OPs time for a given host:

#cURL requres url encoding of GET query params

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/measurements?compose=derive%28s%28%22librato.disk.disk_ops.read%22%2C+%7B%22host%22%3A%22ip-192-168-15-18.ec2.internal%22%29%2C+%7Bdetect_reset%3A+%22true%22%7D%29&start_time=1484678910&resolution=60'

require 'librato/metrics'
Librato::Metrics.authenticate 'email', 'api_key'

query = {
  compose: "derive(s(\"librato.disk.disk_ops.read\", {\"host\": \"ip-192-168-15-18.ec2.internal\"}), {detect_reset: \"true\"})",
  resolution: 60,
  start_time: 1484678910
}

measurements = Librato::Metrics.get_series "", query

import librato
api = librato.connect('email', 'token')

resp = api.get_tagged(
  "",
  start_time=1484678910,
  resolution=60,
  compose="derive(s(\"librato.disk.disk_ops.read\", {\"host\": \"ip-192-168-15-18.ec2.internal\"}), {detect_reset: \"true\"})"
)

Response (the result of the derive() function over the read disk ops):

[
   {
      "tags":{
         "disk":"disk0",
         "host":"ip-192-168-15-18.ec2.internal"
      },
      "measurements":[
         {
            "time":1484687040,
            "value":430.0
         },
         {
            "time":1484687100,
            "value":738.0
         },
         {
            "time":1484687160,
            "value":111.0
         }
      ],
      "metric":{
         "name":"librato.disk.disk_ops.read",
         "type":"gauge",
         "attributes":{
            "display_units_long":"Operations",
            "display_min":0,
            "created_by_ua":"Librato Agent Integration",
            "display_units_short":"ops"
         },
         "period":60
      },
      "period":60
   }
]

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

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

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

Metrics

Metrics represent the individual time-series sent to the Librato service. Each measurement sent to Librato is associated with a Metric.

Metric Properties

Parameter	Definition
type	Type of metric to create (gauge 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. A list of metric attributes can be found in the Metric Attributes table.
composite optional	The composite definition. Only used when type is composite.

Create a Metric

Create a metric named librato.cpu.percent.used matching the tags environment:prod and service:api:

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "type": "gauge",
  "name": "librato.cpu.percent.used",
  "period": 60,
  "attributes": {
    "summarize_function": "sum",
    "color": "#FFFFFF"
  },
  "tags": {
    "environment": "prod",
    "service": "api"
  }
}' \
-X PUT \
'https://metrics-api.librato.com/v1/metrics/librato.cpu.percent.used'

Metrics can be created without submitting a measurement value using a PUT to the /metrics endpoint. Metrics are automatically created by POSTing a measurement for the first time. See Create a Measurement.

HTTP Request

PUT https://metrics-api.librato.com/v1/metrics/: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

Creating Persisted Composite Metrics

Create a persisted composite named librato.cpu.percent.used matching the tags environment:prod and service:api:

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "type": "composite",
  "name": "librato.cpu.percent.used",
  "composite": "s(\"librato.cpu.percent.user\", {\"environment\" : \"prod\", \"service\": \"api\"})"
}' \
-X PUT \
'https://metrics-api.librato.com/v1/metrics/librato.cpu.percent.used'

Not yet available

Not yet available

Response Body

{
  "name": "librato.cpu.percent.used",
  "display_name": null,
  "type": "composite",
  "description": null,
  "period": null,
  "source_lag": null,
  "composite": "s(\"librato.cpu.percent.user\", {\"environment\" : \"prod\", \"service\": \"api\"})"
}

HTTP Request

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

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.

Retrieve a Metric

The Librato API lets you search for metric metadata and measurements within the system. For example, you could query a list of all available metrics in the system or those matching a specific naming pattern.

Retrieve a Metric by Name

How to retrieve the metadata for the metric cpu_temp:

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.get_metric :cpu_temp

import librato
api = librato.connect(<user>, <token>)
metric = api.get("cpu_temp")
print(metric.attributes)

Response Body:

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

Returns information for a specific metric.

HTTP Request

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

Update a Metric

HTTP Request

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

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names%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)

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names=*.time&display_units_short=ms' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metrics names: ["*.time"] , display_units_short: "ms"

Not available

Response Code

204 No Content OR 202 Accepted

Response Headers

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

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

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

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

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Update a Metric by Name

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'display_name=Temperature in Celsius&attributes[display_min]=0' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics/temp'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :temp, name: "Temperature in Celsius", attributes: { display_min: '0' }

import librato
api = librato.connect(<user>, <token>)
for metric in api.list_metrics(name="temp"):
  gauge = api.get(metric.name)
  attrs = gauge.attributes
  attrs['display_name'] = 'Temperature in Celsius'
  attrs['display_min'] = '0'
  api.update(metric.name, attributes=attrs)

Response Code

204 No Content

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'type=gauge&description=Length of app queue&display_name=num. elements' \
  -X PUT \
  'https://metrics-api.librato.com/v1/metrics/queue_len'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :queue_len, type: :gauge, display_name: "num. elements", period: 15

import librato
api = librato.connect(<user>, <token>)
api.submit("queue_len", 10)

Response Code

201 Created

Response Headers

Location: /v1/metrics/queue_len

Response Body

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

HTTP Request

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

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

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

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, 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. A list of metric attributes can be found in the Metric Attributes table.
composite optional	The composite definition. Only used when type is composite.

Delete a Metric

HTTP Request

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

Delete the metrics cpu, servers and reqs:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names%5B%5D=cpu&names%5B%5D=servers&names%5B%5D=reqs' \
  -X DELETE \
  'https://metrics-api.librato.com/v1/metrics'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.delete_metrics :cpu, :servers, :reqs

import librato
api = librato.connect(<user>, <token>)
api.delete(names=['cpu', 'servers', 'reqs'])

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'names=cpu*.90' \
  -X DELETE \
  'https://metrics-api.librato.com/v1/metrics'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.delete_metrics names: ["cpu*.90"]

Not available

Response Code

204 No Content OR 202 Accepted

Response Headers

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

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

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

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

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

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

Delete a Metric by Name

HTTP Request

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

Delete the metric named app_requests.

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.delete_metrics :app_requests

import librato
api = librato.connect(<user>, <token>)
api.delete("app_requests")

Response Code

204 No Content

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

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

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

List All Metrics

HTTP Request

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

Metric Metadata Queries

List all metrics:

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.metrics

import librato
api = librato.connect(<user>, <token>)
api.list_metrics()

Response Code

200 OK

Response (when there are two total):

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

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

List a Subset of Metrics

Retrieve all metrics containing request in the metric name:

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.metrics name:'request'

import librato
api = librato.connect(<user>, <token>)
api.list_metrics(name="request")

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

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

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

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

Metric Attributes

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'attributes[display_max]=150' \
  -X PUT \
  https://metrics-api.librato.com/v1/metrics/temperature

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :temperature, attributes: { display_max: '150' }

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'attributes[aggregate]=true' \
  -X PUT \
  https://metrics-api.librato.com/v1/metrics/speed

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.update_metric :speed, attributes: { aggregate: 'true' }

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.

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.

Attributes

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 metric streams should be aggregated in a visualization (e.g. stacked graphs). This option is disabled by default.
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 metric. When enabled, measurements sent using the same tag set will be aggregated into single measurements on an interval defined by the period of the metric. If there is no period defined for the metric then all measurements will be aggregated on a 60-second interval. This option takes a value of true or false. If this option is not set for a metric it will default to false.

Pagination

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

Request Parameters

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  'https://metrics-api.librato.com/v1/metrics?offset=10&length=10'

Not available

# pagination not available, use list_metrics() for all metrics
for m in api.list_metrics():
    print m.name

Response Code:

200

Response Body:

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

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

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

Response Parameters

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  https://metrics-api.librato.com/v1/metrics?name=api&offset=20&limit=10

Not available

# pagination not available, use list_metrics() for all metrics
for m in api.list_metrics():
    print m.name

Response Code:

200

Response Body:

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

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

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

Spaces

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

Space Properties

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

Pagination Parameters

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

Parameter	Definition
name	Search by name of the space.

Create a Space

Create a space with name CPUs:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=CPUs' \
  -X POST \
  'https://metrics-api.librato.com/v1/spaces'

Not available

import librato
api = librato.connect('email', 'token')
space = api.create_space("CPUs")
print("Created '%s'" % space.name)

Using JSON

{
  "name": "CPUs"
}

Response Code

201 Created

Response Headers

Location: /v1/spaces/129

Response Body

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Retrieve a Space

Return the details of a Space with ID 129:

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

Not available

import librato
api = librato.connect('email', 'token')
space_info = api.get_space(129)
print space_info.name

Response Code

200 OK

Response Body

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

Returns the details of a specific space.

HTTP Request

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

Update a Space

Change the name of the space to MEMORY:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'name=MEMORY' \
  -X PUT \
  'https://metrics-api.librato.com/v1/spaces/:id'

Not available

import librato
api = librato.connect('email', 'token')
space = api.find_space('CPUs')
space.name = "MEMORY"
space.save()

Using JSON

{
  "name": "MEMORY"
}

Response Code

204 No Content

Modifies a space by changing its name.

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Delete Space

Delete the space with ID 129:

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/spaces/129'

Not available

import librato
api = librato.connect('email', 'token')
api.delete_space(129)

Response Code

204 No Content

Delete the space identified by :id.

HTTP Request

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

List all Spaces

HTTP Request

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

Retrieve all spaces:

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

Not available

import librato
api = librato.connect('email', 'token')
spaces = api.list_spaces()
for s in spaces:
  print s.name

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

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

Not available

import librato
api = librato.connect('email', 'token')
spaces = api.list_spaces(name="ops")
for s in spaces:
  print(s.name)

Response Code

200 OK

Response Body

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

Returns all spaces created by the user.

Charts

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

Create a Chart

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

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "type": "line",
  "name": "CPU Usage",
  "streams": [
    {
      "metric": "librato.cpu.percent.idle",
      "tags": [{"name": "environment", "values": ["*"]}]
    },
    {
      "metric": "librato.cpu.percent.user",
      "tags": [{"name": "environment", "dynamic": True}]
    }
  ]
}' \
-X POST \
'https://metrics-api.librato.com/v1/spaces/:space_id/charts'

Not available

import librato
api = librato.connect('email', 'token')
space = api.get_space(123)
linechart = api.create_chart(
  'cities MD line chart',
  space,
  streams=[
    {
      "metric": "librato.cpu.percent.idle",
      "tags": [{"name": "environment", "values": ["*"]}]
    },
    {
      "metric": "librato.cpu.percent.user",
      "tags": [{"name": "environment", "dynamic": True}]
    }
  ]
)

Response Code

201 Created

Response Headers

Location: /v1/spaces/123

Response Body

{
  "id": 1234567,
  "name": "CPU Usage",
  "type": "line",
  "streams": [
    {
      "id": 27032885,
      "metric": "librato.cpu.percent.idle",
      "type": "gauge",
      "tags": [
        {
          "name": "environment",
          "values": [
            "*"
          ]
        }
      ]
    },
    {
      "id": 27032886,
      "metric": "librato.cpu.percent.user",
      "type": "gauge",
      "tags": [
        {
          "name": "environment",
          "values": [
            "prod"
          ]
        }
      ]
    }
  ],
  "thresholds": null
}

Create a Big Number chart with a threshold of > 90:

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "type": "bignumber",
  "name": "CPU Usage",
  "streams": [
    {
      "metric": "librato.cpu.percent.user",
      "tags": [{"name": "environment", "values": ["prod"]}]
    }
  ],
  "thresholds":[
    {
      "operator":">",
      "value":90,
      "type":"red"
    }
  ]
}' \
-X POST \
'https://metrics-api.librato.com/v1/spaces/:space_id/charts'

Not available

import librato
api = librato.connect('email', 'token')
space = api.get_space(123)
linechart = api.create_chart(
  'CPU Usage',
  space,
  type='bignumber',
  streams=[
    {
      "metric": "librato.cpu.percent.user",
      "tags": [{"name": "environment", "values": ["prod"]}]
    }
  ],
  thresholds=[
    {
      "operator": ">",
      "value": 90,
      "type": "red"
    }
  ]
)

When creating a new chart you can specify any metrics to include.

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

Parameter	Definition
name	Title of the chart when it is displayed.
streams	An array of hashes describing the metrics and tags 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
thresholds	required when creating a BigNumber chart. When creating a threshold you will need to provide the operator (>, <, or =), the value to trigger the threshold, and the type (red or yellow) which specifies the color for the BigNumber chart to display when the criteria is met.

Stream Properties

Parameter	Definition
metric	Name of metric
tags	An array of objects that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. The values array accepts specific wildcard entries. For example us-west-*-app will match us-west-21-app but not us-west-12-db. Using grouped: true groups measurements by the tag name. Using dynamic: true optionally injects space level filters and groupings into the stream measurements. The full set of unique tag pairs defines a single data stream.
composite	A composite metric query string to execute when this stream is displayed. This can not be specified with a metric, tag or group_function.
group_function	How to process the results when multiple streams 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 tags. If the function is breakout, a separate line will be drawn for the values in the highest tag cardinality. If this property is not supplied, the behavior will default to average.
summary_function	When visualizing complex measurements or a rolled-up measurement, this allows you to choose which statistic to use. If unset, defaults to “average”. Valid options are one of: [max, min, average, sum, count].
downsample_function	This allows you to choose which statistic to use during roll-ups (for composite metrics only). If unset, defaults to “average”. Valid options are one of: [max, min, average, sum, count].
color	Sets a color to use when rendering the stream. Must be a seven character string that represents the hex code of the color e.g. #52D74C.
name	A display name to use for the stream when generating the tooltip.
units_short	Unit value string to use as the tooltip label.
units_long	String value to set as they Y-axis label. All streams that share the same units_long value will be plotted on the same Y-axis.
min	Theoretical minimum Y-axis value.
max	Theoretical maximum Y-axis value.
transform_function	Linear formula to run on each measurement prior to visualization.
period	An integer value of seconds that defines the period this stream reports at. This aids in the display of the stream and allows the period to be used in stream display transforms.

Retrieve a Chart

Return chart by id and space id.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id'

Not available

import librato
api = librato.connect('user', 'token')
chart = api.get_chart(chart_id, space_id)
for s in chart.streams:
  print(s.metric, s.tags, s.group_function, s.summary_function)

Response Code

200 OK

Response Body

{
  "id": 3700969,
  "name": "CPU Usage",
  "type": "line",
  "streams": [
    {
      "id": 27003258,
      "metric": "librato.cpu.percent.idle",
      "type": "gauge",
      "tags": [
        {
          "name": "region",
          "values": [
            "us-east-1"
          ]
        }
      ]
    }
  ],
  "thresholds": null
}

Returns a specific chart by its id and space id.

HTTP Request

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

Update a Chart

Update a chart name to Temperature:

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "type": "line",
  "name": "Temperature"
}' \
-X PUT \
'https://metrics-api.librato.com/v1/spaces/:space_id/charts/:chart_id'

Not available

import librato
api = librato.connect('user', 'token')
space = api.get_space(123)
charts = space.chart_ids
chart = api.get_chart(charts[0], space.id)
chart.name = 'Temperature'
chart.save()

Response Code

200 OK

Response Body

{
  "id": 3700969,
  "name": "Temperature",
  "type": "line",
  "streams": [
    {
      "id": 27003258,
      "metric": "collectd.cpu.0.cpu.user",
      "type": "gauge",
      "tags": [
        {
          "name": "region",
          "values": [
            "us-east-1"
          ]
        }
      ]
    }
  ],
  "thresholds": null
}

How to add a composite metric to a chart

NOTE: This will replace existing streams within the specified chart

curl \
-u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
-H "Content-Type: application/json" \
-d '{
  "type": "line",
  "streams": [
    {
      "composite": "divide([sum(s(\"librato.cpu.percent.idle\",{\"environment\":\"*\"})),sum(s(\"librato.cpu.percent.user\",{\"environment\":\"*\"}))])"
    }
  ]
}' \
-X POST \
'https://metrics-api.librato.com/v1/spaces/:space_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(\"librato.cpu.percent.idle\",{\"environment\":\"*\"})),"
"sum(s(\"librato.cpu.percent.user\",{\"environment\":\"*\"}))])")
chart.save()

Response Body

{
   "id":1234567,
   "name":"CPU Usage",
   "type":"line",
   "streams":[
      {
         "id":27037351,
         "composite":"divide([sum(s(\"librato.cpu.percent.idle\",{\"environment\":\"*\"})),sum(s(\"librato.cpu.percent.user\",{\"environment\":\"*\"}))])",
         "type":"composite"
      }
   ],
   "thresholds":null
}

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

Parameter	Definition
name	Title of the chart when it is displayed.
streams	An array of hashes describing the metrics and tags 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
thresholds	required when creating a BigNumber chart. When creating a threshold you will need to provide the operator (>, <, or =), the value to trigger the threshold, and the type (red or yellow) which specifies the color for the BigNumber chart to display when the criteria is met.

Stream Properties

Property	Definition
metric	Name of metric
tags	An array of objects that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. The values array accepts specific wildcard entries. For example us-west-*-app will match us-west-21-app but not us-west-12-db. Using grouped: true groups measurements by the tag name. Using dynamic: true optionally injects space level filters and groupings into the stream measurements.
composite	A composite metric query string to execute when this stream is displayed. This can not be specified with a metric, tag or group_function.
group_function	How to process the results when multiple streams 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 tags. If the function is breakout, a separate line will be drawn for the values in the highest tag cardinality. 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	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. DO NOT MULTIPLY x BY ITSELF (e.g. x*x). Nonlinear functions will not apply correctly against the automatically generated aggregate values and produce false data.
period	An integer value of seconds that defines the period this stream reports at. This aids in the display of the stream and allows the period to be used in stream display transforms.

Delete a Chart

Delete the chart ID 123.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/spaces/:id/charts/:chart_id'

Not available

import librato
api = librato.connect('user', 'token')
space = api.get_space(123)
charts = space.chart_ids
chart = api.get_chart(charts[0], space_id)
chart.delete()

Response Code

204 No Content

Delete the specified chart.

HTTP Request

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

List all Charts in Space

List all charts in a Space with ID 129.

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

Not available

import librato
api = librato.connect('user', 'token')
space = api.get_space(129)
charts = space.chart_ids
for c in charts:
   i = api.get_chart(c, space.id)
   for s in i.streams:
       print(s.id, s.tags, s.source, s.group_function, s.summary_function)

Response Code

200 OK

Response Body

[
  {
    "id": 1234567,
    "name": "CPU Usage",
    "type": "line",
    "streams": [
      {
        "id": 27035309,
        "metric": "librato.cpu.percent.idle",
        "type": "gauge",
        "tags": [
          {
            "name": "environment",
            "values": [
              "*"
            ]
          }
        ]
      },
      {
        "id": 27035310,
        "metric": "librato.cpu.percent.user",
        "type": "gauge",
        "tags": [
          {
            "name": "environment",
            "values": [
              "prod"
            ]
          }
        ]
      }
    ],
    "thresholds": null
  }
]

Return charts for a given space.

HTTP Request

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

Annotations

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

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

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

Annotation Streams

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

Annotation Stream Properties

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

Annotation Events

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

Annotation Event Properties

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

Create an Annotation

Create an annotation event in the app-deploys stream:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=Deployed v56&source=foo3.bar.com&description=v56 - Fixed typo in page titles' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/app-deploys'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.annotate :'app-deploys', 'Deployed v56', source: 'foo3.bar.com',
    description: 'v56 - Fixed typo in page titles'

import librato
api = librato.connect(<user>, <token>)
api.post_annotation("app-deploys",
  title="Deployed v56",
  source="foo3.bar.com",
  description="v56 - Fixed typo in page titles")

Create an annotation event at a specific timestamp:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=My Annotation&description=Joe deployed v29 to metrics&start_time=1234567890' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.annotate :'app-deploys', 'My Annotation', source: 'foo3.bar.com',
    start_time: 1234567890, description: 'Joe deployed v29 to metrics'

import librato
api = librato.connect(<user>, <token>)
api.post_annotation("app-deploys",
  title="My Annotation",
  source="foo3.bar.com",
  start_time="1234567890",
  description="Joe deployed v29 to metrics")

Create an annotation event with a link:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'title=My Annotation&description=Joe deployed v29 to metrics&start_time=1234567890' \
  -d 'links[0][label]=Metrics Gem' \
  -d 'links[0][href]=https://github.com/librato/librato-metrics' \
  -d 'links[0][rel]=github' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics.annotate :'app-deploys', 'My Annotation', source: 'foo3.bar.com',
    start_time: 1234567890, description: 'Joe deployed v29 to metrics',
    links: [label: 'Metrics Gem', href: 'https://github.com/librato/librato-metrics', rel: 'github']

import librato
api = librato.connect(<user>, <token>)
api.post_annotation("app-deploys",
  title="My Annotation",
  source="foo3.bar.com",
  start_time="1234567890",
  description="Joe deployed v29 to metrics",
  links=[{'rel': 'github', 'href': 'https://github.com/librato/librato-metrics'}])

Response Code

201 Created

Response Headers

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

Response Body

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

  ]
}

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

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

Retrieve an Annotation

Return details of the annotation stream name api-deploys.

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/annotations/api-deploys?start_time=1507050000'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.list name: ('api-deploys')

import librato
api = librato.connect(<user>, <token>)
stream = api.get_annotation_stream("api-deploys", start_time="1234500000")
for source in stream.events:
   print source
   events = stream.events[source]
   for event in events:
       print event['id']
       print event['title']
       print event['description']

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

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X GET \
  'https://metrics-api.librato.com/v1/annotations/blog-posts?start_time=1234500000&end_time=1234600000&sources%5B%5D=db1.acme&sources%5B%5D=db2.acme'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.fetch :'blog-posts', start_time: 1234500000, end_time: 1234600000, sources: ['db1.acme', 'db2.acme']

import librato
api = librato.connect(<user>, <token>)
stream = api.get_annotation_stream("blog-posts",
  start_time="1234500000",
  end_time="1234600000",
  sources=['db1.acme', 'db2.acme'])
print(stream.events)

Response Code

200 OK

Response Body

An annotation stream from multiple sources:

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

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

          ]
        }
      ]
    }
  ]
}

Return a list of annotations associated with given stream name.

HTTP Request

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

Annotation Search Parameters

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

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

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

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

Retrieve an Annotation Event

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

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.fetch :'api-deploys', start_time: (Time.now.to_i-3600)

Not available

Response Code

200 OK

Response Body

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

Return annotation event details associated with given stream name.

HTTP Request

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

Update an Annotation

Add link to annotation event

Add a link to a specific annotation event.

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'rel=github&label=Github Commit&href=https://github.com/acme/app/commits/01beaf' \
  -X POST \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/198/links'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.fetch :'app-deploys', start_time: (Time.now.to_i-3600), end_time: (Time.now.to_i), sources: ['db1.acme', 'db2.acme']

Not available

Response Code

201 Created

Response Headers

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

Response Body

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

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

Update an Annotation Stream Attributes

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

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

Not available

Not available

Response Code

204 No Content

Update the attributes of an annotation stream.

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Annotation Stream Parameters

Parameter	Definition
display_name	Name used to display the annotation stream.

Update Annotation Event Metadata

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'description=Deployed git SHA 601060a68ff2e' \
  -X PUT \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/143'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.update_event :app-deploys, 143, description: 'Deployed git SHA 601060a68ff2e'

Not available

Response Code

204 No Content

Update the metadata of an annotation event.

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Annotation Event Parameters

The following parameters can be updated.

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

Delete an Annotation

Delete the annotation stream api-deploys

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/annotations/api-deploys'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.delete :api-deploys

import librato
api = librato.connect(<user>, <token>)
api.delete_annotation_stream("api-deploys")

Response Code

204 No Content

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

HTTP Request

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

Delete an Annotation Event

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

curl \
  -i \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X DELETE \
  'https://metrics-api.librato.com/v1/annotations/app-deploys/123'

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.delete_event :api-deploys, 123

Not available

Response Code

204 No Content

Delete an annotation event.

HTTP Request

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

Delete Link From Annotation Event

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

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

Not available

Not available

Response Code

204 No Content

Delete a link from an annotation event.

HTTP Request

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

List all Annotations

Return all annotation streams:

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.list

import librato
api = librato.connect(<user>, <token>)
for stream in api.list_annotation_streams():
  print(stream.name)

Return all annotation streams matching the name api:

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

require "librato/metrics"
Librato::Metrics.authenticate <user>, <token>
Librato::Metrics::Annotator.new.list name: ('api')

import librato
api = librato.connect(<user>, <token>)
for stream in api.list_annotation_streams(name="api"):
  print(stream.name)

Response Code

200 OK

Response Body (all annotation streams)

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

Return a list of annotation streams.

HTTP Request

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

Pagination Parameters

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

Alerts

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

The Alert Object

Alerts Properties

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

Alert Conditions

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

We currently support three alert condition types:

Condition	Definition
above	Condition is met when the stream 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.
tags optional	A set of key/value pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. Examples include the region a server is located in, the size of a cloud instance or the country a user registers from. The full set of unique tag pairs defines a single data stream. Wildcards can be used here (e.g. prod-* will include all tags that begin with prod-). Data Streams matching the specified tag set can be grouped with the property "grouped":true. If left false each data stream matching the tag set will be evaluated individually.
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].
duration	integer: Number of seconds that data for the specified metric/tag 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/tag combination must not be missing before the condition is met. This will only trigger for a given metric/tag 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].
duration	integer: Number of seconds that data for the specified metric/tag combination must be below the threshold for before the condition is met. All data points within the given duration must be below the threshold to meet this condition. This avoids a single drop from triggering the condition. If unset, a single sample below the threshold will trigger the condition. The tracking duration begins with samples received after the alert condition is created or updated. Must be >= 60 seconds and <= 3600 seconds.

Alert Attributes

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

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

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

Create an Alert

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

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
   "name":"production.web.frontend.response_time",
   "description":"Web Response Time",
   "conditions":[
      {
         "type":"above",
         "metric_name":"web.nginx.response_time",
         "threshold":200,
         "summary_function":"max",
         "tags":[
            {
               "name":"tag_name",
               "grouped":false,
               "values":[
                  "tag_value"
               ]
            }
         ]
      }
   ],
   "services":[
      849
   ],
   "attributes": {
        "runbook_url": "http://myco.com/runbooks/response_time"
   },
   "active":true,
   "md":true
}' \
"https://metrics-api.librato.com/v1/alerts"

Not available

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

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

Response Code

201 Created

Response Headers

Location: /v1/alerts/123

Response Body

{
   "id":1234567,
   "name":"production.web.frontend.response_time",
   "description":"Web Response Time",
   "conditions":[
      {
         "id":19376030,
         "type":"above",
         "metric_name":"web.nginx.response_time",
         "source":null,
         "threshold":200.0,
         "summary_function":"max",
         "tags":[
            {
               "name":"tag_name",
               "grouped":false,
               "values":[
                  "tag_value"
               ]
            }
         ]
      }
   ],
   "services":[
      {
         "id":17584,
         "type":"slack",
         "settings":{
            "url":"https://hooks.slack.com/services/ABCDEFG/A1B2C3/asdfg1234"
         },
         "title":"librato-services"
      }
   ],
   "attributes":{
      "runbook_url":"http://myco.com/runbooks/response_time"
   },
   "active":true,
   "created_at":1484594787,
   "updated_at":1484594787,
   "version":2,
   "rearm_seconds":600,
   "rearm_per_signal":false,
   "md":true
}

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

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

Retrieve an Alert

Return alert with the id 123

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

Not available

import librato
api = librato.connect(<user>, <token>)
alerts = api.list_alerts(id="123")
for a in alerts:
  print(a.name)

Response Code

200 OK

Response Body

{
  "id": 123,
  "name": "production.web.frontend.response_time",
  "description":"Web Response Time",
  "conditions":[
      {
         "id":19375969,
         "type":"above",
         "metric_name":"web.nginx.response_time",
         "source":null,
         "threshold":200.0,
         "summary_function":"average",
         "tags":[
            {
               "name":"environment",
               "grouped":false,
               "values":[
                  "production"
               ]
            }
         ]
      }
   ],
  "services":[
      {
         "id":17584,
         "type":"slack",
         "settings":{
            "url":"https://hooks.slack.com/services/XYZABC/a1b2c3/asdf"
         },
         "title":"librato-services"
      }
   ],
  "attributes": {
    "runbook_url": "http://myco.com/runbooks/response_time"
  },
  "active":true,
  "created_at":1484588756,
  "updated_at":1484588756,
  "version":2,
  "rearm_seconds":600,
  "rearm_per_signal":false,
  "md":true
}

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

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

Not available

import librato
api = librato.connect(<user>, <token>)
alerts = api.list_alerts(name="production")
for a in alerts:
  print(a.name)

Response Code

200 OK

Response Body

{
  "query": {
    "found": 1,
    "length": 1,
    "offset": 0,
    "total": 1
  },
  "alerts": [
    {
      "id": 123,
      "name": "production.web.frontend.response_time",
      "description":"Web Response Time",
      "conditions":[
            {
               "id":19375969,
               "type":"above",
               "metric_name":"librato.cpu.percent.interrupt",
               "source":null,
               "threshold":200.0,
               "summary_function":"average",
               "tags":[
                  {
                     "name":"name",
                     "grouped":false,
                     "values":[
                        "value"
                     ]
                  }
               ]
            }
         ],
      "services":[
        {
           "id":17584,
           "type":"slack",
           "settings":{
              "url":"https://hooks.slack.com/services/XYZABC/a1b2c3/asdf"
           },
           "title":"librato-services"
        }
     ],
      "attributes": {
        "runbook_url": "http://myco.com/runbooks/response_time"
      },
      "active":true,
       "created_at":1484588756,
       "updated_at":1484588756,
       "version":2,
       "rearm_seconds":600,
       "rearm_per_signal":false,
       "md":true
    }
  ]
}

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

Retrieve Status of Specific Alert

Return the status for alert ID 120:

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

Not available

Not available

Response for an alert that is triggered:

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

Response for an alert that is not triggered:

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

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

HTTP Request

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

Update an Alert

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

To disable an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
   "id":6553597,
   "name":"my.alert.name",
   "description":"High CPU Load",
   "conditions":[
          {
            "id":19375969,
            "type":"above",
            "metric_name":"my.alert.name",
            "threshold":90,
            "summary_function":"average",
            "tags":[
              {
               "name":"my.environment",
               "grouped":false,
               "values":[
                  "production"
            ]
          }
        ]
      }
    ],
    "active":false
  }' \
"https://metrics-api.librato.com/v1/alerts/123"

Not available

import librato
api = librato.connect(<user>, <token>)
alert = api.get_alert("my.alert.name")
alert.active = "false"
alert.save()

To enable an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
   "id":6553597,
   "name":"my.alert.name",
   "description":"High CPU Load",
   "conditions":[
          {
            "id":19375969,
            "type":"above",
            "metric_name":"my.alert.name",
            "threshold":90,
            "summary_function":"average",
            "tags":[
              {
               "name":"my.environment",
               "grouped":false,
               "values":[
                  "production"
            ]
          }
        ]
      }
    ],
    "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.active = "true"
alert.save()

Update the description of an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
   "id":6553597,
   "name":"my.alert.name",
   "description":"A new description",
   "conditions":[
          {
            "id":19375969,
            "type":"above",
            "metric_name":"my.alert.name",
            "threshold":90,
            "summary_function":"average",
            "tags":[
              {
               "name":"my.environment",
               "grouped":false,
               "values":[
                  "production"
            ]
          }
        ]
      }
    ],
    "active":true
  }' \
"https://metrics-api.librato.com/v1/alerts/123"

Not available

import librato
api = librato.connect(<user>, <token>)
alert = api.get_alert("my.alert.name")
alert.description = "A new description"
alert.save()

Update the runbook URL for an alert:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
   "id":6553597,
   "name":"my.alert.name",
   "description":"A new description",
   "conditions":[
          {
            "id":19375969,
            "type":"above",
            "metric_name":"my.alert.name",
            "threshold":90,
            "summary_function":"average",
            "tags":[
              {
               "name":"my.environment",
               "grouped":false,
               "values":[
                  "production"
            ]
          }
        ]
      }
    ],
    "attributes": {
        "runbook_url": "http://myco.com/runbooks/response_time"
   },
    "active":true
  }' \
"https://metrics-api.librato.com/v1/alerts/123"

Not available

Not available

Response Code

204 No Content

Update the specified alert.

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

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

Notification Services

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

Associate a Service with an Alert

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

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

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d 'service=290' \
  -X POST \
  'https://metrics-api.librato.com/v1/alerts/45/services'

Not available

import librato
alert = api.get_alert("my.alert.name")
alert.add_service("290")
alert.save()

Response Code

201 Created

Headers

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

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

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

Remove a Service from an Alert

HTTP Request

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

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

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

Not available

Not available

Response Code

204 No Content

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

Resolve an Alert

Resolve alert ID 120:

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

Not available

Not available

Response Code

204 No Content

Clears the alert specified using the alert id.

HTTP Request

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

Delete Alert

Delete the alert id 123

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

Not available

import librato
api = librato.connect(<user>, <token>)
api.delete_alert("alert_name")

Response Code

204 No Content

Delete an alert by specifying a unique id or name.

HTTP Request

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

List all Alerts

List all alerts:

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

Not available

import librato
for alert in api.list_alerts():
    print(alert.name)

Response Body

{
  "query": {
    "offset": 0,
    "length": 2,
    "found": 2,
    "total": 7
  },
  "alerts": [
    {
      "id": 1400310,
      "name": "CPU.utilization",
      "description": null,
      "conditions": [
        {
          "id": 1016,
          "type": "above",
          "metric_name": "AWS.EC2.CPUUtilization",
          "source": "*prod*",
          "threshold": 90,
          "duration": 300,
          "summary_function": "max"
        }
      ],
      "services": [
        {
          "id": 1153,
          "type": "mail",
          "settings": {
            "addresses": "foo@domain.com,bar@domain.com"
          },
          "title": "Ops Team"
        }
      ],
      "attributes": {},
      "active": true,
      "created_at": 1394745670,
      "updated_at": 1394745670,
      "version": 2,
      "rearm_seconds": 600,
      "rearm_per_signal": false,
      "md": false
    },
    {
    // 1 more alert...
    }
  ]
}

List the status of all alerts:

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

Not available

Not available

Response Body

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

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

HTTP Request

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

Pagination Parameters

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

Other Parameters

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

API Tokens

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

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

API Token Properties

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

Create a Token

HTTP Request

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

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

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

Not available

Using JSON

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

Response Code

201 Created

Response Headers

Location: /v1/api_tokens/28

Response Body

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

Creates a new API Token.

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Retrieve a Token

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

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

Response Code

200 OK

Response Body

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

Returns the details for API Tokens that match a name. Supports wildcards, e.g. ? name=*token*.

HTTP Request

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

Retrieve a Token by ID

Retrieve the token with the id 28:

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

Response Code

200 OK

Response Body

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

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

HTTP Request

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

Update a Token

Update the token associated with the id 28:

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

Not available

Not available

Response Code

200 OK

Response Body

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

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Delete a Token

Delete the API token with ID 28:

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

Not available

Response Code

204 No Content

Delete the API Token identified by :id.

HTTP Request

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

List all Tokens

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

Not available

Response Code

200 OK

Response Body

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

Returns all API Tokens.

HTTP Request

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

Jobs

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

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

Job Properties

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

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

Retrieve a Job

Check status for job qith the id 123456:

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

Not available

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

Job in progress:

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

Job which has completed successfully:

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

A queued job which has not started yet:

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

A job that has failed:

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

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

HTTP Request

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

About Jobs

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

Snapshots

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

Snapshot Properties

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

Create a Snapshot

Create a snapshot of a stacked chart with the id of 1, and streams matching the tag set environment:prod*:

curl \
  -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \
  -d '{
    "subject": {
      "chart": {
        "id": 1,
        "tags": [{"name": "environment", "values": ["prod*"]}],
        "type": "stacked"
      }
    }
  }
  ' \
  -X POST \
  'https://metrics-api.librato.com/v1/snapshots'

Not available

Response Code

202 Accepted

Response Headers

Location: /v1/snapshots/:id

Response Body

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

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

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

Subject Parameters

Parameter	Definition
id	Each chart has a unique numeric ID.
type	Indicates the type of chart. One of line, stacked or bignumber.
tags	A set of key/value pairs that describe the particular data stream. Tags behave as extra dimensions that data streams can be filtered and aggregated along. The full set of unique tag pairs defines a single data stream. Wildcards can be used here (e.g. prod-* will include all tags that begin with prod-).

Retrieve a Snapshot

Return the snapshot with the id 1.

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

Not available

Response Code

200 OK

Response Body

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

Returns a specific snapshot associated with an id.

HTTP Request

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

Services

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

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

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

Service Properties

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

Pagination Parameters

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

Create a Service

Create a service that notifies the campfire room Ops:

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

Not available

Not available

Response Code

201 Created

Response Headers

Location: /v1/services/145

Response Body

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

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

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Parameters

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

Retrieve a Service

Return the service 156:

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

Not available

Not available

Response Code

200 OK

Response Body

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

Returns the specific service associated to the provided service id.

HTTP Request

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

Update a Service

Update the title for service 145:

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

Not available

Not available

Response Code

204 No Content

Updates a service by specifying the service id.

HTTP Request

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

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

Delete a Service

Delete the service 145:

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

Not available

Not available

Response Code

204 No Content

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

HTTP Request

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

List all Services

Return all services:

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

Not available

import librato
api = librato.connect(<user>, <token>)
services = api.list_services()
for s in services:
  print(s._id, s.title, s.settings)

Response Code

200 OK

Response Body

All services (when there are two total):

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

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

HTTP Request

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