Мониторинг Node.js приложений с помощью Proto Observability

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

• Введение
• Установка Node.js трейсера ProtoOBP
  • Пример добавления токена аутентификации в Gitlab CI
  • Если приложение запускается в Docker контейнере
    • Пример запуска для Nuxt
• Если приложение работает в Kubernetes
  • Без использования автоматического подключения трейсера
  • С использованием автоматического подключения трейсера
  • Автоматическое подключение трейсера без использования лейблов
• Диагностика неполадок
• Поддерживаемые технологии
  • Поддерживаемые версии Node.js
  • Автоматическая инструментация веб-фрейморков
  • Автоматическая инструментация нативных модулей
  • Хранилища данных
  • Совместимость с системами очередей сообщений
  • Совместимость с Promise библиотеками
  • Совместимость с логгерами
• Сбор runtime метрик Node.js
  • Правила алертинга по метрикам Node.js runtime
• Дополнительная инструментация вызовов

Введение

Общий процесс подключения Node JS приложения на мониторинг:

1. Установка ProtoOBP Агента
2. Установка трейсера

Установка Node.js трейсера ProtoOBP

1. Установка pobp-trace модуля:

   • В .npmrc добавьте аутентификационный токен для репозитория ProtoOBP:

     :registry=https://git.proto.group/projects/125/packages/npm/
     //git.proto.group/api/v4/projects/125/packages/npm/:_authToken=<your_token>
     

     Где <your_token> – значение авторизационного токена из вашего лицензионного сертификата (поле токен или пароль).

   • Выполните установку модуля из репозитория ProtoOBP:

     npm install --no-audit https://git.proto.group/api/v4/projects/125/packages/npm/pobp-trace/-/pobp-trace-2.2.2.tgz
     

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

    const tracer = require('pobp-trace').init();
   

3. Добавьте следующие переменные окружения:

   • export POBP_SERVICE=my_service - Имя сервиса
   • export POBP_RUNTIME_METRICS_ENABLED="true" - Включение runtime метрик Node JS
   • export POBP_DOGSTATSD_NON_LOCAL_TRAFFIC="true" - Обязательно при включении метрик
   • export POBP_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true" - Обязательно при включении метрик
   • export POBP_TRACE_TELEMETRY_ENABLED="false"

Пример добавления токена аутентификации в Gitlab CI

• в настройках проекта в Gitlab добавьте переменную окружения (Проект -> Settings -> CI/CD -> Variables):

  • имя: PROTOOBP_INSTALL_TOKEN_KEY, значение = ваши данные из лицензионного сертификата (поле пароль или токен)

• .gitlab-ci.yml :

    script:
      - echo -e ":registry=https://git.proto.group/projects/125/packages/npm/\n//git.proto.group/api/v4/projects/125/packages/npm/:_authToken=${PROTOOBP_INSTALL_TOKEN_KEY}" >> .npmrc
  

Если приложение запускается в Docker контейнере

Выполните пункты 1 и 2 указанные выше и добавьте следующие переменные окружения:

• POBP_AGENT_HOST – адрес Агента, на который будет отсылать данные трейсер:
  • если Агент запущен в Docker контейнере, укажите имя Docker контейнера Агента:

    ENV POBP_AGENT_HOST="protoobp-agent"
    

    Убедитесь, что контейнер Агента и контейнер приложения находятся в одной Docker сети. Адрес агента должен быть доступен из Docker контейнера приложения.
  • если Агент запущен на хосте как сервис (не в контейнере):

    ENV POBP_AGENT_HOST="host.docker.internal"
    

    Убедитесь что в конфигурации Агента разрешен прием APM данных от контейнеров:

    apm_config:
      apm_non_local_traffic: true
    

• POBP_SERVICE – имя сервиса, которое будет отображаться в интерфейсе Proto OBP:

  ENV POBP_SERVICE="my_service_name"
  

• POBP_DOGSTATSD_NON_LOCAL_TRAFFIC – обязательно установите в true для получения runtime метрик

  ENV POBP_DOGSTATSD_NON_LOCAL_TRAFFIC="true"
  

• POBP_RUNTIME_METRICS_ENABLED – обязательно установите в true для получения runtime метрик

  ENV POBP_RUNTIME_METRICS_ENABLED="true"
  

• POBP_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED – обязательно установите в true для получения runtime метрик

  ENV POBP_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true"
  

• POBP_TRACE_TELEMETRY_ENABLED – установите в false

  ENV POBP_TRACE_TELEMETRY_ENABLED="false"
  

Пример Dockefile:

FROM node:22.4.1

ARG PROTOOBP_INSTALL_TOKEN_KEY

WORKDIR /opt/server
COPY package.json /opt/server/

# 1) изменяем .npmrc, дефолт — публичный npm
RUN printf "registry=https://registry.npmjs.org/\n" > /root/.npmrc \
 && printf "always-auth=true\n" >> /root/.npmrc \
 && printf "//git.proto.group/api/v4/projects/125/packages/npm/:_authToken=%s\n" "$PROTOOBP_INSTALL_TOKEN_KEY" >> /root/.npmrc

COPY package.json ./

# 2) подключаем pobp-trace как tarball по URL с токеном (НЕ меняя registry)
RUN npm install --no-audit --verbose \
  "https://your_token_name:${PROTOOBP_INSTALL_TOKEN_KEY}@git.proto.group/api/v4/projects/125/packages/npm/pobp-trace/-/pobp-trace-2.2.2.tgz"

# остальные пакеты устанавливаются из дефолтного npm репозитория
RUN npm install 

COPY server.js /opt/server/

# необходимые переменные окружения для работы трейсера ProtoOBP
ENV POBP_SERVICE="имя_вашего_сервиса" \
    POBP_RUNTIME_METRICS_ENABLED="true" \
    POBP_DOGSTATSD_NON_LOCAL_TRAFFIC="true" \
    POBP_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true" \
    POBP_TRACE_TELEMETRY_ENABLED="false"
EXPOSE 8080

CMD ["node", "server.js"]

Пример запуска для Nuxt

node --require pobp-trace/init /path/to/your/app/node_modules/nuxt/bin/nuxt.js start

Если приложение работает в Kubernetes

Убедитесь, что у вас успешно установлен и настроен ProtoOBP Агент для Kubernetes.

Без использования автоматического подключения трейсера

Дополнительно необходимо передать поду переменную окружения POBP_AGENT_HOST со значением IP адреса воркер-ноды, а также переменные окружения для связи трейсов с инфраструктурой (имя k8s кластера нужно задать вручную).

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<CONTAINER_NAME>"
        image: "<CONTAINER_IMAGE>/<TAG>"
        env:
          - name: POBP_SERVICE
            value: dispatch			
          - name: POBP_AGENT_HOST
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: POD_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
          - name: POD_NAME
            valueFrom:
              fieldRef:
                fieldPath: metadata.name
          - name: POBP_TAGS
            value: "pod_name:$(POD_NAME),node:$(NODE_NAME),kube_namespace:$(POD_NAMESPACE),kube_cluster_name:<my_cluster_name>"            
            

С использованием автоматического подключения трейсера

Агент ProtoOBP в K8s кластере по умолчанию инструментирует Node.js приложения с лейблом: admission.proto.group/enabled: "true"

1. В спецификации пода приложения добавьте анотацию и лейбл с версией NodeJS трейсинг агента:

apiVersion: apps/v1
kind: Deployment
metadata:
 labels:
 ...
...
template:
   metadata:
     annotations:
       admission.proto.group/js-lib.version: "v1"
     creationTimestamp: null
     labels:
       admission.proto.group/enabled: "true" # Включение автоматической инструментации
       tags.proto.group/service: "my_service" #Укажите имя сервиса
       service: my_service

1. В спецификации пода добавьте imagePullSecrets для доступа к Docker репозиторию ProtoOBP. Подробнее о добавление Secret указано в документации Установка агента в Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
  ...
...
 template:
    metadata:
      annotations:
        admission.proto.group/js-lib.version: "latest" #Рекомендуем использовать последнюю версию NodeJS  трейсинг агента
      creationTimestamp: null
      labels:
        admission.proto.group/enabled: "true" # Включение автоматической инструментации
        service: my_service
   spec:
      containers:
         ...
      ...
      imagePullSecrets:
      - name: protoobp-registry

Автоматическое подключение трейсера без использования лейблов

В конфигурации агента вы можете включить автоматическую инструментацию без использования лейблов.

Диагностика неполадок

Если после подключения трейсера данные в интерфейсе ProtoOBP не отображаются:

1. Проверьте, что установлены все необходимые переменные окружения для работы трейсера.
2. Дайте нагрузку на приложение (вызовы к приложению).
3. Проверьте логи запуска вашего приложения (stdout или файл), в них при успешном подключении трейсера должны быть записи от трейсера.
4. Проверьте, что от контейнера/пода с приложением есть сетевой доступ до Агента по порту 8126/tcp и 8125/udp (в случае Kubernetes – по NodeIP).
5. Добавьте переменные окружения к приложению для вывода отладочной инфинформации:

   POBP_TRACE_STARTUP_LOGS=true
   

6. Заново дайте назрузку на приложение и проверьте данные в интерфейсе ProtoOBP.

Пример лога запуска приложений с трейсером:

rs-cart  | PROTOOBP TRACER CONFIGURATION - {"date":"2025-08-07T11:22:41.989Z","os_name":"Linux","os_version":"5.15.0-151-generic","architecture":"x64","version":"2.2.2","la
ng":"nodejs","lang_version":"22.4.1","env":"","service":"cart","agent_url":"http://protoobp-agent:8126","debug":false,"sample_rate":1,"sampling_rules":[],"tags":{"team":"de
vops","service_group":"ecommerce_app","service":"cart","env":"","version":"1.0.0","runtime-id":"4c10336d-8d6e-4cfc-8e90-a129776243c4"},"pobp_version":"1.0.0","log_injection
_enabled":true,"runtime_metrics_enabled":true,"profiling_enabled":false,"integrations_loaded":[],"appsec_enabled":false}

1. На строне агента:
   1. проверьте логи агента на предмет ошибок подключения к бэкенду.

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

Поддерживаемые версии Node.js

Поддерживаются актуальные LTS версии Node.js.

Автоматическая инструментация веб-фрейморков

Автоматическая инструментация нативных модулей

Хранилища данных

Совместимость с системами очередей сообщений

Совместимость с Promise библиотеками

Совместимость с логгерами

Сбор runtime метрик Node.js

Помимо трейсов, ошибок и метрик по трейсам, Proto OBP также собирает runtime метрики Node.js приложений. Runtime метрики отображаются на дашборде конкретного инстанса сервиса.

Правила алертинга по метрикам Node.js runtime

Документация в разработке.

Дополнительная инструментация вызовов

Документация в разработке.