Get started
Yandex Monitoring

Installing and running Yandex Unified Agent

Written by

List of supported operating systems

Unified Agent is supported by the following operating systems:

  • Ubuntu 14.04 or higher.
  • Debian 9 or higher.
  • CentOS 7 or higher.
  • Fedora 32 or higher.
  • Fedora CoreOS.

Before you begin installation

Prior to installing Yandex Unified Agent, follow these steps:

  1. Create a VM in Yandex.Cloud or a host outside Yandex.Cloud on one of the supported operating systems, for example, Ubuntu 14.04 or older.

  2. (optional) Install Docker if you want to use Docker to run Unified Agent.

  3. Create a service account in the folder you want to write metrics to and assign it the monitoring.editor role.

  4. Set up agent authorization in the Yandex Monitoring API:

Installation

Install Unified Agent using one of the following methods:

Unified Agent is distributed as a Docker image. The image is published in the cr.yandex/yc repository with the unified_agent name and latest tag. The image includes a binary file with the agent and a configuration file used to set up the agent for delivering Linux system metrics to Yandex Monitoring.

The configuration file is located at /etc/yandex/unified_agent/config.yml and parameterized by environment variables. For more information about starting a Docker container, see below.

To start a container with the agent, run the following command, indicating FOLDER_ID as the ID of the folder the metrics are going to be written to:

docker run \
    -p 16241:16241 -it --detach --uts=host \
    --name=ua \
    -v /proc:/ua_proc \
    -e PROC_DIRECTORY=/ua_proc \
    -e FOLDER_ID=a1bs... \
    cr.yandex/yc/unified-agent

To launch a container with its own configuration file, add -v to the container start command and specify the path to the configuration file. For example:

  docker run \
    -p 16241:16241 -it --detach --uts=host \
    --name=ua \
    -v /proc:/ua_proc \
    -v config.yml:/etc/yandex/unified_agent/conf.d/config.yml \
    -e PROC_DIRECTORY=/ua_proc \
    -e FOLDER_ID=a1bs... \
    cr.yandex/yc/unified-agent

For more information about agent configuration, see Configuration.

Unified Agent is distributed as a deb package for Ubuntu 14.04 or higher. The package contains a binary file with the agent and an empty configuration file located at /etc/yandex/unified_agent/config.yml.

To download the latest version of the agent's deb package, run:

ubuntu_name="ubuntu-14.04-trusty" ua_version=$(curl -s https://storage.yandexcloud.net/yc-unified-agent/latest-version) bash -c 'curl -s -O https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb'

Supported values for the ubuntu_name parameter:

  • ubuntu-14.04-trusty
  • ubuntu-16.04-xenial
  • ubuntu-18.04-bionic
  • ubuntu-20.04-focal

To find out all the available versions of the agent, run the command:

curl -s https://storage.yandexcloud.net/yc-unified-agent/all-versions

To install the deb package, run the command:

sudo dpkg -i yandex-unified-agent_21.02.03_amd64.deb

To make sure Unified Agent is successfully installed and running, run the command systemctl status unified-agent. Sample command output:

user@my-vm:~$ systemctl status unified-agent
● unified-agent.service - Yandex Unified Agent service
   Loaded: loaded (/lib/systemd/system/unified-agent.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2021-02-09 15:57:08 UTC; 2 weeks 2 days ago
 Main PID: 141403 (unified_agent)
    Tasks: 8 (limit: 507)
   Memory: 9.4M
   CGroup: /system.slice/unified-agent.service
           └─141403 /usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml --log-priority NOTICE

After installing the package, edit the configuration file /etc/yandex/unified_agent/config.yml, for example, by setting up the agent for delivering Linux system metrics. For more information about agent configuration, see Configuration.

Unified Agent is distributed as a binary file built for the x86-64/amd64 architecture for Ubuntu 14.04 or higher.

To download the latest version of the agent's binary file, run:

ua_version=$(curl -s https://storage.yandexcloud.net/yc-unified-agent/latest-version) bash -c 'curl -s -O https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

To find out all the available versions of the agent, run the command:

wget --quiet -O - https://storage.yandexcloud.net/yc-unified-agent/all-versions

Download the agent's executable file and then create a configuration file, for example, with the settings for delivering Linux system metrics. For more information about agent configuration, see Configuration.

To start the agent, run the command specifying the path to the configuration file in the parameter --config:

./unified_agent --config unified_agent.yml

Parameters for launching a Docker container with Unified Agent

If you install Unified Agent using Docker, you can configure the agent using environment variables. In that case, you won't need to edit the configuration file located at /etc/yandex/unified_agent/config.yml. The environment variables are listed in the table below.

Environment variable Default value Description
UA_STATUS_PORT 16241 The port where the agent status will be available.
For more information, see status section.
UA_LOG_PRIORITY NOTICE The agent's logging level.
For more information, see agent_log section.
FOLDER_ID A required parameter,
has no default value
 ID of the folder the metrics are going to be saved to.
For more information, see yc_metrics output.
PROC_DIRECTORY /proc A directory with mounted procfs where the agent is going to get the Linux system metrics.
For more information, see linux_metrics input.
SYS_DIRECTORY /sys A directory with mounted sysfs where the agent is going to get the Linux system metrics.
For more information, see linux_metrics input.
UA_LINUX_RESOURCE_CPU
UA_LINUX_RESOURCE_MEMORY
UA_LINUX_RESOURCE_NETWORK
UA_LINUX_RESOURCE_STORAGE
UA_LINUX_RESOURCE_IO
UA_LINUX_RESOURCE_KERNEL		 basic The detail level of the system metrics for CPU, network, disks, I/O system, and Linux kernel.
For more information, see linux_metrics input.

What's next

In this article: