Get a counter

Home - HTTP Interface - Get a counter

Usage

GET /counter.name
GET /counter.name?start=A
GET /counter.name?end=B
GET /counter.name?start=A&end=B
GET /counter.name?format=csv

Parameters

• counter.name - The string specifying the name of a counter to get.
• start - An optional Unix timestamp specifying the lower time bound to use. (Default: 15 minutes before end)
• end - An optional Unix timestamp specifying the upper time bound to use. (Default: now)
• samples - An optional maximum number of samples for this counter. (Default: 1000)
• format - An optional format specifier, which may be either or json or csv. (Default: json)
• The value of end must be >= start.

Overview

Use this URI to get a counter from istatd using the counter name format (e.g. cpu.idle.abc123). Optionally, specify the start and/or end time range of the counter data to narrow the search.

If start and end are not specified, then the response will contain the finest interval data recorded in the last 15 minutes for the specified counter. Currently, the finest interval is 10 seconds. Therefore, up to 90 buckets may be returned with this query (10s * 90 buckets = 15 minutes of data).

If only start is specified, then the response will contain up to 90 samples of data of the finest resolution starting at the specified time. For example, if the finest resolution is 10s interval data, then the time range could be a long as 15 minutes. On the other hand, if the finest resolution is 3600s interval data, then the time range could be up to 90 hours.

If only end is specified, then return up to 90 samples of data of the finest resolution ending at the specified time.

If start and end are both specified, then return the finest resolution of data that covers the entire requested range. No more samples than the value specified by samples will be returned in this case. (There are 8760 buckets in a years worth of 1 hour interval data.) If the selected range is more than samples, then data is coalesced to a coarser resolution, generating "synthetic" buckets of data.

istatd does not like samples (buckets) that have a start time that is not an even multiple of the size of the bucket. This means that a request for a certain time range may be rounded up/down to make sure each bucket is "properly" aligned to its size. At the extreme case of samples=1, this mechanism breaks down somewhat. The returned sample will still be reduced to a single bucket, but that bucket will be aligned at a boundary that is half that of the extent of the bucket. The easiest way to get "what you want" out of the query arguments, is to want data in buckets whose time stamps are naturally aligned on multiples of the bucket length. For example, if you want five minute buckets for an hour's period, ask for 12 buckets, starting at an even multiple of 5 minutes.

If there is no data for a counter in the specified time range, a JSON object with an empty list.

There is also an optional format parameter, which can determine the document type to serve. The document may either be json (the default) or csv.

Response

When data is found a list of buckets is returned in a JSON structure,

• Status code: 200
• Every bucket in the list has the same interval
• The first and last bucket in the last always has a value. The first and last bucket may be the same bucket (i.e. list of one bucket)
• The list can be sparse, when there are gaps in the data.
• The list may not cover the entire requested range whenever data for that range is missing.

Response body:

{
    "start"    : int,  // time of the first bucket in the list. Might be later than the start time requested, due to time gaps.
    "end"      : int,  // time of the last bucket in the list + the interval time. Might be earlier than the end time requested, due to time gaps.
    "interval" : int,  // interval of bucket. all buckets in list have the same interval
    "buckets"  : [ 
        {
            "time" : int,   // time at beginning of bucket
            "data" : {
                "count" : int,     // num values in bucket
                "min"   : float,   // min value in bucket
                "max"   : float,   // max value in bucket
                "sum"   : float,   // sum of values in bucket
                "sumsq" : float    // sum of squares of values in bucket
                "avg"   : float    // the average over all values in this bucket, zero if count == 0.
                "sdev"  : float    // the standard deviation over all in this bucket, zero if count < 2.
            }
        },
        // ... the rest of the buckets.
    ]
}

When data is not found,

• Status code: 200

Response body:

{
    "interval": 0,
    "buckets": []
}

When a counter does not exist,

• Status code: 404

When any argument is invalid,

• Status code: 400

• Examples of bad parameters:

  • ?start=Monday
  • ?start=999999&end=1
  • ?end=-5
  • ?samples=-10
  • ?format=dumb