Search By Category

Is it possible to download metrics and monitors?

Metrics and monitoring rules posted to Mackerel can be downloaded using the API or the CLI tool mkr.

This page provides sample commands using curl in a Linux environment. If you are calling the API from a different environment, replace the commands as appropriate.

Notes on Downloading

  • Downloading from the Web console is not supported.
  • Only items that can be retrieved via the API can be downloaded.
  • Labeled metrics are not supported for download.
  • Check monitoring is not supported for download.
  • The output format for both the API and mkr is JSON.
  • For details on how to output in CSV format, see "Converting JSON Output to CSV Format".
  • If you use mkr, please install it beforehand by referring to this page.
    • On Windows, mkr is bundled with mackerel-agent.

Downloading Metrics

About Metric Retrieval

  • Specifying metric names
    • Refer to the following for system metric names posted by mackerel-agent:
    • For custom metric names registered by plugins, check them using one of the following methods:
  • Specifying the time period
    • Specify the period using epoch seconds (Unix time).
    • When retrieving metrics via the API or mkr, the granularity of the metrics changes depending on the specified period, and the retrieved values will be the averages for that granularity. To retrieve values at 1-minute granularity, specify a period of 20 hours or less.

How to retrieve metrics with the API

$ curl \
-s https://api.mackerelio.com/api/v0/hosts/<hostId>/metrics?name=loadavg1&from=<epoch seconds>&to=<epoch seconds> \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <API Key>' \
-X GET

{"metrics":[{"time":1617163080,"value":0.27},{"time":1617163140,"value":0.13}, ...]}

How to retrieve metrics with mkr

  • Metrics can be retrieved using mkr metrics or mkr fetch.
  • Below is an example of retrieving the loadavg1 metric using the mkr metrics command.
$ mkr metrics --host <hostId> --name loadavg1 --from <epoch seconds> --to <epoch seconds>
[
  {
    "time": 1617163080,
    "value": 0.27
  },
  :
]

Downloading Monitoring Rules

How to retrieve monitoring rules with the API

  • For details about the monitoring rule API, see the following API documentation:
  • When retrieving an individual monitoring rule using the API, specify the <monitorId> by referring to either of the following:
    • The id value of each monitoring rule included in the response of the List Monitor Configurations API.
    • The monitor=xxxxxxx value in the URL when opening the monitoring rule details screen in the Web console.
  • Below is an example of retrieving a monitoring rule using the curl command.
$ curl \
-s https://api.mackerelio.com/api/v0/monitors/<monitorId> \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <API Key>' \
-X GET

{"monitor":{"duration":1,"maxCheckAttempts":3,"critical":95,"isMute":false,"metric":"cpu%","excludeScopes":[],"name":"CPU %","warning":80,"id":"xxxxxxxx","scopes":[],"type":"host","operator":">"}}

How to retrieve monitoring rules with mkr

  • Monitoring rules can be retrieved using mkr monitors pull.
    • A monitors.json file will be created in the directory where the command is executed.
    • In addition to pull, mkr monitors also supports diff (view differences) and push (update).
  • Below is an example of retrieving monitoring rules using the mkr command.
$ mkr monitors pull
info Monitor rules are saved to 'monitors.json' (6 rules).

Converting JSON Output to CSV Format

You can filter JSON responses from the API and convert them to CSV format by piping the JSON string into the jq command.

$ curl \
-s https://api.mackerelio.com/api/v0/hosts/<hostId>/metrics?name=loadavg1&from=<epoch seconds>&to=<epoch seconds> \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <API Key>' \
-X GET \
| jq '.[] | .[] | [.time, .value] | @csv'

1617163080,0.27
1617163140,0.13
:

Similarly, mkr can filter and convert data to CSV format using the --jq option (which complies with the gojq specification).

mkr metrics --host <hostId> --name loadavg1 --from <epoch seconds> --to <epoch seconds> --jq '.[] | [.time,.value] | @csv'

1617163080,0.27
1617163140,0.13
:

Related articles