Metric Sources
Using Instrumental
- Metrics
- Graphs
- Alerts
- Notices
- Querying
- Where to Start
InstrumentalD
- Installation
- Configuration
- System Metrics
- Service Metrics
- - Docker
  - MySQL
  - Memcached
  - MongoDB
  - Nginx
  - PostgreSQL
  - Redis
- Plugin Scripts
Data Collector
- TCP Collector Protocol
API Reference

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