Використання бібліотек інструментування

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

Багато бібліотек та фреймворків вже підтримують OpenTelemetry або підтримуються через інструментування OpenTelemetry, щоб вони могли генерувати телеметрію, яку ви можете експортувати до системи спостереження.

Якщо ви інструментуєте застосунок або сервіс, який використовує сторонні бібліотеки або фреймворки, дотримуйтесь цих інструкцій, щоб дізнатися, як використовувати нативно інструментовані бібліотеки та бібліотеки інструментування для ваших залежностей.

Використання нативно інструментованих бібліотек

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

Бібліотека може вимагати додаткової конфігурації для інструментування. Перейдіть до документації цієї бібліотеки, щоб дізнатися більше.

• Elasticsearch Ruby Client

Використання бібліотек інструментування

Якщо бібліотека не підтримує OpenTelemetry з коробки, ви можете використовувати бібліотеки інструментування для генерації телеметричних даних для бібліотеки або фреймворку.

Наприклад, якщо ви використовуєте Rails і увімкнете opentelemetry-instrumentation-rails, ва застосунок Rails, який вже працює, автоматично генеруватиме телеметричні дані для вхідних запитів до ваших контролерів.

Налаштування всіх бібліотек інструментування

OpenTelemetry Ruby надає метапакунок opentelemetry-instrumentation-all, який обʼєднує всі бібліотеки інструментування на основі Ruby в один пакунок. Це зручний спосіб додати телеметрію для всіх ваших бібліотек з мінімальними зусиллями:

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'

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

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
  c.service_name = '<YOUR_SERVICE_NAME>'
  c.use_all() # увімкнути всі інструментування!
end

Це встановить всі бібліотеки інструментування та увімкне ті, що відповідають бібліотекам, які ви використовуєте у вашому застосунку.

Перевизначення конфігурації для конкретних бібліотек інструментування

Якщо ви увімкнули всі інструментування, але хочете перевизначити конфігурацію для якоїсь конкретної, викличте use_all з параметром конфігураційної map, де ключ представляє бібліотеку, а значення — її конкретний параметр конфігурації.

Наприклад, ось як ви можете встановити всі інструментування, крім інструментування Redis у ваш застосунок:

require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  config = {'OpenTelemetry::Instrumentation::Redis' => { enabled: false }}
  c.use_all(config)
end

Щоб перевизначити більше інструментувань, додайте ще один запис у map config.

Перевизначення конфігурації для конкретних бібліотек інструментування за допомогою змінних середовища

Ви також можете вимкнути конкретні бібліотеки інструментування за допомогою змінних середовища. Інструментування, вимкнене за допомогою змінної середовища, має пріоритет над локальною конфігурацією. Домовленість для імен змінних середовища — назва бібліотеки, записана великими літерами з заміною :: на підкреслення, OPENTELEMETRY скорочено до OTEL_LANG, і додавання _ENABLED.

Наприклад, імʼя змінної середовища для OpenTelemetry::Instrumentation::Sinatra — OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED.

export OTEL_RUBY_INSTRUMENTATION_SINATRA_ENABLED=false

Налаштування конкретних бібліотек інструментування

Якщо ви віддаєте перевагу більш вибірковому встановленню та використанню лише конкретних бібліотек інструментування, ви також можете це зробити. Наприклад, ось як використовувати лише Sinatra та Faraday, при цьому Faraday налаштовується з додатковим параметром конфігурації.

Спочатку встановіть конкретні бібліотеки інструментування, які ви хочете використовувати:

gem install opentelemetry-instrumentation-sinatra
gem install opentelemetry-instrumentation-faraday

Потім налаштуйте їх:

require 'opentelemetry/sdk'

# встановити всі сумісні інструментування зі стандартною  конфігурацією
OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::Sinatra'
  c.use 'OpenTelemetry::Instrumentation::Faraday', { opt: 'value' }
end

Налаштування конкретних бібліотек інструментування за допомогою змінних середовища

Ви також можете визначити параметр для конкретних бібліотек інструментування за допомогою змінних середовища. За домовленістю, змінна середовища буде назвою інструментування, записаною великими літерами з заміною :: на підкреслення, OPENTELEMETRY скорочено до OTEL_{LANG}, і додавання _CONFIG_OPTS.

Наприклад, імʼя змінної середовища для OpenTelemetry::Instrumentation::Faraday — OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS. Значення peer_service=new_service;span_kind=client перевизначає параметри, встановлені з попереднього розділу для Faraday.

export OTEL_RUBY_INSTRUMENTATION_FARADAY_CONFIG_OPTS="peer_service=new_service;span_kind=client"

Наступна таблиця містить прийнятний формат значень відповідно до типу даних параметра:

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

Бібліотеки інструментування — це найпростіший спосіб генерувати багато корисних телеметричних даних про ваші Ruby застосунки. Але вони не генерують дані, специфічні для логіки вашого застосунку! Для цього вам потрібно буде збагачувати інструментування з бібліотек інструментування вашим власним кодом інструментування.