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

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

• Введение
• Установка Java трейсера ProtoOBP
  • Java приложение в Docker
  • Java приложение в Kubernetes
    • Без использования автоматического подключения трейсера
    • С использованием автоматического подключения трейсера
      • Автоматическое подключение трейсера без использования лейблов
  • Добавление тегов для приложений в Kubernetes
  • Проверка успешного подключения трейсера
• Поддерживаемые технологии
  • Версии Java
  • Автоматическая инструментация библиотек и фреймворков
    • HTTP серверы и клиенты
  • Интеграции, отключенные по умолчанию
    • Хранилища данных
  • Прочие фреймворки
  • Включение и отключение инструментации конкретной библиотеки или фреймворка
• Метрики JVM
  • Список метрик JVM, собираемых Proto OBP

Введение

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

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

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

Общая инструкция по подключению трейсера к Java приложению. Может напрямую использоваться, если Java приложение запускается в Linux среде без контейнеризации. Для других случаев смотрите соответствующие инструкции - Docker, Kubernetes

1. Скачайте файл трейсера в архиве pobp-java-agent.tar.gz

   curl --header "PRIVATE-TOKEN:<your_token>" \
    "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-java-agent/v1.46.0/protoobp-java-agent-v1.46.0.tar.gz" \
    --output protoobp-java-agent-v1.46.0.tar.gz
   
   tar -xzvf protoobp-java-agent-v1.46.0.tar.gz
   

   Или сразу jar файл:

   curl --header "PRIVATE-TOKEN:<your_token>" \
    "https://git.proto.group/api/v4/projects/125/packages/generic/protoobp-java-agent/v1.46.0/protoobp-java-agent.jar" \
     --output protoobp-java-agent.jar
   

2. К параметрам запуска вашего приложения добавьте:

   • -javaagent:/path/to/pobp-java-agent.jar
   • -Dpobp.service=my_service_name - Имя сервиса, для отображениея в интерфейсе
   
   Примеры для различных серверов приложений и сценариев:
   • Вариант запуска приложения:
   • SpringBoot
   • Tomcat
   • JBoss
   • Jetty
   Если ваше приложение называется my_app.jar, создайте файл my_app.conf, содержащий:

   JAVA_OPTS=-javaagent:/path/to/pobp-java-agent.jar
   

   Linux: В файл запуска Tomcat, например, setenv.sh, добавьте:

   CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/pobp-java-agent.jar"
   

   Windows: В файл запуска Tomcat, например, setenv.bat, добавьте:

   set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"c:\path\to\pobp-java-agent.jar"
   

   В standalone режиме на Linux: добавьте следующее в standalone.conf:

   JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/pobp-java-agent.jar"
   

   В standalone режиме на Windows: добавьте следующее в standalone.conf.bat:

   set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/path/to/pobp-java-agent.jar"
   

   В domain режиме: добавьте строку в файле domain.xml, в разделе server-groups.server-group.jvm.jvm-options:

   <option value="-javaagent:/path/to/pobp-java-agent.jar"/>
   

   Исли используется jetty.sh для запуска Jetty как сервис, добавьте в этот файл:

   JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/pobp-java-agent.jar"
   

   Если используется start.ini для запуска Jetty, добавьте следующую строку (после --exec или добавьте --exec если такой строки нет):

   -javaagent:/path/to/pobp-java-agent.jar
   

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

   Если вы добавляете аргумент -javaagent к команде java -jar, он должен быть добавлен перед аргументом -jar – как аргумент JVM, а не как аргумент приложения. Например:

   java -javaagent:/path/to/pobp-java-agent.jar -jar my_app.jar
   

3. Перезапустите Java приложение.

Java приложение в Docker

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

1. Скачайте файл агента pobp-java-agent.jar.

2. Добавьте файл с агентом в ваш контейнер

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

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

4. К параметрам запуска вашего приложения добавьте:

   -javaagent:/path/to/the/pobp-java-agent.jar
   

5. Запустите контейнер с приложением

Пример готового Dockerfile

FROM openjdk:8-jdk
EXPOSE 8080
WORKDIR /opt/shipping
# Переменные окружения ProtoOBP Java трейсера
ENV POBP_AGENT_HOST="protobp-agent" # - Имя ProtoOBP агента
ENV POBP_SERVICE="my_service_name" # - Имя сервиса
ENV POBP_DOGSTATSD_NON_LOCAL_TRAFFIC="true"  # - Необходимо для runtime метрик JVM

COPY --from=build /opt/shipping/target/shipping-1.0.jar shipping.jar
COPY --from=build /opt/shipping/pobp-java-agent.jar pobp-java-agent.jar
CMD [ "java", "-Xmn256m","-javaagent:pobp-java-agent.jar", "-Xmx768m","-jar", "shipping.jar" ]

Java приложение в 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      # Имя сервиса в интерфейсе ProtoOBP
            value: dispatch			
          - name: POBP_AGENT_HOST   # Адрес агента
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP
            

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

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

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

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

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

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     labels:
     ...
   ...
   template:
     metadata:
       annotations:
         admission.proto.group/java-lib.version: "v1.46.0" 
       creationTimestamp: null
       labels:
         admission.proto.group/enabled: "true"  # Включение автоматической инструментации
         tags.proto.group/service: "my_service" # Имя сервиса в интерфейсе ProtoOBP
         service: my_service
   spec:
       containers:
         ...
       ...
       imagePullSecrets:
       - name: protoobp-registry
   

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

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

Добавление тегов для приложений в Kubernetes

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

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<CONTAINER_NAME>"
        image: "<CONTAINER_IMAGE>/<TAG>"
        env:
          - name: POBP_SERVICE
            value: dispatch		        
          - 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>"   
          - name: POBP_DOGSTATSD_NON_LOCAL_TRAFFIC
            value: true            
            

Проверка успешного подключения трейсера

В случае успешного подключения трейсера:

1. В логе приложения сразу после его запуска отобразится информации инициализации Java трейсере ProtoOBP, пример:

   [pobp.trace 2025-02-25 10:23:51:374 +0000] [pobp-task-scheduler] 
   INFO protoobp.trace.agent.core.StatusLogger - PROTOOBP TRACER CONFIGURATION 
   {"version":"1.47.0-SNAPSHOT~709cd8ebbd","os_name":"Linux",
   "os_version":"5.15.0-131-generic",
   "architecture":"amd64","lang":"jvm",
   "lang_version":"1.8.0_342","jvm_vendor":"Oracle Corporation",
   "jvm_version":"25.342-b07","java_class_version":"52.0",
   "http_nonProxyHosts":"null","http_proxyHost":"null","enabled":true,
   "service":"shipping","agent_url":"http://protoobp-agent:8126",
   "agent_error":false,"debug":false,"trace_propagation_style_extract":["protoobp","tracecontext"],
   "trace_propagation_style_inject":["protoobp","tracecontext"],"analytics_enabled":false,
   "priority_sampling_enabled":true,"logs_correlation_enabled":true,
   "profiling_enabled":false,"remote_config_enabled":true,"debugger_enabled":false,
   "debugger_exception_enabled":false,"debugger_span_origin_enabled":false,
   "appsec_enabled":"ENABLED_INACTIVE","rasp_enabled":false,"telemetry_enabled":false,
   "telemetry_dependency_collection_enabled":false,"telemetry_log_collection_enabled":false,
   "pobp_version":"","health_checks_enabled":true,"configuration_file":"no config file present",
   "runtime_id":"1e6866ee-d537-4297-a9a5-be200d7d59f2",
   "logging_settings":{"levelInBrackets":false,"dateTimeFormat":"'[pobp.trace 'yyyy-MM-dd HH:mm:ss:SSS Z']'",
   "logFile":"System.err","configurationFile":"simplelogger.properties","showShortLogName":false,
   "showDateTime":true,"showLogName":true,"showThreadName":true,"defaultLogLevel":"INFO",
   "warnLevelString":"WARN","embedException":false},"cws_enabled":false,"cws_tls_refresh":5000,
   "protoobp_profiler_enabled":false,"protoobp_profiler_safe":false,"protoobp_profiler_enabled_overridden":false,
   "data_streams_enabled":false}
   

2. В разделе Приложения > Сервисы появится новый сервис с типом Java.

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

Версии Java

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

HTTP серверы и клиенты

Интеграции, отключенные по умолчанию

Инструментация следующих фрейморков отключена по умолчанию и может быть включена с помощью настроек ниже:

Трейсинг сетевых запросов включает:

• время запроса до ответа
• тэги для запроса (например, код ответа)
• детали ошибки и стэктрейс
• распределенный трейсинг

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

Трейсинг обращения к хранилищу включает:

• время запроса до ответа
• информацию о запросе (например, query string)
• детали ошибки и стэктрейс

Агент совместим с основными JDBC драйверами, включая следующие:

• Apache Derby
• Firebird SQL
• H2 Database Engine
• HSQLDB
• IBM DB2
• MariaDB
• MSSQL (Microsoft SQL Server)
• MySQL
• Oracle
• Postgres SQL
• ScalikeJDBC

Инструментация следующих датасторов отключена по умолчанию и может быть включена с помощью настроек ниже:

Прочие фреймворки

Включение и отключение инструментации конкретной библиотеки или фреймворка

Большинство интеграций включено по умолчанию. Следующие настройки позволяют изменить поведение по умолчанию для всех интеграций:

• System Property: -Dpobp.integrations.enabled=false
• Переменная окружения: POBP_INTEGRATIONS_ENABLED=false

Каждая интеграция может быть включена или отключена по отдельности (переопределяя поведение по умолчанию и настройку выше):

• System Property: -Dpobp.integration.<INTEGRATION_NAME>.enabled=true
• Переменная окружения: POBP_INTEGRATION_<INTEGRATION_NAME>_ENABLED=true

Метрики JVM

Для каждой JVM трейсер ProtoOBP собирает и отображает JVM runtime метрики. Посмотреть их можно выбрав Сервисы > дашборд Java Сервиса, далее выбрать вкладку Инстансы > инстанс сервиса с вызовами > вкладка JVM.

Сбор метрик JVM включен по умолчанию. Он может быть отключен с помощью конфигурации:

• System Property: -Dpobp.jmxfetch.enabled=false
• Переменная окружения: POBP_JMXFETCH_ENABLED=false или POBP_RUNTIME_METRICS_ENABLED=false

По умолчанию, JVM метрики из приложений отсылаются Агенту на порт 8125.

Если Агент работает в контейнере:

• убедитесь, что переменная POBP_DOGSTATSD_NON_LOCAL_TRAFFIC установлена в значение true, и что порт 8125 открыт на агенте;
• дополнительно для Kubernetes - порт DogstatsD должен быть host port.

Список метрик JVM, собираемых Proto OBP

Для каждой JVM собираются следующие метрики после включения сбора JVM runtime метрик.