Agent Configuration

To specify the location of the agent configuration file use the --config flag. The default is /etc/outlyer/agent.yaml

python3 ./agent.py --config /etc/outlyer/agent.yaml

The config file should be valid YAML with the following structure:

---
agent:                 # agent block
    key:               # DEFAULT: none, required field
    hostname:          # DEFAULT: auto-detected
    labels:            # DEFAULT: none
        env: "prod"
        region: "US"

    metric_labels:     # DEFAULT: none
        - "region"

    home_dir:          # DEFAULT: "/etc/outlyer"
    config_dir:        # DEFAULT: "/etc/outlyer/conf.d"
    plugin_dir:        # DEFAULT: "/etc/outlyer/plugins"
    solo:              # DEFAULT: false
    docker:            # DEFAULT: false
    rootfs:            # DEFAULT: "/host"
    debug:             # DEFAULT: false
    api_port:          # DEFAULT: 2014
    api_host:          # DEFAULT: 127.0.0.1
    graceful_shutdown  # DEFAULT: true

Note: these settings need to be under the agent block, this states that the agent is the intended target for the configuration

Warning: When editing the YAML file please remember that YAML files use spaces as indentation, you can use 2 or 4 spaces for indentation, but no tab. If the indentation is incorrect the agent will fail to parse the agent.yaml file and you will not see the agent appear in Outlyer till its fixed.

key

Key is the only required field in the agent configuration. Therefore, there is no default. You can find your key under Agent Integration on the Integrations page of the app.

hostname

We use the hostname as the unique name for your host, and for labelling the performance metrics, it returns. The agent does attempt to locate a unique, but descriptive, hostname. However, you can use this field if you need to set a different hostname.

_Note: Please ensure you keep your hostnames unique if you override this. Two instances with the same hostname will only appear as one host in Outlyer, which can be confusing.

labels

Labels are key/value string pairs used to describe a host. Host labels are used for grouping hosts with common properties, for instance, when selecting a set of hosts to deploy a check.

By default all hosts are given the host: <hostname> label, and all containers the container: <container_name> label.

metric_labels

By default host labels are applied to all metrics returned from a host. However, for performance reasons we only apply the first twenty host labels to the metrics. If you would prefer to specify which exactly which host labels to apply to a host’s metric, then use metrics_labels to list the keys of the labels you would like to use. As an example if you specify env, region, then the env:<prod> and region:<US> host labels would be applied to all metrics

home_dir

The home directory for the agent to store its files. The agent needs to have write access to this folder.

config_dir

Config dir is the location from which the agent load local check configuration files (see Check Config).

plugin_dir

Typically a service check (check) requires the facilities of a Plugin to inspect the status of particular Service. The Agent will look here for any Plugins required by a Check.

solo

One of the key benefits of the Outlyer monitoring platform is the ability configure your monitoring from one central location. To support central configuration the agent asks the Outlyer servers for its check configuration and plugins. To disable this feature, and control check deployment yourself, run the agent in solo-mode, by setting solo: true.

Note: In solo-mode the agent will not load ANY central check configurations or plugins. The Agent will only locally deployed Checks and Plugins (see config_dir and plugin_dir)

docker

This enables the automatic detection and monitoring any docker containers it finds on the Host. If you would like to enable this please set docker: true.

Note: the official Outlyer agent container enables docker mode by default

rootfs

To collect performance stats for containers running on the host, the Agent needs access to cgroup files on the host. Since the agent is likely to be running in a container itself when used to monitor docker, the roof FS location is independently configurable.

Note: the official Outlyer agent container recommends mounting certain parts of the host FS under /host, for this reason, it defaults rootfs: '/host'

debug

Set the Agent to verbose logging.

api_port:

The agent has an API/Status page available on this port number (default port: 2014). The API allows users to push metrics and get the current status of the agent. Setting the port to ‘0’ will disable this feature on the agent.

api_host:

This is the IP address of the host the agent API/status pages binds to on the server. By default it is set to localhost (127.0.0.1) which means only requests from localhost will be accepted. If you would like to enable remote access from another host, set the IP address to ‘0.0.0.0’. Please note this will enable anyone with access to the api_port on that server to post custom metrics and view the status page if set.

graceful_shutdown:

This determines whether the agent will deregister from Outlyer when it is stopped. This can be useful if you would always like to be alerted when an agent goes offline, be that an intentional service stop, or a crashed agent. To disable this feature, please set graceful_shutdown:false