Metrics API
Authentication
The metrics endpoint uses a project token for authentication, all other endpoints use your user token.
Response Format
All API responses to the Metrics API are contained in a JSON hash that follows the general format:
{ "version":2, // The API version you requested "flags":0, // Reserved for future use "response": {…} // Requested data }
List Metrics
The metrics listing API endpoint allows you to list up to 500 of a project's metrics. You may specify an offset
parameter if your project has more than 500 metrics.
The returned data does not include any datapoints. To retrieve metric datapoints, use the Get Metric Data endpoint.
Request Examples
List the first 500 metrics in your account
GET /api/2/metrics
List 500 metrics from your account starting 500 in
GET /api/2/metrics?offset=500
Command Line Example
curl -H 'X-Instrumental-Token: PROJECT_TOKEN' https://instrumentalapp.com/api/2/metrics
Response
{ "version": 2, "flags": 0, "response": { "metrics": [ { "id": "test.gauge_metric", // The name of the metric "project_id": 1, // The integer id associated with your project "type": "gauge", // The type you've reported as the metric "created_at": 1326493549, // When you first reported the metric "updated_at": 1326493549, // When you last updated the metric "values": null, // Datapoints, not returned "expression": null, // Expression used to retrieve metric, not returned "name": null // Name derived from expression of metric, not returned }, { "id": "test.increment_metric", "project_id": 1, "type": "increment", "created_at": 1326493537, "updated_at": 1326493537, "values": null, "expression": null, "name": null } ] } }
Find Metrics
The find metrics API endpoint allows you to find all metrics whose name matches some string. A find query expressed as ?query=my.metric
will return data regarding any metric that begins with the string my.metric
. A find query using a wildcard character ?query=my.*
will return all metrics that have the prefix my.
; multiple wildcards are supported, e.g. ?query=request.*.db.*
.
Metrics Used After Some Date
The list of metrics returned can be scoped to only those active after a certain date. You may specify the date by providing a querystring parameter used_later_than
, whose value is the Unix timestamp in seconds of that date.
Matching Behavior
The default behavior of the matching endpoint is to return any metrics whose prefix matches the query provided. You may disable this behavior by specifying the parameter prefix_match
and set its value to 0
.
Returned Values
The returned data does not include any datapoints. To retrieve metric datapoints, use the Get Metric Data endpoint.
Request Examples
Find all metrics whose name matches metric.query*
GET /api/2/metrics/matching?query=metric.query
Find all metrics matching the wildcard query *gauge*
GET /api/2/metrics/matching?query=*gauge*
Find the metric whose names is metric.query
GET /api/2/metrics/matching?query=metric.query&prefix_match=0
Find all metrics reported after January 1st, 2012 that match metric.*
GET /api/2/metrics/matching?query=metric.*&used_later_than=1325376000
Command Line Example
curl -H 'X-Instrumental-Token: PROJECT_TOKEN' -G -d "query=YOUR_QUERY" https://instrumentalapp.com/api/2/metrics/matching
Response
{ "version": 2, "flags": 0, "response": { "metrics": [ { "id": "test.gauge_metric", // The name of the metric "project_id": 7, // The integer id associated with your project "type": "gauge", // The type you've reported as the metric "created_at": 1326493549, // When you first reported the metric "updated_at": 1326493549, // When you last updated the metric "values": null, // Datapoints, not returned "expression": null, // Expression used to retrieve metric, not returned "name": null // Name derived from expression of metric, not returned } ] } }
Get Metric Data
The metric data endpoint will return metric information and datapoints for the named metrics you specify. The datapoints returned will be interpolated over a specific duration and resolution.
The default duration for these requests is 30 minutes; the default resolution is 1 minute.
Duration and Resolution
When requesting metrics, you may specify a duration and resolution from the following values:
Durations | Resolutions | ||
---|---|---|---|
1800 | 30 minutes (Default) | 60 | 1 minute (Default) |
3600 | 1 hour | 300 | 5 minutes |
10800 | 3 hours | 1200 | 20 minutes |
21600 | 6 hours | 3600 | 1 hour |
43200 | 12 hours | 10800 | 3 hours |
86400 | 1 day | 21600 | 6 hours |
259200 | 3 days | 86400 | 1 day |
604800 | 7 days | 604800 | 7 days |
1209600 | 14 days | ||
2592000 | 1 month | ||
7776000 | 3 months |
Instrumental Query Language
When retrieving metrics, you may pass one or more query language expressions to be evaluated by the API. See the language reference for more information regarding the syntax and functions available. Keep in mind that depending on the form of your syntax, you may be required to escape your expression using a function similar to JavaScript's encodeURI
in order to craft a proper URL.
Errors
If you submit an incorrectly formed expression to the Instrumental API, or attempt to use functions that don't exist, you will cause an error. The API will indicate the sort of error caused through the HTTP status code and response body.
HTTP Status Code | Meaning |
---|---|
400 |
The expression you provided was unable to be parsed. Please check the response body for more information. |
500 |
The expression you provided was unable to be evaluated due to some internal error. The response body should indicate the nature of the error. |
Request Examples
Metric named test.metric
GET /api/2/metrics/test.metric
Metric named test.metric
as of 24 hours ago
GET /api/2/metrics/test.metric%20@%2024%20hours
All metrics starting with the string "test
"
GET /api/2/metrics/test*
The deviation of test.metric
from its average, with the name aliased as test_deviation
GET /api/2/metrics/series_deviation(test.metric)%20as%20test_deviation
Metrics named test.metric
and test.response_time
GET /api/2/metrics/test.metric;test.response_time
Metric named test.metric
with the default duration and resolution of 5 minutes
GET /api/2/metrics/test.metric?resolution=300
Metric named test.metric
with duration of 24 hours and default resolution
GET /api/2/metrics/test.metric?duration=86400
Metrics named test.metric
with duration of 24 hours and resolution of 1 hour
GET /api/2/metrics/test.metric?duration=86400&resolution=3600
Command Line Example
curl -H 'X-Instrumental-Token: PROJECT_TOKEN' https://instrumentalapp.com/api/2/metrics/YOUR_METRIC_NAME
Response
{ "version": 2, "flags": 0, "response": { "metrics": [ { "id": "test.gauge_metric", // The name of the metric "project_id": 1, // The integer id associated with your project "type": "gauge", // The type you've reported as the metric "created_at": 1326493549, // When you first reported the metric "updated_at": 1326729988, // When you last updated the metric "expression": "test.gauge_metric", // Expression used to retrieve metric "name": "test.gauge_metric", // Name derived from expression of metric "values": { // Datapoints "start": 1326728400, // The beginning of the time series "stop": 1326730200, // The end of the time series "resolution": 60, // The requested resolution of the time series "duration": 1800, // The requested duration of the time series "data": [ { "s": 4675616.0, // The sum of datapoints at this moment "c": 94742, // The count of datapoints at this moment "a": 49.351037554622025 // Average (sum/count) }, // ... Above hash repeats over duration ] } } ] } }