Уведомление об архивировании

❗Уведомление: Этот проект был архивирован в текущем состоянии и больше не поддерживается.

Роль Ansible для Java-агента New Relic была архивирована из-за низкого использования. Она по-прежнему доступна для использования в текущем состоянии.

Роль Ansible: Java-агент New Relic

Эта роль устанавливает и настраивает Java-агент New Relic. Она должна работать с минимальной конфигурацией для приложений, работающих на Tomcat, Jetty или Wildfly. Мы планируем поддерживать самые популярные Java веб-серверы со временем.

• Требования
• Установка
• Конфигурация
  • Переменные конфигурации роли
  • Переменные конфигурации агента
  • Другая конфигурация конкретного агента
  • Использование собственного файла конфигурации агента
• Пример использования
• Сообщество
• Проблемы / Запросы на улучшения
• Лицензия

Требования

Команда unzip должна быть доступна на целевых хостах.

Установка

Рекомендуемый способ установки роли — использовать Ansible Galaxy:

$ ansible-galaxy install newrelic.new_relic_java_agent

Если вы хотите внести свой вклад в роль, вы можете клонировать этот репозиторий и внести изменения, затем установить её локально, запустив:

sh examples/install_role.sh

В зависимости от того, как Ansible установлен в вашей системе, возможно, вам нужно будет предшествовать команде sudo.

Конфигурация

Эта роль использует переменные для двух целей: конфигурация роли и конфигурация агента.

Переменные конфигурации роли описывают, как настроены ваши хосты, чтобы роль могла установить файлы агента в правильное место и настроить вашу Java-среду для запуска агента.

Переменные конфигурации агента могут быть установлены глобально в вашем плейбуке или для каждого хоста или группы в вашем файле инвентаря. Они используются для создания файла newrelic.yml, который Java-агент использует для определения своей конфигурации.

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

server_type

Обязательно Веб-сервер, используемый вашим приложением. Возможные значения: tomcat, jetty, и wildfly (только в автономном режиме).

server_root

Обязательно Место расположения веб-сервера на хосте. Файлы JAR агента, конфигурации и логи будут располагаться в подкаталоге этой директории.

jvm_conf_file

Обязательно Путь к конфигурационному файлу веб-сервера для ссылки на Java-агент New Relic. Например, для Tomcat это setenv.sh. Если его нет, файл будет создан.

server_user / server_group

Обязательно Пользователь и группа, от имени которых работает веб-сервер. Используется для установки прав собственности на файлы newrelic.jar и newrelic.yml.

restart_web_server

Необязательно - По умолчанию: true Если установлено в false, роль не перезапускает веб-сервер после установки агента.

Обратите внимание, что агент не активируется до перезапуска веб-сервера.

service_name

Обязательно (если restart_web_server не установлен в false) Имя сервиса, под которым работает веб-сервер. Используется Ansible для перезапуска веб-сервера после установки агента.

custom_instrumentation_files

Необязательно Список XML-файлов для включения пользовательской инструментировки Java-агентом. См. раздел Пользовательская инструментировка для получения дополнительной информации.

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

Конфигурация агента помещается в словарь nr_java_agent_config и добавляется в конфигурационный файл Java-агента - newrelic.yml. Наиболее распространённые настройки можно задавать через эту роль. Примеры можно найти в examples/agent_install.yml.

Чтобы задать настройки для конкретных хостов в вашем инвентаре, используйте словарь nr_java_agent_host_config. Для примеров см. examples/inventory.yml. Значения хостов переопределяют значения в nr_java_agent_config.

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

license_key

Обязательно Ваш ключ лицензии New Relic.

app_name

Обязательно Имя приложения, которое инструментируется. Для получения дополнительных сведений см. документацию New Relic по именованию приложений.

proxy_host / proxy_port / proxy_user / proxy_password, / proxy_scheme

Необязательно Если вы подключаетесь к сборщику New Relic через прокси, вы можете настроить параметры прокси с помощью этих значений. Для получения дополнительных сведений см. документацию New Relic по настройке Java-агента.

labels

Необязательно Пользовательские метки для агента. Метки представляют собой пары имя-значение. Имена и значений ограничены 255 символами и не могут содержать двоеточия (:) или точки с запятой (;). Значение должно быть списком пар ключ-значение, разделённых точками с запятой. Например:

nr_java_agent_config:
  ...
  labels: Server:One;Data Center:Primary

collector_host

Необязательно Если вам нужно указать хост сборщика, вы можете использовать переменную collector_host. Для получения дополнительных сведений см. документацию New Relic по конечным точкам сборщика.

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

Кроме перечисленных выше, вы можете настроить следующие параметры через эту роль Ansible:

• agent_enabled
• high_security
• enable_auto_app_naming
• log_level
• audit_mode
• log_file_count
• log_limit_in_kbytes
• log_daily
• log_file_name
• log_file_path
• max_stack_trace_lines
• attributes: enabled, include, exclude
• transaction_tracer: enabled, transaction_threshold, record_sql, log_sql, stack_trace_threshold, explain_enabled, explain_threshold, top_n
• error_collector: enabled, ignore_errors, ignore_status_codes
• transaction_events: enabled, max_samples_stored
• distributed_tracing: enabled
• cross_application_tracer: enabled
• thread_profiler: enabled
• browser_monitoring: auto_instrument
• labels

Для получения более подробной информации о этих настройках и других, смотрите документацию по конфигурации Java-агента. Если вам нужно настроить параметры, кроме этих, вам понадобится предоставить полностью заданный файл newrelic.yml. Для получения дополнительных сведений см. раздел Использование собственного файла конфигурации агента.

Использование собственного файла конфигурации агента

Если вам нужно указать настройки конфигурации агента, выходящие за рамки перечисленных выше, вам нужно будет предоставить свой файл newrelic.yml. Любые настройки в словаре nr_java_agent_config будут проигнорированы. Установите переменную nr_java_agent_config_file на путь к вашему файлу, например:

nr_java_agent_config_file: /path/to/your/newrelic.yml

Если этот файл находится на целевых хостах, а не на системе, на которой выполняется Ansible, установите nr_java_agent_config_file_is_remote в true:

nr_java_agent_config_file_is_remote: true

Пример использования

Файлы examples/agent_install.yml и examples/inventory.yml предоставляют пример того, как использовать роль.

После настройки переменных в examples/agent_install.yml и вашего инвентаря в examples/inventory.yml вы можете протестировать роль, запустив Ansible:

ansible-playbook -i examples/inventory.yml examples/agent_install.yml

Пользовательская инструментировка

Если вы хотите включить пользовательскую инструментировку с помощью XML, вы можете предоставить список XML-файлов в переменной custom_instrumentation_files. Эти файлы будут скопированы на каждый хост, на который устанавливается Java-агент, если вы укажете переменную в своем плейбуке. Вы также можете устанавливать разные файлы на разные хосты, указывая переменную на уровне хоста в вашем инвентаре, или разные файлы для различных групп хостов, задавая переменную на уровне группы, либо через ваш инвентарь, либо через файлы в директории group_vars.

Смотрите документацию Ansible о инвентарях и переменных для получения дополнительной информации о том, как управлять переменными хостов и групп. Вы можете увидеть некоторые примеры в этом репозитории о том, как указывать пользовательскую инструментировку в файлах custom_instrumentation_playbook.yml и custom_instrumentation_inventory.yml.

Разработка

Тестирование

Эта роль использует molecule для тестирования. Вам понадобятся Docker и Python версии 3.6 или выше. Установите molecule с модулем docker, если вы этого еще не сделали:

$ pip install molecule[docker]

Это также установит ansible, если это необходимо. Для выполнения тестов вызовите molecule test из верхнего уровня каталога.

$ git clone https://github.com/newrelic/newrelic-java-agent-ansible-role
$ cd newrelic-java-agent-ansible-role
$ molecule test
--> Тестовая матрица

└── по умолчанию
    ├── зависимость
    ├── проверка стиля
    ├── очистка
...

Сообщество

New Relic управляет онлайн-форумом, где клиенты могут общаться с сотрудниками New Relic, а также с другими клиентами для получения помощи и обмена лучшими практиками. Как и все официальные открытые проекты New Relic, в нем есть соответствующая тема сообщества в хабе исследователей New Relic. Вы можете найти тему/ветки проекта здесь:

https://discuss.newrelic.com/t/ansible-role-for-new-relic-java-agent/99654

Проблемы / Запросы на улучшения

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

Лицензия

Проект выпущен под версией 2.0 лицензии Apache.