Ruby OpenTelemetry auto-instrumentation

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 0.16.0.

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 0.16.0
$ gem install opentelemetry-exporter-otlp -v 0.16.0

   • Bundler, the packages have to be inserted into your gemfile and bundle install command has to be run

     gem 'opentelemetry-sdk', '0.16.0'
gem 'opentelemetry-exporter-otlp', '0.16.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.16.0
$ gem install opentelemetry-instrumentation-net_http -v 0.16.0

   • Installation of the “all in one” package - installing this package will install all available instrumentation packages

     $ gem install opentelemetry-instrumentation-all -v 0.16.0

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'
require 'opentelemetry/exporter/otlp'
Bundler.require
OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Sinatra'
   c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
   c.add_span_processor(
       OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
         OpenTelemetry::Exporter::OTLP::Exporter.new
       )
     )
end

   • "All in one" instrumentation - this configuration will instrument all available package:

     require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
Bundler.require
OpenTelemetry::SDK.configure do |c|
   c.use_all
   c.add_span_processor(
       OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
         exporter: OpenTelemetry::Exporter::OTLP::Exporter.new
       )
     )
end

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.

   • OTEL_EXPORTER_OTLP_ENDPOINT=http://collection-sumologic-otelcol.sumologic:55681 - environment variable configures the endpoint where telemetry data will be sent.
     
     In this example, the value of the variable points to the default Sumologic Kubernetes Collector. For Kubernetes environments see the available endpoints for a direct connection. For other environments see endpoints and protocols.

   • OTEL_RESOURCE_ATTRIBUTES=service.name=my-service - configure the service name

4. Kubernetes metadata configuration
   
   In scenarios when your application runs on Kuberenetes, it is important to insert an additional attribute to the span generated by your microservice that allows the OpenTelemetry collector to properly assign Kubernetes infrastructure metadata.
   
   The k8s.pod.ip attribute contains the IP address of the pod and the simplest way to configure it in the Kubernetes deployment yaml file is to add the below code into the spec.template.spec.containers section:
   
   env:
 - name: MY_POD_IP
   valueFrom:
    fieldRef:
     fieldPath: status.podIP
 - name: OTEL_RESOURCE_ATTRIBUTES
   value: "service.name=my-service,k8s.pod.ip=$(MY_POD_IP)"
 - name: OTEL_EXPORTER_OTLP_ENDPOINT
   value: "http://collection-sumologic-otelcol.sumologic:55681"
 - name: OTEL_EXPORTER_OTLP_INSECURE
   value: "true"