API

Please note: This documentation is a work in progress and more detail is required.

Query using PromQL

Query using PromQL and returns JSON datapoints compatible with the Prometheus Grafana plugin.

URL

/api/v1/query_range

Method

GET

URL Params

Required

• start=[time in RFC3339Nano]
• end=[time in RFC3339Nano]
• step=[time duration]
• target=[string]

Optional

• debug=[bool]
• lookback=[string|time duration]: This sets the per request lookback duration to something other than the default set in config, can either be a time duration or the string “step” which sets the lookback to the same as the step request parameter.

Header Params

Optional

• M3-Metrics-Type:
  If this header is set, it determines what type of metric to store this metric value as. Otherwise by default, metrics will be stored in all namespaces that are configured. You can also disable this default behavior by setting downsample options to all: false for a namespace in the coordinator config, for more see disabling automatic aggregation. Must be one of:
  unaggregated: Write metrics directly to configured unaggregated namespace.
  aggregated: Write metrics directly to a configured aggregated namespace (bypassing any aggregation), this requires the M3-Storage-Policy header to be set to resolve which namespace to write metrics to.

• M3-Storage-Policy:
  If this header is set, it determines which aggregated namespace to read/write metrics directly to/from (bypassing any aggregation).
  The value of the header must be in the format of resolution:retention in duration shorthand. e.g. 1m:48h specifices 1 minute resolution and 48 hour retention. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”. Here is an example of querying metrics from a specific namespace.

• M3-Restrict-By-Tags-JSON:
  If this header is set it can ensure specific label matching is performed as part of every query including series metadata endpoints. As an example, the following header would unconditionally cause globaltag=somevalue to be a part of all queries issued regardless of if they include the label or not in a query and also strip the “globaltag” from appearing as a label in any of the resulting timeseries:

M3-Restrict-By-Tags-JSON: '{"match":[{"name":"globaltag","type":"EQUAL","value":"somevalue"}],"strip":["globaltag"]}'

• M3-Limit-Max-Series:
  If this header is set it will override any configured per query time series limit. If the limit is hit, it will either return a partial result or an error based on the require exhaustive configuration set.

• M3-Limit-Max-Docs:
  If this header is set it will override any configured per query time series * blocks limit (docs limit). If the limit is hit, it will either return a partial result or an error based on the require exhaustive configuration set.

• M3-Limit-Require-Exhaustive:
  If this header is set it will override any configured require exhaustive setting. If “true” it will return an error if query hits a configured limit (such as series or docs limit) instead of a partial result. Otherwise if “false” it will return a partial result of the time series already matched with the response header M3-Results-Limited detailing the limit that was hit and a warning included in the response body.

Data Params

None.

Sample Call

curl 'http://localhost:7201/api/v1/query_range?query=abs(http_requests_total)&start=1530220860&end=1530220900&step=15s'
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "code": "200",
          "handler": "graph",
          "method": "get"
        },
        "values": [
          [
            1530220860,
            "6"
          ],
          [
            1530220875,
            "6"
          ],
          [
            1530220890,
            "6"
          ]
        ]
      },
      {
        "metric": {
          "code": "200",
          "handler": "label_values",
          "method": "get"
        },
        "values": [
          [
            1530220860,
            "6"
          ],
          [
            1530220875,
            "6"
          ],
          [
            1530220890,
            "6"
          ]
        ]
      }
    ]
  }
}