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

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

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

Введение

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

1. Установка ProtoOBP Агента.
2. Установка трейсера.
3. Инициализация трейсера.
4. Конфигурирование трейсера.

Установка трейсера

• Трейсер:
• ProtoOBP
• Datadog
• New Relic
• OpenTelemetry

npm install dd-trace --save

npm install dd-trace@latest-node16

Инициализация трейсера

• Трейсер:
• ProtoOBP
• Datadog
• New Relic
• OpenTelemetry

node --import dd-trace/register.js app.js

node --import dd-trace/register.js --require dd-trace/init app.js

Конфигурирование трейсера

• Трейсер:
• ProtoOBP
• Datadog
• New Relic
• OpenTelemetry

POBP_SERVICE=my_service  # Имя сервиса, которое будет отображаться в интерфейсе Proto OBP, обязательно
POBP_ENV=prod            # Название окружения, желательно, например prod, pre-prod, stage и тд
POBP_VERSION=1.2.3       # Версия приложения, опционально (по умолчанию - версия из package.json)
POBP_AGENT_HOST=protoobp-agent # Адрес Агента, на который будет отсылать данные трейсер (смотри ниже примеры для Docker и Kubernetes)
POBP_RUNTIME_METRICS_ENABLED="true"     
POBP_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true"
POBP_TRACE_TELEMETRY_ENABLED="false"    

DD_SERVICE=my_service   # Имя сервиса, которое будет отображаться в интерфейсе Proto OBP, обязательно
DD_ENV=prod             # Название окружения, желательно, например prod, pre-prod, stage и тд
DD_VERSION=1.2.3        # Версия приложения, опционально (по умолчанию - версия из package.json)
DD_RUNTIME_METRICS_ENABLED="true"     
DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true"
DD_TRACE_TELEMETRY_ENABLED="false"    

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

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

• Трейсер:
• ProtoOBP
• Datadog
• New Relic
• OpenTelemetry

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

# 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_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true" \
    POBP_TRACE_TELEMETRY_ENABLED="false"
EXPOSE 8080

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

   POBP_AGENT_HOST: protoobp-agent

FROM node:22.4.1

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

RUN npm install dd-trace --save

RUN npm install 

COPY server.js /opt/server/

# необходимые переменные окружения для работы трейсера Datadog
ENV DD_SERVICE="имя_вашего_сервиса" \
    DD_RUNTIME_METRICS_ENABLED="true" \
    DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED="true" \
    DD_TRACE_TELEMETRY_ENABLED="false"
EXPOSE 8080

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

   DD_AGENT_HOST: protoobp-agent

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

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

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

• Трейсер:
• ProtoOBP
• Datadog
• New Relic
• OpenTelemetry

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>"            
            

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<CONTAINER_NAME>"
        image: "<CONTAINER_IMAGE>/<TAG>"
        env:
          - name: DD_SERVICE
            value: dispatch			
          - name: DD_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: DD_TAGS
            value: "pod_name:$(POD_NAME),node:$(NODE_NAME),kube_namespace:$(POD_NAMESPACE),kube_cluster_name:<my_cluster_name>"            
            

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

Агент 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
   

2. Если локальный репозиторий Docker образов не используется, то в спецификации пода добавьте 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 без использования лейблов

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

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

Если после подключения трейсера данные в интерфейсе 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. проверьте логи агента на предмет ошибок подключения к бэкенду.

Поддерживаемые технологии (трейсер ProtoOBP)

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

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

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

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

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

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

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

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

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

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