This article is an explanation of the latest version of mackerel-agent.
mackerel-agent [-conf <config-file>] [options]
Running in the foreground,
- 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.
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" verbose = false silent = false display_name = "My Host" roles = [ "My-Service:app", "Another-Service:db" ] include = "/etc/mackerel-agent/conf.d/*.conf" [host_status] on_start = "working" on_stop = "poweroff" [filesystems] ignore = "/dev/ram.*" use_mountpoint = true [plugin.metrics.vmstat] command = "ruby /etc/sensu/plugins/system/vmstat-metrics.rb" [plugin.checks.ssh] command = "ruby /path/to/check-ssh.rb" [plugin.metadata.packages] command = "perl /path/to/packages.pl"
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
- as for character string, authenticity value, and array settings (
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.
includesetting 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”.
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.
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 [host_status] on_start = "working" on_stop = "poweroff"
Possible statuses are
maintenance , and
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 [filesystems] 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 [filesystems] 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.
You can register optional JSON data in the "plugin.metadata.*" section of the configuration file. For details, please refer to Using metadata.
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
The following metrics can be collected.
For more information please refer to https://golang.org/pkg/runtime/#MemStats.
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.
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_KEYThis 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.confThis 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/mackerel-agent.pidThis is the PID file path.
-root=/var/lib/mackerel-agentThis 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.
-oncethis will execute metric collection and display standard output just one time. Metrics will not be posted.
-diagnosticmetrics 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.
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.
Check the syntax of the configuration file (
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
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