About the Mackerel API
With Mackerel, various types of data can be collected and updated using the API.
For example you can get the list of hosts you are managing using curl as shown below.
$ curl -H "X-Api-Key: <YOUR_API_KEY>" https://mackerel.io/api/v0/hosts.json
For more information please refer to the API specs.
Introduction to the safer and more secure read-only API keys
Until now, however, all API keys had write permission and there were several areas where security was weak.
- fear of accidentally doing an update operation
- fear of improper operations being done due to a leak of information
Of course is was possible before as well to delete API keys in the event of a breach in security, but there was the potential threat of improper actions being taken by a malicious third party before an information leak is recognized.
In this blog post, we will introduce some recently added APIs, particularly the read-only API key and some examples of ways it can be used.
3 usage examples
Server Operations using the API
By getting host information from Mackerel’s API, repetitive tasks such as logging in to all hosts belonging to a role in a certain service at the same time can be optimized.
Here we will show how just by writing a simple shell script you can use the API even more easily.
The script we will introduce here can be used by configuring
MACKEREL_APIKEY in the environment variables.
$ export MACKEREL_APIKEY="YOUR API KEY"
Script to get the list of services
#!/bin/bash curl -s -H "X-Api-Key: $MACKEREL_APIKEY" "https://mackerel.io/api/v0/services" | jq -a -M -r '.services.name'
Using the above script you can get the list of services.
Script to get the list of roles
#!/bin/bash if [[ $1 == '' ]]; then echo "required service name" exit 1 fi curl -s -H "X-Api-Key: $MACKEREL_APIKEY" -X GET "https://mackerel.io/api/v0/services/$1/roles" | jq -a -M -r '.roles.name'
By passing a service name as the argument, you can get the list of roles attached to that service.
More convenient joining
These kinds of small scripts might not seem so convenient at first, but by putting them together they can save you time in dealing with daily operations.
In order to log in to hosts in one role of a service at the same time with SSH, which we mentioned earlier, we’ll need to get the list of hosts from Mackerel.
#!/bin/bash if [[ $1 == '' ]]; then # Script to get the list of services service=$(services | peco) else service=$1 fi if [[ $2 == '' ]]; then # Script to get the list of roles role=$(roles $service | peco) else role=$2 fi curl -s -H "X-Api-Key:$MACKEREL_APIKEY" -X GET "https://mackerel.io/api/v0/hosts.json?service=$service&role=$role" | jq -a -M -r ".hosts.name"
In this example, while it’s not possible to do things such as selecting multiple roles, compared to having to enter each host name every time it’s much more convenient.
Depending on your arrangement, it’s possible to use these kinds of simple APIs together in a very convenient manner.
Easily make custom dashboards with Mackerel Dashboard Generator!
With custom dashboards you can line up your favorite graphs to be displayed in one place.
When using custom dashboards there may be a time when you want to display each metric graph of a host belonging to a role in a service, but to paste all of those graphs into the custom dashboard manually would end up taking a long time.
Using a tool called mackerelio/mdg you can now generate Markdown for custom dashboards.
If designating the target services and roles, as well as the time spans of the graphs that will be displayed, it’s possible to automatically generate Markdown that will display embedded metrics graphs.
$ mdg -o Saba -s Saba-service -r db
Designating the service and other information in the option as shown above and executing will generate the following Markdown.
### disk.writes |2d|3w|3mo| |:--|:--|:--| |<iframe src='https://mackerel.io/embed/orgs/Saba/services/Saba-service/db?graph=disk.writes&period=2d' height='200' width='400' frameborder='0'></iframe>|<iframe src='https://mackerel.io/embed/orgs/Saba/services/Saba-service/db?graph=disk.writes&period=3w' height='200' width='400' frameborder='0'></iframe>|<iframe src='https://mackerel.io/embed/orgs/Saba/services/Saba-service/db?graph=disk.writes&period=3mo' height='200' width='400' frameborder='0'></iframe>| ...
This tool, if you really think about it, isn’t using an API. Having to enter the service name and role name every time is a pain though.
For that, please try using the shell script that was created last time to acquire the service name and role name.
Automatic creation of server management register
In this example we are getting the information of the hosts being managed using Google Apps Script and creating a list. Also, by using Google Spreadsheets, automatically displaying statistical information is also possible.
The freedom to combine Mackerel with other software can be taken advantage of in many ways such as creating written reports or for getting an overview of large numbers of hosts that will increase as your company continues to grow.
In addition to the APIs which were introduced, we are also offering APIs to handle metrics and monitor settings. Of course we are also offering APIs used to carry out update operations using API keys with write permissions. For more information please refer to the API specs
Our development team is always working to continue making Mackerel easier and more convenient for our users. As always we greatly appreciate your requests, opinions, and feedback.
We really hope you’ll give Mackerel’s even easier to use API a try.