Beeline a Rubynak

A méhsejt Ruby Beeline gyors és egyszerű módja a Ruby alkalmazás hangszerelésének. Több opcionális burkolót tartalmaz, amelyek automatikusan HTTP-kéréseket és adatbázis-lekérdezéseket programoznak.

Ruby Beeline

Automatikus nyomon követést biztosít a dobozból, összekapcsolva az adatbázis-lekérdezéseket a HTTP-kéréssel, amelyből származnak. Bár ez egy nagyszerű módja annak, hogy a lehető leggyorsabban általános betekintést nyerjünk az alkalmazásával kapcsolatban, miközben előrelép a megfigyelhető utazás során, előfordulhat, hogy új eseményeket vagy nyomokat szeretne hozzáadni az alkalmazáshoz kapcsolódó további részletek hozzáadásához. A Ruby Beeline egyszerű interfészeket kínál mindkettő hozzáadásához.

Ha meg szeretné tekinteni a Ruby Beeline működésének példáját, próbálja ki a példákat.

Ha további lehetőségeket szeretne látni a Ruby Beeline-ben, kérjük, nyújtson be egy kérdést, vagy szavazzon egy már benyújtottra! Vegye fel velünk a kapcsolatot a [email protected] címen is.

Követelmények 🔗

  • Egy Ruby alkalmazás, lehetőleg olyan, amely HTTP kéréseket hallgat, vagy SQL hívásokat indít
  • Ruby 2.3 vagy újabb
  • Honeycomb API kulcs

API kulcsát a Csapatbeállítások oldalon találja. Ha még nincs API kulcsa, iratkozzon fel egy Honeycomb próbára.

Gyors telepítés 🔗

A Ruby Beeline telepítése az alkalmazáshoz:

Méhsejt-beeline hozzáadása a Gemfile-hez:

Ha rendelkezik sínalkalmazással, futtathatja a generátort a konfigurációs fájl létrehozásához:

Ellenkező esetben a kódban inicializálja a beeline-t az API kulcsával és az adatkészlet nevével:

Bővítse az adatokat érdekes információkkal az alkalmazásból és további kontextusokról, például hibákról, hogy gazdag információkat láthasson alkalmazásáról a Honeycomb-ban.

Adjon hozzá további fesztávolságokat, és fordítson nyomon eseménysorozatot:

Inicializálás proxykkal való használatra 🔗

Proxy használatához létre kell hoznia egy egyedi libhoney klienst, amelyet meg kell adnia a Beeline konfigurálásakor:

jegyzet: A proxy támogatás hozzáadódott a libhoney 1.14.0 verziójához.

Környezet hozzáadása az eseményekhez 🔗

A Ruby Beeline az aktuális fesztávolságot követi a teljes nyomon belül. Ez lehetővé teszi annyi további egyéni mező hozzáadását, amennyit csak akar.

Íme egy példa egy egyéni mező hozzáadására az aktuális tartományra:

További mezők kerülnek az alkalmazás alá. névtér. Például a fenti mező az app.big_num néven jelenik meg az eseményedben. A névtér csoportosítja a mezőket, hogy könnyen megtalálhatók és megvizsgálhatók legyenek.

Ha szeretné elkerülni az alkalmazást. névtér - például egy automatikusan kitöltött mező felülírása érdekében - megadhatja, hogy a blokk paraméternek vegye az aktuális tartományt, és közvetlenül az adott példányon hívja meg az add_field mezőt.

Ezek a további mezők lehetőséget nyújtanak arra, hogy fontos és részletes kontextust adjon a hangszerhez. Helyezzen egy időzítőt egy kódrész köré, adjon meg felhasználónkénti információkat, adjon meg részleteket arról, mi kellett a válasz elkészítéséhez, és így tovább. Várhatóan egyes mezők csak egyes kérések esetén lesznek jelen. A hibakezelők nagyszerű példa erre; nyilvánvalóan csak akkor léteznek, ha hiba történt.

Általános gyakorlat, hogy ezeken a mezőkön egész idő alatt hozzáadják őket, mivel ezeket a köztes szoftverek különböző szintjein dolgozzák fel. Például, ha van egy hitelesítő köztes szoftver, akkor egy mezőt ad hozzá a hitelesített felhasználó azonosítójával és nevével, amint megoldja őket. Később a hívásveremben hozzáadhat további mezőket, amelyek leírják, hogy mit próbál elérni a felhasználó ezzel a speciális HTTP-kéréssel.

Ha érdekel, hogy egyéni mezőket adjon hozzá az összes tartományhoz, használja inkább az add_field_to_trace elemet.

Az add_field_to_trace hozzáadja a mezőt az aktuálisan aktív tartományhoz és az összes többi olyan tartományhoz, amelyet még el kell küldeni, és részt vesz ebben a folyamatban előforduló nyomban. Ezenkívül ezeket a mezőket összecsomagolják és továbbadják a későbbi folyamatoknak, ha szintén bélvonalat használnak. Ez a funkció jó kontextus hozzáadásához, amely jobban körbe van sorolva a kérésben, mint ez a konkrét munkaegység, pl. felhasználói azonosítók, globálisan releváns jellemzők, hibák stb. Az itt hozzáadott mezők szintén előtaggal vannak ellátva az alkalmazással.

Fesztávolságok hozzáadása egy nyomhoz 🔗

Arra biztatjuk az embereket, hogy gondolkodjanak el a műszerezésen a „munkaegységek” szempontjából. Ahogy a programod növekszik, ami munkaegységet jelent, valószínűleg az egész szolgáltatás részei lesznek, nem pedig egy teljes futás. A szakaszok egy külső művelet (például egy HTTP-kérés) több kisebb egységre bontására szolgálnak annak érdekében, hogy minél több betekintést nyerhessünk a szolgáltatásába. Sok fesztávolság együttesen nyomot hoz létre, amelyet a Méhsejt lekérdező készítőn belül vizualizálhat.

A Ruby Beeline-vel egyszerű a távolság átadása! Itt van egy példa, ahol a slow_operation hívások megkapják a saját tartományukat a nyomon belül:

A szakaszok mindig kapnak néhány mezőt:

  • egy név - ebben az esetben lassú_működés
  • időtartam - mennyi idő telt el a mérés megkezdése és elküldése között
  • service_name - általában a Beeline inicializálása során konfigurálva
  • több azonosító - nyomkövetési, span és szülőazonosítók (UUID)

Mindig örömmel fogadjuk (és bátorítjuk!), Hogy a Honeycomb.add_field módszerrel adjon meg további mezőket az átfogókhoz.

Egyéb integrációk 🔗

A Ruby Beeline integrálódik más közönséges rubin drágakövekkel annak érdekében, hogy hasznos információkat nyújtson a szakaszokon és a nyomokon.

Aktív támogatás 🔗

A Ruby Beeline meghallgathat bármilyen aktív támogatási műszerhívást az alkalmazásában, és minden eseményről elkészítheti a szakaszokat. A Beeline konfigurálásakor listát adva meghallgathatja az eseményeket.

A rubin beeline automatikusan rögzíti az aws-sdk gem v2 vagy v3 használatával indított hívásokat, és minden híváshoz teret készít.

Faraday 🔗

A Ruby Beeline nyomon terjesztési fejlettel próbálja terjeszteni a kimenő HTTP kéréseket. Ez lehetővé teszi más Beeline-t használó szolgáltatások számára, hogy elosztott nyomot állítsanak elő.

A Ruby Beeline egy darab rack köztes szoftvert kínál, amely felhasználható rack alkalmazásokban. Ez létrehoz egy nyomkövetési és gyökérterületet minden kéréshez, és folytatja az összes elosztott nyomot a többi Beelines által a fejlécben található nyomazonosítókkal.

Sínek 🔗

A Ruby Beeline egy síngenerátort biztosít a könnyű konfiguráláshoz. Létrehoz egy konfigurációs fájlt a megadott API-kulccsal, néhány alapvető aktív támogatási esemény konfigurálva, és egy presend_hook-ot, hogy eltávolítsa a lehetséges PII-t a konfigurált értesítési eseményekből. A Rails még sok aktív támogatási értesítési eseményt kínál, amelyeket hozzáadhat a műszeréhez. A sínek által biztosított események teljes listáját itt találja.

A Ruby Beeline automatikusan műszerezi a rake feladatait, és minden rake feladathoz létrehoz egy nyomot és gyökérterületet.

Folytatás 🔗

A Ruby Beeline automatikusan műszerezi a folytatási adatbázis-hívásokat, és minden híváshoz teret készít.

Sinatra 🔗

A Ruby Beeline tovább fejleszti a rendelkezésre álló rack köztes szoftvert, hogy extra információkat gyűjtsön a Sinatra alkalmazáshoz.

Fesztávolság növelése vagy súrolása 🔗

Ha bármilyen átalakítást szeretne végrehajtani minden szakaszon, mielőtt elhagyná a méhsejt folyamatát, akkor a presend_hook a lehetősége ezeknek a változtatásoknak a végrehajtására. Ilyenek például az érzékeny adatok súrolása (például biztos lehet abban, hogy bizonyos mezőket eldobnak vagy kivonatolnak), vagy az adatok bővítése (pl. Sávon kívüli fordítások egy azonosító és egy emberileg olvashatóbb verzió között). Az alábbiakban bemutatott sample_hook-hoz hasonlóan átadod a presend_hook blokkot, amelyet minden spanon meghívnak, argumentumként az adott span mezõit. A funkció szabadon módosíthatja az átadott hash-t, és ezek a mutációk lesznek azok, amelyek végül elküldődnek Honeycomb-nak.

Példaként mondjuk, hogy vannak olyan HTTP kéréseink, amelyek érzékeny értékeket szolgáltatnak, és amelyeket hozzáadtak egy tartományhoz. Ez a kód megvizsgálja az összes tartományt közvetlenül a Honeycomb elküldése előtt, és az érzékeny értékeket „[REDACTED]” -re cseréli.

Mintavételi események 🔗

Az események egy részének mintavételezéséhez nagyon nagy áteresztőképességű szolgáltatásokhoz, vegyen fel egy egyedi klienst a minta_ráta értékkel a Ruby Beeline inicializálásába. Ez az összes esemény 1/n-ét küldi, így az 5-ös mintavételi arány az események 20% -át küldi. Próbáljon 10-es értékkel kezdeni:

A mintavételt alapértelmezés szerint nyomonként végezzük a Ruby Beeline-ben, így a mintavétel hozzáadása nem fogja feltörni a nyomokat. Vagy az összes nyomon átívelő távolságot elküldjük, vagy a nyomban lévő tartományokat nem küldjük el.

A Honeycomb motor átértékeli a lekérdezés eredményeit annak érdekében, hogy a mintavételezett számítások helyes eredményeket adjanak vissza.

A mintavételi logika testreszabása 🔗

A Beeline segítségével megadhat egy minta_horgot a determinisztikus nyomonkénti mintavételhez használt logika testreszabása érdekében.

Tegyük fel például, hogy műszerezett egy HTTP szervert. Szeretne megtartani minden hibás kérést, és erősen meg kell mintáznia az egészséges forgalmat (200 válaszkód). Ezenkívül nem igazán érdekel 302 átirányítás az alkalmazásodban, ezért hagyd el ezeket. Meghatározhat egy mintavevő függvényt:

jegyzet: A mintavételi horog meghatározása felülírja a nyomazonosítók determinisztikus mintavételi viselkedését. Hacsak nem veszi figyelembe a trace.trace_id elemet (ahogy fentebb tettük a DeterministicSampler kiterjesztésével), hiányos nyomokat kap.

Elosztott nyomkövetés 🔗

Ha a rendszer egyetlen nyomon több folyamat is áthaladhat, akkor arra lesz szüksége, hogy az egyes szolgáltatások által kibocsátott tartományokat egyetlen nyomba kapcsolja. Ezt úgy kezeli, hogy a nyomkövetési kontextust egy HTTP fejlécen keresztül terjeszti.

A Honeycomb beelines méhsejt-specifikus formátumban, valamint a W3C Trace Context formátumban támogatja a nyomkövetési fejléceket.

Ha a Honeycomb Beeline-t és a faraday-t használja HTTP-hívások kezdeményezéséhez, akkor minden készen áll, és a nyomkövetést automatikusan kezeli az Ön számára.

Interoperabilitás az OpenTelemetry-vel 🔗

A Honeycomb Beeline és az OpenTelemetry műszerekkel ellátott szolgáltatásokat tartalmazó elosztott nyomkövetések támogatása érdekében a Beeline marsall és unmarars függvényeket tartalmaz, amelyek előállíthatják és értelmezik a W3C Trace Context fejléceket, az OpenTelemetry által használt formátumot.

Annak megadásához, hogy egy szolgáltatásnak elemeznie kell a W3C Trace Context fejléceket a beérkező kérelmektől, meg kell adnia egy http_trace_parser_hook elemet a beeline konfigurációban.

A http_trace_parser_hook egy olyan függvény, amely argumentumként veszi a rack env-t, és Honeycomb: Propagation: Context-t ad vissza. A rack env a függvény számára biztosított, hogy a szerző a kérelemben szereplő információk alapján dönthessen arról, hogy megbízik-e a beérkező fejlécekben (pl. Talán nem akarja elfogadni a fejléceket a nyilvános internetről).

A nyomkövetési fejlécek támogatott formátumban történő elküldéséhez meg kell adnia egy http_trace_propagation_hook elemet. Ez a beeline konfigurálása során történik.

A http_trace_propagation_hook egy olyan függvény, amely egy Faraday-env-t és egy Honeycomb: Propagation: Context-et vesz fel argumentumként, és névkivonatot ad vissza, értékpárokat, amelyek a sorosított fejléceket képviselik. A fent leírt elemzőhoroghoz hasonlóan a Faraday env és a Propagation Context objektumokat is átadják ennek a függvénynek, így a szerző eldöntheti, hogy a kimenő kérelembe belefoglalja-e a nyomkövetési kontextust (pl. Előfordulhat, hogy nem kíván nyomkövetési fejléceket küldeni, amikor hív egy harmadik fél API).

Mivel megadtunk egy http_trace_propagation_hook sorosított fejlécet W3C nyomkövetési kontextusban, a kimenő kérelem tartalmazza a megfelelő nyomkövetési környezet fejlécet.

A Beeline hibaelhárítása 🔗

Három általános megközelítés létezik annak kiderítésére, hogy mi a baj, ha a Ruby Beeline nem azt csinálja, amit elvár.

Engedélyezze a hibakeresési módot 🔗

Adja hozzá a hibakeresési sort a konfigurációs blokkhoz.

Használjon LogClient 🔗

A Rubh Beeline konfigurálásakor a Libhoney LogClient használatával elküldheti az eseményeket az STDOUT-nak.

ENV-változók használata a keretrendszer-integrációk vezérléséhez 🔗

Ha a Rails, a Faraday, a Sequel stb. Integrációjával van problémája, használja a következő ENV változókat annak meghatározásához, hogy melyik integráció okozhatja a problémát, vagy teljesen tiltsa le.

Használja a HONEYCOMB_DISABLE_AUTOCONFIGURE = true lehetőséget, hogy megakadályozza, hogy a Beeline bármelyik Beeline integrációt igényeljen. Ez továbbra is lehetővé teszi a Beeline használatát, de az automatikus műszer nélkül.

Használhatja a HONEYCOMB_INTEGRATIONS = síneket is, míg vesszővel elválasztott lista használatával csak meghatározott integrációkat tölthet be. Ez lehetővé teszi, hogy szelektívebb legyen abban, hogy melyik automatikus műszerintegrációt szeretné használni. A rendelkezésre álló integrációs lista a következő: active_support, aws, faraday, rack, rails, railtie, rake, folytatás, sinatra.

A köztes szoftver helyének testreszabása a Rails alkalmazásban

A Rails keretrendszer integrálása automatikusan beilleszti a Rack köztes szoftvert a Rails: Rack: Logger köztes program elé. Ha ezt valamilyen más helyre szeretné beilleszteni, tiltsa le a vasúti összeköttetést a fentiek szerint, a HONEYCOMB_INTEGRATIONS ENV változóval. Ezután manuálisan be kell illesztenie a Honeycomb: Rails: Middleware szoftvert a köztes szoftver verembe.

Példa esemény 🔗

Az alábbiakban bemutatunk egy minta eseményt a Ruby Beeline-től. Ez a példa egy http_szerver esemény, amelyet akkor generáltak, amikor az alkalmazás kezeli a bejövő HTTP kéréseket.

Kipróbálandó lekérdezések 🔗

Íme néhány példa arra, hogy elkezdhesse lekérdezni az alkalmazás viselkedését:

Melyik alkalmazásom útvonala a leglassabb? 🔗

  • CSOPORT: kérelem.útvonal
  • VIZUALIZÁLÁS: P99 (időtartam_ms)
  • HOL: név = http_request
  • MEGRENDELÉS: P99 (időtartam_ms) DESC

Hol tölti az alkalmazásom a legtöbb időt? 🔗

  • CSOPORT: név
  • VIZUALIZE: SUM (időtartam_ms)
  • MEGRENDELÉS: SUM (duration_ms) DESC

Melyik felhasználó használja azt a végpontot, amelyet szeretnék megszüntetni? (Egyéni mező használatával user.email) 🔗

  • CSOPORTOSÍTÁS: app.user.email
  • VIZUALIZÁL: COUNT
  • HOL: request.path ==/my/elavult/végpont

Hozzájárulások 🔗

A Beelines szolgáltatásait, hibajavításait és egyéb változtatásait örömmel fogadjuk. Kérjük, a GitHubon keresztül nyissa meg a változtatással kapcsolatos kérdéseket vagy kérést. Ne felejtse el hozzáadni a nevét a RÉSZVEVŐK fájlhoz!

Minden hozzájárulás az Apache License 2.0 alatt kerül kiadásra.