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包含一些类型的定义，这些定义用于在软件包之间将数据递给数据。
