mackerel-agent specifications

This article is an explanation of the latest version of mackerel-agent.


mackerel-agent [-conf <config-file>] [options]


Running in the foreground, mackerel-agent

  • registers hosts information with Mackerel,
  • gathers resource information and posts it to Mackerel (once every minute),
  • updates hosts’ information (once every hour)

You can check your hosts’ and resources’ posted data on Mackerel’s web interface.

Configuration file

The configuration file is located here /etc/mackerel-agent/mackerel-agent.conf by default.

The contents will be described in TOML and if multibyte characters are included in the configuration, file encoding must be UTF-8. Description examples follow below.

apikey = "APIKEY"
pidfile = "/path/to/pidfile"
root = "/var/lib/mackerel-agent"

cloud_platform = "ec2"

verbose = false
silent = false

display_name = "My Host"

roles = [ "My-Service:app", "Another-Service:db" ]

include = "/etc/mackerel-agent/conf.d/*.conf"

on_start = "working"
on_stop  = "poweroff"

ignore = "/dev/ram.*"
use_mountpoint = true

command = "ruby /etc/sensu/plugins/system/vmstat-metrics.rb"

command = "ruby /path/to/your/plugin/mysql.rb"

command = ""
env = { "ES_HOSTS" = "," }
action = { command = "cardiac_massage", user = "doctor", env = { SAMPLE_KEY_1 = "VALUE_1", SAMPLE_KEY_2 = "VALUE_2" } }

command = "ruby /path/to/check-ssh.rb"

command = "perl /path/to/"

The configuration file will be read when the agent starts up, so you'll have to restart the agent after changes are made to this file.

All options other than APIKEY are optional, so if the default settings are acceptable it’s okay to leave values empty.

Reading other configuration files

It is possible to have other configuration files be read by setting the item to include in the configuration file.

  • file globe can be specified as shown here /etc/mackerel-agent/conf.d/*.conf
  • as for character string, authenticity value, and array settings (verbose and roles), if these values are present in a later read configuration file, they will be overwritten
  • if there are multiple matching configuration files present, the order in which they will be read will be inconsistent.
  • the include setting item within configuration files that have been read will be ignored

Service and role configuration

Designation of hosts’ services and roles can be done from either the agent launch options or the settings file. If the services and roles you have designated here do not yet exist, they will be created automatically. If an irregular string is included the proper connections will not be made, so please double-check your designations if the agent is not operating as intended.

Example: Linking “My-Service” to a role called “app” as well as “Another-Service” to a role called “db”.

Specify the roles setting item in the configuration file. (TOML array)

# /etc/mackerel-agent/mackerel-agent.conf
roles = [ "My-Service:app", "Another-Service:db" ]


mackerel-agent -role=My-Service:app -role=Another-Service:db …

With these settings in place, the connections will be made when the agent is launched. Changes made on the web will not be synced with the agent settings file.

Display name config

It is possible to set an optional alias for a host by assigning a name within the configuration file. If a display name has already been assigned, the host will be updated to the new display name. Additionally, even if the display name assignment of a host has been deleted from the configuration file, the display name will remain as it was configured. Display names can be deleted in the host's settings page.

# /etc/mackerel-agent/mackerel-agent.conf
display_name = "My Host"

Connecting via HTTP Proxy.

By specifying a URL like shown below, you can configure an HTTP Proxy.

# /etc/mackerel-agent/mackerel-agent.conf
http_proxy = "http://localhost:8080"

The environment variable HTTP_PROXY is also supported. For example, by specifying this as shown below, you gain access via HTTP Proxy.

% HTTP_PROXY=http://localhost:8080 mackerel-agent

By appending an environment variable to the file /etc/sysconfig/mackerel-agent for yum/rpm packages and /etc/default/mackerel-agent for apt/deb packages, it’s possible to apply this to the mackerel-agent. For example, you can specify the following.


Running the agent on EC2, Azure VM, and other IaaS

When running mackerel-agent on AWS EC2, Azure VM, or GCP, it automatically detects the IaaS environment. When these IaaS environments can be identified, mackerel-agent collects the IaaS metadata and applies the necessary identifier (custom_identifier) to the host for integration with AWS integration or Azure integration.

Normally, this detection is done automatically, but the platform can be specified explicitly by specifying the cloud_platform option in the configuration file. There are five valid values: " auto " (default) " ec2 " " gce " " azurevm " " none ".

If you want to launch multiple mackerel-agents on one IaaS instance and for them be recognized as separate hosts, when using Docker container etc. for example, this option must be set to "none" in all of the configuration files except for the mackerel-agent running on the instance.

Host status config

It is possible to set a host's status by assigning a new status within the configuration file. It is possible to assign different statuses for when the agent boots up and for when it shuts down.

By making the assignments as shown below, a host's status will be set to working when the agent boots up, and poweroff when the agent successfully shuts down.

# /etc/mackerel-agent/mackerel-agent.conf
on_start = "working"
on_stop  = "poweroff"

Possible statuses are working , standby , maintenance , and poweroff .

Excluding specific file systems

Metric collections from specific file systems can be excluded by designating so in the config file.

By designating a regular expression like shown below, metrics from the designated file system will no longer be collected.

# /etc/mackerel-agent/mackerel-agent.conf
ignore = "/dev/ram.*"

Obtaining filesystem metrics for each mount point

You can obtain filesystem metrics for each mount point by specifying the following in the configuration file.

# /etc/mackerel-agent/mackerel-agent.conf
use_mountpoint = true

Posting user-defined metrics

Register custom user-defined metrics in the 「plugin.metrics.*」section of the settings file to post them to Mackerel. For more information please refer to Posting user-defined custom metrics.

Posting monitoring results from scripts

In the 「plugin.checks.*」section of the configuration file it is possible to register an optional script and post it's execution results to Mackerel. For more information please check Adding monitors for script checks.

Posting metadata

You can register optional JSON data in the "plugin.metadata.*" section of the configuration file. For details, please refer to Using metadata.

Diagnostics mode

By activating this feature in the agent's startup options or in the configuration file, the agent's memory usage status information can be collected and posted as a custom metric.

# /etc/mackerel-agent/mackerel-agent.conf
diagnostic = true


mackerel-agent -diagnostic

The following metrics can be collected.

  • custom.agent.memory.alloc
  • custom.agent.memory.sys
  • custom.agent.memory.heapAlloc
  • custom.agent.memory.heapSys

For more information please refer to

Log output related configurations

DEBUG log output

The DEBUG log output can be enabled by setting verbose = true.

Log output suppression

Log output below WARN level can be suppressed by setting silent = true.

Startup options

The following startup options can be specified. If the same items are specified in the configuration file, the startup option items will take precedence.

  • -apikey=API_KEY This is the API key that a host is identified by on the web. This key is how Mackerel knows which organization a host belongs to. (This is not recommended. We recommend that you include this in the configuration file from version 0.5.1.)
  • -conf=/etc/mackerel-agent/mackerel-agent.conf This is the settings file path. If you haven’t specified this yet,/etc/mackerel-agent/mackerel-agent.confwill be read by default.
  • -pidfile=/var/run/ This is the PID file path.
  • -root=/var/lib/mackerel-agent This is the path of the directory where the status of the mackerel-agent is recorded. Currently only the ID file that identifies the host will be placed here.
  • -role=<service>:<role> This designates the roles and services a role is assigned to.
  • -once this will execute metric collection and display standard output just one time. Metrics will not be posted.
  • -diagnostic metrics for the agent itself will be collected and posted.


How does the agent distinguish between different hosts?

The agent tells one host from another by looking at the host ID which is stored in /var/lib/mackerel-agent/id. A host’s name cannot be used to distinguish it. (If the settings file is changing the root with the boot options, an ID file will be created under that root.)

The agent won’t launch.

If there is an incorrect ID stored in /var/lib/mackerel-agent/id the agent will not launch properly. Delete /var/lib/mackerel-agent/id and try launching again. (This will recognize it as a new host.) (If the settings file is changing the root with the boot options, an ID file will be created under that root.)

Can multibyte characters be used?

Yes, they can be used. However, please note that the conf file character code (encoding) must be UTF - 8.

Sub Commands

mackerel-agent has several commands that can be used.


mackerel-agent retire [-conf <config-file>] [-force] [options]

This command will retire the host. When executed a confirmation prompt will be displayed. Attaching the -force option will bypass the confirmation prompt and retire the host.


mackerel-agent configtest

Check the syntax of the configuration file (mackerel-agent.conf).

Settings file for init script

By appending environment variable settings to, for yum/rpm packages /etc/sysconfig/mackerel-agent, for apt/deb packages /etc/default/mackerel-agent, it’s possible to have them applied to the mackerel-agent. The following variables can be configured.


This will assign the option you want to add in the mackerel-agent. For example, by making an assignment like OTHER_OPTS=”diagnostic-verbose”, diagnostics mode will be activated and the DEBUG log will be outputted.


By assigning a character string other than 0 to this variable, the host will be automatically retired upon OS shutdown (or more specifically /etc/init.d/mackerel-agent stop).

Caution Even if you have manually typed /etc/init.d/mackerel-agent stop, if the above assignment has already been made, the host will be retired. If you want to, say, update the agent to the latest version or start/stop the agent, please use /etc/init.d/mackerel-agent reload.