OpenTelemetry for Ruby can be used to add automatic and manual instrumentation to your applications. Automatic instrumentation is enabled by adding instrumentation packages. Manual instrumentation can be added using the OpenTelemetry API.
These instructions will explain how to set up automatic and manual instrumentation for a Ruby service. In order to follow along, you will need:
- Ruby 2.5 or higher
- Docker Compose
The first step is to add these gems to your Gemfile:
gem 'opentelemetry-sdk' gem 'opentelemetry-exporter-otlp' gem 'opentelemetry-instrumentation-all'
The inclusion of
opentelemetry-instrumentation-all in the above list provides instrumentations for several frameworks such as Rails and Sinatra as well as database drivers and HTTP libraries.
The OpenTelemetry initialization needs to happen early in your application lifecycle. For Rails applications, the usual way to initialize OpenTelemetry is in a Rails initializer. For other Ruby services, perform this initialization as early as possible in the start-up process.
# config/initializers/opentelemetry.rb require 'opentelemetry/sdk' require 'opentelemetry/exporter/otlp' require 'opentelemetry/instrumentation/all' OpenTelemetry::SDK.configure do |c| c.service_name = '<YOUR_SERVICE_NAME>' c.use_all() # enables all instrumentation! end
Now that you have setup your application to perform tracing, you’ll need to configure the SDK to export the traces somewhere. Our example loaded the
OTLP exporter, which the SDK tries to use by default. Next, we’ll use the OpenTelemetry Collector to receive these traces and visualize them using Jaeger and Zipkin!
The following section assumes you are new to OpenTelemetry or do not currently use a vendor that supports distributed tracing using OTLP. Please refer to your vendor’s product documentation if you would like to export your traces to a vendor for analysis and vizualization.
For the purposes of this tutorial you will configure an OpenTelemetry collector that will receive the traces and vizualize them using Jaeger or Zipkin UI.
First, start up an example system:
$> git clone email@example.com:open-telemetry/opentelemetry-ruby.git; \ cd open-telemetry-ruby/examples/otel-collector; \ docker-compose up -d
Next, you’ll have to let the SDK know where the collector endpoint is to receive traces.
OTEL_EXPORTER_OTLP_ENDPOINT environment variable to
Now, start up your application and perform a few operations to generate tracing data, e.g. navigate around your web app or kick off background tasks.
Achievement Unlocked: Tracing Enabled
Adding tracing to a single service is a great first step and although auto-instrumenation provides quite a bit of insight on its own, OpenTelemetry provides a few more features that will allow you gain even deeper insights!
Context Propagation is perhaps one of the most powerful concepts in OpenTelemetry because it will upgrade your single service trace into a distributed trace, which makes it possible for OpenTelemetry vendors to visualize a request from end-to-end accross process and network boundaries.
Span Events allow you to add a human-readable message on a span that represents “something happening” during its lifetime.
Manual Instrumentation will give provide you the ability to enrich your traces with domain specific data.