Using our API, a wide range of features can be implemented. In this blog post we will be introducing some different ways to use our even more convenient than before API.
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
Since the responses come back in JSON, you can use multiple language’s JSON libraries to parse the JSON or use tools such as jq to retrieve necessary data.
For more information please refer to the API specs.
Introduction to the safer and more secure read-only API keys
Mackerel API uses and authenticates API keys for each organization.
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.
To solve these problems, and make it so that the API can be used more freely, we’ve made it possible to configure API keys with read-only permission.
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"
Here we will use a filtering tool called peco, select the service and role while filtering the list of services and roles we got from the API, and lastly we will obtain a list of hosts with the API.
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.
APIs used
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>| ...
Pasting this Markdown into a custom dashboard will produce the dashboard below.
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.
An example of how to conveniently use the API together with peco can be found in the mdg README
APIs used
Automatic creation of server management register
Using the API, you can create a chart of the information of the hosts you are managing in each role and service. Below is an example of a chart made with Google Spreadsheets.
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.
APIs used
Review
With the addition of read-only API keys and service and role APIs, Mackerel’s API is now safer and easier to use than ever.
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.
