Початок роботи

Ця сторінка покаже вам, як почати роботу з OpenTelemetry у Ruby.

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

Попередні вимоги

Переконайтеся, що у вас встановлено наступне:

• CRuby >= 3.1, JRuby >= 9.3.2.0, or TruffleRuby >= 22.1
• Bundler

Приклад застосунку

Наступний приклад використовує базовий застосунок Rails. Якщо ви не використовуєте Rails, це не проблема, ви можете використовувати OpenTelemetry Ruby з іншими веб-фреймворками, такими як Sinatra та Rack. Для повного списку бібліотек для підтримуваних фреймворків дивіться реєстр.

Для більш детальних прикладів дивіться приклади.

Залежності

Для початку встановіть Rails:

gem install rails

Створення застосунку

Створіть новий застосунок тільки для API з назвою dice-ruby і перейдіть до новоствореної теки dice-ruby

rails new --api dice-ruby
cd dice-ruby

Створіть контролер для кидання кубика:

rails generate controller dice

Це створить файл з назвою app/controllers/dice_controller.rb. Відкрийте цей файл у вашому улюбленому редакторі та оновіть його наступним кодом:

class DiceController < ApplicationController
  def roll
    render json: rand(1..6).to_s
  end
end

Далі відкрийте файл config/routes.rb і додайте наступний код:

Rails.application.routes.draw do
  get 'rolldice', to: 'dice#roll'
end

Запустіть застосунок за допомогою наступної команди та відкрийте http://localhost:8080/rolldice у вашому вебоглядачі, щоб переконатися, що він працює.

rails server -p 8080

Якщо все працює правильно, ви повинні побачити число від 1 до 6. Тепер ви можете зупинити застосунок і інструментувати його за допомогою OpenTelemetry.

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

Встановіть пакунки opentelemetry-sdk та opentelemetry-instrumentation-all:

bundle add opentelemetry-sdk opentelemetry-instrumentation-all

Включення opentelemetry-instrumentation-all надає інструментування для Rails, Sinatra, кількох HTTP-бібліотек та інших.

Для застосунків Rails звичайний спосіб ініціалізації OpenTelemetry знаходиться в ініціалізаторі Rails. Для інших Ruby-сервісів виконайте цю ініціалізацію якомога раніше в процесі запуску.

Створіть файл з назвою config/initializers/opentelemetry.rb з наступним кодом:

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
  c.service_name = 'dice-ruby'
  c.use_all() # включає все інструментування!
end

Виклик c.use_all() включає все інструментування в пакунку instrumentation/all. Якщо у вас є складніші потреби в конфігурації, дивіться конфігурацію конкретних бібліотек інструментування.

Запуск інструментованого застосунку

Тепер ви можете запустити ваш інструментований застосунок і вивести його в консоль:

env OTEL_TRACES_EXPORTER=console rails server -p 8080

Відкрийте http://localhost:8080/rolldice у вашому вебоглядачі та перезавантажте сторінку кілька разів. Ви повинні побачити відрізки, виведені в консоль, такі як наступні:

#<struct OpenTelemetry::SDK::Trace::SpanData
 name="DiceController#roll",
 kind=:server,
 status=#<OpenTelemetry::Trace::Status:0x000000010587fc48 @code=1, @description="">,
 parent_span_id="\x00\x00\x00\x00\x00\x00\x00\x00",
 total_recorded_attributes=8,
 total_recorded_events=0,
 total_recorded_links=0,
 start_timestamp=1683555544407294000,
 end_timestamp=1683555544464308000,
 attributes=
  {"http.method"=>"GET",
   "http.host"=>"localhost:8080",
   "http.scheme"=>"http",
   "http.target"=>"/rolldice",
   "http.user_agent"=>"curl/7.87.0",
   "code.namespace"=>"DiceController",
   "code.function"=>"roll",
   "http.status_code"=>200},
 links=nil,
 events=nil,
 resource=
  #<OpenTelemetry::SDK::Resources::Resource:0x000000010511d1f8
   @attributes=
    {"service.name"=>"<YOUR_SERVICE_NAME>",
     "process.pid"=>83900,
     "process.command"=>"bin/rails",
     "process.runtime.name"=>"ruby",
     "process.runtime.version"=>"3.2.2",
     "process.runtime.description"=>"ruby 3.2.2 (2023-03-30 revision e51014f9c0) [arm64-darwin22]",
     "telemetry.sdk.name"=>"opentelemetry",
     "telemetry.sdk.language"=>"ruby",
     "telemetry.sdk.version"=>"1.2.0"}>,
 instrumentation_scope=#<struct OpenTelemetry::SDK::InstrumentationScope name="OpenTelemetry::Instrumentation::Rack", version="0.23.0">,
 span_id="\xA7\xF0\x9B#\b[\xE4I",
 trace_id="\xF3\xDC\b8\x91h\xB0\xDF\xDEn*CH\x9Blf",
 trace_flags=#<OpenTelemetry::Trace::TraceFlags:0x00000001057b7b08 @flags=1>,
 tracestate=#<OpenTelemetry::Trace::Tracestate:0x00000001057b67f8 @hash={}>>

Що далі?

Додавання трасування до одного сервісу — це чудовий перший крок. OpenTelemetry надає ще кілька функцій, які дозволять вам отримати ще глибші знання!

• Експортери дозволяють експортувати ваші дані до обраного бекенду.
• Поширення контексту є, можливо, однією з найпотужніших концепцій в OpenTelemetry, оскільки вона перетворить ваше одиничне трасування сервісу в розподілене трасування, що дозволяє візуалізувати запит від кінця до кінця через процеси та мережеві межі.
• Події відрізків дозволяють додати повідомлення зрозуміле людині на відрізок, яке представляє “щось, що відбувається” під час його життя.
• Інструментування дозволить вам збагачувати ваші трасування даними, специфічними для домену.
• Демо OpenTelemetry включає оснований на Ruby Email Service.