brave

Courageux

Brave est une bibliothèque d'instruments de traçage distribuée. Brave intercepte généralement les demandes de production pour collecter des données de synchronisation, corréler et propager les contextes de trace. Bien que les données de trace soient généralement envoyées au serveur Zipkin, des plugins tiers sont disponibles pour être envoyés à d'autres services tels qu'Amazon X-Ray.

Ce référentiel comprend des bibliothèques Java sans dépendance et une instrumentation pour les composants courants utilisés dans les services de production. Par exemple, cela inclut des filtres de trace pour le servlet et la corrélation des journaux pour Apache Log4J.

Vous pouvez consulter notre exemple de projet pour savoir comment tracer une application Web simple.

Ce qui est inclus

La bibliothèque de traceurs sans dépendance de Brave fonctionne avec JRE6+. Il s'agit de l'API sous-jacente que l'instrumentation utilise pour chronométrer les opérations et ajouter des balises qui les décrivent. Cette bibliothèque inclut également du code qui analyse les en-têtes X-B3-TraceId .

La plupart des utilisateurs n’écrivent pas directement le code de traçage. Au contraire, ils réutilisent les instruments écrits par d’autres. Consultez notre instrumentation et la liste Zipkin avant de lancer le vôtre. Des bibliothèques de traçage courantes telles que JDBC, Servlet et Spring existent déjà. Les instruments écrits ici sont testés et comparés.

Si vous essayez de tracer des applications héritées, vous pourriez être intéressé par Spring XML Configuration. Cela vous permet de configurer le traçage sans aucun code personnalisé.

Vous souhaiterez peut-être insérer des ID de trace dans vos fichiers journaux ou modifier le comportement local des threads. Consultez nos bibliothèques de contexte, pour l'intégration avec des outils tels que SLF4J.

Politique de compatibilité des versions

Toutes les bibliothèques Brave correspondent à la version Java minimale de ce qui est tracé ou intégré, et n'ajoute aucune dépendance tierce. Le but est de ne pas influencer les choix de vos projets, ni de soumettre votre projet à des décisions de dépendance prises par d'autres.

Par exemple, même en incluant une bibliothèque de rapports de base, zipkin-sender-urlconnection, Brave n'inclut de manière transitive aucune dépendance json, journalisation, protobuf ou thrift. Cela signifie aucun souci si votre application choisit une version spécifique de SLF4J, Gson ou Guava. De plus, l'ensemble de l'arborescence des dépendances, y compris les rapports de base en json, thrift ou protobuf, fait moins de 512 Ko de fichiers jar.

Il existe une version Java 1.6, qui autorise les anciens JRE et les anciens environnements d'exécution Android, mais peut limiter certaines applications. Par exemple, Servlet 2.5 fonctionne avec Java 1.5, mais comme Brave est 1.6, vous ne pourrez pas tracer les applications Servlet 2.5 tant que vous n'aurez pas utilisé au moins JRE 1.6.

Toutes les intégrations définissent leur bibliothèque associée sur la portée « fournie ». Cela garantit que Brave n'interfère pas avec les versions que vous choisissez.

Certaines bibliothèques sont souvent mises à jour, ce qui entraîne une dérive des API. Dans certains cas, nous testons les plages de versions pour en réduire l’impact. Par exemple, nous testons gRPC et Kafka sur plusieurs versions de bibliothèques.

Artefacts

Tous les artefacts sont publiés sur l'ID de groupe « io.zipkin.brave ». Nous utilisons une version commune pour tous les composants.

Sorties de la bibliothèque

Les instantanés sont téléchargés sur Sonatype qui se synchronise avec Maven Central

Instantanés de la bibliothèque

Les instantanés sont téléchargés sur Sonatype après leur validation auprès du maître.

Alignements de versions

Lorsque vous utilisez plusieurs composants courageux, vous souhaiterez aligner les versions en un seul endroit. Cela vous permet d'effectuer une mise à niveau plus sûre, avec moins de soucis liés aux conflits.

Vous pouvez utiliser notre BOM (Bill of Materials) d'instrumentation Maven pour cela :

Ex. dans votre section dépendances, importez la BOM comme ceci :

  < 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 >

Désormais, vous pouvez laisser de côté la version lorsque vous choisissez une instrumentation prise en charge. De plus, toute utilisation indirecte aura des versions alignées :

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

Une fois ce qui précède en place, vous pouvez utiliser la propriété brave.version pour remplacer les versions de dépendances de manière cohérente. Il s’agit le plus souvent de tester une nouvelle fonctionnalité ou un correctif.

Remarque : Si vous remplacez une version, vérifiez toujours que votre version est valide (égale ou ultérieure) à celle que vous mettez à jour. Cela évitera les conflits de classes.