入门
此页面将向您展示如何在 Ruby 中开始使用 OpenTelemetry。
您将了解如何对一个简单的应用程序进行插装，从而将 跟踪 发送到控制台。
先决条件
请确保您已在本地安装以下软件
- CRuby >=
3.1, JRuby >=9.3.2.0, 或 TruffleRuby >=22.1 - Bundler
尽管经过测试，但目前对 jruby 和 truffleruby 的支持是尽力而为的。
示例应用程序
以下示例使用了一个基本的 Rails 应用程序。如果您不使用 Rails，也没关系 — 您也可以在其他 Web 框架（如 Sinatra 和 Rack）中使用 OpenTelemetry Ruby。有关支持框架的库的完整列表，请参阅 注册表。
有关更详细的示例，请参阅 示例。
依赖项
开始之前，请安装 Rails
gem install rails
创建应用程序
创建一个名为 dice-ruby 的新仅 API 应用程序，并进入新创建的文件夹 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
使用以下命令运行应用程序，然后在浏览器中打开 https://: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() # enables all instrumentation!
end
调用 c.use_all() 可启用 instrumentation/all 包中的所有插装。如果您有更高级的配置需求，请参阅 配置特定的插装库。
运行已 instrumented 的应用
您现在可以运行已插装的应用程序，并暂时将其输出到控制台
env OTEL_TRACES_EXPORTER=console rails server -p 8080
在您的 Web 浏览器中打开 https://:8080/rolldice 并重新加载页面几次。您应该会在控制台中看到打印的 span，例如以下内容
#<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 供应商能够可视化跨进程和网络边界的端到端请求。
- Span 事件允许您在 span 上添加人类可读的消息，表示在其生命周期中“发生的某件事”。
- 插装将为您提供用领域特定数据丰富跟踪的能力。
- OpenTelemetry 演示包括基于 Ruby 的 电子邮件服务。