Archivierungsmitteilung

❗Hinweis: Dieses Projekt wurde wie es ist archiviert und wird nicht mehr aktiv gewartet.

Die New Relic Java Ansible Rolle wurde aufgrund geringer Nutzung archiviert. Sie kann jedoch weiterhin in ihrem aktuellen Zustand verwendet werden.

Ansible Rolle: New Relic Java Agent

Diese Rolle installiert und konfiguriert den New Relic Java Agent. Sie sollte mit minimaler Konfiguration für Anwendungen unter Tomcat, Jetty oder Wildfly funktionieren. Wir haben das Ziel, im Laufe der Zeit die beliebtesten Java-Webserver zu unterstützen.

• Anforderungen
• Installation
• Konfiguration
  • Variablen für die Rollen-Konfiguration
  • Variablen für die Agent-Konfiguration
  • Weitere agentenspezifische Konfiguration
  • Verwendung Ihrer eigenen Konfigurationsdatei für den Agenten
• Beispielnutzung
• Gemeinschaft
• Probleme / Verbesserungsvorschläge
• Lizenz

Anforderungen

Der Befehl unzip muss auf den Zielhosts verfügbar sein.

Installation

Der empfohlene Weg zur Installation der Rolle ist die Verwendung von Ansible Galaxy:

$ ansible-galaxy install newrelic.new_relic_java_agent

Wenn Sie zur Rolle beitragen möchten, können Sie dieses Repository klonen und Änderungen vornehmen. Installieren Sie es dann lokal, indem Sie Folgendes ausführen:

sh examples/install_role.sh

Je nachdem, wie Ansible auf Ihrem System installiert ist, müssen Sie möglicherweise den obigen Befehl mit sudo beginnen.

Konfiguration

Diese Rolle verwendet Variablen für zwei Zwecke: Rollen-Konfiguration und Agenten-Konfiguration.

Variablen für die Rollen-Konfiguration beschreiben, wie Ihre Hosts eingerichtet sind, damit die Rolle die Agenten-Dateien am richtigen Ort installieren und Ihre Java-Umgebung zum Ausführen des Agenten einrichten kann.

Variablen für die Agenten-Konfiguration können global in Ihrem Playbook oder pro Host oder Gruppe in Ihrer Inventardatei festgelegt werden. Sie werden verwendet, um die newrelic.yml-Datei zu erstellen, die der Java-Agent verwendet, um seine Konfiguration zu bestimmen.

Variablen für die Rollen-Konfiguration

server_type

Erforderlich Webserver, der von Ihrer Anwendung verwendet wird. Mögliche Werte sind: tomcat, jetty und wildfly (nur im Standalone-Modus).

server_root

Erforderlich Standort des Webservers auf dem Host. Die JAR-, Konfigurations- und Protokolldateien des Agenten befinden sich in einem Unterverzeichnis dieses Verzeichnisses.

jvm_conf_file

Erforderlich Pfad der Konfigurationsdatei des Webservers für den New Relic Java-Agenten. Für Tomcat beispielsweise ist es setenv.sh. Wenn es nicht existiert, wird die Datei erstellt.

server_user / server_group

Erforderlich Benutzer und Gruppe, unter denen der Webserver läuft. Verwendet, um den Besitz der Dateien newrelic.jar und newrelic.yml festzulegen.

restart_web_server

Optional - Standard: true Wenn auf false gesetzt, wird der Webserver nach der Installation des Agenten nicht neu gestartet.

Hinweis: Der Agent ist erst aktiviert, nachdem der Webserver neu gestartet wurde.

service_name

Erforderlich (es sei denn, restart_web_server ist auf false gesetzt) Dienstname, unter dem der Webserver läuft. Wird von Ansible verwendet, um den Webserver nach der Installation des Agenten neu zu starten.

custom_instrumentation_files

Optional Liste von XML-Dateien, um die benutzerdefinierte Instrumentierung durch den Java-Agenten zu aktivieren. Weitere Details finden Sie im Abschnitt Benutzerdefinierte Instrumentierung.

Variablen für die Agent-Konfiguration

Die Konfiguration des Agenten erfolgt im Wörterbuch nr_java_agent_config und wird zur Konfigurationsdatei des Java-Agenten - newrelic.yml - hinzugefügt. Die häufigsten Einstellungen können über diese Rolle angegeben werden. Beispiele finden Sie in examples/agent_install.yml.

Um Einstellungen für bestimmte Hosts in Ihrem Inventar anzugeben, verwenden Sie das Wörterbuch nr_java_agent_host_config. Für Beispiele siehe examples/inventory.yml. Hostwerte haben Vorrang vor denen in nr_java_agent_config.

Wenn Sie Einstellungen konfigurieren müssen, die nicht aufgeführt sind, müssen Sie Ihre eigene, vorkonfigurierte Datei newrelic.yml bereitstellen (siehe Verwendung Ihrer eigenen Konfigurationsdatei für den Agenten).

license_key

Erforderlich Ihrer New Relic Lizenzschlüssel.

app_name

Erforderlich Name der instrumentierten Anwendung. Weitere Details finden Sie in der New Relic-Dokumentation zur App-Benennung.

proxy_host / proxy_port / proxy_user / proxy_password, / proxy_scheme

Optional Wenn Sie über einen Proxy mit dem New Relic-Collector verbinden, können Sie Ihre Proxy-Einstellungen mit diesen Werten konfigurieren. Weitere Details finden Sie in der New Relic-Dokumentation zur Konfiguration des Java-Agenten.

labels

Optional Benutzerkonfigurierbare benutzerdefinierte Labels für den Agenten. Labels sind Namens-Wert-Paare. Namen und Werte sind auf 255 Zeichen begrenzt und dürfen keine Doppelpunkte (:) oder Semikolons (;) enthalten. Der Wert sollte eine durch Semikolons getrennte Liste von Schlüssel-Wert-Paaren sein. Zum Beispiel:

nr_java_agent_config:
  ...
  labels: Server:One;Datacenter:Primary

collector_host

Optional Wenn Sie einen Collector-Host angeben müssen, können Sie die Variable collector_host verwenden. Weitere Details finden Sie in der New Relic-Dokumentation zu Collector-Endpunkten.

Weitere agentenspezifische Konfiguration

Neben den oben aufgeführten können Sie die folgenden Einstellungen über diese Ansible-Rolle konfigurieren:

• 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

Siehe die Dokumentation zur Java-Agent-Konfiguration für weitere Details zu diesen Einstellungen und anderen. Wenn Sie andere Einstellungen konfigurieren müssen, müssen Sie eine vollständig angegebene Datei newrelic.yml bereitstellen. Weitere Informationen finden Sie im Abschnitt Verwendung Ihrer eigenen Konfigurationsdatei für den Agenten.

Verwendung Ihrer eigenen Konfigurationsdatei für den Agenten

Wenn Sie Agenten-Konfigurationseinstellungen angeben müssen, die über die oben aufgeführten hinausgehen, müssen Sie Ihre eigene Datei newrelic.yml bereitstellen. Alle Einstellungen im Wörterbuch nr_java_agent_config werden dann ignoriert. Setzen Sie die Variable nr_java_agent_config_file auf den Pfad zu Ihrer Datei, zum Beispiel:

nr_java_agent_config_file: /pfad/zu/Ihrer/newrelic.yml

Wenn sich diese Datei auf den Zielhosts und nicht auf dem System befindet, das Ansible ausführt, setzen Sie nr_java_agent_config_file_is_remote auf true:

nr_java_agent_config_file_is_remote: true

Beispielnutzung

Die Dateien examples/agent_install.yml und examples/inventory.yml bieten ein Beispiel, wie man die Rolle verwenden kann.

Nachdem Sie Ihre Variablen in examples/agent_install.yml und Ihr Inventar in examples/inventory.yml festgelegt haben, können Sie die Rolle testen, indem Sie Ansible ausführen:

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

Benutzerdefinierte Instrumentierung

Wenn Sie benutzerdefinierte Instrumentierung mit XML aktivieren möchten, können Sie eine Liste von XML-Dateien in der Variable custom_instrumentation_files bereitstellen. Diese Dateien werden auf jeden Host kopiert, auf dem der Java-Agent installiert wird, wenn Sie die Variable in Ihrem Playbook angeben. Sie können auch unterschiedliche Dateien auf unterschiedliche Hosts installieren, indem Sie die Variable auf der Host-Ebene in Ihrem Inventar oder unterschiedliche Dateien für unterschiedliche Hostgruppen angeben, entweder über Ihr Inventar oder durch Dateien im Verzeichnis group_vars.

Siehe die Ansible-Dokumentation zu Inventar und Variablen für weitere Informationen zur Verwaltung von Host- und Gruppenvariablen. In diesem Repository finden Sie einige Beispiele, wie man die benutzerdefinierte Instrumentierung in den Dateien custom_instrumentation_playbook.yml und custom_instrumentation_inventory.yml angibt.

Entwicklung

Tests

Diese Rolle verwendet molecule für Tests. Sie benötigen Docker und Python 3.6 oder später. Installieren Sie Molecule mit dem Docker-Modul, falls Sie dies noch nicht getan haben:

$ pip install molecule[docker]

Dies wird auch Ansible installieren, falls notwendig. Um die Tests auszuführen, rufen Sie molecule test im obersten Verzeichnis auf.

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

└── standard
    ├── Abhängigkeit
    ├── Lint
    ├── Aufräumen
...

Gemeinschaft

New Relic veranstaltet und moderiert ein Online-Forum, in dem Kunden mit New Relic-Mitarbeitern sowie anderen Kunden interagieren können, um Hilfe zu erhalten und bewährte Verfahren auszutauschen. Wie bei allen offiziellen Open Source-Projekten von New Relic gibt es ein zugehöriges Community-Thema im New Relic Explorers Hub. Sie finden das Thema/die Threads des Projekts hier:

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

Probleme / Verbesserungsvorschläge

Probleme und Verbesserungsvorschläge können im Issues-Tab dieses Repositorys eingereicht werden. Bitte suchen Sie nach bestehenden offenen Problemen und überprüfen Sie diese, bevor Sie ein neues Problem einreichen.

Lizenz

Das Projekt wird unter Version 2.0 der Apache-Lizenz veröffentlicht.