refinery
v2.8.4
Pour une liste détaillée des demandes de traction liées fusionnées dans chaque version, voir Changelog.md. Pour des informations plus lisibles sur les modifications récentes, veuillez consulter liver_notes.md.
La raffinerie est un proxy d'échantillonnage basé sur la queue et fonctionne au niveau d'une trace entière. La raffinerie examine des traces entières et applique intelligemment les décisions d'échantillonnage à chaque trace. Ces décisions déterminent l'opportunité de conserver ou de supprimer les données de trace dans les données échantillonnées transmises à Honecomb.
Un modèle d'échantillonnage basé sur la queue vous permet d'inspecter une trace entière en même temps et de prendre une décision d'échantillonner en fonction de son contenu. Par exemple, vos données peuvent avoir une portée racine qui contient le code d'état HTTP pour servir à une demande, et une autre durée qui contient des informations sur la description des données à partir d'un cache. À l'aide de la raffinerie, vous pouvez choisir de garder uniquement des traces qui avaient un code de statut 500 et ont également été servis à partir d'un cache.
Support de la raffinerie plusieurs types d'échantillonnage de queue:
http.status_code , vous pouvez inclure dans vos données échantillonnées:2xx4xx5xxLa raffinerie vous permet de combiner toutes les techniques ci-dessus pour réaliser le comportement d'échantillonnage souhaité.
La raffinerie est conçue pour siéger dans votre infrastructure où toutes les traces peuvent l'atteindre. La raffinerie peut s'exécuter autonome ou être déployée dans un groupe de deux processus de raffinerie ou plus accessibles via un équilibreur de charge séparé.
Les processus de raffinerie doivent être en mesure de communiquer entre eux pour concentrer les traces sur des serveurs uniques.
Dans votre application (ou d'autres sources d'événements en nid d'abeille), vous configureriez l' API Host pour être http(s)://load-balancer/ . Tout le reste reste le même, comme la clé API, le nom de l'ensemble de données, etc., car tout ce qui vit avec le client d'origine.
Chaque instance de raffinerie doit avoir un minimum de:
linux/amd64 ou linux/arm64Dans de nombreux cas, la raffinerie n'a besoin que d'un seul nœud. Si vous rencontrez un grand volume de trafic, vous devrez peut-être évoluer vers plusieurs nœuds et probablement besoin d'une petite instance Redis pour gérer la mise à l'échelle.
Nous vous recommandons d'augmenter la quantité de RAM et le nombre de cœurs après votre configuration initiale. RAM et CPU supplémentaires peuvent être utilisés en augmentant les valeurs de configuration; En particulier, CacheCapacity est une valeur de configuration importante. Le système Stress Relief de la raffinerie fournit une bonne indication de la dureté de la raffinerie et, lorsqu'elle est invoquée, les journaux (en reason ) du nom de la valeur de configuration de la raffinerie qui devraient être augmentés pour réduire le stress. Utilisez notre documentation de mise à l'échelle et de dépannage pour en savoir plus.
La raffinerie est disponible en tant que graphique de barre dans le référentiel de barre en nid d'abeille.
Vous pouvez installer une raffinerie avec la commande suivante, qui utilise le fichier de valeurs par défaut:
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryAlternativement, fournissez votre propre fichier de valeurs personnalisées:
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml où /path/to/refinery-values.yaml est le chemin du fichier.
Lorsque vous opérez dans un cluster, la raffinerie prévoit de rassembler toutes les portées dans une trace sur une seule instance afin qu'elle puisse prendre une décision de trace. Étant donné que chaque portée arrive indépendamment, chaque instance de raffinerie doit être en mesure de communiquer avec tous ses pairs afin de distribuer des traces à l'instance correcte.
Cette communication peut être gérée de deux manières: via une liste explicite de pairs dans le fichier de configuration, ou en utilisant l'auto-inscription via un cache Redis partagé. Les installations doivent généralement préférer utiliser Redis. Même dans les grandes installations, la charge sur le serveur Redis est assez légère, chaque instance ne faisant que quelques demandes par minute. Une seule instance redis avec CPU fractionnaire est généralement suffisante.
La configuration est contrôlée par les deux fichiers de configuration de la raffinerie, qui est généralement appelé config.yaml pour la configuration générale et rules.yaml pour la configuration d'échantillonnage. Ces fichiers peuvent être chargés à partir d'un système de fichiers accessibles ou chargé d'une demande de GET non authentifiée d'une URL.
En savoir plus sur config.yaml et tous les paramètres qui contrôlent le fonctionnement de la raffinerie dans notre documentation de configuration de raffinerie.
En savoir plus sur rules.yaml .
Il est valable de spécifier plus d'une source de configuration. Par exemple, il serait possible d'avoir un fichier de configuration commun, plus un fichier séparé contenant uniquement des touches. Sur la ligne de commande, spécifiez plusieurs fichiers en répétant le commutateur de ligne de commande. Dans les variables d'environnement, séparez plusieurs emplacements de configuration avec des virgules.
La raffinerie est une application de ligne de commande de style Linux typique et prend en charge plusieurs commutateurs de ligne de commande.
refinery -h Imprimera un texte d'aide prolongé répertoriant toutes les options de ligne de commande et les variables d'environnement prises en charge.
La raffinerie prend en charge les variables d'environnement clés suivantes; Veuillez consulter l'aide de la ligne de commande ou la documentation en ligne pour la liste complète. Les commutateurs de ligne de commande ont priorité sur la configuration du fichier, et les variables d'environnement ont priorité sur les deux.
| Variable d'environnement | Champ de configuration |
|---|---|
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 |
Remarque: REFINERY_HONEYCOMB_METRICS_API_KEY a priorité sur REFINERY_HONEYCOMB_API_KEY pour la configuration LegacyMetrics.APIKey .
L'envoi de données à Honeycomb nécessite d'attacher une clé API à la télémétrie. Afin de faciliter la gestion de la télémétrie, la raffinerie prend en charge les options de configuration ReceiveKeys et SendKey , ainsi que AcceptOnlyListedKeys et SendKeyMode . Dans diverses combinaisons, ils ont beaucoup de pouvoir expressif. Veuillez consulter la documentation de configuration pour plus de détails sur la façon de définir ces paramètres.
Un démarrage rapide pour des scénarios spécifiques est ci-dessous:
SendKey à une clé en nid d'abeille valideSendKeyMode à allSendKey à une clé en nid d'abeille valideSendKeyMode à nonblankReceiveKeys sur la liste des exceptionsSendKey à une clé en nid d'abeille valideSendKeyMode sur unlistedSendKey à une clé en nid d'abeille valideSendKeyMode à missingonlyReceiveKeysAcceptOnlyListedKeys sur trueSendKey à une clé en nid d'abeille valideSendKeyMode sur listedonlyAcceptOnlyListedKeys en falseReceiveKeys des touches qui doivent être remplacéesSendKey à une clé en nid d'abeille valideSendKeyMode sur listedonly + Remarque + + Lorsque vous utilisez des beylines avec une clé API classique pour envoyer des données à la raffinerie, assurez-vous que le SendKey est également une clé classique, pas une clé d'environnement et de service (E&S).
Lorsque vous commencez avec la raffinerie ou lors de la mise à jour des règles d'échantillonnage, il peut être utile de vérifier que les règles fonctionnent comme prévu avant de commencer à abandonner le trafic. Pour ce faire, utilisez le mode de course à sec dans la raffinerie.
Activez le mode Dry Run en ajoutant DryRun = true dans votre fichier de configuration ( config.yaml ). Ensuite, utilisez Query Builder dans l'interface utilisateur en nid d'abeille pour exécuter les requêtes pour vérifier vos résultats et vérifier que les règles fonctionnent comme prévu.
Lorsque le mode d'exécution à sec est activé, la métrique trace_send_kept augmentera pour chaque trace, et la métrique pour trace_send_dropped restera 0 , reflétant que nous envoyons toutes les traces à Honeycomb.
La raffinerie utilise des files d'attente limitées et des tampons circulaires pour gérer les traces d'allocation, donc même sous l'utilisation de la mémoire à haut volume ne devrait pas se développer considérablement. Cependant, étant donné que les traces sont stockées dans un tampon circulaire, lorsque le débit des traces dépasse la taille du tampon, les choses commenceront à mal tourner. Si vous avez des statistiques configurées, un compteur nommé collect_cache_buffer_overrun sera incrémenté à chaque fois que cela se produit. Les symptômes de cela seront que les traces cesseront de s'accumuler ensemble, et à la place, qui devrait faire partie de la même trace sera traitée comme deux traces distinctes. Toutes les traces continueront d'être envoyées (et échantillonnées), mais certaines décisions d'échantillonnage seront prises sur des données incomplètes. La taille du tampon circulaire est une option de configuration nommée CacheCapacity . Pour choisir une bonne valeur, vous devriez considérer le débit des traces (par exemple, les traces / secondes démarrées) et multiplier cela par la durée maximale d'une trace (comme 3 secondes), puis multiplier cela par un grand tampon (peut-être 10x) . Cette estimation donnera une bonne marge de pointe.
La détermination du nombre de machines nécessaires dans le cluster n'est pas une science exacte et est mieux influencée par la surveillance des dépassements de tampons. Mais pour une heuristique rugueuse, comptez sur une seule machine en utilisant environ 2 Go de mémoire pour gérer 5 000 événements entrants et suivre 500 traces de sous-seconde par seconde (pour chaque trace complète de moins d'une seconde et une taille moyenne de 10 portées par trace) .
La raffinerie offre un mécanisme appelé Stress Relief qui améliore la stabilité sous une charge lourde. La métrique stress_level est une métrique synthétique sur une échelle de 0 à 100 qui est construite à partir de plusieurs métriques de raffinerie relatives aux tailles de file d'attente et à l'utilisation de la mémoire. En fonctionnement normal, sa valeur doit généralement être dans les chiffres. Pendant les rafales de trafic élevé, les niveaux de stress pourraient se remonter à la hausse puis baisser à mesure que le volume baisse. À l'approche de 100, il est de plus en plus probable que la raffinerie commencera à échouer et éventuellement à planter.
Stress Relief est un système qui peut surveiller la métrique stress_level et la charge de la perte lorsque le stress devient un danger pour la stabilité. Une fois le ActivationLevel atteint, le mode Stress Relief deviendra actif. Dans cet état. La raffinerie échantillonnera de manière déterministe chaque portée en fonction de TraceID sans avoir à stocker le reste de la trace ou d'évaluer les conditions de règle. Stress Relief restera actif jusqu'à ce que le stress tombe en dessous du DeactivationLevel spécifié dans la configuration.
Les paramètres de soulagement du stress sont:
Mode - Réglage pour indiquer comment Stress Relief est utilisé. n'indique never que Stress Relief ne s'activera pas. monitor signifie que Stress Relief s'activera lorsque le ActivationLevel et désactivera lorsque le est atteint. signifie always que le mode Stress Relief sera en continu. Le mode always est destiné à être utilisé dans les situations d'urgence.ActivationLevel - Lorsque le niveau de contrainte s'élève au-dessus de ce seuil, la raffinerie activera Stress Relief .DeactivationLevel - Lorsque le niveau de contrainte tombe en dessous de ce seuil, la raffinerie désactivera Stress Relief .SamplingRate - La vitesse à laquelle la raffinerie échantillonne pendant que Stress Relief est actif. Le stress_level est actuellement le meilleur indicateur de la charge globale sur la raffinerie. Même si Stress Relief n'est pas actif, si stress_level est souvent supérieur à 50, c'est un bon indicateur que la raffinerie a besoin de plus de ressources - plus de processeurs, plus de mémoire ou plus de nœuds. D'un autre côté, si stress_level ne passe jamais à deux chiffres, il est probable que la raffinerie soit surévaluée.
La raffinerie émet un certain nombre de mesures pour donner une indication sur la santé du processus. Ces mesures doivent être envoyées au nid d'abeille, généralement avec une télémétrie ouverte, et peuvent également être exposées à Prometheus. Les intéressants à regarder sont:
[incoming|peer]_router_* : Combien d'événements (pas d'informations sur trace) par rapport aux étendues de trace) ont été acceptées, et combien envoyés à des pairs?collect_cache_buffer_overrun : cela devrait rester zéro; Une valeur positive indique la nécessité de développer la taille du tampon de trace circulaire de la raffinerie (via CacheCapacity de configuration).process_uptime_seconds : enregistre le temps de disponibilité de chaque processus; Recherchez des redémarrages inattendus comme clé des contraintes de mémoire. Le niveau d'exploitation de warn par défaut est assez silencieux. Le niveau debug émet trop de données à utiliser dans la production, mais contient d'excellentes informations dans un environnement de pré-production, y compris les informations de décision de trace. info sont quelque part entre. La définition du niveau de journalisation pour debug pendant la configuration initiale aidera à comprendre ce qui fonctionne et ce qui ne fonctionne pas, mais lorsque les volumes de trafic augmentent, il devrait être défini pour warn ou même error . Les journaux peuvent être envoyés à STDOUT ou à Honecomb.
La raffinerie valide sa configuration au démarrage ou lorsqu'une configuration est rechargée, et il émet des diagnostics pour tout problème. Au démarrage, il refusera de commencer; En rechargement, il ne modifiera pas la configuration existante.
Vérifiez la configuration chargée en utilisant l'un des points de terminaison /query de la ligne de commande sur un serveur qui peut accéder à un hôte de raffinerie.
Les points de terminaison /query sont protégés et peuvent être activés en spécifiant QueryAuthToken dans le fichier de configuration ou en spécifiant REFINERY_QUERY_AUTH_TOKEN dans l'environnement. Toutes les demandes au point de terminaison de n'importe quel /query doivent inclure l'en-tête X-Honeycomb-Refinery-Query définie sur la valeur du jeton spécifié.
Pour les configurations basées sur des fichiers (le seul type actuellement pris en charge), la valeur hash est identique à la valeur générée par la commande md5sum pour le fichier de configuration donné.
Pour toutes ces commandes:
$REFINERY_HOST devrait être l'URL de votre raffinerie.$FORMAT peut être l'un des yaml , toml ou json .$DATASET est le nom de l'ensemble de données que vous souhaitez vérifier.Pour récupérer l'intégralité de la configuration des règles:
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
Pour récupérer l'ensemble de règles que la raffinerie utilise pour l'ensemble de données spécifié, qui sera renvoyé comme carte du type d'échantillonneur à son ensemble de règles:
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
Pour récupérer des informations sur les configurations actuellement utilisées, y compris l'horodatage lorsque la configuration a été chargée pour la dernière fois:
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
La raffinerie peut envoyer une télémétrie qui comprend des informations qui peuvent aider à déboguer les décisions d'échantillonnage prises. Pour activer, dans le fichier de configuration, définissez AddRuleReasonToTrace sur true . Cela provoquera des traces envoyées à Honeycomb pour inclure un champ meta.refinery.reason , qui contiendra du texte indiquant quelle règle a été évaluée qui a provoqué l'inclusion de la trace.
La raffinerie ne tamponne pas encore les traces ni les décisions d'échantillonnage au disque. Lorsque vous redémarrez le processus, toutes les traces en vol seront rincées (envoyées en amont en nid d'abeilles), mais vous perdrez le record des décisions de trace passées. Lorsqu'il a été recommencé, il commencera par une ardoise propre.
Dans chaque répertoire, l'interface que la dépendance exporte est dans le fichier avec le même nom que le répertoire, puis (pour la plupart) chacun des autres fichiers sont des implémentations alternatives de cette interface. Par exemple, dans logger , /logger/logger.go contient la définition de l'interface et logger/honeycomb.go contient l'implémentation de l'interface logger qui enverra des journaux à Honeycomb.
main.go configure l'application et fait des choix sur les versions des implémentations de dépendance à utiliser (par exemple quel logger, quel échantillonneur, etc.) il démarre tout, puis lance App .
app/app.go est le principal point de contrôle. Lorsque sa fonction Start se termine, le programme s'arrête. Il lance deux Router qui écoutent les événements entrants.
route/route.go écoute le réseau pour le trafic entrant. Il y a deux routeurs en cours d'exécution et ils gèrent différents types de trafic entrant: les événements provenant du monde extérieur (le routeur incoming ) et des événements provenant d'un autre membre du cluster de raffinerie (trafic peer ). Une fois qu'il a obtenu un événement, il décide où il devrait aller ensuite: cette demande entrante est-elle un événement (ou un lot d'événements), et si oui, a-t-il un ID de trace? Tout ce qui n'est pas un événement ou un événement qui n'a pas d'identification de trace est immédiatement transmis à transmission pour être transmis à Honeycomb. S'il s'agit d'un événement avec un ID de trace, le routeur extrait l'ID de trace, puis utilise le sharder pour décider quel membre du cluster de raffinerie doit gérer cette trace. S'il s'agit d'un pair, l'événement sera transmis à ce pair. S'il est nous, l'événement sera transformé en une représentation interne et remis au collector en éventail en traces.
collect/collect.go Le collectionneur est responsable de l'effondrement des étendues ensemble en traces et décidant du moment de les envoyer à Honeycomb ou s'ils doivent être abandonnés. La première fois qu'un ID de trace est vu, le collecteur démarre une minuterie. Si la portée racine, qui est une portée avec un ID de trace et sans ID parent, arrive avant l'expiration du minuteur, la trace est considérée comme complète. La trace est envoyée et la minuterie est annulée. Si la minuterie expire avant l'arrivée de la portée racine, la trace sera envoyée si elle est complète ou non. Juste avant l'envoi, le collecteur demande à l' sampler un taux d'échantillonnage et de maintenir ou non la trace. Le collecteur obéit à cette décision d'échantillonnage et l'enregistre (le dossier est appliqué à toute portée qui pourrait faire partie de la trace après la décision de la décision). Après avoir pris la décision d'échantillonnage, si la trace doit être maintenue, elle est transmise à la transmission pour l'envoi réel.
transmit/transmit.go est un emballage autour des interactions HTTP avec l'API Honeycomb. Il gère les événements par lots et les envoie en amont.
logger et metrics sont destinés à gérer les journaux et les métriques que la raffinerie elle-même produit.
sampler contient des algorithmes pour calculer les fréquences d'échantillonnage en fonction des traces fournies.
sharder détermine quel pair dans une configuration de raffinerie en cluster est censé gérer une trace individuelle.
types contient quelques définitions de types qui sont utilisées pour remettre des données entre les packages.
