PUT /v1/metrics/:name

Description

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

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

URL

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

Method

PUT

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

type

Type of metric to create (gauge or counter).

Optional Parameters

display_name

Name which will be used for the metric when viewing the Metrics website.

description

Text that can be used to explain precisely what the gauge is measuring.

period

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

The attributes hash configures specific components of a metric's visualization.

Examples

Updating a metric

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

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

Response Code

204 No Content

Response Body

** NOT APPLICABLE **

Creating a metric

Creates the gauge metric named queue_len (assumes this metric does not exist).

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

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"
  }
}