OpenTelemetry-Java-Instrumentierung: ein Agent, der sich an die JVM anhängt

Ein Java-Agent, der Telemetrie auf Bytecode-Ebene injiziert 1

Das Hauptprodukt des Repositorys ist ein Java-Agent-JAR, das an jede Java-8+-Anwendung angehängt werden kann. Nach dem Anhängen injiziert der Agent dynamisch Bytecode, um Telemetrie aus einer Reihe beliebter Bibliotheken und Frameworks zu erfassen. Das README sagt, dass das Nettoergebnis die Fähigkeit ist, Telemetriedaten aus einer Java-Anwendung ohne Codeänderungen zu sammeln. Der Export wird in einer Vielzahl von Formaten unterstützt, und sowohl der Agent als auch der Exporter lassen sich über Befehlszeilenargumente oder Umgebungsvariablen konfigurieren. Die Repository-Metadaten beschreiben das Projekt als Auto-Instrumentierung und Instrumentierungsbibliotheken für Java. Das Anhängen des Agents erfordert keine Codeänderungen und keine Neukompilierung, was der Hauptunterschied zur manuellen Instrumentierung ist. Dasselbe Repository veröffentlicht auch eigenständige Instrumentierungen für mehrere Bibliotheken, für Benutzer, die das dem Agent vorziehen; das README verweist diese Benutzer auf die Spalte für eigenständige Bibliotheksinstrumentierung im Dokument für unterstützte Bibliotheken.

Agent anhängen und wohin die Daten standardmäßig gehen 2

Der Einstiegspfad im README führt über das Herunterladen der neuesten opentelemetry-javaagent.jar von der GitHub-Releases-Seite. Das Paket enthält den Instrumentierungs-Agent sowie Instrumentierungen für alle unterstützten Bibliotheken und alle verfügbaren Daten-Exporter. Der Agent wird mit der JVM-Flagge -javaagent aktiviert; das Beispiel im README lautet `java -javaagent:path/to/opentelemetry-javaagent.jar -jar myapp.jar`. Standardmäßig verwendet der Agent den OTLP-Exporter, der so konfiguriert ist, dass er Daten an einen OpenTelemetry-Collector unter http://localhost:4318 sendet. Das README beschreibt nicht, wie dieser Collector bereitgestellt wird oder wie man Verbindungsparameter über den Standard-Endpunkt hinaus ändert; es verlinkt stattdessen auf das Collector-Repository und das Exporter-Quellverzeichnis.

Konfigurationsfläche und ihre Volatilität 3

Konfigurationsparameter werden als Java-Systemeigenschaften (-D-Flags) oder Umgebungsvariablen übergeben. Das Beispiel im README setzt `-Dotel.resource.attributes=service.name=your-service-name` und wechselt den Trace-Exporter mit `-Dotel.traces.exporter=zipkin` auf Zipkin. Der Agent wird als hochkonfigurierbar beschrieben, mit Exporter-Wahl, Exporter-Einstellungen wie dem Zielort der Daten und Trace-Kontext-Propagations-Headern. Zwei Dokumentationsseiten sind verlinkt: eine für die Agent-Konfiguration und eine für die SDK-Konfiguration. Das README warnt, dass sich die Namen der Konfigurationsparameter im Laufe der Zeit sehr wahrscheinlich ändern, und bittet Benutzer, bei neuen Versionen zurückzuschauen und Fehler oder unerwartetes Verhalten zu melden. Eine konkrete Liste von Konfigurationselementen muss daher anhand der Dokumentation der aktuellen Version überprüft werden und sollte nicht als feste Schnittstelle behandelt werden.

Unterstützte Bibliotheken, Frameworks und Anwendungsserver 4

Das README behauptet Unterstützung für eine riesige Anzahl von Bibliotheken und Frameworks und für die Mehrheit der beliebtesten Anwendungsserver, und beschreibt diese Unterstützung als sofort einsatzbereit. Das bedeutet, dass der Agent nach dem Anhängen die Aufrufe dieser Bibliotheken ohne zusätzliche Einrichtung erkennt. Es verweist auf docs/supported-libraries.md für die vollständige Liste; dieses Dokument behandelt auch deaktivierte Instrumentierungen und wie man unerwünschte Instrumentierungen unterdrückt. Das README selbst nennt keine konkreten Bibliotheken, Versionen oder Zahlen, daher muss jede konkrete Liste gegen das verlinkte Dokument geprüft werden. Das README quantifiziert auch nicht, was "riesig" oder "Mehrheit" bedeutet, also ist die tatsächliche Abdeckung nur über dieses Dokument verifizierbar.

Erweiterungen und Distributionen 5

Agent-Erweiterungen fügen dem Agent neue Funktionen hinzu, ohne eine separate Distribution zu erstellen oder das Repository zu forken. Das README nennt als Beispiele benutzerdefinierte Sampler, Span-Exporter und neue Standardwerte, die alle in den Agent eingebettet werden, um eine einzige JAR-Datei zu erhalten. Eine separate Seite behandelt die Erstellung einer Agent-Distribution, die als Sammlung von Beispielen für das Neupacken des Agents mit benutzerdefinierten Funktionen dient. Das README empfiehlt Erweiterungen für die meisten Benutzer, weil sie einfacher sind und kein Neubauen bei jeder Veröffentlichung des OpenTelemetry-Java-Agents erfordern. Die Rolle der Distributionsseite ist enger: Sie zeigt, wie man den Agent mit benutzerdefinierten Funktionen neu packt, was ein aufwendigerer Prozess ist als das Schreiben einer Erweiterung.

Manuelle Instrumentierung und Log-Korrelation 6

Für die meisten Benutzer ist die Out-of-the-Box-Instrumentierung ausreichend, aber das README beschreibt Fälle, in denen Benutzer Attribute zu den automatischen Spans hinzufügen oder Spans für eigenen Code manuell erstellen möchten, und verlinkt die Dokumentation zur manuellen Instrumentierung. Außerdem injiziert die Logger-MDC-Auto-Instrumentierung Trace-Informationen wie Trace-IDs und Span-IDs in benutzerdefinierte Anwendungslogs; Details stehen in einem eigenen Dokument. Beide Pfade bauen auf dem Agent auf, ersetzen ihn aber nicht. Ein Benutzer, der von der automatischen Instrumentierung abhängt, kann also weiterhin bei Bedarf eigene Spans und Attribute hinzufügen.

Redaktionelles Fazit

Das README behandelt den Agent als Standardweg und die eigenständige Instrumentierung als Alternative; die vollständige Liste unterstützter Bibliotheken, die Konfigurationsoptionen und die Mechanismen zum Unterdrücken von Instrumentierung verweist es auf separate Dokumente. Die Details, von denen die meisten Deployment-Fragen abhängen, stehen in diesen verlinkten Dokumenten, nicht im README selbst.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository
4. Release notes