refinery
v2.8.4
Eine detaillierte Liste der verknüpften Pull -Anfragen, die in jeder Version verschmolzen sind, siehe ChangeLog.md. Weitere lesbare Informationen zu aktuellen Änderungen finden Sie unter Release_Notes.md.
Raffinerie ist ein schwanzbasiertes Stichprobenproxy und arbeitet auf der Ebene einer gesamten Spur. Raffinerie untersucht ganze Spuren und wendet intelligent Stichprobenentscheidungen auf jede Spur an. Diese Entscheidungen bestimmen, ob die Trace -Daten in den an die Wabe weitergeleiteten Abtastdaten aufbewahrt oder fallen sollen.
Mit einem schwanzbasierten Stichprobenmodell können Sie eine gesamte Spur gleichzeitig inspizieren und sich entscheiden, basierend auf dem Inhalt zu probieren. Beispielsweise können Ihre Daten eine Stammspanne haben, die den HTTP -Statuscode enthält, der für eine Anfrage dient, und eine andere Spanne, die Informationen darüber enthält, ob die Daten aus einem Cache bedient wurden. Mit Raffinerie können Sie nur Spuren mit einem Statuscode 500 aufbewahren und auch aus einem Cache bedient wurden.
Raffinerieunterstützung verschiedene Arten von Schwanzprobene:
http.status_code basiert, können Sie Ihre Stichprobendaten einbeziehen:2xx zurückgeben4xx zurückgeben5xx zurückgibtMit Raffinerie können Sie alle oben genannten Techniken kombinieren, um Ihr gewünschtes Stichprobenverhalten zu erreichen.
Die Raffinerie ist so konzipiert, dass sie in Ihrer Infrastruktur sitzt, wo alle Spuren sie erreichen können. Die Raffinerie kann Standalone ausführen oder in einem Cluster von zwei oder mehr Raffinerieprozessen eingesetzt werden, die über einen separaten Lastausgleich zugänglich sind.
Raffinerieprozesse müssen in der Lage sein, miteinander zu kommunizieren, um Spuren auf einzelnen Servern zu konzentrieren.
Innerhalb Ihrer Anwendung (oder anderen Waben-Ereignisquellen) konfigurieren Sie den API Host als http(s)://load-balancer/ . Alles andere bleibt gleich, wie z. B. API -Schlüssel, Datensatzname usw., seit all dem, was mit dem ursprünglichen Kunden lebt, lebt.
Jede Raffinerie -Instanz sollte ein Minimum haben:
linux/amd64 oder linux/arm64 -BetriebssystemIn vielen Fällen benötigt Raffinerie nur einen Knoten. Wenn Sie ein großes Verkehrsvolumen erleiden, müssen Sie möglicherweise auf mehrere Knoten skalieren und wahrscheinlich eine kleine Redis -Instanz benötigen, um die Skalierung zu verarbeiten.
Wir empfehlen, die Menge an RAM und die Anzahl der Kerne nach Ihrer ersten Einrichtung zu erhöhen. Zusätzliche RAM und CPU können durch Erhöhen der Konfigurationswerte verwendet werden. Insbesondere ist CacheCapacity ein wichtiger Konfigurationswert. Das Stress Relief von Refinery liefert einen guten Hinweis darauf, wie harte Raffinerie funktioniert, und leuchtet beim Aufrufen (als reason ) den Namen des Raffinerie -Konfigurationswerts an, der erhöht werden sollte, um die Stress zu verringern. Verwenden Sie unsere Skalierungs- und Fehlerbehebungsdokumentation, um mehr zu erfahren.
Die Raffinerie ist als Helm -Diagramm im Helm -Repository Helm -Helm erhältlich.
Sie können die Refinerie mit dem folgenden Befehl installieren, in dem die Standard -Wertedatei verwendet wird:
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryGeben Sie alternativ Ihre eigene Datei für benutzerdefinierte Werte an:
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml wobei /path/to/refinery-values.yaml der Pfad der Datei ist.
Bei einem Cluster erwartet Raffinerie, alle Spannweiten in einer Spur auf eine einzelne Instanz zu sammeln, damit sie eine Spurenentscheidung treffen kann. Da jede Spanne unabhängig eintrifft, muss jede Raffinerie -Instanz in der Lage sein, mit allen Kollegen zu kommunizieren, um Spuren auf die richtige Instanz zu verteilen.
Diese Kommunikation kann auf zwei Arten verwaltet werden: über eine explizite Liste von Kollegen in der Konfigurationsdatei oder durch Verwendung der Selbstregistrierung über einen gemeinsam genutzten Redis-Cache. Installationen sollten im Allgemeinen die Verwendung von Redis bevorzugen. Selbst in großen Installationen ist die Last auf dem Redis -Server ziemlich leicht, wobei jede Instanz nur einige Anfragen pro Minute darstellt. Eine einzelne Redis -Instanz mit fraktionaler CPU ist normalerweise ausreichend.
Die Konfiguration wird durch die beiden Konfigurationsdateien von Refinery gesteuert, die im Allgemeinen als config.yaml für allgemeine Konfiguration und rules.yaml bezeichnet werden. Diese Dateien können aus einem zugänglichen Dateisystem geladen oder mit einer nicht authentifizierten GET -Anforderung von einer URL geladen werden.
Erfahren Sie mehr über config.yaml und alle Parameter, die den Betrieb von Raffinerie in unserer Refinery -Konfigurationsdokumentation steuern.
Erfahren Sie mehr über rules.yaml und Sampler -Konfiguration in unserer Dokumentation der Refinery -Stichprobenmethoden.
Es ist gültig, mehr als eine Konfigurationsquelle anzugeben. Beispielsweise wäre es möglich, eine gemeinsame Konfigurationsdatei sowie eine separate Datei mit nur Schlüssel zu haben. Geben Sie in der Befehlszeile mehrere Dateien an, indem Sie den Befehlszeilenschalter wiederholen. In Umgebungsvariablen separate mehrere Konfigurationsorte mit Kommas.
Die Raffinerie ist eine typische Befehlszeilenanwendung im Linux-Stil und unterstützt mehrere Befehlszeilenschalter.
refinery -h druckt einen erweiterten Hilfegtext, der alle Befehlszeilenoptionen und unterstützten Umgebungsvariablen auflistet.
Raffinerie unterstützt die folgenden wichtigen Umgebungsvariablen. Weitere Informationen finden Sie in der Befehlszeile oder der Online -Dokumentation für die vollständige Liste. Befehlszeilenschalter haben Vorrang vor der Dateikonfiguration, und Umgebungsvariablen haben Vorrang vor beiden.
| Umgebungsvariable | Konfigurationsfeld |
|---|---|
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 |
Hinweis: REFINERY_HONEYCOMB_METRICS_API_KEY hat Vorrang vor REFINERY_HONEYCOMB_API_KEY für die LegacyMetrics.APIKey -Konfiguration.
Um Daten an Waben zu senden, muss ein API -Schlüssel an die Telemetrie angeschlossen werden. Um die Verwaltung von Telemetrie zu vereinfachen, unterstützt die ReceiveKeys und SendKey -Konfigurationsoptionen sowie AcceptOnlyListedKeys und SendKeyMode . In verschiedenen Kombinationen haben sie viel ausdrucksstarke Kraft. Weitere Informationen zum Festlegen dieser Parameter finden Sie in der Konfigurationsdokumentation.
Ein kurzer Start für bestimmte Szenarien ist unten:
SendKey auf einen gültigen WabenschlüsselSendKeyMode auf allSendKey auf einen gültigen WabenschlüsselSendKeyMode auf nonblank einReceiveKeys auf die Liste der AusnahmenSendKey auf einen gültigen WabenschlüsselSendKeyMode auf unlistedSendKey auf einen gültigen WabenschlüsselSendKeyMode auf missingonlyReceiveKeys zu erhaltenAcceptOnlyListedKeys auf trueSendKey auf einen gültigen WabenschlüsselSendKeyMode auf listedonly festAcceptOnlyListedKeys auf falseReceiveKeys auf die Schlüssel, die ersetzt werden solltenSendKey auf einen gültigen WabenschlüsselSendKeyMode auf listedonly fest + Hinweis + + Bei Verwendung von Beelines mit einem klassischen API -Schlüssel zum Senden von Daten an die Refinerie stellen Sie sicher, dass der SendKey auch ein klassischer Schlüssel ist, kein Schlüssel (E & S).
Wenn Sie mit Raffinerie beginnen oder die Stichprobenregeln aktualisieren, kann es hilfreich sein, zu überprüfen, ob die Regeln wie erwartet funktionieren, bevor Sie den Verkehr fallen lassen. Verwenden Sie dazu den Trockenlaufmodus in der Raffinerie.
Aktivieren Sie den Trockenlaufmodus durch Hinzufügen von DryRun = true in Ihrer Konfigurationsdatei ( config.yaml ). Verwenden Sie dann den Abfragebuilder in der Honeycomb -Benutzeroberfläche, um Abfragen auszuführen, um Ihre Ergebnisse zu überprüfen, und überprüfen Sie, ob die Regeln wie beabsichtigt funktionieren.
Wenn der Trockenlaufmodus aktiviert ist, erhöht der metrische trace_send_kept für jede Trace, und die Metrik für trace_send_dropped bleibt 0 , was widerspiegelt, dass wir alle Spuren an Wabe senden.
Raffinerie verwendet begrenzte Warteschlangen und kreisförmige Puffer, um Zuweisungsspuren zu verwalten. Daher sollte auch unter hohem Volumenspeicher die Verwendung nicht dramatisch erweitert werden. Angesichts der Tatsache, dass Spuren in einem kreisförmigen Puffer gespeichert werden, werden die Dinge schief gehen, wenn der Durchsatz der Spuren die Größe des Puffers überschreitet. Wenn Sie Statistiken konfiguriert haben, wird ein Zähler mit dem Namen collect_cache_buffer_overrun jedes Mal inkrementiert. Die Symptome davon werden darin bestehen, dass sich Spuren aufhören, sich gemeinsam zu sammeln, und stattdessen als zwei getrennte Spuren behandelt werden. Alle Spuren werden weiterhin gesendet (und abgetastet), einige Stichprobenentscheidungen werden jedoch an unvollständigen Daten getroffen. Die Größe des kreisförmigen Puffers ist eine Konfigurationsoption mit dem Namen CacheCapacity . Um einen guten Wert auszuwählen, sollten Sie den Durchsatz von Spuren (z. B. Spuren / Sekunde gestartet) berücksichtigen und diese mit der maximalen Dauer einer Spur (z. . Diese Schätzung ergibt einen guten Kopffreiheit.
Die Ermittlung der Anzahl der im Cluster erforderlichen Maschinen ist keine genaue Wissenschaft und wird am besten durch das Beobachten von Pufferüberschreitungen beeinflusst. Für eine grobe Heuristik zählen Sie jedoch auf eine einzelne Maschine mit etwa 2 GB Speicher, um 5.000 eingehende Ereignisse zu bewältigen und 500 Sub-Sekunden-Spuren pro Sekunde zu verfolgen (für jede volle Spur von weniger als einer Sekunde und einer durchschnittlichen Größe von 10 Spannweiten pro Spur). .
Raffinerie bietet einen Mechanismus, der als Stress Relief bezeichnet wird und die Stabilität unter starker Belastung verbessert. Die stress_level -Metrik ist eine synthetische Metrik auf einer Skala von 0 bis 100, die aus mehreren Raffinerie -Metriken im Zusammenhang mit Warteschlangengrößen und Speicherverbrauch hergestellt wird. Bei normalem Betrieb sollte sein Wert normalerweise in den einzelnen Ziffern liegen. Während des hohen Verkehrs stürmte die Spannungsstufen und sinken dann wieder, wenn die Lautstärke sinkt. Da es sich 100 nähert, ist es immer wahrscheinlicher, dass die Raffinerie scheitert und möglicherweise zum Absturz ist.
Stress Relief ist ein System, das die Belastung stress_level und Schuppen überwachen kann, wenn Stress zu einer Stabilitätsgefahr wird. Sobald der ActivationLevel erreicht ist, wird der Stress Relief aktiv. In diesem Zustand. Die Raffinerie wird jede Spanne, die auf TraceID basiert, ohne den Rest der Trace oder die Bewertung der Regelbedingungen determinalerweise abtastet. Stress Relief bleibt aktiv, bis der Stress unter die in der Konfiguration angegebene DeactivationLevel fällt.
Die Einstellungen zur Stressabbau sind:
Mode - Einstellung, um anzuzeigen, wie Stress Relief verwendet wird. Zeigt never an, dass Stress Relief nicht aktiviert wird. monitor bedeutet, dass Stress Relief aktiviert wird, wenn die ActivationLevel und deaktiviert werden, wenn der erreicht wird. always bedeutet, dass der Stress Relief kontinuierlich engagiert wird. Der always -Modus ist für die Verwendung in Notsituationen vorgesehen.ActivationLevel - Wenn der Spannungsniveau über dieser Schwelle steigt, aktiviert die Raffinerie Stress Relief .DeactivationLevel - Wenn der Spannungsniveau unter diese Schwelle fällt, deaktiviert die Raffinerie Stress Relief .SamplingRate - die Geschwindigkeit, mit der Raffinerie -Proben während der aktiven Stress Relief aktiv ist. Der stress_level ist derzeit der beste Proxy für die Gesamtbelastung der Raffinerie. Auch wenn stress_level Stress Relief nicht aktiv ist, ist es ein guter Indikator dafür, dass Raffinerie mehr Ressourcen benötigt - mehr CPUs, mehr Speicher oder mehr Knoten. Andererseits ist es wahrscheinlich, dass die Raffinerie, wenn stress_level niemals in zweistellige Ziffern geht.
Raffinerie gibt eine Reihe von Metriken aus, um einen Hinweis auf die Gesundheit des Prozesses zu geben. Diese Metriken sollten in der Regel mit offener Telemetrie an Wabe gesendet werden und können auch Prometheus ausgesetzt werden. Die interessanten zu sehen sind:
[incoming|peer]_router_* : Wie viele Ereignisse (keine Trace -Info) gegen Spans (haben Trace -Info) akzeptiert und wie viele an Kollegen gesendet?collect_cache_buffer_overrun : Dies sollte Null bleiben; Ein positiver Wert zeigt die Notwendigkeit, die Größe des kreisförmigen Spurenpuffers der Raffinerie (über CacheCapacity ) zu erweitern.process_uptime_seconds : zeichnet die Verfügbarkeit jedes Prozesses auf; Suchen Sie nach unerwarteten Neustarts als Schlüssel zu Speicherbeschränkungen. Die Standardprotokollierungsstufe der warn ist ziemlich ruhig. Die debug Ebene gibt zu viele Daten aus, um in der Produktion verwendet zu werden, enthält jedoch hervorragende Informationen in einer Vorproduktionsumgebung, einschließlich Trace-Entscheidungsinformationen. info sind irgendwo dazwischen. Das Festlegen der Protokollierungsstufe für debug während der ersten Konfiguration hilft zu verstehen, was funktioniert und was nicht, aber wenn das Verkehrsvolumina erhöht wird, sollte sie auf warn oder sogar error eingestellt werden. Protokolle können an stdout oder an Wabe gesendet werden.
Die Raffinerie bestätigt seine Konfiguration beim Start oder wenn eine Konfiguration neu geladen wird, und es wird Diagnostik für Probleme abgebildet. Beim Start wird es sich weigern, zu starten. Beim Nachladen wird die vorhandene Konfiguration nicht geändert.
Überprüfen Sie die geladene Konfiguration mithilfe eines der Endpunkte /query -Endpunkte in der Befehlszeile auf einem Server, der auf einen Raffinerie -Host zugreifen kann.
Die Endpunkte /query -Endpunkte sind geschützt und können aktiviert werden, indem QueryAuthToken in der Konfigurationsdatei angegeben oder REFINERY_QUERY_AUTH_TOKEN in der Umgebung angegeben wird. Alle Anfragen an einen beliebigen /query -Endpunkt müssen den Header X-Honeycomb-Refinery-Query enthalten, der auf den Wert des angegebenen Tokens eingestellt ist.
Für dateibasierte Konfigurationen (der einzige derzeit unterstützte Typ) ist der hash Wert mit dem von dem Befehl md5sum für die angegebenen Konfigurationsdatei generierten Wert identisch.
Für all diese Befehle:
$REFINERY_HOST sollte die URL Ihrer Raffinerie sein.$FORMAT kann eines von yaml , toml oder json sein.$DATASET ist der Name des Datensatzes, den Sie überprüfen möchten.Um die gesamte Regelnkonfiguration abzurufen:
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
Um den Regelsatz abzurufen, den Raffinerie für den angegebenen Datensatz verwendet, wird er als Karte des Samplertyps in seinen Regelsatz zurückgegeben:
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
Um Informationen über die derzeit verwendeten Konfigurationen abzurufen, einschließlich des Zeitstempels, wenn die Konfiguration zuletzt geladen wurde:
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
Raffinerie kann Telemetrie senden, die Informationen enthält, die dazu beitragen können, die getroffenen Stichprobenentscheidungen zu debuggen. Um in der Konfigurationsdatei zu aktivieren, setzen Sie AddRuleReasonToTrace auf true . Dies führt zu Spuren, die an Wabe gesendet werden, um eine meta.refinery.reason zu enthalten, die Text enthält, die angibt, welche Regel bewertet wurde, die dazu führte, dass die Spur einbezogen wurde.
Die Raffinerie puffert noch keine Spuren oder Stichprobenentscheidungen an der Festplatte. Wenn Sie den Vorgang neu starten, werden alle Spuren der Flucht gespült (stromaufwärts an Wabe gesendet), aber Sie verlieren die Aufzeichnung früherer Spurenentscheidungen. Bei der Wiederaufnahme beginnt es mit einem sauberen Schiefer.
In jedem Verzeichnis befindet sich die Schnittstelle Die Abhängigkeitsexporte befinden sich in der Datei mit demselben Namen wie im Verzeichnis und dann (zum größten Teil) sind jede der anderen Dateien alternative Implementierungen dieser Schnittstelle. In logger enthält /logger/logger.go beispielsweise die Schnittstellendefinition und logger/honeycomb.go enthält die Implementierung der logger -Schnittstelle, die Protokolle an Waitecomb sendet.
main.go richtet die App ein und entscheidet sich dafür, welche Versionen von Abhängigkeitsimplementierungen verwendet werden sollen (z. B. welchen Logger, welcher Abtaster usw.) alles startet und dann App startet.
app/app.go ist der Hauptsteuerpunkt. Wenn seine Start endet, wird das Programm abgeschaltet. Es startet zwei Router , die auf eingehende Ereignisse hören.
route/route.go hört im Netzwerk auf eingehende Verkehr zu. Es werden zwei Router ausgeführt, die verschiedene Arten des eingehenden Verkehrs erledigen: Ereignisse aus der Außenwelt (dem incoming Router) und Ereignisse, die von einem anderen Mitglied des Raffinerie -Clusters ( peer -Verkehr) stammen. Sobald es ein Ereignis erzielt hat, entscheidet es, wo es als nächstes gehen soll: Ist diese eingehende Anfrage ein Ereignis (oder eine Reihe von Ereignissen), und wenn ja, hat es eine Spuren -ID? Alles, was kein Ereignis oder ein Ereignis ist, das keine Trace -ID hat, wird sofort an transmission übergeben, die an Waben weitergeleitet werden soll. Wenn es sich um ein Ereignis mit einer Trace -ID handelt, extrahiert der Router die Trace -ID und verwendet dann den sharder um zu entscheiden, welches Mitglied des Raffinerieclusters diese Spur umgehen soll. Wenn es sich um einen Gleichaltrigen handelt, wird die Veranstaltung an diesen Kollegen weitergeleitet. Wenn wir es sind, wird das Ereignis in eine interne Darstellung umgewandelt und dem collector übergeben, um Spannweiten in Spuren zu bündeln.
collect/collect.go Das erste Mal, dass ein Spuren -ID zu sehen ist, startet der Sammler einen Timer. Wenn die Wurzelspanne, die eine Spannweite mit einer Trace -ID und ohne übergeordnete ID ist, vor Ablauf des Timers eintrifft, wird die Spur als vollständig angesehen. Die Spur wird gesendet und der Timer wird abgesagt. Wenn der Timer vor dem Eintreffen der Wurzelspanne abläuft, wird die Spur gesendet, unabhängig davon, ob er abgeschlossen ist oder nicht. Kurz vor dem Senden fragt der Kollektor den sampler nach einer Stichprobenrate und ob die Spur beibehalten oder nicht. Der Sammler folgt dieser Stichprobenentscheidung und zeichnet sie auf (die Aufzeichnung wird auf alle Spannweiten angewendet, die nach der Entscheidung der Entscheidung eingehen können). Nachdem die Stichprobenentscheidung getroffen hat, wird die Spur beibehalten, wenn sie zur transmission zum tatsächlichen Versand weitergegeben wird.
transmit/transmit.go ist ein Wrapper um die HTTP -Wechselwirkungen mit der Waben -API. Es kümmert sich zusammen zusammen und sendet sie stromaufwärts.
logger und metrics dienen zum Verwalten der Protokolle und Metriken, die die Raffinerie selbst erzeugt.
sampler enthält Algorithmen zur Berechnung der Stichprobenraten basierend auf den bereitgestellten Spuren.
sharder stellt fest, welcher Peer in einer Cluster -Raffineriekonfiguration eine individuelle Spur verarbeiten soll.
types enthalten einige Typ -Definitionen, die verwendet werden, um Daten zwischen den Paketen zu handeln.
