Skip to content

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.

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