Instrument and report Ruby application data using the OpenTelemetry Ruby SDK - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Instrumente uma aplicação Ruby com o SDK do OpenTelemetry e exporte dados de rastreamento para o Managed Service for OpenTelemetry. Este guia aborda duas abordagens:

Auto-instrumentação (recomendada): gera spans automaticamente para frameworks compatíveis, como Rails, Sinatra e bibliotecas comuns. Comece por aqui para configurar o ambiente mais rapidamente.
Instrumentação manual: oferece controle refinado sobre a criação de spans. Use esta opção para rastrear lógicas de negócio personalizadas não cobertas pela auto-instrumentação.

Pré-requisitos

Runtime Ruby: MRI Ruby 3.0+, JRuby 9.3.2.0+ ou TruffleRuby 22.1+
Uma conta Alibaba Cloud com o Application Real-Time Monitoring Service (ARMS) ativado

Obtenha o endpoint do OpenTelemetry

Faça login no console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Em seguida, clique na aba Access point information.
Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.
Na seção Client, clique em OpenTelemetry.
Copie o endpoint da coluna Related Information.

Se a aplicação for executada em um ambiente de produção da Alibaba Cloud, use um endpoint de Virtual Private Cloud (VPC). Caso contrário, use um endpoint público.

Código de exemplo

Um exemplo funcional completo está disponível em ruby-opentelemetry-demo.

Auto-instrumentação (Rails)

A auto-instrumentação cria spans automaticamente para bibliotecas e frameworks compatíveis, sem necessidade de criação manual.

Frameworks compatíveis

A auto-instrumentação abrange diversas bibliotecas Ruby, incluindo:

Categoria	Bibliotecas
Frameworks web	rails, rack, sinatra, grape
Banco de dados	active_record, mysql2, pg, mongo, trilogy, redis, dalli, lmdb
Clientes HTTP	net_http, faraday, excon, http, http_client, httpx, ethon, restclient
Filas de tarefas	sidekiq, delayed_job, resque, active_job, que, rake
Mensageria	bunny, rdkafka, ruby_kafka, racecar
Outros	aws_sdk, graphql, koala, concurrent_ruby, active_support, action_pack, action_view, active_model_serializers, gruf, rspec

Para consultar a lista completa, acesse o repositório contrib do OpenTelemetry Ruby.

Etapa 1: Crie um projeto Rails

Ignore esta etapa se você já tiver uma aplicação Rails.

gem install rails
rails new <your-project-name>
cd <your-project-name>

Substitua <your-project-name> pelo nome da sua aplicação, por exemplo rails new otel-demo.

Caso encontre o erro Rails is not currently installed on this system , feche e reabra o terminal e execute o comando novamente.

Etapa 2: Adicione as gems do OpenTelemetry

Adicione estas linhas ao arquivo Gemfile do projeto:

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'

Em seguida, instale as dependências:

gem install bundler   # skip if Bundler is already installed
bundle install

Etapa 3: Configure o SDK do OpenTelemetry

Crie o arquivo config/initializers/opentelemetry.rb:

# 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>' # Replace with your OpenTelemetry HTTP endpoint.
      )
    )
  )
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::HOST_NAME => '<your-host-name>',
  })
  c.service_name = '<your-service-name>'
  c.use_all() # Enable auto-instrumentation for all supported libraries.
end

Substitua os placeholders pelos valores reais:

Placeholder	Descrição	Exemplo
`<endpoint>`	Endpoint HTTP do OpenTelemetry obtido nos pré-requisitos	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxx`
`<your-host-name>`	Nome do host do servidor	`my-rails-server`
`<your-service-name>`	Nome da aplicação exibido no console do ARMS	`my-rails-app`

Etapa 4: Inicie a aplicação

rails server

Saída esperada:

* 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

Etapa 5: Verifique o envio de dados

Abra http://127.0.0.1:3000 no navegador. Se o terminal exibir a saída de log abaixo, os dados de rastreamento estão sendo exportados para o Managed Service for OpenTelemetry:

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)

Instrumentação manual

A instrumentação manual proporciona controle total sobre quais operações geram spans. Ela funciona com qualquer aplicação Ruby, não apenas com Rails.

Etapa 1: Instale as dependências

Instale as seguintes dependências do OpenTelemetry:

gem install opentelemetry-api
gem install opentelemetry-sdk
gem install opentelemetry-exporter-otlp

Etapa 2: Inicialize o SDK

Crie um arquivo (por exemplo, manual.rb) e configure o exporter OTLP. O BatchSpanProcessor armazena spans em buffer e os envia em lotes para melhorar o desempenho:

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>' # Replace with your OpenTelemetry HTTP endpoint.
      )
    )
  )
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAMESPACE => 'tracing',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => '<your-service-name>',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1',
  })
end

Substitua os placeholders:

Placeholder	Descrição	Exemplo
`<endpoint>`	Endpoint HTTP do OpenTelemetry obtido nos pré-requisitos	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxx`
`<your-service-name>`	Nome da aplicação exibido no console do ARMS	`ruby_demo`

Etapa 3: Crie spans

Obtenha um tracer e crie um span:

tracer = OpenTelemetry.tracer_provider.tracer('<your-tracer-name>', '0.1.0')

tracer.in_span('parent_span') do |parent_span|
  # Your application logic here.
end

O nome do tracer identifica a biblioteca de instrumentação no console do ARMS. Escolha um nome que descreva o componente rastreado, como 'order-service' ou 'payment-processor'.

Etapa 4: Adicione atributos e leia o contexto do span

Dentro de um bloco de span, adicione atributos e recupere o ID do rastreamento e o ID do span:

tracer.in_span('parent_span') do |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

Etapa 5: Crie spans aninhados

Aninhe chamadas de in_span para representar relações pai-filho entre operações:

tracer.in_span('parent_span') do |parent_span|
  # Parent span logic.
  tracer.in_span('child_span') do |child_span|
    current_span = OpenTelemetry::Trace::current_span
    pp current_span  # This is the child span.
  end
end

Exemplo completo

Este exemplo abrange criação de spans, atributos, eventos, spans aninhados e tratamento de erros em um único script:

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>' # Replace with your OpenTelemetry HTTP endpoint.
      )
    )
  )
  c.resource = OpenTelemetry::SDK::Resources::Resource.create({
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAMESPACE => 'tracing',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME => 'ruby_demo',
    OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION => '0.0.1',
  })

  # Alternatively, set the service name without the 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 span attributes.
  parent_span.set_attribute('language', 'ruby')
  parent_span.set_attribute("attribute_key", ["attribute_value1", "attribute_value1", "attribute_value1"])

  # Add a span event.
  parent_span.add_event("event", attributes: {
    "pid" => 1234,
    "signal" => "SIGHUP"
  })

  # Read the trace ID and span ID.
  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
      # Mark the span as errored.
      child_span.status = OpenTelemetry::Trace::Status.error("error in child span")
    end

    pp child_span
  end
end

sleep 10

Execute a aplicação:

ruby manual.rb

Visualize dados de rastreamento no console do ARMS

Faça login no console do ARMS.
No painel de navegação à esquerda, escolha Application Monitoring > Applications.
Na página Applications, clique em Applications para visualizar os dados de rastreamento.

Se o ícone aparecer na coluna Language , a aplicação está conectada via Application Monitoring. Se houver um hífen ( - ), a conexão foi feita pelo Managed Service for OpenTelemetry.