refinery
v2.8.4
有關在每個版本中合併的鏈接拉請請求的詳細列表，請參見ChangElog.md。有關最近更改的更多可讀信息，請參見Release_notes.md。
煉油廠是一個基於尾部的採樣代理，並且在整個痕蹟的水平上運行。煉油廠檢查整個痕跡，並智能地將採樣決定應用於每個跡線。這些決定決定了是否將痕量數據保留在轉發給蜂窩的採樣數據中。
基於尾巴的採樣模型使您可以一次檢查整個痕跡，並根據其內容進行採樣決定。例如，您的數據可能具有包含用於請求的HTTP狀態代碼的根跨度，另一個範圍包含有關是否從緩存提供數據的信息。使用煉油廠，您可以選擇僅保留具有500狀態代碼的軌跡，並且還可以從緩存中提供。
煉油廠支持幾種尾巴採樣：
http.status_code的鍵，您可以在採樣數據中包含：2xx的請求4xx請求中，每10個踪跡中有一個5xx的請求煉油廠允許您結合上述所有技術以實現所需的採樣行為。
煉油廠旨在坐在您的基礎設施中，所有痕跡都可以到達它。煉油廠可以獨立運行或部署在兩個或多個煉油廠過程的集群中，可以通過單獨的負載平衡器訪問。
煉油廠過程必須能夠相互通信，以將軌跡集中在單個服務器上。
在您的應用程序（或其他HoneyComb事件源）中，您將API Host配置為http(s)://load-balancer/ 。其他所有內容都保持不變，例如API密鑰，數據集名稱等，因為與原始客戶端一起生活。
每個煉油廠實例都應具有至少：
linux/amd64或linux/arm64操作系統在許多情況下，煉油廠只需要一個節點。如果經歷大量流量，則可能需要擴展到多個節點，並且可能需要一個小的Redis實例來處理縮放。
我們建議在初始設置後增加RAM的數量和核心數量。可以通過增加配置值來使用其他RAM和CPU；特別是， CacheCapacity是重要的配置值。煉油廠的Stress Relief系統很好地表明了煉油廠的工作方式，並在調用時（作為reason ）將煉油廠配置值的名稱（應增加）增加以減輕壓力。使用我們的縮放和故障排除文檔來了解更多信息。
煉油廠可作為HoneyComb Helm存儲庫中的舵圖。
您可以使用以下命令安裝煉油廠，該命令使用默認值文件：
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其中/path/to/refinery-values.yaml是文件的路徑。
當在集群中操作時，煉油廠希望將痕跡中的所有跨度收集到一個實例上，以便可以做出跟踪決策。由於每個跨度都獨立到達，因此每個煉油廠實例都需要能夠與其所有同行進行通信，以便將跟踪分配到正確的實例。
可以通過兩種方式管理此通信：通過配置文件中的同行的明確列表，或通過共享的REDIS緩存使用自我註冊。裝置通常應該更喜歡使用Redis。即使在大型安裝中，Redis服務器上的負載也很輕，每個實例每分鐘只提出幾個請求。具有分數CPU的單個REDIS實例通常就足夠了。
配置由煉油廠的兩個配置文件控制，通常稱為config.yaml用於一般配置和rules.yaml 。這些文件可以從可訪問的文件系統中加載，也可以加載未經身份驗證的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優先於REFINERY_HONEYCOMB_API_KEY for LegacyMetrics.APIKey配置。
將數據發送到蜂窩需要將API密鑰附加到遙測中。為了使管理遙測變得更加容易，精煉廠支持ReceiveKeys和SendKey配置選項以及AcceptOnlyListedKeys和SendKeyMode 。在各種組合中，它們具有很大的表現力。請參閱配置文檔，以獲取有關如何設置這些參數的詳細信息。
以下特定方案的快速啟動：
SendKey設置為有效的蜂窩密鑰SendKeyMode設置為allSendKey設置為有效的蜂窩密鑰SendKeyMode設置為nonblankReceiveKeys設置為例外列表SendKey設置為有效的蜂窩密鑰SendKeyMode設置為unlistedSendKey設置為有效的蜂窩密鑰SendKeyMode設置為missingonlyReceiveKeys中AcceptOnlyListedKeys設置為trueSendKey設置為有效的蜂窩密鑰SendKeyMode設置為listedonlyAcceptOnlyListedKeys設置為falseReceiveKeys設置為應更換的鍵SendKey設置為有效的蜂窩密鑰SendKeyMode設置為listedonly + Note + +將Beelines與經典API密鑰一起發送到煉油廠時，請確保SendKey也是經典密鑰，而不是環境和服務（E＆S）密鑰。
當開始使用煉油廠或更新採樣規則時，在開始降低流量之前，驗證規則是否按預期工作可能會有所幫助。為此，請在煉油廠使用乾式運行模式。
通過在配置文件（ config.yaml ）中添加DryRun = true來啟用乾式運行模式。然後，使用honeycomb UI中的查詢構建器運行查詢以檢查您的結果並驗證規則是否按預期工作。
當啟用乾式運行模式時，每個跟踪的度量trace_send_kept將增加， trace_send_dropped的指標將保留0 ，反映出我們將所有跟踪發送到蜂窩。
煉油廠使用有界的隊列和圓形緩衝區來管理分配軌跡，因此即使在大量內存儲器下，也不應大幅度擴展。但是，鑑於跡線存儲在圓形緩衝區中，當痕蹟的吞吐量超過緩衝區的大小時，情況就會開始出錯。如果您配置了統計信息，則每次發生這種情況時，都會增加一個名為collect_cache_buffer_overrun的計數器。這樣做的症狀將是痕跡將停止積累在一起，而應將其跨越相同痕蹟的一部分跨越將被視為兩個單獨的痕跡。所有跡線將繼續發送（並進行採樣），但是將在不完整的數據上做出一些抽樣決定。圓形緩衝區的大小是名為CacheCapacity的配置選項。要選擇一個良好的價值，您應該考慮跡線的吞吐量（例如，軌跡/秒開始），並將其乘以痕蹟的最大持續時間（例如3秒），然後將其乘以一些大型緩衝區（也許是10x） 。此估計將為良好的餘量提供。
確定集群中必要的機器數量不是一門精確的科學，並且最好通過觀察緩衝區超支的影響。但是對於粗糙的啟發式態，可以使用約2GB的內存來依靠單台計算機來處理5,000個傳入事件並每秒跟踪500個亞秒痕跡（對於每個完整的痕跡持續少於一秒鐘，平均大小為10跨度10跨度） 。
煉油廠提供了一種稱為Stress Relief的機制，可改善重負荷下的穩定性。 stress_level度量是一個從0到100的量表的合成指標，它是由與隊列大小和內存使用情況有關的幾個煉油廠指標構建的。在正常操作下，其值通常應為單位數字。在交通高峰期間，壓力水平可能會逐漸爬升，然後隨著音量下降而再次下降。隨著它接近100，煉油廠越來越有可能開始失敗並可能崩潰。
Stress Relief是一個系統，可以在壓力成為穩定性的危險時監視stress_level度量和脫落負載。一旦達到ActivationLevel時， Stress Relief模式將變得活躍。在這個狀態。精煉廠將根據TraceID確定每個跨度的確定性品嚐，而無需存儲其餘的跟踪或評估規則條件。 Stress Relief將保持活躍，直到應力降至配置中指定的DeactivationLevel低於。
壓力緩解設置是：
Mode - 設置以指示如何Stress Relief 。 never表明Stress Relief不會激活。 monitor表示Stress Relief時，當ActivationLevel並停用時，將激活應力。 always意味著Stress Relief模式將不斷參與。 always用於緊急情況的模式。ActivationLevel - 當應力水平上升到該閾值以上時，煉油廠將激活Stress Relief 。DeactivationLevel - 當應力水平低於此閾值時，煉油廠將停用Stress Relief 。SamplingRate - 在Stress Relief時煉油廠樣品的速度。 stress_level目前是煉油廠總體負載的最佳代理。即使Stress Relief不活躍，如果stress_level經常高於50，也是一個很好的指標，即煉油廠需要更多的資源 - 更多的CPU，更多的內存或更多節點。另一方面，如果stress_level永遠不會達到兩位數，則煉油廠可能會過度配置。
煉油廠發出了許多指標，以表明該過程的健康狀況。這些指標應發送給蜂窩，通常帶有開放的遙測，也可以暴露於普羅米修斯。有趣的觀看是：
[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之一。$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 。這將導致發送到蜂窩的踪跡包括一個字段meta.refinery.reason 。
煉油廠尚未緩衝軌跡或對磁盤進行採樣決定。重新啟動過程時，所有飛行中的跡線將被沖洗（將其上游發送到蜂窩），但是您將失去過去的跟踪決策的記錄。啟動後，它將以乾淨的板岩開始。
在每個目錄中，接口依賴項導出在文件中，名稱與目錄相同，然後（大部分）其他文件是該接口的替代實現。例如，在logger中， /logger/logger.go包含接口定義和logger/honeycomb.go包含將將日誌發送到蜂窩的logger接口的實現。
main.go設置該應用程序，並選擇要使用哪些版本的依賴項實現（例如，哪個記錄器，哪個採樣器等）啟動所有內容，然後啟動App 。
app/app.go是主要控制點。當其Start功能結束時，程序會關閉。它啟動了兩個Router S，可以聆聽來源的事件。
route/route.go在網絡上聆聽傳入流量。有兩個路由器正在運行，它們處理了不同類型的傳入流量：來自外界的事件（ incoming路由器）和來自煉油廠集群的另一個成員（ peer流量）的事件。一旦有一個事件，它就會決定下一步應該去的地方：這是該傳入請求事件（或事件批次），如果是的，它是否有跟踪ID？任何不是一個沒有跟踪ID的事件的事件都會立即交給transmission ，以轉發給HoneyComb。如果是帶有跟踪ID的事件，路由器將提取跟踪ID，然後使用sharder來確定煉油廠群集的哪個成員應處理此跟踪。如果是同行，則該事件將轉發給該同行。如果是我們，則該事件將轉變為內部表示形式，並交給collector以將跨度捆綁成痕跡。
collect/collect.go收集器負責將跨度捆綁在一起痕跡，並決定何時將它們發送到蜂窩狀或是否應該丟棄。第一次看到跟踪ID時，收集器啟動了計時器。如果根本跨度是帶有跟踪ID且沒有父ID的跨度，則在計時器到期之前到達，則將其視為完成。發送跟踪已發送，並取消計時器。如果計時器在根本跨度到達之前到期，則該定時器是否已完成，將發送跟踪。在發送之前，收集器向sampler詢問採樣率以及是否保留跟踪。收藏家遵守此抽樣決定並記錄下來（記錄適用於做出決定後可能作為痕蹟的任何跨度）。做出採樣決定後，如果要保留跟踪，則將其傳遞給transmission以進行實際發送。
transmit/transmit.go是與蜂窩API的HTTP相互作用圍繞的包裝器。它將批處理事件處理在一起，並將它們發送到上游。
logger和metrics用於管理煉油廠本身產生的日誌和指標。
sampler包含基於所提供的痕跡來計算採樣速率的算法。
sharder確定簇狀煉油廠配置中的哪個對等應處理單個跟踪。
types包含一些類型的定義，這些定義用於在軟件包之間將數據遞給數據。
