Avis d'Archivage

❗Avis : Ce projet a été archivé tel quel et n'est plus activement maintenu.

Le rôle Ansible pour New Relic Java a été archivé en raison de son faible usage. Il reste utilisable dans son état actuel.

Rôle Ansible : Agent Java New Relic

Ce rôle installe et configure l'agent Java New Relic. Il devrait fonctionner avec une configuration minimale pour les applications exécutées sous Tomcat, Jetty ou Wildfly. Nous visons à prendre en charge les serveurs web Java les plus populaires au fil du temps.

• Exigences
• Installation
• Configuration
  • Variables de configuration du rôle
  • Variables de configuration de l'agent
  • Autres configurations spécifiques à l'agent
  • Utiliser votre propre fichier de configuration d'agent
• Exemple d'utilisation
• Communauté
• Problèmes / Demandes d'amélioration
• Licence

Exigences

La commande unzip doit être disponible sur les hôtes cibles.

Installation

La manière recommandée pour installer le rôle est d'utiliser Ansible Galaxy :

$ ansible-galaxy install newrelic.new_relic_java_agent

Si vous souhaitez contribuer au rôle, vous pouvez cloner ce dépôt et y apporter des modifications, puis l'installer localement en exécutant :

sh examples/install_role.sh

Selon la façon dont Ansible est installé sur votre système, vous devrez peut-être précéder la commande ci-dessus de sudo.

Configuration

Ce rôle utilise des variables à deux fins : configuration du rôle et configuration de l'agent.

Variables de configuration du rôle décrivent comment vos hôtes sont configurés afin que le rôle puisse installer les fichiers de l'agent au bon endroit et préparer votre environnement Java pour exécuter l'agent.

Variables de configuration de l'agent peuvent être définies globalement dans votre playbook ou par hôte ou groupe dans votre fichier d'inventaire. Elles sont utilisées pour créer le fichier newrelic.yml que l'agent Java utilise pour déterminer sa configuration.

Variables de configuration du rôle

server_type

Requis Serveur web utilisé par votre application. Valeurs possibles : tomcat, jetty, et wildfly (mode autonome uniquement).

server_root

Requis Emplacement du serveur web sur l'hôte. Le JAR, la configuration et les fichiers journaux de l'agent se trouveront dans un sous-répertoire de ce répertoire.

jvm_conf_file

Requis Chemin du fichier de configuration du serveur web pour référencer l'agent Java New Relic. Par exemple, pour Tomcat, c'est setenv.sh. Si le fichier n'existe pas, il sera créé.

server_user / server_group

Requis Utilisateur et groupe sous lesquels le serveur web fonctionne. Utilisés pour définir la propriété des fichiers newrelic.jar et newrelic.yml.

restart_web_server

Facultatif - Par défaut : true S'il est défini sur false, le rôle ne redémarre pas le serveur web après l'installation de l'agent.

Notez que l'agent n'est pas activé tant que le serveur web n'est pas redémarré.

service_name

Requis (sauf si restart_web_server est défini sur false) Nom du service sous lequel le serveur web fonctionne. Utilisé par Ansible pour redémarrer le serveur web après l'installation de l'agent.

custom_instrumentation_files

Facultatif Liste de fichiers XML pour activer l'instrumentation personnalisée par l'agent Java. Voir la section Instrumentation personnalisée pour plus de détails.

Variables de configuration de l'agent

La configuration de l'agent se trouve dans le dictionnaire nr_java_agent_config et est ajoutée au fichier de configuration de l'agent Java - newrelic.yml. Les paramètres les plus courants peuvent être spécifiés via ce rôle. Des exemples peuvent être trouvés dans examples/agent_install.yml.

Pour spécifier des paramètres pour des hôtes spécifiques dans votre inventaire, utilisez le dictionnaire nr_java_agent_host_config. Pour des exemples, voir examples/inventory.yml. Les valeurs des hôtes remplacent celles dans nr_java_agent_config.

Si vous devez configurer des paramètres qui ne sont pas listés ci-dessous, vous devez fournir votre propre fichier newrelic.yml préconfiguré (voir Utiliser votre propre fichier de configuration d'agent).

license_key

Requis Votre clé de licence New Relic.

app_name

Requis Nom de l'application à instrumenter. Pour plus de détails, voir la documentation New Relic sur le nommage des applications.

proxy_host / proxy_port / proxy_user / proxy_password, / proxy_scheme

Facultatif Si vous vous connectez au collecteur New Relic via un proxy, vous pouvez configurer vos paramètres proxy avec ces valeurs. Pour plus de détails, voir la documentation New Relic sur la configuration de l'agent Java.

labels

Facultatif Étiquettes personnalisées configurables par l'utilisateur pour l'agent. Les étiquettes sont des paires nom-valeur. Les noms et valeurs sont limités à 255 caractères et ne peuvent pas contenir de deux-points (:) ni de points-virgules (;). La valeur doit être une liste de paires clé-valeur séparées par des points-virgules. Par exemple :

nr_java_agent_config:
  ...
  labels: Serveur:Un;Centre de Données:Principal

collector_host

Facultatif Si vous devez spécifier un hôte collecteur, vous pouvez utiliser la variable collector_host. Voir la documentation New Relic sur les points de collecte pour plus de détails.

Autres configurations spécifiques à l'agent

Outre celles énumérées ci-dessus, vous pouvez configurer les paramètres suivants via ce rôle 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

Voir la documentation de configuration de l'agent Java pour plus de détails sur ces paramètres et d'autres. Si vous devez configurer d'autres paramètres, vous devrez fournir un fichier newrelic.yml entièrement spécifié. Pour des détails, voir la section Utiliser votre propre fichier de configuration d'agent.

Utiliser votre propre fichier de configuration d'agent

Si vous devez spécifier des paramètres de configuration d'agent au-delà de ceux listés ci-dessus, vous devrez fournir votre propre fichier newrelic.yml. Tous les paramètres dans le dictionnaire nr_java_agent_config seront alors ignorés. Définissez la variable nr_java_agent_config_file au chemin de votre fichier, par exemple :

nr_java_agent_config_file: /chemin/vers/votre/newrelic.yml

Si ce fichier se trouve sur les hôtes cibles plutôt que sur le système exécutant Ansible, définissez nr_java_agent_config_file_is_remote sur true :

nr_java_agent_config_file_is_remote: true

Exemple d'utilisation

Les fichiers examples/agent_install.yml et examples/inventory.yml fournissent un exemple de la façon d'utiliser le rôle.

Après avoir configuré vos variables dans examples/agent_install.yml et votre inventaire dans examples/inventory.yml, vous pouvez essayer le rôle en exécutant Ansible :

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

Instrumentation personnalisée

Si vous souhaitez activer l'instrumentation personnalisée avec XML, vous pouvez fournir une liste de fichiers XML dans la variable custom_instrumentation_files. Ces fichiers seront copiés sur chaque hôte sur lequel l'agent Java est installé, si vous spécifiez la variable dans votre playbook. Vous pouvez également installer différents fichiers sur différents hôtes en spécifiant la variable au niveau de l'hôte dans votre inventaire, ou différents fichiers pour différents groupes d'hôtes en spécifiant la variable au niveau du groupe, soit dans votre inventaire, soit via des fichiers dans le répertoire group_vars.

Voir la documentation Ansible sur l'inventaire et les variables pour plus de détails sur la gestion des variables d'hôtes et de groupes. Vous pouvez voir quelques exemples dans ce dépôt sur la façon de spécifier une instrumentation personnalisée dans les fichiers custom_instrumentation_playbook.yml et custom_instrumentation_inventory.yml.

Développement

Tests

Ce rôle utilise molecule pour les tests. Vous aurez besoin de Docker et de Python 3.6 ou plus. Installez molecule avec le module docker, si vous ne l'avez pas encore fait :

$ pip install molecule[docker]

Cela installera également ansible si nécessaire. Pour exécuter les tests, appelez molecule test depuis le répertoire de niveau supérieur.

$ git clone https://github.com/newrelic/newrelic-java-agent-ansible-role
$ cd newrelic-java-agent-ansible-role
$ molecule test
--> Matrice de test

└── par défaut
    ├── dépendance
    ├── lint
    ├── nettoyage
...

Communauté

New Relic héberge et modère un forum en ligne où les clients peuvent interagir avec les employés de New Relic ainsi qu'avec d'autres clients pour obtenir de l'aide et partager les meilleures pratiques. Comme tous les projets open source officiels de New Relic, il existe un sujet communautaire associé dans le New Relic Explorers Hub. Vous pouvez trouver le sujet / fils du projet ici :

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

Problèmes / Demandes d'amélioration

Les problèmes et demandes d'amélioration peuvent être soumis dans l'onglet Problèmes de ce dépôt. Veuillez rechercher et examiner les problèmes ouverts existants avant de soumettre un nouvel problème.

Licence

Le projet est publié sous la version 2.0 de la licence Apache.