Skip to main content

Ruby OpenTelemetry auto-instrumentation

Obtaining telemetry data from applications written in Ruby has never been easier. Thanks to Opentelemetry-Ruby the instrumentation process is very simple. Enabling auto-instrumentation requires you to perform three steps, explained in detail below. First, installation of the required gems, which hold the OpenTelemetry SDK and library-specific instrumentation. Second, code changes required for instrumentation enable and lastly, the exporter configuration.

How to instrument your Ruby application?‚Äč

There are a few simple steps to instrument the application and export the telemetry data by OpenTelemetry Protocol exporter - version sdk=1.2.0, exporter=0.24.0.

Step 1. Gems Installation‚Äč

Installation of the packages listed below is required to apply the instrumentation and export telemetry data. All listed gems are located on RubyGems.org and they can be installed in two different ways:

  • gem¬†command

    gem install opentelemetry-sdk -v 1.2.0
    gem install opentelemetry-exporter-otlp -v 0.24.0
  • bundler,¬†the packages have to be inserted into your gemfile and bundle install command has to be run

    gem 'opentelemetry-sdk', '1.2.0'
    gem 'opentelemetry-exporter-otlp', '0.24.0'

Installation of the gems above is mandatory. The next step is to install instrumentation packages corresponding to the libraries used in the application. A complete list of available plugins can be found here.

There are two solutions:

  • Installation of the specific packages - for¬†example, if the¬†application is a Sinatra HTTP server which is also performing some HTTP requests using Net HTTP package. To instrument all the incoming and outgoing requests corresponding instrumented packages have to be installed:

    gem install opentelemetry-instrumentation-sinatra -v 0.22.0
    gem install opentelemetry-instrumentation-net_http -v 0.22.0
  • Installation of the ‚Äúall in one‚ÄĚ package - installing this package will install all available instrumentation packages:

    gem install opentelemetry-instrumentation-all -v 0.35.0

Step 2. Required code changes‚Äč

To enable instrumentation in the application and export the telemetry data it is enough to add the code below to the project. Two examples below present a specific package and an ‚Äúall in one‚ÄĚ instrumentation.¬†

  • Specific package instrumentation - in this example only Sinatra and Net HTTP libraries will be instrumented.

    require 'opentelemetry/sdk'
    Bundler.require
    OpenTelemetry::SDK.configure do |c|
    c.use 'OpenTelemetry::Instrumentation::Sinatra'
    c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
    end
  • "All in one"¬†instrumentation - this configuration will instrument all available package:

    require 'opentelemetry/sdk'
    Bundler.require
    OpenTelemetry::SDK.configure do |c|
    c.use_all
    end

Step 3. Telemetry data exporter configuration‚Äč

The final step is to configure the exporter host and service name. This can be done directly in the code or by environment variables. In this example, the exporter will be configured by environment variables.

  • Environment variable sets the exporter to OTLP:

    OTEL_EXPORTER=otlp
  • Environment variable configures the endpoint where telemetry data will be sent:

    OTEL_EXPORTER_OTLP_ENDPOINT=http://OTLP_ENDPOINT:4318

    This should be OpenTelemetry Collector/Agent endpoint address or OTLP/HTTP source. For Kubernetes environments, see the available endpoints for a direct connection. For other environments see endpoints and protocols.

  • Configure the service name.¬†Ensure the string value¬†represents its business logic, such as FinanceServiceCall. ¬†This will appear as a tracing service name¬†in Sumo Logic.

    OTEL_SERVICE_NAME=SERVICE_NAME
  • Configure the application¬†name.¬†This will appear as a tracing application name¬†in Sumo Logic. Additional¬†attributes can be added here as comma separated key=value pairs:

    OTEL_RESOURCE_ATTRIBUTES=application=APPLICATION_NAME

TraceID, SpanID and operation data injection into logs‚Äč

Additional information like TraceID, SpanID or operation data in the application logs could be very helpful to correlate traces, spans and operations with specific logs. To add this data to the logs it is required to obtain it from OpenTelemetry::Trace and modify logger.

Please see example code:

logger = ::Logger.new(STDOUT)
logger.formatter = proc do |severity, time, progname, msg|
span_id = OpenTelemetry::Trace.current_span.context.hex_span_id
trace_id = OpenTelemetry::Trace.current_span.context.hex_trace_id
if defined? OpenTelemetry::Trace.current_span.name
operation = OpenTelemetry::Trace.current_span.name
else
operation = 'undefined'
end

"#{time}, #{severity}: #{msg} - trace_id=#{trace_id} - span_id=#{span_id} - operation=#{operation}\n"
end
set :logger, logger

Example output:

"2022-02-28 13:01:25 +0000, INFO: {:remote_ip\>\"127.0.0.6\", :request_path\>\"/get_beans\", :query_string\>\"\", :request_method\>\"POST\", :execution_time_sec\>0.00033453479409217834, :response_status_code\>200} - trace_id=cdd460d538917f82560cbb91373a05a6 - span_id=12a09921c89fd6e9 - operation=POST /get_beans
Legal
Privacy Statement
Terms of Use

Copyright © 2023 by Sumo Logic, Inc.