Before you can view the trace data of your application, you must use a client to report the trace data to Managed Service for OpenTelemetry. This topic describes how to use OpenTelemetry SDK for Ruby to report the trace data of a Ruby application.
Prerequisites
Background information
OpenTelemetry supports the following Ruby versions: MRI Ruby 3.0 and later, JRuby 9.3.2.0 and later, and TruffleRuby 22.1 and later.
OpenTelemetry SDK for Ruby supports manual and semi-automatic instrumentation. Semi-automatic instrumentation means that you do not need to manually create spans, but you must add a configuration file. For more information about the frameworks supported by semi-automatic instrumentation, see OpenTelemetry official documentation.
Sample code
Download the sample code from ruby-opentelemetry-demo.
Method 1: Use the HTTP protocol to report data
Install the following OpenTelemetry dependencies that are required for manual instrumentation:
gem install opentelemetry-api gem install opentelemetry-sdk gem install opentelemetry-exporter-otlp
Initialize OpenTelemetry.
Add a component that is used to export monitoring data, and replace
<endpoint>
with the endpoint that you obtained.require 'opentelemetry/sdk' require 'opentelemetry-exporter-otlp' OpenTelemetry::SDK.configure do |c| c.add_span_processor( OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new( OpenTelemetry::Exporter::OTLP::Exporter.new( endpoint: '<endpoint>' # The endpoint of OpenTelemetry that is accessible over HTTP. ) ) ) c.resource = OpenTelemetry::SDK::Resources::Resource.create({ OpenTelemetry::SemanticConventions::Resource::SERVICE_NAMESPACE => 'tracing', OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => 'ruby_demo', # The name of the Ruby application whose data you want to report by using OpenTelemetry. OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1', }) end
Obtain a tracer and create a span.
tracer = OpenTelemetry.tracer_provider.tracer('<your_tracer_name>', '0.1.0') tracer.in_span('parent_span') do |parent_span| # ... end
Obtain the current span, add information to the current span, and then obtain the trace ID and span ID.
# ... tracer.in_span('parent_span') do |parent_span| # The current span is a parent span named parent_span. current_span = OpenTelemetry::Trace::current_span current_span.set_attribute('key', 'value') pp current_span.context.trace_id pp current_span.context.span_id end
Create a nested span.
# ... tracer.in_span('parent_span') do |parent_span| # ... tracer.in_span('child_span') do |child_span| # In this case, the current span is a child span named child_span. current_span = OpenTelemetry::Trace::current_span pp current_span end end
Run the application.
ruby manual.rb
Method 2: Automatically report data
OpenTelemetry SDK for Ruby also allows you to implement automatic instrumentation and observation for your application. This section describes how to use OpenTelemetry to implement automatic tracing analysis on a Rails application and report the trace data of the application.
Download the open source web application framework Rails.
gem install rails
Use Rails to create a web project.
rails new <your-project-name>
Replace
<your-project-name>
with the name of your application. Example:rails new auto-demo
.If the
Rails is not currently installed on this system
error message is returned after you run the preceding command, close and reopen the CLI, and then enter and run the command again.
Add the following content to the Gemfile in the directory of the application:
gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-instrumentation-all'
Download the third-party dependencies required by the application.
Go to the root directory of the project.
cd <your-project-name>
Download the Ruby dependency management tool Bundler.
gem install bundler
Download the dependencies in the Gemfile.
bundle install
In the <your-project-name>/config/initializers directory, create a opentelemetry.rb file and add the following content to the file:
# config/initializers/opentelemetry.rb require 'opentelemetry/sdk' require 'opentelemetry/exporter/otlp' require 'opentelemetry/instrumentation/all' OpenTelemetry::SDK.configure do |c| c.add_span_processor( OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new( OpenTelemetry::Exporter::OTLP::Exporter.new( endpoint: '<endpoint>' # The endpoint of OpenTelemetry that is accessible over HTTP. ) ) ) c.resource = OpenTelemetry::SDK::Resources::Resource.create({ OpenTelemetry::SemanticConventions::Resource::HOST_NAME => '<your-host-name>', # The hostname. }) c.service_name = '<your-service-name>' # The name of the application. c.use_all() # The libraries supported by automatic OpenTelemetry observation. end
Replace
<endpoint>
with the endpoint that you obtained.Replace
<your-host-name>
and<your-service-name>
with the actual hostname and application name.
Run the project.
rails server
If the following results are returned, the operation is successful:
* Puma version: 5.6.5 (ruby 2.7.2-p137) ("Birdie's Version") * Min threads: 5 * Max threads: 5 * Environment: development * PID: 79842 * Listening on http://127.0.0.1:3000 * Listening on http://[::1]:3000 Use Ctrl-C to stop
Visit
http://127.0.0.1:3000
in a browser. If the following content is displayed on the CLI, the data is reported to the Managed Service for OpenTelemetry console.Started GET "/" for 127.0.0.1 at 2023-01-01 10:00:00 +0800 Processing by Rails::WelcomeController#index as HTML Rendering /Users/username/.rvm/gems/ruby-2.7.2/gems/railties-7.0.4.3/lib/rails/templates/rails/welcome/index.html.erb Rendered /Users/username/.rvm/gems/ruby-2.7.2/gems/railties-7.0.4.3/lib/rails/templates/rails/welcome/index.html.erb (Duration: 0.8ms | Allocations: 665) Completed 200 OK in 6ms (Views: 2.1ms | ActiveRecord: 0.0ms | Allocations: 5440)
View the monitoring data
On the Applications page of the Managed Service for OpenTelemetry console, click the name of the application. On the page that appears, view the trace data.