Before you can view the trace data of your application in the Tracing Analysis console, you must use a client to submit the trace data to Tracing Analysis. This topic describes how to use OpenTelemetry SDK for Ruby to submit the trace data of a Ruby application.

Prerequisites

To obtain an endpoint of OpenTelemetry, perform the following steps:
  1. Log on to the Tracing Analysis console.
  2. In the left-side navigation pane, click Cluster Configurations. Then, click the Access point information tab.
  3. In the top navigation bar, select a region. In the Cluster Information section, turn on Show Token.
  4. In the Client section, click OpenTelemetry.
    Obtain an endpoint of OpenTelemetry in the Related Information column of the table in the lower part. Endpoint of OpenTelemetry
    Note If your application is deployed in an Alibaba Cloud production environment, use a private endpoint. Otherwise, use a public endpoint.

Sample code

Download the sample code from the ruby-opentelemetry-demo.

Method 1: Use the HTTP protocol

  1. Install the following dependencies that are required for manual OpenTelemetry instrumentation: 
    gem install opentelemetry-api
gem install opentelemetry-sdk
gem install opentelemetry-exporter-otlp
  2. Initialize OpenTelemetry.
    Add a component that is used to export monitoring data, and replace the <endpoint> parameter with the endpoint of OpenTelemetry that you obtained for the corresponding region. For more information, see the "Prerequisites" section of this topic. 
    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 submit by using OpenTelemetry.
    OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1',
  })
end
  3. Obtain the name of the 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
  4. Obtain the current span, add information to the span, and then obtain the trace ID and span ID: 
    # ...
tracer.in_span('parent_span') do |parent_span|
  # The current 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
  5. Create a nested span: 
    # ...
tracer.in_span('parent_span') do |parent_span|
  # ...
  tracer.in_span('child_span') do |child_span|
    # The current child span.
    current_span = OpenTelemetry::Trace::current_span
    pp current_span
  end
end
    View the complete sample code
    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.
    OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1',
  })

  # Set the application name without using OpenTelemetry Resources API.
  # c.service_name = 'ruby_demo'
end

tracer = OpenTelemetry.tracer_provider.tracer('instrumentation_library_name', '0.1.0')

tracer.in_span('parent_span') do |parent_span|
  # Set the attributes of the span.
  parent_span.set_attribute('language', 'ruby')
  parent_span.set_attribute("attribute_key", ["attribute_value1", "attribute_value1", "attribute_value1"])
  # Add an event to the span.
  parent_span.add_event("event", attributes: {
    "pid" => 1234,
    "signal" => "SIGHUP"
  })

  # Obtain the trace ID and the ID of the current span.
  current_span = OpenTelemetry::Trace::current_span
  pp current_span.context.trace_id
  pp current_span.context.span_id

  tracer.in_span('child_span') do |child_span|
    child_span.add_attributes({
      "key1" => "value1",
      "key2" => "value2"
    })

    child_span.add_event("mock exception here")

    begin
      raise 'An error has occurred'
    rescue
      # Set the status of the child span to error if an error occurs.
      child_span.status = OpenTelemetry::Trace::Status.error("error in child span")
    end

    pp child_span

  end
end

sleep 10
  6. Run the program: 
    ruby manual.rb

Method 2: Automatically submit 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 submit the trace data of the application.

  1. Download the open source web application framework Ruby on Rails: 
    gem install rails
  2. Use Rails to create a web project: 
    rails new <your-project-name>
    • Replace the <your-project-name> variable with the application name. In this example, the application is named rails new auto-demo.
    • If the message Rails is not currently installed on this system. appears after you run the preceding command, close and reopen the terminal, and then re-enter the command.
  3. Add the following content to the Gemfile of the application directory: 
    gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'
  4. Download the required third-party dependencies for the application.
    1. Go to the root directory of the project: 
      cd <your-project-name>
    2. Download the Ruby dependency management tool Bundler: 
      gem install bundler
    3. Download the dependencies in the Gemfile: 
      bundle install
  5. Create a opentelemetry.rb file in the <your-project-name>/config/initializers directory and add the following content: 
    # 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 service name.
  c.use_all()    # The libraries supported by automatic OpenTelemetry observation, 
end
    • Replace the <endpoint> variable with the endpoint of the region that you obtained in Prerequisites.
    • Replace the <your-host-name> and <your-service-name> variables based on your needs.
  6. Run the project: 
    rails server
    If the following result is 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
  7. Visit http://127.0.0.1:3000 in a browser. If the following output is displayed on the terminal, the data is submitted to the Tracing Analysis 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 monitoring data

On the Applications page in the Tracing Analysis console, click the name of the application. On the page that appears, view the trace data.