Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Blog
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
Yandex Monitoring
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Working with metrics
      • Delivering Linux system metrics
      • Delivering custom application metrics
      • Delivering metrics from HAProxy and other third-party applications
      • Delivering metrics from hosts outside Yandex Cloud
      • Writing custom metrics via the API
      • Getting a list of metrics
      • Downloading metrics
      • Exporting metrics in Prometheus format
    • Working with dashboards
      • Creating dashboards
      • Copying dashboards
      • Adding widgets to a dashboard
      • Deleting widgets from a dashboard
      • Deleting dashboards
      • Examples of working with the gRPC API
    • Working with alerts
      • Creating alerts
      • Creating notification channels
      • Deleting alerts
  • Concepts
    • Service overview
    • Data model
    • Visualization
      • Overview
      • Query string
      • Widgets
      • Dashboards
    • Transmitting metrics
      • Agent for delivering metrics
        • Overview
        • Installation and startup
        • Configuration
        • Best practices for using the agent
    • Query language
    • Alerting
    • Data decimation
    • Deleting expired metrics (TTL)
    • Quotas and limits
  • Access management
  • Pricing policy
    • Current pricing policy
    • Archive
      • Policy before October 1, 2020
  • API reference
    • Authentication in the API
    • REST
      • Overview
      • MetricsData
        • Overview
        • read
        • write
        • prometheusMetrics
      • MetricsMeta
        • Overview
        • listLabelKeys
        • listLabelValues
        • listMetricNames
        • listMetrics
    • gRPC
      • Overview
      • DashboardService
  • Metric reference
  • Questions and answers
    • General questions
    • Navigation
    • Metric collection and export
    • Metrics and units of measure
    • Alerts / notifications
    • All questions on one page
  1. Concepts
  2. Transmitting metrics
  3. Agent for delivering metrics
  4. Installation and startup

Installing and running Yandex Unified Agent

Written by
Yandex Cloud
  • List of supported operating systems
  • Before you begin installation
  • Setup
  • Parameters for launching a Docker container with Unified Agent

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.

    • Set up a public IPv4 address (recommended).
    • Configure Docker to work with IPv6 and enable network address translation if you can't use a public IPv4 address.
  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:

    • If the agent is installed on a VM in Yandex Cloud, link the service account you created to the VM. In that case, the agent will automatically receive the service account's IAM token from the metadata service.
    • If the agent is installed on a host outside Yandex Cloud, create an authorized key for service accounts. For more information about delivering metrics from hosts outside Yandex Cloud, see Delivering metrics from hosts outside Yandex Cloud.

Setup

Install Unified Agent using one of the following methods:

Docker image
deb package
Binary file
When creating a VM

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 Linux system metric delivery in Yandex Monitoring.

Warning

To monitor secondary disks attached to the host, pass the paths to their mount points using the -v parameter of the docker run command. For more information, see Linux_metrics input.

The agent's 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:

  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

Where FOLDER_ID is the ID of the folder the metrics are going to be written.

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

  docker run \
    -p 16241:16241 -it --detach --uts=host \
    --name=ua \
    -v /proc:/ua_proc \
    -v `pwd`/config.yml:/etc/yandex/unified_agent/config.yml \
    --entrypoint="" \
    -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 this command:

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

To install the deb package, run this 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 this command:

curl -s 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:

./unified_agent --config unified_agent.yml

Where --config is the path to the configuration file.

You can install the agent when creating a VM in the management console. To do this, enable Agent for delivering metrics under Monitoring. The agent is installed automatically with the default configuration file that will send basic VM metrics and agent health metrics. You'll be charged for metric delivery.

The installed agent is a regular Unified Agent that you can additionally set up to deliver custom metrics or logs to Cloud Logging.

To install the agent while creating a VM in the CLI or API, add the following line to user-defined metadata (user-data):

#cloud-config\nruncmd:\n  - wget -O - https://monitoring.api.cloud.yandex.net/monitoring/v2/unifiedAgent/config/install.sh | bash"

To install the agent and send metrics properly, make sure the created VM has access to the internet.

You are responsible for updating and maintaining the agent.

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

  • Review Unified Agent concepts
  • Learn more about configuring Unified Agent
  • Read the Unified Agent operating instructions

Was the article helpful?

Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
In this article:
  • List of supported operating systems
  • Before you begin installation
  • Setup
  • Parameters for launching a Docker container with Unified Agent