Установка агентов Proto Observability Platform

На этой странице:

• Описание
  • Схема взаимодействия компонентов ProtoOBP
  • Поддерживаемые технологии
• Linux
  • Linux агент – установка
  • Linux агент – конфигурация
  • Linux агент – обновление
  • Linux агент – удаление
  • Linux агент – управление
  • Linux агент – ручная настройка systemd-юнитов
    • Переопределение параметров юнита (drop-in)
    • Переменные окружения агента
    • Состав юнитов
  • Linux агент – управление на системах без systemd
    • DEB-пакет (Ubuntu, Debian, Astra Linux и т.д.)
    • RPM-пакет (CentOS, Alt Linux, Rosa Linux, РЕД ОС и т.д.)
    • Собственные init-скрипты для «чистого» SysV
    • init-скрипт основного агента
    • init-скрипт trace-агента (APM)
    • Регистрация скриптов и автозапуск
    • Команды управления собственными скриптами
    • Обновление со старой версии на системах без systemd
• Windows
  • Windows агент – установка
    • GMSA
  • Windows агент – конфигурация
  • Windows агент – управление
  • Windows агент – типовые проблемы
    • Сервис не запускается
    • Ошибка “Сервис помечен для удаления”
• Docker
  • Запуск Docker агента (отдельный контейнер)
  • Запуск Docker агента (docker compose)
  • Запуск агента в Docker Swarm
    • Автообнаружение и теги Swarm
    • Отправка трейсов и метрик приложений
    • Ограничения в Docker Swarm
• Kubernetes
  • Установка Kubernetes агента
  • Использование hostPath ноды
  • Работа в непривилегированном режиме
  • Дополнительная конфигурация для OpenShift
  • Изменение параметров Kubernetes агента
  • Удаление Kubernetes агента
• Работа агента через proxy
• Файлы конфигурации агента
• Проверка работы агента
• Логи агента
• Собираемые системные метрики по хостам
• Собираемые контейнерные метрики

Описание

ProtoOBP агент автоматически собирает метрики, трейсы и логи и отправляет полученные данные на ProtoOBP Backend сервер.

Сбор трейсов приложения осуществляется с помощью трейсеров, автоматически инструментируя код следующих языков программирования:

• Java
• PHP
• NodeJS
• Python
• .NET/.NET Core
• GO

Сбор метрик осуществляется автоматически для всех поддерживамых технологий

Схема взаимодействия компонентов ProtoOBP

Поддерживаемые технологии

• Список поддерживаемых агентом технологий для сбора инфраструктурных метрик

Linux

Linux агент – установка

Агент работает на всех основных DEB/RPM дистрибутивах ОС Linux. Подробнее

1. Скачайте и установите пакет с агентом для вашей ОС

   Выберите версию агента. Актуальная версия — 7.80.2.

   • Версия агента:
   • 7.80.2 (актуальная)
   • 7.40.2
   DEB-based (Ubuntu, Debian, Astra Linux и т.д.):

   curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.80.2/protoobp-agent_7.80.2-1_amd64.deb" --output protoobp-agent_7.80.2-1_amd64.deb
   apt install ./protoobp-agent_7.80.2-1_amd64.deb
   

   RPM-based (CentOS, Alt Linux, Rosa Linux, РЕД ОС и т.д.):

   curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.80.2/protoobp-agent-7.80.2-1.x86_64.rpm" --output protoobp-agent-7.80.2-1.x86_64.rpm
   rpm -ivh protoobp-agent-7.80.2-1.x86_64.rpm
   

   Значение <your_token> берётся из лицензионного сертификата, полученного ранее от вендора, из раздела «Учетные данные → Пароль».

   В случае появления ошибки на Альт или Роса Линукс:

   ошибка: Неудовлетворенные зависимости: glibc-common нужен для protoobp-agent-1:7.80.2-1.x86_64

   установку агента необходимо выполнить следующей командой:

   rpm -ivh --nodeps protoobp-agent-7.80.2-1.x86_64.rpm
   

   DEB-based (Ubuntu, Debian, Astra Linux и т.д.):

   curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.40.2/protoobp-agent_7.40.2_amd64.deb" --output protoobp-agent_7.40.2_amd64.deb
   apt install ./protoobp-agent_7.40.2_amd64.deb
   

   RPM-based (CentOS, Alt Linux, Rosa Linux, РЕД ОС и т.д.):

   curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.40.2/protoobp-agent_7.40.2_amd64.rpm" --output protoobp-agent_7.40.2_amd64.rpm
   rpm -ivh protoobp-agent_7.40.2_amd64.rpm
   

   Значение <your_token> берётся из лицензионного сертификата, полученного ранее от вендора, из раздела «Учетные данные → Пароль».

   В случае появления ошибки на Альт или Роса Линукс:

   ошибка: Неудовлетворенные зависимости: glibc-common нужен для protoobp-agent-1:7.40.2-1.x86_64

   установку агента необходимо выполнить следующей командой:

   rpm -ivh --nodeps protoobp-agent_7.40.2_amd64.rpm
   

2. Убедитесь что агент корректно установлен, выполнив:

   protoobp-agent version
   

   Результат выполнения команды (значение Commit приведено для примера и зависит от сборки):

   Agent 7.80.2 - Commit: 39e8d835 - Serialization version: v5.0.196 - Go version: go1.25.12
   

Linux агент – конфигурация

1. По умолчанию файл конфигурации агента расположен в каталоге /etc/protoobp-agent/

2. Создайте файл protoobp.yaml:

   vim /etc/protoobp-agent/protoobp.yaml
   

   и укажите в нем следующее:

   api_key: my_api_key
   pobp_url: http://protoobp-backend        # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
   apm_config:
     apm_non_local_traffic: true
     apm_pobp_url: http://protoobp-backend  # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
     telemetry:
       enabled: false
   agent_telemetry:
     enabled: false       
   process_config:
     enabled: false
     process_collection:
       enabled: false
     container_collection:
       enabled: false
     process_discovery:
       enabled: false
   

   Где,

   • api_key - ваш токен из лицензионного сертификата
   • pobp_url - адрес ProtoOBP Backend сервера
   • apm_pobp_url - адрес ProtoOBP Backend сервера

   Полный пример конфигурации, можно посмотреть в файле protoobp.yaml.example

3. Если на хосте запускаются Docker контейнеры, то необходимо добавить пользователя pobp-agent в группу Docker, чтобы агент мог собирать метрики по работе контейнеров, в дополнение к метрикам самого хоста:

   usermod -a -G docker pobp-agent
   

4. Если на хосте запускаются Docker контейнеры с приложениями, в которые будут добавлены трейсеры:

   1. При конфигурации трейсера для Docker контейнера с приложением, отсылающим трейсы в Агента, установленного на хосте (не в контейнере):

      POBP_AGENT_HOST=host.docker.internal
      

   2. При запуске контейнера с приложением добавьте опцию extra_hosts в ваш docker-compose.yaml файл:

      extra_hosts:                            
        - "host.docker.internal:host-gateway"
      

      host-gateway – это специальная строка-шаблон, появившаяся в Docker 20.10.0+, ее значение при использовании в extra_hosts будет соответствовать IP адресу машины. Таким образом, по имени host.docker.internal будет доступен IP адрес машины.

5. Запустите агента, выполнив:

   systemctl start protoobp-agent
   

   При успешной настройке агента вы сможете увидеть новый хост в разделе Инфраструктура > Хосты в течение одной-двух минут.

Linux агент – обновление

Обновление выполняется установкой пакета новой версии поверх старой — удалять предыдущую версию не нужно. Файл /etc/protoobp-agent/protoobp.yaml и содержимое conf.d/ при обновлении сохраняются, служба перезапускается автоматически.

Пример обновления с 7.40.2 на 7.80.2:

DEB-based (Ubuntu, Debian, Astra Linux и т.д.):

curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.80.2/protoobp-agent_7.80.2-1_amd64.deb" --output protoobp-agent_7.80.2-1_amd64.deb
apt install ./protoobp-agent_7.80.2-1_amd64.deb

RPM-based (CentOS, Alt Linux, Rosa Linux, РЕД ОС и т.д.):

curl --header "PRIVATE-TOKEN:<your_token>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.80.2/protoobp-agent-7.80.2-1.x86_64.rpm" --output protoobp-agent-7.80.2-1.x86_64.rpm
rpm -Uvh protoobp-agent-7.80.2-1.x86_64.rpm

Для RPM используется именно rpm -Uvh (upgrade), а не rpm -ivh (install): -ivh на уже установленном агенте завершится ошибкой «package is already installed». Если на Альт или Роса Линукс возникает ошибка о неудовлетворённых зависимостях glibc-common, добавьте --nodeps: rpm -Uvh --nodeps protoobp-agent-7.80.2-1.x86_64.rpm.

Проверьте результат обновления:

protoobp-agent version
systemctl status protoobp-agent
sudo protoobp-agent status

sudo cp -a /etc/protoobp-agent /etc/protoobp-agent.bak

Linux агент – удаление

Возможны два сценария: удаление агента с сохранением конфигурации (например, перед переустановкой) и полное удаление вместе с настройками и логами.

DEB-based (Ubuntu, Debian, Astra Linux и т.д.):

# удалить агента, сохранив /etc/protoobp-agent (конфигурацию и conf.d)
sudo apt remove protoobp-agent

# полное удаление: пакет, конфигурация, логи, служебный пользователь pobp-agent
sudo apt purge protoobp-agent

RPM-based (CentOS, Alt Linux, Rosa Linux, РЕД ОС и т.д.):

sudo rpm -e protoobp-agent

Что удаляется в каждом случае:

Если после rpm -e или apt remove требуется полностью очистить систему, удалите оставшиеся каталоги и учётную запись вручную:

sudo rm -rf /etc/protoobp-agent /opt/protoobp-agent /var/log/protoobp
sudo userdel pobp-agent

Linux агент – управление

ProtoOBP Agent запускается как systemd служба - protoobp-agent.

Linux агент – ручная настройка systemd-юнитов

dpkg -S /lib/systemd/system/protoobp-agent.service        # DEB
rpm -qf /usr/lib/systemd/system/protoobp-agent.service    # RPM

Переопределение параметров юнита (drop-in)

Drop-in-файлы лежат в /etc/systemd/system/, установщиком агента не затрагиваются и переживают обновление. Пример — изменить политику перезапуска основного агента:

mkdir -p /etc/systemd/system/protoobp-agent.service.d
cat > /etc/systemd/system/protoobp-agent.service.d/override.conf <<'EOF'
[Service]
Restart=always
RestartSec=10
EOF
systemctl daemon-reload
systemctl restart protoobp-agent

Посмотреть итоговый юнит со всеми применёнными drop-in:

systemctl cat protoobp-agent

Переменные окружения агента

Юниты подключают файл переменных окружения:

EnvironmentFile=-/etc/protoobp-agent/environment

По умолчанию файла нет — при необходимости создайте его. Пример:

cat > /etc/protoobp-agent/environment <<'EOF'
POBP_LOG_LEVEL=debug
EOF
systemctl restart protoobp-agent

Так задаются любые параметры конфигурации в виде переменных POBP_* — альтернатива правке protoobp.yaml. Выполнять daemon-reload не требуется: файл читается при старте службы.

Состав юнитов

Отдельно запускать дочерние юниты не требуется: основной protoobp-agent объявляет их в Wants= и поднимает вместе с собой.

Linux агент – управление на системах без systemd

На дистрибутивах без systemd (RHEL 6.x, CentOS 6, старые линейки Alt Linux, Rosa Linux, РЕД ОС и др.) команды systemctl недоступны. Способ управления агентом зависит от типа пакета — DEB и RPM разворачивают разные наборы скриптов запуска.

DEB-пакет (Ubuntu, Debian, Astra Linux и т.д.)

DEB-пакет штатно устанавливает и SysV init-скрипты в /etc/init.d/, и задания upstart в /etc/init/ — писать их вручную не нужно. Какой набор будет задействован, определяет система инициализации дистрибутива.

SysV init-скрипты:

Управление:

Скрипт основного агента при старте и остановке сам подтягивает остальные компоненты (trace, process, security и др.), поэтому запускать их по отдельности не требуется. Отключить конкретный компонент можно через /etc/default/<имя_скрипта>.

SysV-скрипты рассчитаны на Debian-совместимое окружение: используют start-stop-daemon и /lib/lsb/init-functions. На RPM-дистрибутивах они неработоспособны.

Если в системе используется upstart, применяются задания из /etc/init/, а управление выполняется через initctl — так же, как описано ниже для RPM.

RPM-пакет (CentOS, Alt Linux, Rosa Linux, РЕД ОС и т.д.)

RPM-пакет SysV init-скрипты не устанавливает — только задания upstart в /etc/init/ (protoobp-agent.conf, protoobp-agent-trace.conf, protoobp-agent-process.conf, protoobp-agent-security.conf, protoobp-agent-sysprobe.conf, protoobp-agent-data-plane.conf, protoobp-agent-action.conf) — они рассчитаны на старую версию upstart (0.6.5) из RHEL 6.

Если в системе используется upstart (RHEL 6.x, CentOS 6), управление выполняется штатно:

Команды service protoobp-agent start|stop|status на таких системах также работают — они транслируются в initctl.

Если же в дистрибутиве нет ни systemd, ни upstart (классический SysV-init), штатных скриптов запуска в пакете нет — используйте init-скрипты, приведённые ниже.

Собственные init-скрипты для «чистого» SysV

Скрипты ниже нужны только там, где нет ни systemd, ни upstart, ни штатных init-скриптов из DEB-пакета. Они разработаны под основной агент (protoobp-agent) и trace-агент APM (protoobp-agent-trace) и проверены на версии 7.80.2.

Скрипты покрывают только эти два компонента. Остальные компоненты 7.80.2 (process, security, system-probe, data-plane, private action runner, DDOT) на «чистом» SysV остаются неуправляемыми — при необходимости заведите для них скрипты по аналогии, взяв команду запуска из соответствующего файла /etc/init/protoobp-agent-*.conf.

init-скрипт основного агента

Сохраните в /etc/init.d/protoobp-agent:

#!/bin/bash
#
# protoobp-agent  ProtoOBP monitoring agent (main)
#
# chkconfig: 2345 99 01
# description: ProtoOBP monitoring agent (main)
# pidfile: /opt/protoobp-agent/run/agent.pid

### BEGIN INIT INFO
# Provides:          protoobp-agent
# Required-Start:    $local_fs $network $remote_fs $syslog
# Required-Stop:     $local_fs $network $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: ProtoOBP monitoring agent (main)
### END INIT INFO

. /etc/rc.d/init.d/functions

NAME="protoobp-agent"
USER="pobp-agent"
DAEMON="/opt/protoobp-agent/bin/agent/agent"
DAEMON_ARGS="run -p /opt/protoobp-agent/run/agent.pid"
PIDFILE="/opt/protoobp-agent/run/agent.pid"

LOCKFILE="/var/lock/subsys/${NAME}"
LOGFILE="/var/log/protoobp/${NAME}-init.log"
RUNDIR="/opt/protoobp-agent/run"
LOGDIR="/var/log/protoobp"

[ -x "$DAEMON" ] || { echo "$DAEMON not found"; exit 5; }
[ -d "$RUNDIR" ] || install -d -o "$USER" -g "$USER" "$RUNDIR"
[ -d "$LOGDIR" ] || install -d -o "$USER" -g "$USER" "$LOGDIR"

is_running() {
    [ -f "$PIDFILE" ] || return 1
    local pid
    pid="$(cat "$PIDFILE" 2>/dev/null)"
    [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
}

start() {
    echo -n "Starting $NAME: "
    if is_running; then
        echo "already running (pid $(cat "$PIDFILE"))"
        return 0
    fi
    nohup su "$USER" -s /bin/bash -c "exec $DAEMON $DAEMON_ARGS" \
        >> "$LOGFILE" 2>&1 < /dev/null &
    for _ in 1 2 3 4 5 6 7 8 9 10; do
        is_running && break
        sleep 1
    done
    if is_running; then
        touch "$LOCKFILE"
        echo "OK (pid $(cat "$PIDFILE"))"
        return 0
    fi
    echo "FAILED — см. $LOGFILE"
    return 1
}

stop() {
    echo -n "Stopping $NAME: "
    if ! is_running; then
        echo "not running"
        rm -f "$LOCKFILE" "$PIDFILE"
        return 0
    fi
    killproc -p "$PIDFILE" -d 15 "$DAEMON"
    rc=$?
    [ $rc -eq 0 ] && rm -f "$LOCKFILE"
    return $rc
}

case "$1" in
    start)   start ;;
    stop)    stop ;;
    restart) stop; sleep 2; start ;;
    status)
        if is_running; then
            echo "$NAME is running (pid $(cat "$PIDFILE"))"
            exit 0
        fi
        echo "$NAME is not running"
        exit 3
        ;;
    *) echo "Usage: $0 {start|stop|restart|status}"; exit 2 ;;
esac
exit $?

init-скрипт trace-агента (APM)

Если используется APM, дополнительно сохраните в /etc/init.d/protoobp-agent-trace:

#!/bin/bash
#
# protoobp-agent-trace  ProtoOBP APM trace agent
#
# chkconfig: 2345 98 02
# description: ProtoOBP APM trace agent
# pidfile: /opt/protoobp-agent/run/trace-agent.pid

### BEGIN INIT INFO
# Provides:          protoobp-agent-trace
# Required-Start:    $local_fs $network $remote_fs $syslog protoobp-agent
# Required-Stop:     $local_fs $network $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: ProtoOBP APM trace agent
### END INIT INFO

. /etc/rc.d/init.d/functions

NAME="protoobp-agent-trace"
USER="pobp-agent"
DAEMON="/opt/protoobp-agent/embedded/bin/trace-agent"
DAEMON_ARGS="--config /etc/protoobp-agent/protoobp.yaml --pidfile /opt/protoobp-agent/run/trace-agent.pid"
PIDFILE="/opt/protoobp-agent/run/trace-agent.pid"

LOCKFILE="/var/lock/subsys/${NAME}"
LOGFILE="/var/log/protoobp/${NAME}-init.log"
RUNDIR="/opt/protoobp-agent/run"
LOGDIR="/var/log/protoobp"

[ -x "$DAEMON" ] || { echo "$DAEMON not found"; exit 5; }
[ -d "$RUNDIR" ] || install -d -o "$USER" -g "$USER" "$RUNDIR"
[ -d "$LOGDIR" ] || install -d -o "$USER" -g "$USER" "$LOGDIR"

is_running() {
    [ -f "$PIDFILE" ] || return 1
    local pid
    pid="$(cat "$PIDFILE" 2>/dev/null)"
    [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
}

start() {
    echo -n "Starting $NAME: "
    if is_running; then
        echo "already running (pid $(cat "$PIDFILE"))"
        return 0
    fi
    nohup su "$USER" -s /bin/bash -c "exec $DAEMON $DAEMON_ARGS" \
        >> "$LOGFILE" 2>&1 < /dev/null &
    for _ in 1 2 3 4 5 6 7 8 9 10; do
        is_running && break
        sleep 1
    done
    if is_running; then
        touch "$LOCKFILE"
        echo "OK (pid $(cat "$PIDFILE"))"
        return 0
    fi
    echo "FAILED — см. $LOGFILE"
    return 1
}

stop() {
    echo -n "Stopping $NAME: "
    if ! is_running; then
        echo "not running"
        rm -f "$LOCKFILE" "$PIDFILE"
        return 0
    fi
    killproc -p "$PIDFILE" -d 15 "$DAEMON"
    rc=$?
    [ $rc -eq 0 ] && rm -f "$LOCKFILE"
    return $rc
}

case "$1" in
    start)   start ;;
    stop)    stop ;;
    restart) stop; sleep 2; start ;;
    status)
        if is_running; then
            echo "$NAME is running (pid $(cat "$PIDFILE"))"
            exit 0
        fi
        echo "$NAME is not running"
        exit 3
        ;;
    *) echo "Usage: $0 {start|stop|restart|status}"; exit 2 ;;
esac
exit $?

Регистрация скриптов и автозапуск

chmod 755 /etc/init.d/protoobp-agent /etc/init.d/protoobp-agent-trace
chkconfig --add protoobp-agent
chkconfig --add protoobp-agent-trace
chkconfig protoobp-agent on
chkconfig protoobp-agent-trace on

Проверить регистрацию:

chkconfig --list protoobp-agent
chkconfig --list protoobp-agent-trace

Команды управления собственными скриптами

Логи агента — в /var/log/protoobp/agent.log, trace-agent.log. Stdout/stderr самих init‑скриптов пишутся в /var/log/protoobp/<service>-init.log и полезны при диагностике падения процесса сразу после запуска.

Обновление со старой версии на системах без systemd

При обновлении с 7.40.2 на 7.80.2 на системе без systemd учитывайте следующее.

1. Собственные init-скрипты нужно поправить. В 7.80.2 у trace-агента переименован флаг PID-файла: --pid больше не принимается (Error: unknown flag: --pid), используется --pidfile. Если вы разворачивали скрипт по инструкции для 7.40.2, замените аргумент:

sed -i 's/--pid /--pidfile /' /etc/init.d/protoobp-agent-trace
service protoobp-agent-trace restart

Аргументы основного агента (run -p <pidfile>) и пути к бинарным файлам (/opt/protoobp-agent/bin/agent/agent, /opt/protoobp-agent/embedded/bin/trace-agent) не изменились.

2. На DEB собственные скрипты будут перезаписаны. Начиная с 7.80.2 DEB-пакет сам ставит /etc/init.d/protoobp-agent и скрипты остальных компонентов. Если вы ранее положили туда свои версии, пакет их заменит. Это штатная ситуация: после обновления пользуйтесь скриптами из пакета, собственные больше не нужны. Проверить, чей скрипт сейчас установлен:

dpkg -S /etc/init.d/protoobp-agent

После обновления перезапустите агента и убедитесь, что версия сменилась:

service protoobp-agent restart
protoobp-agent version

hostname: my-host-name

Windows

Windows агент – установка

1. Скачайте .msi установщик с агентом (замените <YOUR_TOKEN> на значение вашего токена из вашего лицензионного сертификата)

   • ОС:
   • Linux (curl)
   • Windows (Powershell)
   curl --header "PRIVATE-TOKEN:<YOUR_TOKEN>"  "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.40.2/protoobp-agent-7.40.2-x64.msi" --output protoobp-agent-7.40.2-x64.msi
   

   $headers = @{
        "PRIVATE-TOKEN" = "<YOUR-TOKEN>"
   }
   try {
      Write-Host "Requesting file..."
      Invoke-WebRequest `
          -Uri "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-agent/7.40.2/protoobp-agent-7.40.2-x64.msi" `
          -Headers $headers `
          -OutFile "protoobp-agent-7.40.2-x64.msi" `
          -Verbose `
          -ErrorAction Stop
        Write-Host "Download completed."
   }
   catch {
      Write-Host "HTTP download failed: $($_.Exception.Message)"
   }
   

2. Запустите .msi установщик в графическом режиме и следуйте указаниям мастера установки агента, разрешите административные привилегии в момент запроса.

   • Для консольной установки используйте PowerShell команду (запуск PowerShell должен быть от Администратора):

     Start-Process -Wait msiexec -ArgumentList '/qn /i protoobp-agent-7.40.2-x64.msi APIKEY="<YOUR-TOKEN>"'
     

GMSA

Использование GMSA не является обязательным. GMSA для установки и запуска агент может применяться в доменной структуре с ограничивающими доменными политиками безопасности или если при использовании стандартного способа установки агенту не хватает прав на запуск сервисов из-за ограничений безопасности.

Для использования агента с GMSA выполните следующие шаги:

1. Создайте Security Group и добавьте в нее все компьютеры, на которых будет установлен агент с использованием GMSA:

   1. Откройте Active Directory Users and Computers (ADUC).
   2. Перейдите в нужный Organizational Unit (OU).
   3. Сделайте клик правой кнопкой мыши и выберите New > Group.
   4. Назовите группу, например, ProtoOBPAgentsGroup
   5. Установите необходимый скоуп группы, например Domain local.
   6. Установите тип группы: Security.
   7. Добавьте в эту группу все компьютеры, которые будут использовать GMSA для установки и запуска агента.

2. Создайте GMSA c именем ProtoobpGMSA:

   1. Октройте PowerShell с привилегиями Администратора.

   2. Выполните следующую команду для создания GMSA, замените <YOUR_DOMAIN_CONTROLLER_NAME> на DNS имя вашего контроллера домена:

      New-ADServiceAccount `
       -Name ProtoobpGMSA `
       -DNSHostName <YOUR_DOMAIN_CONTROLLER_NAME> `
       -PrincipalsAllowedToRetrieveManagedPassword ProtoOBPAgentsGroup
      

      Убедитесь, что команда выполнена без ошибок.

      В случае ошибок:

      • создайте Kds ключ:

        Add-KdsRootKey -EffectiveTime ((Get-Date).AddHours(-10))
        

      • проверьте, что указанная группа существует:

        Get-ADGroup -Identity ProtoOBPAgentsGroup
        

      • выполните создание GMSA еще раз:

        New-ADServiceAccount `
         -Name ProtoobpGMSA `
         -DNSHostName <YOUR_DOMAIN_CONTROLLER_NAME> `
         -PrincipalsAllowedToRetrieveManagedPassword ProtoOBPAgentsGroup
        

3. Подключите GMSA и убедитесь, что GMSA может быть использована на целевой машине. На целевой машине откройте PowerShell и выполните:

   Install-ADServiceAccount -Identity ProtoobpGMSA
   

   Убедитесь, что команда выполнена без ошибок.

   Проверьте, что GMSA успешно установлена:

   Test-ADServiceAccount -Identity ProtoobpGMSA
   

   Ожидаемый вывод команды: True

   Устранение неполадок подключения GMSA на целевую машину:

   • проверьте, какие группы имеют разрешение использовать GMSA:

     Get-ADServiceAccount -Identity ProtoobpGMSA -Properties PrincipalsAllowedToRetrieveManagedPassword
     

     если группа ProtoOBPAgentsGroup отсутствует в списке в разделе PrincipalsAllowedToRetrieveManagedPassword, обновите GMSA и добавьте группу ProtoOBPAgentsGroup:

     Set-ADServiceAccount -Identity ProtoobpGMSA -PrincipalsAllowedToRetrieveManagedPassword ProtoOBPAgentsGroup
     

   • проверьте, что машина является членом группы:

     Get-ADGroupMember -Identity ProtoOBPAgentsGroup
     

     убедитесь, что в выводе есть имя текущего компьютра, если его нет – добавьте компьютер в группу:

     Add-ADGroupMember -Identity ProtoOBPAgentsGroup -Members <ComputerName>
     

   • выполните обновление групповых политик, удалите Kerberos тикеты и перезагрузите компьютер:

     gpupdate /force
     klist purge
     Restart-Computer
     

4. Установите агента с использованием GMSA:

   1. Если агент ранее был установлен стандартным методом (запуск от новой учетной записи pobpagentuser, созданной на этапе установки агента), то необходимо полностью удалить агента и его файлы, перед использованием установки с использованием GMSA.
      1. Через Control Panel удалите пакет агента (через графический интерфейс).
      2. Вручную удалите папку C:\ProgramData\Protoobp (обязательный шаг, иначе последующая установка завершится ошибкой)
   2. Запустите .msi установщик агента.
   3. Введите запрашиваемые ключ и адрес бэкенд сервера
   4. На этапе выбора учётной записи (Please enter the username) укажите созданную и установленную на этой машине GMSA в формате: <ВАШ_ДОМЕН>\ProtoobpGMSA$ – обязательно с символом $ в конце. Поле пароль обязательно оставьте пустым.
   5. Зайдите в веб-интерфейс агента, и выполните конфигурацию агента через веб-интерфейс.
   6. Откройте services.msc и убедитесь, что агент запускается от имени доменной GMSA:
      

Windows агент – конфигурация

1. Запустите веб-консоль управления агентом ProtoOBP Agent Manager.
   

2. Откроется веб-браузер с консолью управления. В случае запроса изменения настроек безопасности – добавьте в доверенные узлы http://127.0.0.1 и about:blank.
   

3. Перейдите в раздел Settings и в конфигурации агента укажите следующее:

   api_key: my_api_key
   pobp_url: http://<адрес_бекенд_сервера_protoobp>       # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
   apm_config:
     apm_non_local_traffic: true   
     apm_pobp_url: http://<адрес_бекенд_сервера_protoobp> # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
     enabled: true
     telemetry:
       enabled: false
   process_config:
     process_collection:
       enabled: false
   

   Параметры:

   api_key	значение, указанное в лицензионном сертификате, полученном ранее от вендора, в разделе Учетные данные -> Пароль
   pobp_url	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> - адрес вашего ProtoOBP Backend сервера, доступного для агента
   apm_pobp_url	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> – адрес вашего ProtoOBP Backend сервера, доступного для агента

   Пример окна конфигурации:

4. Перезапустите агента, для этого консоли управления кликните на Restart Agent.

   При успешной настройке агента вы сможете увидеть новый хост в разделе Инфраструктура > Хосты в течение одной-двух минут.

Windows агент – управление

• Режим настройки:
• Веб-интерфейс
• Командная строка

Windows агент – типовые проблемы

Сервис не запускается

В случае, если службы Агента не запускаются с ошибкой Access is denied:

• Убедитесь, что у служебного пользователя, от имени которого запускается агент, есть права Log on as a service. Инсталлятор добавляет это право, но в случае использования групповых доменнных политик это право может быть отозвано у служебной учетной записи. Необходимо настроить групповые политики на разрешение служебному пользователю осуществлять Log on as a service.
  • откройте Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment
  • локальный пользователь, создаваемый в процессе установки (pobpagentuser):
  • в случае использования GMSA – DomainName\ProtoobpGMSA$:
    
• Убедитесь, что служебный пользователь pobpagentuser является членом группы Users на сервере. В случае использования GMSA такое право должно быть у этой учетной записи.

Ошибка “Сервис помечен для удаления”

В случае запуска процедуры удаления агента, файлы агента удаляются, но службы агента остаются видимы в системе, при попытке их удаления через командую строку выводится сообщение о том, что сервис “помечен для удаления”. В этом случае потребуется перезагрузка машины, чтобы произошло полное удаление сервисов. После перезагрузки возможно заново установить пакет агента. Это особенность операционной системы Windows.

Docker

Запуск Docker агента (отдельный контейнер)

1. Подключитесь к Docker репозиторию ProtoOBP выполнив команду:

   sudo docker login --username <USERNAME> registry.git.proto.group
   

   Ваш <USERNAME> и пароль указаны в лицензионном сертификате, полученном ранее от вендора, в разделе “Учетные данные”. Пароль вводится интерактивно.

2. Запустите агента

       docker run -d \
       --cgroupns host \
       --pid host \
       --name protoobp-agent \
       -v /var/run/docker.sock:/var/run/docker.sock:ro \
       -v /proc/:/host/proc/:ro \
       -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
       -e POBP_API_KEY=<your_api_key> \
       -e POBP_POBP_URL=http://<адрес_бекенд_сервера_protoobp> \
       -e POBP_APM_POBP_URL=http://<адрес_бекенд_сервера_protoobp> \
       -e POBP_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED=false \
       registry.git.proto.group/protoobp/protoobp-artifacts/protoobp-agent:7.80.2
   

   Переменные окружения:

   POBP_API_KEY	значение, указанное в лицензионном сертификате, полученном ранее от вендора, в разделе Учетные данные -> Пароль
   POBP_POBP_URL	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> - адрес вашего ProtoOBP Backend сервера, доступного для агента
   POBP_APM_POBP_URL	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> – адрес вашего ProtoOBP Backend сервера, доступного для агента

Запуск Docker агента (docker compose)

1. Подключитесь к Docker репозиторию ProtoOBP выполнив команду:

   sudo docker login --username <USERNAME> registry.git.proto.group
   

   Ваш <USERNAME> и пароль указаны в лицензионном сертификате, полученном ранее от вендора, в разделе “Учетные данные”. Пароль вводится интерактивно.

2. Добавьте в ваш docker-compose.yaml файл следующее:

   protoobp-agent:
     container_name: protoobp-agent
     image: registry.git.proto.group/protoobp/protoobp-artifacts/protoobp-agent:7.80.2
     pid: host
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - /proc/:/host/proc/:ro
       - /sys/fs/cgroup/:/host/sys/fs/cgroup:ro
       - /etc/os-release:/host/etc/os-release:ro
     environment:
       - POBP_API_KEY=<your_api_key>
       - POBP_POBP_URL=http://<адрес_бекенд_сервера_protoobp>     # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
       - POBP_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED=false
       - POBP_APM_POBP_URL=http://<адрес_бекенд_сервера_protoobp> # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
   

   Переменные окружения:

   POBP_API_KEY	значение, указанное в лицензионном сертификате, полученном ранее от вендора, в разделе Учетные данные -> Пароль
   POBP_POBP_URL	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> - адрес вашего ProtoOBP Backend сервера, доступного для агента
   POBP_APM_POBP_URL	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> – адрес вашего ProtoOBP Backend сервера, доступного для агента

3. Запустите агента, выполнив:

   docker compose up -d protoobp-agent
   

Запуск агента в Docker Swarm

В кластере Docker Swarm агент устанавливается как обычный Docker-агент: данные собираются через сокет Docker-демона на каждой ноде кластера. Дополнительных компонентов, аналогичных cluster-агенту в Kubernetes, не требуется.

1. Подключитесь к Docker репозиторию ProtoOBP на каждой ноде кластера:

   sudo docker login --username <USERNAME> registry.git.proto.group
   

   Ваш <USERNAME> и пароль указаны в лицензионном сертификате, полученном ранее от вендора, в разделе “Учетные данные”. Пароль вводится интерактивно.

2. Опишите агента в файле стека (например, protoobp-agent-stack.yaml):

   version: "3.8"
   
   services:
     protoobp-agent:
       image: registry.git.proto.group/protoobp/protoobp-artifacts/protoobp-agent:7.80.2
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - /proc/:/host/proc/:ro
         - /sys/fs/cgroup/:/host/sys/fs/cgroup:ro
         - /etc/os-release:/host/etc/os-release:ro
       environment:
         - POBP_API_KEY=<your_api_key>
         - POBP_POBP_URL=http://<адрес_бекенд_сервера_protoobp>     # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
         - POBP_APM_POBP_URL=http://<адрес_бекенд_сервера_protoobp> # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
         - POBP_APM_NON_LOCAL_TRAFFIC=true
         - POBP_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED=false
       ports:
         - target: 8126
           published: 8126
           protocol: tcp
           mode: host
         - target: 8125
           published: 8125
           protocol: udp
           mode: host
       deploy:
         mode: global
   

3. Разверните стек с ноды-менеджера:

   docker stack deploy -c protoobp-agent-stack.yaml protoobp
   

Автообнаружение и теги Swarm

Агент автоматически добавляет к метрикам и логам контейнеров теги на основе стандартных лейблов Docker Swarm:

Дополнительно на ноды, входящие в кластер Swarm, добавляется тег хоста docker_swarm_node_role со значением manager или worker.

Конфигурация проверок и дополнительные теги задаются лейблами автообнаружения с префиксом com.protoobp.ad. В файле стека такие лейблы необходимо указывать в секции labels сервиса, а не в секции deploy.labels: лейблы из deploy.labels назначаются объекту сервиса Swarm и в контейнер не попадают, поэтому агент их не увидит.

services:
  my-app:
    image: my-app:1.0.0
    labels:                                  # лейблы контейнера – агент их видит
      com.protoobp.ad.tags: '["team:billing"]'
    deploy:
      labels:                                # лейблы сервиса Swarm – агент их НЕ видит
        com.example.owner: "billing"

Отправка трейсов и метрик приложений

Приложение должно отправлять трейсы и пользовательские метрики агенту той ноды, на которой оно запущено. Адрес ноды удобно передавать приложению через встроенные шаблоны Swarm:

services:
  my-app:
    image: my-app:1.0.0
    environment:
      - POBP_AGENT_HOST={{.Node.Hostname}}
      - POBP_TRACE_AGENT_PORT=8126

Имена переменных зависят от используемого трейсера – проверьте их в разделе по инструментации вашего языка (для части трейсеров используется префикс DD_, например DD_AGENT_HOST).

Обращение к агенту по имени сервиса через оверлейную сеть не рекомендуется: балансировка Swarm может направить данные на агента другой ноды.

Ограничения в Docker Swarm

• Объекты Docker Swarm (сервисы, стеки, задачи) не инвентаризируются в ресурсной модели платформы – в отличие от объектов Kubernetes. Принадлежность к сервису и стеку доступна только в виде тегов телеметрии swarm_service и swarm_namespace, по которым можно строить дашборды, отчёты и правила алертов.
• Метрики уровня управления кластером Swarm (заданное и фактическое число реплик, состояние задач, история перепланирования) не собираются.
• Трафик, проходящий через сеть ingress и внутреннюю балансировку Swarm, учитывается на уровне сетевых интерфейсов контейнера, без разбора логики балансировки.
• Файл конфигурации агента и дополнительные конфигурации проверок передаются через переменные окружения либо через механизмы Docker configs и secrets.

Kubernetes

После установки агента в системе появятся поды агента:

• protoobp
• protoobp-cluster-agent

Необходимые сетевые порты для работы Kubernetes агента:

Установка Kubernetes агента

1. Добавьте helm репозиторий ProtoOBP:

   helm repo add --username <my_login> --password <my_password> protoobp https://git.proto.group/api/v4/projects/125/packages/helm/stable
   

   Ваши логин и пароль указаны в лицензионном сертификате, полученном ранее от вендора, в разделе “Учетные данные”.

2. Добавьте secret для скачивания Docker образов из репозитория ProtoOBP. Для этого воспользуйтесь готовым скриптом script.sh:

   # Укажите имя пользователя
   login="my_login"
   # Укажите пароль
   password="my_password"
   # Укажите адрес репозитория
   registry="registry.git.proto.group"
   # Укажите namespace в котором будет установлен агент (по умолчанию protoobp)
   namespace="protoobp"
   
   ######################
   # Скрипт
   set -o errexit
   
   echo 'Создаем Secret'
   kubectl create namespace ${namespace}
   kubectl create secret docker-registry protoobp-registry --docker-username=${login} --docker-password=${password} --docker-server=${registry} --namespace=${namespace}
   

3. Создайте файл values.yaml с конфигурацией агента

   targetSystem: "linux"
   commonLabels: {}
   registry: registry.git.proto.group/protoobp/protoobp-artifacts # необходимо изменить в случае использования собственного Docker репозитория
   protoobp:
     apiKey: <ВАШ_API_KEY>   # указан в лицензионном сертификате 
     clusterName: <ИМЯ_КЛАСТЕРА>  # задается вручную в соответствии с текущим реальным именем кластер
     pobp_url: http://<адрес_бекенд_сервера_protoobp>      # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
     pobp_apm_url: http://<адрес_бекенд_сервера_protoobp>  # используйте httpS только если на сервере ProtoOBP Backend подключен доверенный сертификат
     logLevel: INFO
     processAgent:
       enabled: false
       processCollection: false
     kubelet:
       tlsVerify: false
   clusterAgent:
     image:
       name: cluster-agent
       tag: 7.80.2
       pullSecrets:
         - name: "protoobp-registry"
     env:  ## этот раздел и переменная ниже добавляется только в случае использования локального репозитория Docker образов для компонентов Proto Observability Platform 
       - name: POBP_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY
         value: docker.intranet/protoobp/protoobp-artifacts ## здесь указывается адрес локального репозитория - зеркала образов        
   agents:
     image:
       name: protoobp-agent
       tag: 7.80.2
       pullSecrets:
         - name: "protoobp-registry"
   

   Параметры:

   <ВАШ_API_KEY>	значение, указанное в лицензионном сертификате, полученном ранее от вендора, в разделе Учетные данные -> Пароль
   pobp_url	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> - адрес вашего ProtoOBP Backend сервера, доступного для агента
   apm_pobp_url	строка вида http://<адрес_бекенд_сервера_protoobp>, где <адрес_бекенд_сервера_protoobp> – адрес вашего ProtoOBP Backend сервера, доступного для агента
   <ИМЯ_КЛАСТЕРА>	имя кластера, которое будет отображаться в интерфейсе Proto Observability Platform

4. Установите helm чарт в ваш Kubernetes кластер (в примере ниже исползуется неймспейс protoobp)

   Обратите внимание

   Для изменения параметров агентов Proto OBP допустимы только изменения в файле values.yaml, изменять сам чарт не нужно.

   helm install protoobp -f values.yaml protoobp/protoobp --namespace protoobp
   

Использование hostPath ноды

Поды агента имеют несколько hostPath mount:

Работа в непривилегированном режиме

Для максимальной совместимости и автоматизации сбора данных агент в контейнере по умолчанию запускается от пользователя root.

Использование не root пользователя может ограничить работу некоторых интеграций, которым необходимы данные хоста (ноды).

Пользователя, под которым запускается агент в контейнере, можно изменить, указав в values.yaml ID необходимого пользователя.

protoobp:
...
  securityContext:
      runAsUser: <USER_ID> 
      # UID пользователя, под которым будет запускаться Proto OBP агент
      supplementalGroups:
        - <GROUP_ID> 
        # ID группы, которая является владельцем сокета Docker или containerd

Дополнительная конфигурация для OpenShift

Особенности настройки агентов Proto OBP с OpenShift:

• необходимо указать создание SCC (Security Context Constraints) для агентов
• необходимо указать путь к сокету CRI, так как OpenShift использует CRI-O в качестве рантайма контейнеров
• необходимо добавить tolerations для запуска агентов на master и infra нодах кластера

Для этого в файле values.yaml в разделе agents добавьте:

protoobp:
  criSocketPath: /var/run/crio/crio.sock

...
agents:
  useHostNetwork: true
  podSecurity:
    securityContextConstraints:
      create: true
  tolerations:
    - effect: NoSchedule
      key: node-role.kubernetes.io/master
      operator: Exists
    - effect: NoSchedule
      key: node-role.kubernetes.io/infra
      operator: Exists
clusterAgent:
  podSecurity:
    securityContextConstraints:
      create: true
...

Изменение параметров Kubernetes агента

После внесения изменений в файл values.yaml можно применить изменения с помощью команды:

helm upgrade protoobp -f values.yaml protoobp/protoobp --namespace protoobp

Или воспользуйтесь полным удалением агента и переустановкой.

Удаление Kubernetes агента

Удалить ProtoOBP агента из Kubernetes кластера, можно выполнив (используемый в примере неймспейс – protoobp, замените при использовании нестандартного неймспейса):

helm uninstall protoobp -n protoobp

Работа агента через proxy

1. Настройка прокси-сервера. В качестве примера может использоваться прокси-сервер Nginx и минимальная конфигурация:

   user www-data;
   worker_processes auto;
   error_log /var/log/nginx/error.log;
   pid /run/nginx.pid;
   load_module /usr/lib/nginx/modules/ngx_stream_module.so;
   
   events {
       worker_connections 1024;
   }
   
   stream {
   
       server {
           listen 80;
           proxy_ssl_verify off;
           proxy_ssl on;
           proxy_pass proto-backend:443;
       }
   }
   

   Где proto-backend – адрес вашего бэкенд сервера.

2. Настройка агента для использования прокси. В используемых адресах вместо адресов бэкенда укажите адрес прокси сервера:

   api_key: your-api-key
   pobp_url: http://nginx-proxy
   skip_ssl_validation: true
   apm_config:
     apm_non_local_traffic: true   
     apm_pobp_url: http://nginx-proxy
     telemetry:
       enabled: false
   database_monitoring:
     metrics:
       pobp_url: nginx-proxy
     activity:
       pobp_url: nginx-proxy
     samples:
       pobp_url: nginx-proxy
   

   Где nginx-proxy – адрес вашего прокси сервера.

3. Примените изменения, перезапустив агента.

Файлы конфигурации агента

Основной конфигурационный файл агента:

Файлы конфигурации модулей для мониторинга технологий находятся в папке <путь к папке конфигурации>/conf.d/<технология>.d/..

Путь к папке конфигурации зависит от платформы:

Например, для мониторинга MySQL на агента Linux путь к файлу конфигурации MySQL будет иметь вид:

/etc/protoobp-agent/conf.d/mysql.d/conf.yaml

Проверка работы агента

Логи агента

Логи работы агента располагаются в следующих локациях:

Логи установки агента располагаются в следующих локациях:

Собираемые системные метрики по хостам

Собираемые контейнерные метрики