Інструментування

Інструментування — це процес додавання коду спостереження до вашого застосунку.

Якщо ви інструментуєте застосунок, вам потрібно використовувати OpenTelemetry SDK для вашої мови програмування. Потім ви будете використовувати SDK для ініціалізації OpenTelemetry та API для інструментування вашого коду. Це буде генерувати телеметрію з вашого застосунку та будь-якої бібліотеки, яку ви встановили, що також містить інструментування.

Якщо ви інструментуєте бібліотеку, встановіть лише пакет OpenTelemetry API для вашої мови програмування. Ваша бібліотека не буде генерувати телеметрію самостійно. Вона буде генерувати телеметрію лише тоді, коли буде частиною застосунку, що використовує OpenTelemetry SDK. Для отримання додаткової інформації про інструментування бібліотек дивіться Бібліотеки.

Для отримання додаткової інформації про OpenTelemetry API та SDK дивіться специфікацію.

Налаштування

Спочатку переконайтеся, що у вас встановлений пакунок SDK:

gem install opentelemetry-sdk

Потім включіть код конфігурації, який виконується під час ініціалізації вашої програми. Переконайтеся, що service.name встановлено шляхом налаштування імені сервісу.

Трейси

Отримання Tracer

Щоб почати трейсинг, вам потрібно переконатися, що у вас є ініціалізований Tracer, який надходить від TracerProvider.

Найпростіший і найпоширеніший спосіб зробити це — використовувати глобально зареєстрований TracerProvider. Якщо ви використовуєте бібліотеки інструментування, наприклад, у застосунку Rails, то один буде зареєстрований для вас.

# Якщо в застосунку Rails, це знаходиться в config/initializers/opentelemetry.rb
require "opentelemetry/sdk"

OpenTelemetry::SDK.configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
end

# 'Tracer' тепер можна використовувати у всьому вашому коді
MyAppTracer = OpenTelemetry.tracer_provider.tracer('<YOUR_TRACER_NAME>')

Отримавши Tracer, ви можете вручну відстежувати код.

Отримання поточного відрізка

Дуже часто потрібно додати інформацію до поточного відрізка десь у вашій програмі. Для цього ви можете отримати поточний відрізок і додати до нього атрибути.

require "opentelemetry/sdk"

def track_extended_warranty(extended_warranty)
  # Отримати поточний відрізок
  current_span = OpenTelemetry::Trace.current_span

  # І додати корисні речі до нього!
  current_span.add_attributes({
    "com.extended_warranty.id" => extended_warranty.id,
    "com.extended_warranty.timestamp" => extended_warranty.timestamp
  })
end

Створення нових відрізків

Щоб створити відрізок, вам знадобиться налаштований Tracer.

Зазвичай, коли ви створюєте новий відрізок, ви хочете, щоб він був активним/поточним відрізком. Для цього використовуйте in_span:

require "opentelemetry/sdk"

def do_work
  MyAppTracer.in_span("do_work") do |span|
    # виконайте деяку роботу, яку відстежує відрізок 'do_work'!
  end
end

Створення вкладених відрізків

Якщо у вас є окрема під-операція, яку ви хочете відстежувати як частину іншої, ви можете створити вкладені відрізки, щоб представити це відношення:

require "opentelemetry/sdk"

def parent_work
  MyAppTracer.in_span("parent") do |span|
    # виконайте деяку роботу, яку відстежує відрізок 'parent'!

    child_work

    # виконайте ще деяку роботу після цього
  end
end

def child_work
  MyAppTracer.in_span("child") do |span|
    # виконайте деяку роботу, яку відстежує відрізок 'child'!
  end
end

У наведеному вище прикладі створюються два відрізки, з іменами parent і child, де child вкладений у parent. Якщо ви переглянете трейс з цими відрізками в інструменті візуалізації трейсів, child буде вкладений у parent.

Додавання атрибутів до відрізка

Атрибути дозволяють вам прикріплювати пари ключ/значення до відрізка, щоб він ніс більше інформації про поточну операцію, яку він відстежує.

Ви можете використовувати set_attribute, щоб додати один атрибут до відрізка:

require "opentelemetry/sdk"

current_span = OpenTelemetry::Trace.current_span

current_span.set_attribute("animals", ["elephant", "tiger"])

Ви можете використовувати add_attributes, щоб додати map атрибутів:

require "opentelemetry/sdk"

current_span = OpenTelemetry::Trace.current_span

current_span.add_attributes({
  "my.cool.attribute" => "a value",
  "my.first.name" => "Oscar"
})

Ви також можете додати атрибути до відрізка під час його створення:

require "opentelemetry/sdk"

MyAppTracer.in_span('foo', attributes: { "hello" => "world", "some.number" => 1024 }) do |span|
  # виконайте деяку роботу з відрізком
end

⚠ Відрізки є потокобезпечними структурами даних, які потребують блокувань під час їх зміни. Тому вам слід уникати багаторазового виклику set_attribute і замість цього призначати атрибути гуртом за допомогою Hash, або під час створення відрізка, або за допомогою add_attributes на наявному відрізку.

⚠ Рішення про семплінг приймаються в момент створення відрізка. Якщо ваш семплер враховує атрибути відрізка під час прийняття рішення про відбір відрізка, то ви повинні передати ці атрибути як частину створення відрізка. Будь-які атрибути, додані після створення, не будуть враховані семплером, оскільки рішення про відбір вже прийнято.

Додавання семантичних атрибутів

Семантичні атрибути є попередньо визначеними атрибутами, які є загальновідомими конвенціями іменування для поширених типів даних. Використання семантичних атрибутів дозволяє нормалізувати цю інформацію у ваших системах.

Щоб використовувати семантичні атрибути в Ruby, додайте відповідний gem:

gem install opentelemetry-semantic_conventions

Потім ви можете використовувати його в коді:

require 'opentelemetry/sdk'
require 'opentelemetry/semantic_conventions'

current_span = OpenTelemetry::Trace.current_span

current_span.add_attributes({
  OpenTelemetry::SemanticConventions::Trace::HTTP_METHOD => "GET",
  OpenTelemetry::SemanticConventions::Trace::HTTP_URL => "https://opentelemetry.io/",
})

Додавання подій до відрізка

Подія відрізка — це повідомлення, яке може прочитати людина, на відрізку, яке представляє “щось, що відбувається” під час його існування. Наприклад, уявіть функцію, яка потребує ексклюзивного доступу до ресурсу, який знаходиться у mutex. Подія може бути створена у двох точках: один раз, коли ми намагаємося отримати доступ до ресурсу, і ще один раз, коли ми отримуємо mutex.

require "opentelemetry/sdk"

span = OpenTelemetry::Trace.current_span

span.add_event("Acquiring lock")
if mutex.try_lock
  span.add_event("Got lock, doing work...")
  # виконайте деяку роботу
  span.add_event("Releasing lock")
else
  span.add_event("Lock already in use")
end

Корисною характеристикою подій є те, що їхні часові мітки відображаються як зсуви від початку відрізка, що дозволяє легко побачити, скільки часу пройшло між ними.

Події також можуть мати власні атрибути, наприклад:

require "opentelemetry/sdk"

span.add_event("Cancelled wait due to external signal", attributes: {
  "pid" => 4328,
  "signal" => "SIGHUP"
})

Додавання посилань на відрізки

Відрізок може бути створений з нулем або більшою кількістю посилань на відрізки, які повʼязують його з іншим відрізком. Для створення посилання потрібен контекст відрізка.

require "opentelemetry/sdk"

span_to_link_from = OpenTelemetry::Trace.current_span

link = OpenTelemetry::Trace::Link.new(span_to_link_from.context)

MyAppTracer.in_span("new-span", links: [link])
  # виконайте деяку роботу, яку відстежує відрізком 'new-span'

  # Посилання в 'new_span' причинно повʼязує його з відрізком, з якого воно повʼязане,
  # але це не обовʼязково дочірній відрізок.
end

Посилання на відрізки часто використовуються для звʼязування різних трейсів, які повʼязані певним чином, наприклад, довготривале завдання, яке викликає підзавдання асинхронно.

Посилання також можуть бути створені з додатковими атрибутами:

link = OpenTelemetry::Trace::Link.new(span_to_link_from.context, attributes: { "some.attribute" => 12 })

Встановлення статусу відрізка

Статус можна встановити на Відрізок, зазвичай використовується для вказівки, що Відрізок не завершився успішно — Error. Стандартно, всі відрізки мають статус Unset, що означає, що відрізок завершився без помилок. Статус Ok зарезервований для випадків, коли потрібно явно позначити відрізок як успішний, а не залишати його зі статусом Unset (тобто “без помилок”).

Статус можна встановити в будь-який час до завершення відрізка.

require "opentelemetry/sdk"

current_span = OpenTelemetry::Trace.current_span

begin
  1/0 # щось, що явно не вдається
rescue
  current_span.status = OpenTelemetry::Trace::Status.error("error message here!")
end

Запис помилок у відрізки

Може бути гарною ідеєю записувати помилки, коли вони трапляються. Рекомендується робити це разом з встановленням статусу відрізка.

require "opentelemetry/sdk"

current_span = OpenTelemetry::Trace.current_span

begin
  1/0 # щось, що явно не вдається
rescue Exception => e
  current_span.status = OpenTelemetry::Trace::Status.error("error message here!")
  current_span.record_exception(e)
end

Запис помилки створює подію відрізка на поточному відрізку з трасуванням стека як атрибутом події відрізка.

Виключення також можуть бути записані з додатковими атрибутами:

current_span.record_exception(ex, attributes: { "some.attribute" => 12 })

Поширення контексту

Розподілений трейсинг відстежує прогрес одного запиту, який називається трейсом, коли він обробляється сервісами, що складають застосунок. Розподілений трейс перетинає процеси, мережу та межі безпеки. Глосарій

Це вимагає поширення контексту, механізму, за допомогою якого ідентифікатори для трейсу надсилаються до віддалених процесів.

ℹ SDK OpenTelemetry Ruby подбає про поширення контексту, якщо ваш сервіс використовує бібліотеки з автоматичним інструментуванням. Будь ласка, зверніться до README для отримання додаткової інформації.

Для поширення контексту трейсу через мережу, поширювач повинен бути зареєстрований у SDK OpenTelemetry. Поширювачі W3 TraceContext і Baggage стандартно налаштовані. Оператори можуть перевизначити це значення, встановивши змінну середовища OTEL_PROPAGATORS на список поширювачів, розділених комами, які ви хочете підтримувати:

export OTEL_PROPAGATORS=tracecontext,baggage,b3

Поширювачі, відмінні від tracecontext і baggage, повинні бути додані як залежності gem до вашого Gemfile, наприклад:

gem 'opentelemetry-propagator-b3'

Метрики

API та SDK для метрик наразі розробляються.

Логи

API та SDK для логів наразі розробляються.

Наступні кроки

Вам також потрібно буде налаштувати відповідний експортер для експорту ваших телеметричних даних до одного або більше бекендів телеметрії.