brave

Mutig

Brave ist eine verteilte Tracing-Instrumentierungsbibliothek. Brave fängt in der Regel Produktionsanfragen ab, um Zeitdaten zu sammeln, Trace-Kontexte zu korrelieren und weiterzugeben. Während Trace-Daten normalerweise an den Zipkin-Server gesendet werden, stehen Plugins von Drittanbietern zum Senden an alternative Dienste wie Amazon X-Ray zur Verfügung.

Dieses Repository umfasst abhängigkeitsfreie Java-Bibliotheken und Instrumentierung für allgemeine Komponenten, die in Produktionsdiensten verwendet werden. Dazu gehören beispielsweise Trace-Filter für Servlet und Log-Korrelation für Apache Log4J.

In unserem Beispielprojekt erfahren Sie, wie Sie eine einfache Webanwendung verfolgen.

Was ist enthalten

Die abhängigkeitsfreie Tracer-Bibliothek von Brave funktioniert mit JRE6+. Dies ist die zugrunde liegende API, die die Instrumentierung verwendet, um Vorgänge zeitlich festzulegen und Tags hinzuzufügen, die sie beschreiben. Diese Bibliothek enthält auch Code, der X-B3-TraceId Header analysiert.

Die meisten Benutzer schreiben den Ablaufverfolgungscode nicht direkt. Vielmehr verwenden sie die von anderen geschriebene Instrumentierung wieder. Schauen Sie sich unsere Instrumentierung und Zipkins Liste an, bevor Sie Ihre eigene rollen. Es gibt bereits gängige Tracing-Bibliotheken wie JDBC, Servlet und Spring. Die hier geschriebenen Instrumente werden getestet und einem Benchmarking unterzogen.

Wenn Sie versuchen, Legacy-Anwendungen zu verfolgen, könnte Sie Spring XML Configuration interessieren. Dadurch können Sie die Ablaufverfolgung ohne benutzerdefinierten Code einrichten.

Möglicherweise möchten Sie Trace-IDs in Ihre Protokolldateien einfügen oder das lokale Verhalten des Threads ändern. Schauen Sie sich unsere Kontextbibliotheken für die Integration mit Tools wie SLF4J an.

Richtlinie zur Versionskompatibilität

Alle Brave-Bibliotheken entsprechen der minimalen Java-Version dessen, was verfolgt oder integriert wird, und fügen keine Abhängigkeiten von Drittanbietern hinzu. Das Ziel besteht darin, weder die Entscheidungen Ihrer Projekte zu beeinflussen noch Ihr Projekt von Abhängigkeitsentscheidungen anderer abhängig zu machen.

Selbst wenn Brave beispielsweise eine grundlegende Berichtsbibliothek, zipkin-sender-urlconnection, enthält, enthält es transitiv keine JSON-, Protokollierungs-, Protobuf- oder Thrift-Abhängigkeit. Dies bedeutet, dass Sie sich keine Sorgen machen müssen, wenn Ihre Anwendung eine bestimmte Version von SLF4J, Gson oder Guava auswählt. Darüber hinaus umfasst der gesamte Abhängigkeitsbaum einschließlich der grundlegenden Berichterstattung in JSON, Thrift oder Protobuf weniger als 512 KB an Jars.

Es gibt eine Java-Basisversion von 1.6, die ältere JREs und ältere Android-Laufzeiten zulässt, jedoch möglicherweise einige Anwendungen einschränkt. Beispielsweise funktioniert Servlet 2.5 mit Java 1.5, aber da Brave 1.6 ist, können Sie Servlet 2.5-Anwendungen erst verfolgen, wenn Sie mindestens JRE 1.6 verwenden.

Alle Integrationen setzen ihre zugehörige Bibliothek auf den „bereitgestellten“ Bereich. Dadurch wird sichergestellt, dass Brave die von Ihnen ausgewählten Versionen nicht beeinträchtigt.

Einige Bibliotheken werden häufig aktualisiert, was zu einer API-Drift führt. In einigen Fällen testen wir Versionsbereiche, um die Auswirkungen zu verringern. Beispielsweise testen wir gRPC und Kafka anhand mehrerer Bibliotheksversionen.

Artefakte

Alle Artefakte werden unter der Gruppen-ID „io.zipkin.brave“ veröffentlicht. Wir verwenden für alle Komponenten eine gemeinsame Release-Version.

Bibliotheksveröffentlichungen

Snapshots werden auf Sonatype hochgeladen, das mit Maven Central synchronisiert wird

Bibliotheks-Snapshots

Snapshots werden nach der Übergabe an den Master auf Sonatype hochgeladen.

Versionsausrichtungen

Wenn Sie mehrere Brave-Komponenten verwenden, sollten Sie die Versionen an einem Ort ausrichten. Dadurch können Sie ein Upgrade sicherer durchführen und müssen sich weniger Gedanken über Konflikte machen.

Sie können hierfür unsere Maven-Instrumentierungsstückliste (Bill of Materials) verwenden:

Ex. Importieren Sie im Abschnitt „Abhängigkeiten“ die Stückliste wie folgt:

  < dependencyManagement >
    < dependencies >
      < dependency >
        < groupId >io.zipkin.brave</ groupId >
        < artifactId >brave-bom</ artifactId >
        < version >${brave.version}</ version >
        < type >pom</ type >
        < scope >import</ scope >
      </ dependency >
    </ dependencies >
  </ dependencyManagement >

Jetzt können Sie die Version weglassen, wenn Sie eine unterstützte Instrumentierung auswählen. Außerdem werden bei jeder indirekten Verwendung die Versionen angepasst:

< dependency >
  < groupId >io.zipkin.brave</ groupId >
  < artifactId >brave-instrumentation-okhttp3</ artifactId >
</ dependency >

Wenn die oben genannten Voraussetzungen erfüllt sind, können Sie die Eigenschaft brave.version verwenden, um Abhängigkeitsversionen kohärent zu überschreiben. Dies geschieht am häufigsten, um eine neue Funktion oder Fehlerbehebung zu testen.

Hinweis: Wenn Sie eine Version überschreiben, überprüfen Sie immer, ob Ihre Version gültig (gleich oder höher) als die Version ist, die Sie aktualisieren. Dadurch werden Klassenkonflikte vermieden.