This article is an explanation of latest 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 as is shown in the following instance.
apikey = "APIKEY" pidfile = "/path/to/pidfile" root = "/var/lib/mackerel-agent" verbose = 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.*" [plugin.metrics.vmstat] command = "ruby /etc/sensu/plugins/system/vmstat-metrics.rb" [plugin.checks.ssh] command = "ruby /path/to/check-ssh.rb"
The configuration file will be read when the agent starts up, so it is necessary to restart the agent after you have made changes to this file.
All options other than APIKEY are optional, so if the default setting are acceptable it’s fine to leave values empty.
Reading other configuration files
It is possible to have other configuration files be read by setting the item
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 congigure 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
If running CentOS or Debian, by appending an environment variable preference to
/etc/sysconfig/mackerel-agent, it’s possible to apply this to the agent. For example you can specify this as shown below.
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.*"
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.
By activating this feature in the agent boot 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.
The following boot options can be specified. If you have also specified the same entries in the settings file, the launch options entries will take precedence over them.
-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.)
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.
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