brave

勇敢な

Brave は分散トレース計測ライブラリです。 Brave は通常、プロダクション リクエストをインターセプトして、タイミング データを収集し、トレース コンテキストを関連付けて伝達します。通常、トレースデータは Zipkin サーバーに送信されますが、サードパーティのプラグインを使用して Amazon X-Ray などの代替サービスに送信できます。

このリポジトリには、依存関係のない Java ライブラリと、運用サービスで使用される一般的なコンポーネントのインストルメンテーションが含まれています。たとえば、これにはサーブレットのトレース フィルターや Apache Log4J のログ相関が含まれます。

単純な Web アプリケーションをトレースする方法については、サンプル プロジェクトを参照してください。

含まれるもの

Brave の依存関係のないトレーサ ライブラリは、JRE6+ に対して動作します。これは、インストルメンテーションが操作の時間を計測し、操作を説明するタグを追加するために使用する基盤となる API です。このライブラリには、 X-B3-TraceIdヘッダーを解析するコードも含まれています。

ほとんどのユーザーはトレース コードを直接記述しません。むしろ、他の人が書いたインストルメンテーションを再利用します。独自のインストルメンテーションを作成する前に、当社のインストルメンテーションと Zipkin のリストを確認してください。 JDBC、サーブレット、Spring などの一般的なトレース ライブラリはすでに存在します。ここに書かれたインストルメンテーションはテストされ、ベンチマークされています。

レガシー アプリケーションをトレースしようとしている場合は、Spring XML 構成に興味があるかもしれません。これにより、カスタム コードを使用せずにトレースをセットアップできます。

トレース ID をログ ファイルに追加したり、スレッドのローカル動作を変更したりすることができます。 SLF4J などのツールとの統合については、コンテキスト ライブラリをご覧ください。

バージョン互換性ポリシー

すべての Brave ライブラリは、トレース対象または統合対象の最小 Java バージョンと一致しており、サードパーティの依存関係は追加されません。目標は、プロジェクトの選択に影響を与えたり、他の人による依存関係の決定にプロジェクトを従わせたりしないことです。

たとえば、基本的なレポート ライブラリである zipkin-sender-urlconnection が含まれていても、Brave には json、logging、protobuf、thrift の依存関係が推移的に含まれません。これは、アプリケーションが SLF4J、Gson、または Guava の特定のバージョンを選択しても、心配する必要がないことを意味します。さらに、json、thrift、または protobuf での基本的なレポートを含む依存関係ツリー全体は、jar の 512KiB 未満です。

フロア Java バージョン 1.6 は、古い JRE および古い Android ランタイムを許可しますが、一部のアプリケーションが制限される可能性があります。たとえば、Servlet 2.5 は Java 1.5 で動作しますが、Brave は 1.6 であるため、少なくとも JRE 1.6 を使用するまでは Servlet 2.5 アプリケーションをトレースできません。

すべての統合は、関連するライブラリを「提供された」スコープに設定します。これにより、Brave が選択したバージョンに干渉しないことが保証されます。

一部のライブラリは頻繁に更新されるため、API ドリフトが発生します。場合によっては、この影響を軽減するためにバージョン範囲をテストします。たとえば、gRPC と Kafka を複数のライブラリ バージョンに対してテストします。

アーティファクト

すべてのアーティファクトはグループ ID「io.zipkin.brave」に公開されます。すべてのコンポーネントに共通のリリース バージョンを使用します。

ライブラリのリリース

スナップショットは Sonatype にアップロードされ、Maven Central と同期されます。

ライブラリのスナップショット

スナップショットはマスターへのコミット後に Sonatype にアップロードされます。

バージョンの調整

複数の Brave コンポーネントを使用する場合は、バージョンを 1 か所に揃える必要があります。これにより、競合の心配が少なくなり、より安全にアップグレードできるようになります。

これには、Maven インストルメンテーション BOM (部品表) を使用できます。

元。依存関係セクションで、次のように BOM をインポートします。

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

サポートされているインストゥルメンテーションを選択するときに、バージョンを省略できるようになりました。また、間接的な使用にはバージョンが揃えられます。

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

上記を設定すると、プロパティbrave.version使用して、依存関係のバージョンを一貫してオーバーライドできます。これは、新機能または修正をテストするために最も一般的に行われます。

注: バージョンをオーバーライドする場合は、そのバージョンが更新対象のバージョンと同じかそれ以降であることを常に再確認してください。これにより、クラスの競合が回避されます。