refinery
v2.8.4
各リリースでマージされたリンクされたプル要求の詳細なリストについては、changelog.mdを参照してください。最近の変更に関する詳細情報については、release_notes.mdを参照してください。
製油所はテールベースのサンプリングプロキシであり、トレース全体のレベルで動作します。製油所は痕跡全体を調べ、各トレースにサンプリングの決定をインテリジェントに適用します。これらの決定は、サンプリングされたデータをHoneycombに転送したサンプリングデータに保持するかドロップするかを決定します。
テールベースのサンプリングモデルを使用すると、一度にトレース全体を検査し、その内容に基づいてサンプルを決定することができます。たとえば、データには、リクエストに役立つHTTPステータスコードを含むルートスパンと、データがキャッシュから提供されたかどうかに関する情報を含む別のスパンがあります。製油所を使用すると、 500ステータスコードがあり、キャッシュからも提供されたトレースのみを選択できます。
精製所はいくつかの種類のテールサンプリングをサポートします：
http.status_codeに基づいてキーを使用すると、サンプリングされたデータに含めることができます。2xxを返すリクエストの1,000トレースに1つ4xx返すリクエストの10トレースに1つ5xxを返すすべてのリクエスト精製所を使用すると、上記のすべての手法を組み合わせて、目的のサンプリング動作を実現できます。
製油所は、すべての痕跡が到達できるインフラストラクチャ内に座るように設計されています。製油所は、スタンドアロンを実行したり、別のロードバランサーを介してアクセス可能な2つ以上の製油所プロセスのクラスターに展開できます。
製油所のプロセスは、単一のサーバーにトレースを集中させるために互いに通信できる必要があります。
アプリケーション（または他のハニカムイベントソース）内で、 API Host http(s)://load-balancer/に設定します。 APIキー、データセット名など、他のすべては同じままです。
すべての製油所インスタンスには最小限のものが必要です。
linux/amd64またはlinux/arm64オペレーティングシステム多くの場合、製油所には1つのノードのみが必要です。大量のトラフィックを経験している場合は、複数のノードにスケーリングする必要があり、スケーリングを処理するために小さなRedisインスタンスが必要になる場合があります。
最初のセットアップ後にRAMの量とコア数を増やすことをお勧めします。追加のRAMとCPUは、構成値を増やすことで使用できます。特に、 CacheCapacityは重要な構成値です。製油所のStress Reliefシステムは、硬質製油所がどの程度機能しているか、そして呼び出されたときに、ストレスを軽減するために増加すべき精製所構成値の名前をログ（ reasonとして）の適切な兆候を提供します。詳細については、スケーリングとトラブルシューティングのドキュメントを使用してください。
製油所は、ハニカムヘルムリポジトリのヘルムチャートとして入手できます。
次のコマンドを使用して精製所をインストールできます。これは、デフォルト値ファイルを使用します。
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryまたは、独自のカスタム値ファイルを提供します。
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml WHERE /path/to/refinery-values.yamlはファイルのパスです。
クラスターで操作する場合、製油所はすべてのスパンをトレースで1つのインスタンスに集めて、トレースの決定を下すことを期待しています。各スパンは独立して到着するため、各精製所のインスタンスは、トレースを正しいインスタンスに分配するために、すべてのピアと通信できる必要があります。
この通信は、構成ファイルのピアの明示的なリストを介して、または共有Redisキャッシュを介して自己登録を使用して、2つの方法で管理できます。通常、インストールはRedisを使用することを好むはずです。大規模なインストールであっても、Redisサーバーの負荷は非常に軽いため、各インスタンスは1分あたり数件のリクエストしかありません。分数CPUを備えた単一のRedisインスタンスでは、通常十分です。
構成は、精製所の2つの構成ファイルによって制御されます。これは、一般的に一般的な構成とrules.yamlのconfig.yamlと呼ばれます。これらのファイルは、アクセス可能なファイルシステムからロードするか、URLからの認証されていないGETリクエストをロードすることができます。
config.yamlおよび製油所構成ドキュメントで精製所の操作を制御するすべてのパラメーターの詳細をご覧ください。
リファイナリーサンプリング方法のドキュメントで、 rules.yamlとサンプラーの構成の詳細をご覧ください。
複数の構成ソースを指定することは有効です。たとえば、共通の構成ファイルに加えて、キーのみを含む個別のファイルを持つことができます。コマンドラインで、コマンドラインスイッチを繰り返して複数のファイルを指定します。環境変数では、コンマで複数の構成場所を分離します。
製油所は、典型的なLinuxスタイルのコマンドラインアプリケーションであり、いくつかのコマンドラインスイッチをサポートしています。
refinery -hすべてのコマンドラインオプションとサポートされている環境変数をリストする拡張ヘルプテキストを印刷します。
製油所は、次の主要な環境変数をサポートしています。完全なリストについては、コマンドラインヘルプまたはオンラインドキュメントをご覧ください。コマンドラインスイッチはファイルの構成よりも優先され、環境変数は両方よりも優先されます。
| 環境変数 | 構成フィールド |
|---|---|
REFINERY_GRPC_LISTEN_ADDRESS | GRPCListenAddr |
REFINERY_REDIS_HOST | PeerManagement.RedisHost |
REFINERY_REDIS_USERNAME | PeerManagement.RedisUsername |
REFINERY_REDIS_PASSWORD | PeerManagement.RedisPassword |
REFINERY_HONEYCOMB_API_KEY | HoneycombLogger.LoggerAPIKey |
REFINERY_HONEYCOMB_METRICS_API_KEY | LegacyMetrics.APIKey |
REFINERY_HONEYCOMB_API_KEY | LegacyMetrics.APIKey |
REFINERY_QUERY_AUTH_TOKEN | QueryAuthToken |
注： REFINERY_HONEYCOMB_METRICS_API_KEY 、 LegacyMetrics.APIKey構成のREFINERY_HONEYCOMB_API_KEYよりも優先されます。
Honeycombにデータを送信するには、APIキーをテレメトリに添付する必要があります。 Telemetryの管理を容易にするために、RefineryはReceiveKeysおよびSendKey Configオプションをサポートし、 AcceptOnlyListedKeysとSendKeyModeをサポートします。さまざまな組み合わせで、彼らは多くの表現力を持っています。これらのパラメーターを設定する方法の詳細については、構成ドキュメントを参照してください。
特定のシナリオのクイックスタートは以下にあります。
SendKey有効なハニカムキーに設定しますSendKeyMode allに設定しますSendKey有効なハニカムキーに設定しますSendKeyMode nonblankに設定しますReceiveKeys例外のリストに設定しますSendKey有効なハニカムキーに設定しますSendKeyMode unlistedに設定しますSendKey有効なハニカムキーに設定しますSendKeyMode missingonlyに設定しますReceiveKeysに追加しますAcceptOnlyListedKeys trueに設定しますSendKey有効なハニカムキーに設定しますSendKeyMode listedonlyに設定しますAcceptOnlyListedKeys falseに設定しますReceiveKeysを設定しますSendKey有効なハニカムキーに設定しますSendKeyMode listedonlyに設定します+ note + +クラシックAPIキーを備えたビーラインを使用して精製所にデータを送信する場合、 SendKey環境とサービス（E＆S）キーではなく、古典的なキーであることを確認してください。
製油所を開始するとき、またはサンプリングルールを更新するとき、トラフィックの削除を開始する前にルールが予想どおりに機能していることを確認することが役立つ場合があります。これを行うには、製油所でドライランモードを使用してください。
構成ファイル（ config.yaml ）にDryRun = trueを追加して、ドライランモードを有効にします。次に、Honeycomb UIのクエリビルダーを使用してクエリを実行して結果を確認し、ルールが意図したとおりに機能していることを確認します。
ドライランモードが有効になっている場合、Metric trace_send_kept各TRACEの増加になり、 trace_send_droppedのメトリックは0ままです。
製油所は、境界のあるキューと円形バッファーを使用して割り当てされたトレースを管理するため、大量のメモリ使用でも劇的に拡大することはありません。ただし、トレースが円形のバッファーに保存されていることを考えると、トレースのスループットがバッファーのサイズを超えると、事態はうまくいき始めます。統計が構成されている場合、これが発生するたびにcollect_cache_buffer_overrunという名前のカウンターが増加します。これの症状は、痕跡が一緒に蓄積されるのを止め、代わりに同じトレースの一部であるべきであることが2つの別々の痕跡として扱われることです。すべてのトレースは引き続き送信されます（およびサンプリングされます）が、不完全なデータでいくつかのサンプリング決定が行われます。円形バッファーのサイズは、 CacheCapacityという名前の構成オプションです。適切な値を選択するには、トレースのスループット（トレース /秒が始まった）を検討し、トレースの最大持続時間（3秒など）を掛けてから、大型バッファー（おそらく10x）を掛けてください。 。この見積もりは、良いヘッドルームを与えます。
クラスターで必要なマシンの数を決定することは正確な科学ではなく、バッファオーバーランを監視することに最も影響を受けるものです。しかし、大まかなヒューリスティックの場合、約2GBのメモリを使用して5,000の入っているイベントを処理し、500秒のサブ秒トレースを1秒間追跡します（1秒未満と平均サイズがトレースあたり10スパンの平均サイズごとに）トレースを追跡します） 。
製油所は、重い負荷の下での安定性を改善するStress Reliefと呼ばれるメカニズムを提供します。 stress_levelメトリックは、キューのサイズとメモリ使用に関するいくつかの精製メトリックから構築された0〜100のスケールの合成メトリックです。通常の操作では、その値は通常1桁になるはずです。交通量が多いときに、ストレスレベルが忍び寄ってから、ボリュームが低下すると再び低下する可能性があります。 100に近づくと、精製所が故障し始め、おそらくクラッシュする可能性がますますあります。
Stress Reliefは、ストレスが安定性の危険になるとstress_levelメトリックを監視し、負荷を落とすことができるシステムです。 ActivationLevelに到達すると、 Stress Reliefモードがアクティブになります。この状態。精製所は、残りのトレースを保存したり、ルール条件を評価することなく、 TraceIDに基づいて各スパンを決定的にサンプリングします。 Stress Relief構成で指定された非DeactivationLevelを下回るまで、アクティブのままになります。
ストレス緩和の設定は次のとおりです。
Mode - Stress Reliefがどのように使用されるかを示す設定。 Stress Relief活性化されないことを示すことnever 。 monitor ActivationLevelがアクティブ化されたときにStress Relief活性化され、到達したときに非アクティブになることを意味します。 always Stress Reliefモードが継続的に関与することを意味します。 alwaysモードは、緊急事態で使用することを目的としています。ActivationLevelストレスレベルがこのしきい値を超えて上昇すると、製油所はStress Relief活性化します。DeactivationLevel - ストレスレベルがこのしきい値を下回ると、精製所はStress Relief無効にします。SamplingRate Stress Reliefがアクティブになっている間に精製所がサンプルする速度。 stress_levelは現在、製油所の全体的な負荷に最適なプロキシです。 Stress Reliefがアクティブでなくても、 stress_level頻繁に50を超える場合、精製業者はより多くのリソース、より多くのCPU、より多くのメモリ、またはより多くのノードを必要とすることを示す良い指標です。一方、 stress_level 2桁にならない場合、製油所が過剰に生成されている可能性があります。
精製所は、プロセスの健康に関する何らかの兆候を示すために、多くのメトリックを発します。これらのメトリックは、通常はオープンテレメトリを使用してハニカムに送信する必要があり、プロメテウスにもさらされる可能性があります。見るべき興味深いものは次のとおりです。
[incoming|peer]_router_* ：スパン（トレース情報があります）とスパン（トレース情報はありません）が受け入れられており、ピアに何回送られますか？collect_cache_buffer_overrun ：これはゼロのままです。正の値は、製油所の円形トレースバッファーのサイズを拡大する必要性を示しています（構成のCacheCapacityを介して）。process_uptime_seconds ：各プロセスの稼働時間を記録します。メモリの制約に向けたキーとして、予期しない再起動を探します。 warnのデフォルトのロギングレベルはかなり静かです。 debugレベルは、生産に使用するにはあまりにも多くのデータを放出しますが、トレースの決定情報を含むプロダクション前環境に優れた情報が含まれています。 infoどこかにあります。最初の構成中にロギングレベルをdebugように設定すると、何が機能しているのか、何が機能していないかを理解するのに役立ちますが、トラフィック量が増加すると、 warnまたはerrorさえ設定する必要があります。ログは、stdoutまたはhoneycombに送信できます。
製油所は、起動時または構成がリロードされたときに構成を検証し、問題について診断を発します。スタートアップでは、開始を拒否します。リロードでは、既存の構成は変更されません。
製油所ホストにアクセスできるサーバー上のコマンドラインの/queryポイントのいずれかを使用して、ロードされた構成を確認します。
/queryエンドポイントは保護されており、構成ファイルでQueryAuthToken指定するか、環境でREFINERY_QUERY_AUTH_TOKEN指定することで有効にできます。任意の/queryエンドポイントへのすべての要求には、指定されたトークンの値に設定されたヘッダーX-Honeycomb-Refinery-Queryを含める必要があります。
ファイルベースの構成（現在サポートされている唯一のタイプ）の場合、 hash値は、指定された構成ファイルのmd5sumコマンドによって生成された値と同一です。
これらすべてのコマンドについて：
$REFINERY_HOST製油所のURLでなければなりません。$FORMAT 、 yaml 、 toml 、またはjsonの1つです。$DATASET確認するデータセットの名前です。ルール全体の構成を取得するには：
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
精製所が指定されたデータセットに使用するルールセットを取得するには、サンプラータイプのマップとしてルールセットに返されます。
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
構成が最後にロードされたときのタイムスタンプを含む、現在使用されている構成に関する情報を取得するには。
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
製油所は、行われたサンプリングの決定をデバッグするのに役立つ情報を含むテレメトリーを送信できます。 [構成ファイル]で有効にするには、 AddRuleReasonToTrace trueに設定します。これにより、Honeycombに送られた痕跡がフィールドmeta.refinery.reasonを含むトレースを引き起こします。
製油所は、トレースやサンプリングの決定をディスクにバッファリングしていません。プロセスを再起動すると、すべての飛行中のトレースがフラッシュされます（ハニカムに上流に送信されます）が、過去のトレースの決定の記録が失われます。バックアップを開始すると、きれいなスレートから始まります。
各ディレクトリ内で、インターフェイス依存関係エクスポートはディレクトリと同じ名前のファイルにあり、その後（ほとんどの場合）他の各ファイルはそのインターフェイスの代替実装です。たとえば、 loggerでは、 /logger/logger.go logger/honeycomb.goには、ログをHoneycombに送信するloggerインターフェイスの実装が含まれています。
main.goアプリをセットアップし、使用する依存関係実装のバージョン（どのLogger、どのサンプラーなど）を使用するかを選択して、すべてを起動してからAppを起動します。
app/app.goメインコントロールポイントです。 Start関数が終了すると、プログラムはシャットダウンします。着信イベントを聴く2つのRouterを起動します。
route/route.go着信トラフィックのネットワーク上に耳を傾けます。 2つのルーターが実行されており、さまざまな種類のトラフィックを処理します。外の世界（ incomingルーター）からのイベントと、製油所クラスターの別のメンバー（ peerトラフィック）からのイベントです。イベントを取得したら、次にどこに行くべきかを決定します。この着信リクエストはイベント（またはイベントのバッチ）であり、もしそうなら、トレースIDがありますか？イベントではないものはすべて、トレースIDを持たないイベントではなく、すぐにtransmissionに渡され、ハニカムに転送されます。トレースIDを備えたイベントの場合、ルーターはトレースIDを抽出し、 sharderを使用して、このトレースを処理する精製クラスターのメンバーを決定します。それがピアの場合、イベントはそのピアに転送されます。それが私たちの場合、イベントは内部表現に変換され、 collectorに手渡されてトレースにスパンをバンドルします。
collect/collect.goコレクターは、スパンをトレースにまとめ、いつハニカムに送信するか、またはドロップする必要があるかどうかを決定する責任があります。トレースIDが初めて見られたとき、コレクターはタイマーを起動します。トレースIDと親IDがないスパンであるルートスパンが、タイマーが期限切れになる前に到着する場合、トレースは完全であると見なされます。トレースが送信され、タイマーがキャンセルされます。ルートスパンが到着する前にタイマーが期限切れになった場合、それが完了したかどうかにかかわらず、トレースが送信されます。送信する直前に、コレクターはsamplerにサンプルレートとトレースを維持するかどうかを要求します。コレクターは、このサンプリングの決定に従い、それを記録します（レコードは、決定が下された後、トレースの一部として提供される可能性のあるスパンに適用されます）。サンプリングの決定を下した後、トレースを保持する場合、実際の送信のためにtransmissionに渡されます。
transmit/transmit.go HttpのHonecomb APIとの相互作用に関するラッパーです。バッチイベントを一緒に処理し、上流に送信します。
loggerとmetrics 、製油所自体が生成するログとメトリックを管理するためのものです。
samplerは、提供されたトレースに基づいてサンプルレートを計算するアルゴリズムが含まれています。
sharderクラスター化された製油所構成のどのピアが個々のトレースを処理するかを決定します。
typesパッケージ間でデータを渡すために使用されるいくつかのタイプ定義が含まれています。
