POST /metrics

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

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

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

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

Headers

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

For HTML (default):

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

For JSON:

Content-Type: application/json

Measurement Parameters

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

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

name

The unique identifying name of the property being tracked. The metric name is used both to create new measurements and query existing measurements. Must be 255 or fewer characters, and may only consist of 'A-Za-z0-9.:-_'. Depending on the submission format the location of the name parameter may vary, see examples below in "Measurement Formats". The metric namespace is case insensitive.

value

The numeric value of a single measured sample.

measure_time

(optional) The integer value of the unix timestamp of the measurement. If not specified will default to time the measurement is received.

source

(optional) A string which describes the originating source of a measurement when that measurement is tracked across multiple members of a population. Examples: foo.bar.com, user-123, 77025.

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

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

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

Gauge Specific Parameters

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

count

Indicates the request corresponds to a multi-sample measurement. This is useful if measurements are taken very frequently in a closed loop and the metric value is only periodically reported. If count is set, then sum must also be set in order to calculate an average value for the recorded metric measurement. Additionally min, max, and sum_squares may also be set when count is set. The value parameter should not be set if count is set.

sum

If count was set, sum must be set to the summation of the individual measurements. The combination of count and sum are used to calculate an average value for the recorded metric measurement.

max

If count was set, max can be used to report the largest individual measurement amongst the averaged set.

min

If count was set, min can be used to report the smallest individual measurement amongst the averaged set.

sum_squares

If count was set, sum_squares report the summation of the squared individual measurements. If sum_squares is set, a standard deviation can be calculated for the recorded metric measurement.

Measurement Formats

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

Hashed by name

Each metric name is a hash to the measurement values. For example, for gauges:

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

This example creates a gauge measurement for the gauge login-delay with a value 3.5.

Multiple measurements with the same name

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

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

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

Array format (JSON only)

If the submission Content-Type is JSON, you can also specify the measurement parameters in an array format. This is only supported in JSON formats since the URL-encoded-form content type does not support an array format. For example, the following JSON message will create the same measurements as the previous example:

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

Examples

This creates a total of three new measurements: two counter measurements (conn_servers and write_fails) and one gauge measurement (cpu_temp).

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

Default measure_time and source

curl \
  -u <user>:<token> \
  -d 'measure_time=1234567950' \
  -d 'source=blah.com' \
  -d 'counters[0][name]=conn_servers' \
  -d 'counters[0][value]=5' \
  -d 'counters[1][name]=write_fails' \
  -d 'counters[1][value]=3' \
  -d 'gauges[0][name]=cpu_temp' \
  -d 'gauges[0][value]=88.4' \
  -d 'gauges[0][source]=cpu0_blah.com' \
  -d 'gauges[0][measure_time]=1234567949' \
  -X POST \
  https://metrics-api.librato.com/v1/metrics

Response Code

200 Success

Response Body

** NOT APPLICABLE **