入门指南
本页将向您展示如何在Ruby中开始使用OpenTelemetry。
您将学习如何在一个简单的应用程序中进行仪表化，以便将跟踪发射到控制台。
先决条件
确保您在本地安装了以下内容：
- MRI Ruby >=
3.0、jruby >=9.3.2.0或 truffleruby >= 22.1 - Bundler
警告
虽然经过了测试，但对于jruby和truffleruby的支持在目前是尽力而为的。
示例应用
以下示例使用了基本的Rails应用程序。如果您不使用Rails，没关系——您也可以使用OpenTelemetry Ruby与其他Web框架，如Sinatra和Rack。有关受支持框架的库的完整列表，请参见注册表。
如需更详细的示例，请参阅示例。
依赖项
首先，安装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(6) + 1).to_s
end
end
接下来，打开config/routes.rb文件，并添加以下代码：
Rails.application.routes.draw do
get 'rolldice', to: 'dice#roll'
end
使用以下命令运行应用程序，并在Web浏览器中打开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库等的instrumentations。
对于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包中的所有仪表化。如果您有更高级的配置需求，请参见配置特定的仪表化库。
运行仪表化的应用
现在，您可以运行仪表化的应用并暂时将其打印到控制台：
env OTEL_TRACES_EXPORTER=console rails server -p 8080
在Web浏览器中打开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提供了一些其他功能，让您获得更深入的洞察力！
- Exporters 允许您将数据导出到首选的后端。
- 上下文传播 可能是OpenTelemetry中最强大的概念之一，因为它将您的单个服务跟踪升级为_分布式跟踪_，使OpenTelemetry供应商能够在进程和网络边界之间端到端地可视化请求。
- 跨度事件 允许您在表示其生命周期内的"某个事件发生"的跨度上添加人类可读的消息。
- 手动仪表化 将使您能够使用领域特定数据丰富您的跟踪。
- OpenTelemetry演示应用程序包括基于Ruby的电子邮件服务。