diff --git a/agent_installation_guide/APM/java.md b/agent_installation_guide/APM/java.md index 9b5f831..04ee01a 100644 --- a/agent_installation_guide/APM/java.md +++ b/agent_installation_guide/APM/java.md @@ -1,138 +1,233 @@ -# Установка APM-агента для Java +# Инструкция по установке агента New Relic Java-агента в Docker -Для интеграции APM-агента в Java-приложение выполните следующие шаги: +Вы получили архив `java-agent-docker.tar.gz`. +### 1\. Подготовка файлов -### 1. **Загрузка агента** -1. Скачайте архив с агентом с официального сайта New Relic: +Положите архив `java-agent-docker.tar.gz` в корень вашего проекта, рядом с `Dockerfile`. - ```bash - curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip - ``` +### 2\. Обновление Dockerfile -2. (Опционально) Ознакомьтесь с [официальной инструкцией по установке APM-агента для Java](https://docs.newrelic.com/install/java/) для получения дополнительных подробностей. +Добавьте шаги распаковки агента и настройки переменных окружения. В контейнерах рекомендуется использовать `ENV` вместо правки файла `newrelic.yml`. +Пример `Dockerfile`: +``` +FROM openjdk:11-jre-slim + +# --- УСТАНОВКА АГЕНТА --- +# 1. Копируем архив агента в контейнер +COPY java-agent-docker.tar.gz /tmp/agent.tar.gz + +# 2. Распаковываем в /opt/newrelic и удаляем архив +RUN mkdir -p /opt && \ + tar -xzf /tmp/agent.tar.gz -C /opt && \ + rm /tmp/agent.tar.gz +# Теперь агент доступен по пути: /opt/newrelic/newrelic.jar + +# --- ВАШЕ ПРИЛОЖЕНИЕ --- +COPY target/my-app.jar /app/my-app.jar +WORKDIR /app + +# --- КОНФИГУРАЦИЯ АГЕНТА (Через ENV) --- +# Лицензионный ключ(заглушка, не меняем) +ENV NEW_RELIC_LICENSE_KEY="0123456789-123456789-123456789-123456789" \ + NEW_RELIC_APP_NAME="MY_DOCKER_APP" \ + NEW_RELIC_HOST="gmonit-collector..ru" \ + NEW_RELIC_LOG="stdout" + +# Если нужны кастомные сертификаты (раскомментировать при необходимости) +# COPY rootCA.crt /opt/newrelic/rootCA.crt +# ENV NEW_RELIC_CA_BUNDLE_PATH="/opt/newrelic/rootCA.crt" + +# --- ЗАПУСК --- +# Добавляем -javaagent к запуску +ENTRYPOINT ["java", "-javaagent:/opt/newrelic/newrelic.jar", "-jar", "/app/my-app.jar"] +``` + +### 3\. Сборка образа -### 2. **Распаковка агента** -Распакуйте загруженный архив в предпочтительный каталог. Например: +Выполните сборку: -```bash -sudo mkdir -p /opt/newrelic -sudo unzip newrelic-java.zip -d /opt/newrelic +``` +docker build -t my-java-app:with-monitoring . ``` -> **Важно:** Убедитесь, что файлы `.jar` агента **не находятся** в пути к классам или в каталогах, перечисленных в `java.endorsed.dirs`. +### 4\. Проверка (локальный запуск) +Запустите контейнер локально, чтобы убедиться в корректности подключения: +``` +docker run --rm my-java-app:with-monitoring +``` -### 3. **Настройка конфигурации агента** -Настройте файл `newrelic.yml` или используйте переменные окружения для конфигурации агента. +Смотрите вывод в консоли (`stdout`). -1. **Основные настройки** (через переменные окружения или в `newrelic.yml`): +**Критерии успеха:** - ```bash - NEW_RELIC_LOG=stdout #Логирование агента в stdout - NEW_RELIC_LICENSE_KEY=0123456789-123456789-123456789-123456789 #Ключ(заглушка, не меняем) - NEW_RELIC_HOST=gmonit-collector..ru #Домен коллектора GMONIT - NEW_RELIC_APP_NAME="MY_AWESOME_APP" #Название приложения - замените на своё - ``` +1. Приложение стартует без ошибок. + +2. В логах есть сообщения от `com.newrelic`. + +3. Нет ошибок SSL (`SSLHandshakeException`) или соединения с хостом коллектора. -2. **Если используются самоподписанные сертификаты** - Необходимо явно указать путь до бандла сертификатов (через `newrelic.yml` или переменную окружения): - ```bash - NEW_RELIC_CA_BUNDLE_PATH=/gmonit/ssl/rootCA.crt #Путь до файла с бандлом сертификатов - ``` - Или в `newrelic.yml`: +# Установка APM-агента для Java в K8S + +Вы получили архив `java-apm-k8s-offline.tar.gz`. + +**Целевая среда:** Kubernetes 1.25+ (любой дистрибутив), container runtime containerd или Docker, `kubectl` с доступом к кластеру, закрытый контур без выхода в интернет. - ```yaml - ca_bundle_path: /gmonit/ssl/rootCA.crt - ``` +### 1\. Распаковка архива + +``` +tar -xzvf java-apm-k8s-offline.tar.gz +cd java-apm-k8s-bundle +``` -> При необходимости более тонкой настройки параметров агента смотрите также официальную [документацию по конфигурации агента для Java](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/). +### 2\. Загрузка образа-донора в containerd кластера +**Вариант А: импорт на каждую ноду кластера (containerd напрямую)** -### 4. **Интеграция агента с приложением** -Добавьте флаг запуска агента в команду запуска вашего Java-приложения: +Скопировать `images/newrelic-java-agent-9.1.0.tar` на каждую worker-ноду и выполнить: -```bash --javaagent:/opt/newrelic/newrelic.jar ``` +# Для k3s: +sudo k3s ctr images import newrelic-java-agent-9.1.0.tar + +# Для стандартного k8s с containerd: +sudo ctr -n k8s.io images import newrelic-java-agent-9.1.0.tar -Пример команды запуска: -```bash -java -javaagent:/opt/newrelic/newrelic.jar -jar my-app.jar +# Для кластера на Docker (устарело, но встречается): +docker load -i newrelic-java-agent-9.1.0.tar ``` -### 5. **Проверка работы агента** -После запуска приложения убедитесь, что агент успешно подключился: -- В логах агента (`stdout`) должно появиться сообщение об успешном подключении. -- В интерфейсе мониторинга GMONIT появятся метрики приложения. +Проверка: +``` +sudo k3s ctr images ls -q | grep newrelic-java-agent +# Ожидается: docker.io/library/newrelic-java-agent:9.1.0 +``` -### 6. **Подробнее** -Для более детальной информации о конфигурации и настройке агента обратитесь к [официальной документации New Relic](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/). +**Вариант Б: push в приватный registry клиента (Harbor/Nexus/etc)** +На машине с доступом и к архиву, и к registry клиента: -# Установка APM-агента для Java в K8S +``` +docker load -i images/newrelic-java-agent-9.1.0.tar +docker tag newrelic-java-agent:9.1.0 /newrelic-java-agent:9.1.0 +docker push /newrelic-java-agent:9.1.0 +``` -Для интеграции агента New Relic в Java-приложение, работающее в Kubernetes, выполните следующие шаги: +В `04-deployment-example.yaml` заменить `/newrelic-java-agent:9.1.0` на реальный путь и выставить `imagePullPolicy: IfNotPresent`. +### 3\. Подготовка манифестов -### Шаг 1: Загрузка и распаковка агента New Relic +В каждом файле `manifests/*.yaml` заменить плейсхолдеры: -1. **Скачать Java-агент**: - ```bash - curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip - ``` +| Плейсхолдер | На что заменить | Пример | +| --- | --- | --- | +| `` | Namespace вашего приложения | `payments` | +| `` | Имя приложения в GMONIT | `eldic-payment-service` | +| `` | FQDN коллектора GMONIT | `collector.gmonit.internal` | +| `` | Путь к вашему registry (или `docker.io/library` для локального импорта в containerd) | `registry.bank.kg/library` | +| `<ВАШЕ_ПРИЛОЖЕНИЕ>:` | Образ вашего Java-приложения | `eldic-payment:1.0.0` | -2. **Распаковать агент**: - ```bash - unzip newrelic-java.zip -d /opt/newrelic - ``` - Агент Java нужно распаковать в директорию внутри контейнера, которая будет доступна во время выполнения приложения. +Заменить license\_key в `02-secret-license.yaml` на выданный инженером GMONIT (в кавычках, как в шаблоне). - > **Важно**: Если агент будет расположен в другом месте, убедитесь, что `.jar` файлы агента **не находятся** в директориях, указанных в `java.endorsed.dirs` или в пути к классам. +### 4\. Применение манифестов +``` +kubectl apply -f manifests/01-namespace.yaml +kubectl apply -f manifests/02-secret-license.yaml +kubectl apply -f manifests/03-configmap-newrelic.yaml +kubectl apply -f manifests/04-deployment-example.yaml +``` -### Шаг 2: Настройка агента New Relic +### 5\. Проверка -1. **Откройте файл `newrelic.yml`** и внесите следующие изменения: +**Статус пода:** - ```yaml - common: &default_settings - license_key: '0123456789-123456789-123456789-123456789' #Ключ(заглушка, не меняем) - app_name: "MY_AWESOME_APP" #Название приложения - замените на своё - host: "gmonit-collector..ru" #Домен коллектора GMONIT - agent_enabled: true - log_level: info - log_file_path: stdout #Логирование агента в stdout - ``` +``` +kubectl get pods -n +# STATUS должен быть Running, READY 1/1 +``` -2. Если используются самоподписанные сертификаты, убедитесь, что путь к бандлу сертификатов добавлен в настройки (см. предыдущие разделы). +**Логи initContainer (агент скопирован в том):** +``` +kubectl logs -n -l app= -c nr-agent-init +``` + +**Логи приложения (агент подключился к коллектору):** + +``` +kubectl logs -n -l app= -c app | grep -i "new relic" +``` + +Ожидаемые строки: + +``` +Picked up JAVA_TOOL_OPTIONS: -javaagent:/opt/nr/newrelic.jar +New Relic Agent: Loading configuration file "/opt/nr/./newrelic.yml" +Using configured collector host: +New Relic Agent v9.1.0 is initializing... +Agent 1@/ connected to :443 +New Relic Agent v9.1.0 has started +``` + +**Проверка в UI GMONIT:** -### Шаг 3: Подготовка Docker-образа с агентом +Открыть UI GMONIT → APM → убедиться что приложение `` появилось в списке и метрики идут. -1. **Обновите `Dockerfile`** для вашего Java-приложения. Пример конфигурации: +## Часть 3: Минимальная рабочая конфигурация + +Ниже приведена минимально необходимая конфигурация `newrelic.yml` (внутри ConfigMap): + +``` +common: &default_settings + agent_enabled: true + app_name: + host: + log_level: info + log_file_name: STDOUT + distributed_tracing: + enabled: true + transaction_tracer: + enabled: true +production: + <<: *default_settings +``` + +**Параметры:** + +| Параметр | Назначение | +| --- | --- | +| `agent_enabled: true` | Включение агента | +| `app_name` | Имя приложения в UI GMONIT | +| `host` | FQDN коллектора GMONIT (без схемы) | +| `log_level: info` | Уровень логирования агента | +| `log_file_name: STDOUT` | Вывод логов агента в stdout пода (видны через `kubectl logs`) | +| `distributed_tracing.enabled` | Distributed tracing между сервисами | +| `transaction_tracer.enabled` | Детализация медленных транзакций | + +Если коллектор работает с самоподписанным SSL, добавьте в ConfigMap: + +``` + ca_bundle_path: /opt/nr/cacert.pem +``` - ```dockerfile - FROM openjdk:11-jre-slim - COPY opt/newrelic/ /opt/newrelic/ #Копируем агента New Relic в контейнер - COPY out/ /app #Копируем ваше Java-приложение в контейнер - WORKDIR /app - ENTRYPOINT ["java", "-javaagent:/opt/newrelic/newrelic.jar", "com.example.HelloWorldServer"] - ``` +И примонтировать CA-сертификат как дополнительный ConfigMap/Secret в `/opt/nr/cacert.pem`. -2. **Пересоберите Docker-образ**: - ```bash - docker build -t my-java-app-with-newrelic:latest . - ``` +**License\_key передаётся через Secret как env-переменная `NEW_RELIC_LICENSE_KEY`** (не в `newrelic.yml`). Значение в Secret должно быть **обёрнуто в двойные кавычки** (см. грабли ниже). -3. **Загрузите Docker-образ в кластер Kubernetes**. Пример для использования с `kind`: - ```bash - kind load docker-image my-java-app-with-newrelic:latest - ``` +## Часть 4: Контрольный чек-лист -После выполнения этих шагов ваш Docker-образ с интегрированным APM-агентом готов для развертывания в Kubernetes. Убедитесь, что поды с приложением запускаются корректно, а метрики появляются в интерфейсе GMONIT. +* [ ] Архив распакован +* [ ] Образ `newrelic-java-agent:9.1.0` импортирован в containerd всех нод (или push в приватный registry) +* [ ] Плейсхолдеры в манифестах заменены (``, ``, ``, ``, образ приложения) +* [ ] License\_key в Secret: в двойных кавычках +* [ ] `kubectl apply` выполнен для всех 4 манифестов без ошибок +* [ ] Под `READY 1/1 Running` +* [ ] В логах приложения: `New Relic Agent v9.1.0 has started` + `Agent ... connected to :443` +* [ ] Приложение появилось в UI GMONIT, метрики отображаются \ No newline at end of file