Instrument and report Ruby application data using the OpenTelemetry Ruby SDK - Application Real-Time Monitoring Service

Instrumente una aplicación Ruby con el SDK de OpenTelemetry y exporte los datos de traza a Managed Service for OpenTelemetry. Esta guía aborda dos enfoques:

Auto-instrumentation (recomendado): genera spans automáticamente para frameworks compatibles como Rails, Sinatra y bibliotecas comunes. Comience aquí para lograr la configuración más rápida.
Manual instrumentation: ofrece un control detallado sobre la creación de spans. Utilice este método para rastrear lógica de negocio personalizada que la auto-instrumentation no cubre.

Requisitos previos

Entorno de ejecución de Ruby: MRI Ruby 3.0+, JRuby 9.3.2.0+ o TruffleRuby 22.1+.
Una cuenta de Alibaba Cloud con Application Real-Time Monitoring Service (ARMS) activado.

Obtención del endpoint de OpenTelemetry

Inicie sesión en la consola de Managed Service for OpenTelemetry.
En el panel de navegación izquierdo, haga clic en Cluster Configurations. A continuación, haga clic en la pestaña Access point information.
En la barra de navegación superior, seleccione una región. En la sección Cluster Information, active Show Token.
En la sección Client, haga clic en OpenTelemetry.
Copie el endpoint de la columna Related Information.

Si su aplicación se ejecuta en un entorno de producción de Alibaba Cloud, utilice un endpoint de Virtual Private Cloud (VPC). De lo contrario, use un endpoint público.

Código de ejemplo

Encuentre un ejemplo funcional completo en ruby-opentelemetry-demo.

Auto-instrumentation (Rails)

La auto-instrumentation crea spans para bibliotecas y frameworks compatibles de forma automática, sin necesidad de crear spans manualmente.

Frameworks compatibles

La auto-instrumentation abarca una amplia variedad de bibliotecas Ruby, entre ellas:

Categoría	Bibliotecas
Frameworks web	rails, rack, sinatra, grape
Base de datos	active_record, mysql2, pg, mongo, trilogy, redis, dalli, lmdb
Clientes HTTP	net_http, faraday, excon, http, http_client, httpx, ethon, restclient
Colas de trabajos	sidekiq, delayed_job, resque, active_job, que, rake
Mensajería	bunny, rdkafka, ruby_kafka, racecar
Otros	aws_sdk, graphql, koala, concurrent_ruby, active_support, action_pack, action_view, active_model_serializers, gruf, rspec

Para consultar la lista completa, visite el repositorio contrib de OpenTelemetry Ruby.

Paso 1: Crear un proyecto de Rails

Omita este paso si ya cuenta con una aplicación Rails.

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

Reemplace <your-project-name> con el nombre de su aplicación; por ejemplo, rails new otel-demo.

Si aparece el error Rails is not currently installed on this system , cierre y vuelva a abrir su terminal, y luego ejecute el comando nuevamente.

Paso 2: Agregar gems de OpenTelemetry

Agregue las siguientes líneas al archivo Gemfile de su proyecto:

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

Después, instale las dependencias:

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

Paso 3: Configurar el SDK de OpenTelemetry

Cree el archivo 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

Sustituya los marcadores de posición con sus valores reales:

Marcador de posición	Descripción	Ejemplo
`<endpoint>`	Endpoint HTTP de OpenTelemetry obtenido en los requisitos previos	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxx`
`<your-host-name>`	Nombre de host de su servidor	`my-rails-server`
`<your-service-name>`	Nombre de la aplicación que se muestra en la consola ARMS	`my-rails-app`

Paso 4: Iniciar la aplicación

rails server

Salida 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

Paso 5: Verificar el reporte de datos

Abra http://127.0.0.1:3000 en un navegador. Si su terminal muestra la siguiente salida de registro, los datos de traza se están exportando a 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)

Instrumentación manual

La instrumentación manual otorga control total sobre qué operaciones generan spans. Funciona con cualquier aplicación Ruby, no solo con Rails.

Paso 1: Instalar dependencias

Instale las siguientes dependencias de OpenTelemetry:

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

Paso 2: Inicializar el SDK

Cree un archivo (por ejemplo, manual.rb) y configure el exportador OTLP. El procesador BatchSpanProcessor almacena los spans en búfer y los envía por lotes para mejorar el rendimiento:

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

Reemplace los marcadores de posición:

Marcador de posición	Descripción	Ejemplo
`<endpoint>`	Endpoint HTTP de OpenTelemetry obtenido en los requisitos previos	`http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxx`
`<your-service-name>`	Nombre de la aplicación que se muestra en la consola ARMS	`ruby_demo`

Paso 3: Crear spans

Obtenga un tracer y cree un 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

El nombre del tracer identifica la biblioteca de instrumentación en la consola ARMS. Elija un nombre que describa el componente rastreado; por ejemplo, 'order-service' o 'payment-processor'.

Paso 4: Agregar atributos y leer el contexto del span

Dentro de un bloque de span, agregue atributos y obtenga el ID de traza y el ID de 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

Paso 5: Crear spans anidados

Anide llamadas a in_span para representar relaciones padre-hijo entre operaciones:

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

Ejemplo completo

Este ejemplo abarca la creación de spans, atributos, eventos, spans anidados y manejo de errores en un solo 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

Ejecute la aplicación:

ruby manual.rb

Consulta de datos de traza en la consola ARMS

Inicie sesión en la consola de ARMS.
En el panel de navegación izquierdo, vaya a Application Monitoring > Applications.
En la página Applications, haga clic en el nombre de su aplicación para consultar sus datos de traza.

Si el ícono aparece en la columna Language , la aplicación está conectada mediante Application Monitoring. Si aparece un guion ( - ), la conexión se realiza a través de Managed Service for OpenTelemetry.