Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Agent for collecting Prometheus metrics

Written by
Updated at April 17, 2025

To set up transferring metrics from a VM to Yandex Managed Service for Prometheus®, you first need to install a metrics collection agent. You can install any agent that supports metrics transfers, or you can use Unified Agent which supports transferring Prometheus metrics.

This section describes how to install an agent when creating a VM. For other installation options, see Installing and updating Yandex Unified Agent.

List of supported operating systems

  • Ubuntu 14.04 or higher
  • Debian 9 or higher

Before you begin installation

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

  2. Set up agent authorization in the Yandex Monitoring API. To do this, link your service account to the VM. This way, the agent will automatically get the service account IAM token from the metadata service.

Installation and setup

You can install an agent for collecting metrics when creating a VM using the management console, CLI, API, or Terraform.

  1. In the management console, start creating your VM.

  2. Expand Additional ⟶ Monitoring.

  3. Enable Agent for delivering metrics and select Yandex Managed Service for Prometheus®.

  4. Create a workspace or select an existing one.

  5. Optionally, specify the delivery parameters for your custom metrics, in JSON format.

    It no parameters are specified, the agent will only deliver Linux system metrics. You can add or change the delivery of your custom metrics later, in user metadata.

    Metrics description format:

    {
  "jobs": [
    {
      "job_name": <name>,
      "scrape_interval": "15s",
      "scrape_timeout": "5s",
      "metrics_path": "/metrics",
      "targets": [
        {
          "host": <host_FQDN>, //this is an optional field
          "port": 42
        }
      ]
    }
  ]
}

    Where:

    • job_name: Random name for the set of metrics to collect.
    • scrape_interval: How often the agent will collect metrics.
    • scrape_timeout: Time the agent will have to collect metrics.
    • metrics_path: Path to the service metrics location.
    • targets: Parameters of the host to collect metrics from:
      • host: Full domain name, such as my.example.com. This is an optional setting.
      • port: Port for collecting metrics.

To install the agent, provide the following string in the user metadata (user-data):

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

To install your agent:

  1. Specify the following in the VM creation configuration:

    resource "yandex_compute_instance" "my-vm" {
  ...
  service_account_id = "ajehka*************"
  metadata    = {
    monitoring_workspaceid = "mon618clr**************"
    user-data = "${file("<path_to_configuration_file>")}"
  }
  ...
}

    Where:

    • monitoring_workspaceid: ID of the workspace to which you want to write metrics.
    • service_account_id: ID of the service account with the monitoring.editor role.

  2. In the configuration file (user-data), specify the following line:

    #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, make sure the VM has access to the internet.

The agent is installed with a default configuration file located at /etc/yc/unified_agent/config.yml.

The configuration file is set up to send Linux system metrics and agent health metrics. You will be charged for metric delivery. Additionally, you can set up delivering metrics from your apps, in Prometheus format.

Once the VM is deployed, the agent will start automatically and will be sending metrics to Yandex Managed Service for Prometheus®.

Overview of VM metrics

To view metrics your agent transfers to Yandex Managed Service for Prometheus®:

  1. In the management console, select the folder where the VM is located.

  2. From the list of services, select Monitoring.

  3. Navigate to Prometheus.

  4. Select the workspace to which your VM metrics are written.

  5. Open the Metrics tab and enter a Query in PromQL to view:

    • Linux system metrics: {job="linux_metrics", instance="<VM_name>", __name__="<metric_name>"}.

      Example: {job="linux_metrics", instance="my_vm", __name__="sys_cpu_CpuCores"}.

      For the list of metrics transferred by the Prometheus agent, see Yandex Unified Agent metrics.

    • Custom metrics if the agent has been configured to transfer them: {job="metrics_totality_name", instance="<VM_name>:<port>", __name__="<metric_name>"}.

      Where:

      • job: Name of the set of metrics specified when configuring the agent.
      • instance: VM name and port used by your application.
      • name: Name of the metric your application transfers.

      Example: {job="web_server", instance="my_server:9100", __name__="http_requests_total"}.

  6. Click Execute.

Previous
Overview
Next
Remote Write