Ruby Beeline за пчелна пита е бърз и лесен начин за инструментиране на вашето приложение Ruby. Той включва няколко незадължителни обвивки, които автоматично обработват HTTP заявки и заявки към база данни.

пита

Той осигурява автоматично проследяване извън кутията, свързвайки заявки към база данни с HTTP заявката, от която произхождат. Въпреки че това е чудесен начин да получите възможно най-бърза информация за приложението си, докато напредвате по пътя си за наблюдение, може да откриете, че искате да добавите нови събития или следи, за да добавите повече подробности, специфични за вашето приложение. Ruby Beeline предоставя прости интерфейси за добавяне и на двете.

За да видите пример за Ruby Beeline в действие, изпробвайте примерите.

Ако искате да видите повече опции в Ruby Beeline, моля, подайте проблем или гласувайте за вече подаден! Можете също така да се свържете с нас на [email protected].

Изисквания 🔗

  • Приложение Ruby, за предпочитане такова, което слуша HTTP заявки или прави SQL повиквания
  • Ruby 2.3 или по-нова
  • Ключ за API на пчелна пита

Можете да намерите своя API ключ на страницата си с настройки на екипа. Ако все още нямате API ключ, регистрирайте се за пробна версия на Honeycomb.

Бърза инсталация 🔗

За да инсталирате Ruby Beeline за вашето приложение:

Добавете пчелна пита към вашия Gemfile:

Ако имате приложение за релси, можете да стартирате генератора, за да създадете вашия конфигурационен файл:

В противен случай във вашия код инициализирайте beeline с вашия API ключ и име на набор от данни:

Увеличете данните с интересна информация от вашето приложение и допълнителен контекст, като грешки, така че да можете да видите богата информация за вашето приложение в Honeycomb.

Добавете допълнителни обхвати и превърнете поредица от събития в следа:

Инициализиране за използване с прокси 🔗

За да използвате прокси, ще трябва да създадете персонализиран libhoney клиент и да го предоставите при конфигуриране на Beeline:

Забележка: Поддръжката на прокси е добавена във версия libhoney 1.14.0.

Добавяне на контекст към събития 🔗

Ruby Beeline проследява текущия диапазон в рамките на общата следа. Това ви позволява да добавяте толкова допълнителни персонализирани полета, колкото искате.

Ето пример за добавяне на персонализирано поле към текущия диапазон:

Допълнителни полета се добавят под приложението. пространство от имена. Например горното поле ще се появи във вашето събитие като app.big_num. Пространството от имена групира вашите полета заедно, за да ги направи лесни за намиране и изследване.

Ако предпочитате да избягвате приложението. пространство на имена, например, за да презапишете автоматично попълнено поле, можете да накарате вашия блок да вземе текущия диапазон като параметър и да извика add_field директно на този екземпляр.

Тези допълнителни полета са вашата възможност да добавите важен и подробен контекст към вашата апаратура. Поставете таймер около част от кода, добавете информация за всеки потребител, включете подробности за това, което е било необходимо за създаването на отговор и т.н. Очаква се някои полета да присъстват само при някои заявки. Прекрасният пример за това са манипулаторите на грешки; те очевидно ще съществуват само когато е възникнала грешка.

Честа практика е да добавяте в тези полета по пътя, тъй като те се обработват в различни нива на мидълуер. Например, ако имате удостоверителен междинен софтуер, той ще добави поле с удостоверения идентификатор и име на потребителя веднага щом ги разреши. По-късно в стека на повикванията можете да добавите допълнителни полета, описващи какво потребителят се опитва да постигне с тази специфична HTTP заявка.

Ако се интересувате от добавяне на персонализирани полета към всички обхвати, вместо това използвайте add_field_to_trace.

add_field_to_trace добавя полето както към активния в момента обхват, така и към всички други обхвати, които тепърва трябва да бъдат изпратени и са включени в тази проследяване, която се случва в този процес. Освен това тези полета се пакетират и предават на процесите надолу по веригата, ако те също използват белайн. Тази функция е добра за добавяне на контекст, който е по-добре обхванат към заявката, отколкото тази конкретна единица работа, напр. потребителски идентификатори, глобално значими флагове на функции, грешки и др. Полетата, добавени тук, също имат префикс с приложение.

Добавяне на обхвати към следа 🔗

Ние насърчаваме хората да мислят за инструментариума от гледна точка на „единици работа“. С нарастването на вашата програма това, което представлява единица работа, вероятно ще бъде части от цялостната ви услуга, а не цял цикъл. Обхватите са начин за разделяне на едно външно действие (например HTTP заявка) на няколко по-малки единици, за да получите по-добра представа за вашата услуга. Заедно много обхвати правят проследяване, което можете да визуализирате следи в конструктора на заявки Honeycomb.

Добавянето на интервали с Ruby Beeline е лесно! Ето пример, при който извикванията за slow_operation получават свой собствен диапазон в рамките на проследяването:

Обхватите винаги получават няколко полета:

  • име - в този случай slow_operation
  • продължителност - колко време е изминало между момента на започване и изпращане на интервала
  • име_на услуга - обикновено се конфигурира по време на инициализацията на Beeline
  • няколко идентификатора - проследяване, обхват и родителски идентификатори (UUID)

Винаги сте добре дошли (и насърчавани!) Да добавяте допълнителни полета към обхватите, използвайки метода Honeycomb.add_field.

Други интеграции 🔗

Ruby Beeline се интегрира с други обичайни рубинни скъпоценни камъни, за да запълни обхвата и следите с полезна информация.

Активна поддръжка 🔗

Ruby Beeline може да слуша всякакви повиквания на инструментариума за активна поддръжка във вашето приложение и да създава обхвати от всяко събитие. Можете да слушате събития, като предоставите списък, когато конфигурирате Beeline.

Рубинената линия автоматично ще инструментира всички повиквания, направени с помощта на v2 или v3 на скъпоценния камък aws-sdk и ще създаде диапазон за всяко обаждане.

Фарадей 🔗

Ruby Beeline ще се опита да разпространи изходящи HTTP заявки с заглавие за разпространение на трасиране. Това позволява на други услуги, които използват Beeline, да създават разпределена следа.

Ruby Beeline предоставя част от междинния софтуер за багажник, който може да се използва във вашите приложения за багаж. Това ще създаде проследяване и обхват на корен за всяка заявка и ще продължи всички разпределени следи с идентификатори на проследяване, включени от други Beelines в заглавката.

Релси 🔗

Ruby Beeline осигурява генератор на релси за лесно конфигуриране. Той ще генерира конфигурационен файл с предоставения API ключ, конфигурирани някои основни активни събития за поддръжка и presend_hook за премахване на потенциални PII от конфигурираните съобщения_ събития. Rails предоставя много по-активни събития за известия за поддръжка, които можете да добавите към инструментариума си. Вижте пълния списък на събитията, предоставени от rails тук.

Ruby Beeline автоматично ще инструментира вашите рейк задачи и ще създаде проследяване и обхват на корен за всяка рейк задача.

Продължение 🔗

Ruby Beeline автоматично ще инструментира вашите последващи разговори в базата данни и ще създаде обхват за всяко обаждане.

Синатра 🔗

Ruby Beeline подобрява предоставения междинен софтуер за багажник, за да събира допълнителна информация за приложението на синатра.

Увеличаване или почистване на участъци 🔗

Ако имате някои трансформации, които бихте искали да направите за всеки период, преди той да напусне процеса за Honeycomb, presend_hook е вашата възможност да направите тези промени. Примерите са пречистване на чувствителни данни (напр. Може да искате да се уверите, че конкретни полета са отпаднали или хеширани) или увеличаване на данни (например извършване на преводи извън обхвата между идентификатор и по-четлива за хората версия). Подобно на sample_hook, обсъден по-долу, вие предавате presend_hook блок, който ще бъде извикан на всеки диапазон с полетата на този диапазон като аргумент. Функцията е свободна да мутира хеша, предаден и тези мутации ще бъдат това, което най-накрая ще бъде изпратено до Honeycomb.

Като пример, да речем, че имаме някои HTTP заявки, които предоставят чувствителни стойности, които са добавени към интервал. Този код ще изследва всички обхвати, точно преди да бъдат изпратени до Honeycomb, и ще замени чувствителните стойности с „[РЕАКТИРАН]].

Събиране на събития 🔗

За да вземете проба от част от събития за услуги с много висока производителност, включете потребителски клиент с sample_rate в инициализацията на Ruby Beeline. Това изпраща 1/n от всички събития, така че честотата на вземане на проби от 5 ще изпрати 20% от вашите събития. Опитайте да започнете със стойност 10:

Вземането на проби се извършва по подразбиране на ниво на проследяване в Ruby Beeline, така че добавянето на извадка няма да наруши следите ви. Или всички обхвати в проследяване ще бъдат изпратени, или няма обхвати в проследяването да бъдат изпратени.

Двигателят на пчелна пита преоценява резултатите от заявката, за да гарантира, че извадковите изчисления връщат правилни резултати.

Персонализиране на логиката за вземане на проби 🔗

Нашата Beeline ви позволява да дефинирате sample_hook, за да персонализирате логиката, използвана за детерминирано вземане на проби за проследяване.

Например, да предположим, че сте инструментирали HTTP сървър. Бихте искали да запазите всички грешни заявки и да изпробвате здравословен трафик (200 кода за отговор). Освен това не ви е грижа за 302 пренасочвания във вашето приложение, така че искате да ги откажете. Можете да дефинирате пробна функция по следния начин:

Забележка: Дефинирането на кука за вземане на проби заменя детерминираното поведение за вземане на проби за идентификатори на проследяване. Освен ако не вземете под внимание trace.trace_id (както направихме по-горе, като разширихме DeterministicSampler), ще получите непълни следи.

Разпределено разпространение на следи 🔗

Ако една проследяване във вашата система може да премине през множество процеси, ще ви е необходим начин за свързване на обхвата, излъчвани от всяка услуга, в една проследяване. Това се обработва чрез разпространение на контекста на проследяване чрез HTTP заглавка.

Beelines на Honeycomb поддържат заглавки на проследяване в специфичен за Honeycomb формат, както и W3C Trace Context формат.

Ако използвате Honeycomb Beeline и faraday за извършване на HTTP повиквания, всичко е готово и разпространението на трасирането се обработва автоматично за вас.

Оперативна съвместимост с OpenTelemetry 🔗

За да поддържа разпределени следи, които включват услуги, снабдени с пчелна пита Beeline и OpenTelemetry, Beeline включва маршалски и немаршалски функции, които могат да генерират и анализират заглавките на W3C Trace Context, форматът, използван от OpenTelemetry.

За да посочите, че услугата трябва да анализира заглавките на W3C Trace Context от входящи заявки, трябва да посочите http_trace_parser_hook в конфигурацията на beeline.

Http_trace_parser_hook е функция, която приема стойка env като аргумент и връща Honeycomb: Propagation: Context. Rack env се предоставя на функцията, така че авторът да може да вземе решение дали да се довери на входящите заглавки въз основа на информация, съдържаща се в заявката (напр. Може би не искате да приемате заглавки от публичния интернет).

За да изпратите заглавки за разпространение на проследяване в поддържан формат, трябва да посочите http_trace_propagation_hook. Това се прави по време на конфигурирането на билайн.

Http_trace_propagation_hook е функция, която приема за аргумент Faraday env и Honeycomb: Propagation: Context и връща хеш на име, двойки стойности, представляващи сериализирани заглавки. Подобно на описанието за синтактичен анализ, описано по-горе, обектите Faraday env и Propagation Context се предават на тази функция, така че авторът да може да вземе решение дали да включи контекст на проследяване в изходящата заявка (напр. Може да не искате да изпращате заглавки на контекста на проследяване при извикване API на трета страна).

Тъй като посочихме http_trace_propagation_hook, който връща сериализиран заглавие във формат на контекста на W3C проследяване, изходящата заявка ще включва съответния заглавен контекст на проследяване.

Отстраняване на неизправности на Beeline 🔗

Има три основни подхода за установяване на грешката, когато Ruby Beeline не прави това, което очаквате.

Активирайте режима за отстраняване на грешки 🔗

Добавете реда за отстраняване на грешки в конфигурационния блок.

Използвайте LogClient 🔗

С помощта на Libhoney LogClient при конфигуриране на Ruby Beeline можете да изпращате събитията на STDOUT.

Използване на ENV променливи за контрол на интеграцията на рамката 🔗

Ако имате проблеми с конкретна интеграция с Rails, Faraday, Sequel и др., Използвайте следните променливи ENV, за да определите коя интеграция може да е причина за проблема или да го деактивирате изцяло.

Използвайте HONEYCOMB_DISABLE_AUTOCONFIGURE = true, за да спрете Beeline да изисква някоя от интеграциите на Beeline. Това все пак ще ви позволи да използвате Beeline, но без автоматичното измерване.

Можете също да използвате HONEYCOMB_INTEGRATIONS = релси, faraday с помощта на списък, разделен със запетая, за да заредите само специфични интеграции. Това ще ви позволи да бъдете по-селективни относно това коя автоматична интеграция на измервателни уреди искате да използвате. Наличният списък за интеграция е: active_support, aws, faraday, rack, rails, railtie, rake, продължение, sinatra.

Персонализиране на местоположението на междинния софтуер в приложение Rails 🔗

Интеграцията на Rails framework автоматично ще вмъкне Rack middleware преди Rails: Rack: Logger middleware. За да вмъкнете това на друго място, деактивирайте интеграцията на железопътния транспорт, както е дефинирано по-горе, като използвате променливата ENV HONEYCOMB_INTEGRATIONS. След това ще трябва да вмъкнете ръчно Honeycomb: Rails: Middleware във вашия стек на Middleware.

Примерно събитие 🔗

По-долу е примерно събитие от Ruby Beeline. Този пример е http_server събитие, генерирано, когато приложението ви обработва входяща HTTP заявка.

Заявки, които да опитате 🔗

Ето няколко примера, с които можете да започнете да разпитвате поведението на приложението си:

Кои от маршрутите на приложението ми са най-бавни? 🔗

  • ГРУПИРАНЕ ПО: request.path
  • ВИЗУАЛИЗАЦИЯ: P99 (продължителност_мс)
  • КЪДЕ: име = http_request
  • ПОРЪЧКА ПО: P99 (продължителност_ms) DESC

Къде прекарва най-много време приложението ми? 🔗

  • GROUP BY: име
  • ВИЗУАЛИЗАЦИЯ: SUM (продължителност_ms)
  • ПОРЪЧКА ПО: СУМА (продължителност_ms) DESC

Кои потребители използват крайната точка, която бих искал да отнема? (Използване на потребителско поле user.email) 🔗

  • ГРУПИРАНЕ ПО: app.user.email
  • ВИЗУАЛИЗИРАНЕ: БРОЙ
  • КЪДЕ: request.path ==/my/deprecated/endpoint

Приноси 🔗

Характеристики, корекции на грешки и други промени в Beelines се приемат с удоволствие. Моля, отворете проблеми или заявка за изтегляне с вашата промяна чрез GitHub. Не забравяйте да добавите вашето име към файла CONTRIBUTORS!

Всички вноски ще бъдат публикувани под лиценза Apache 2.0.