OpenTelemetry Instrumentation for Ruby
Overview
OpenTelemetry provides instrumentation for Ruby applications, enabling you to collect telemetry data such as traces and metrics. Although Lumigo does not offer its own OpenTelemetry Distribution for Ruby, you can still configure it. This guide explains how to set up OpenTelemetry Ruby Automatic Instrumentation and configure it to report data to Lumigo.
Prerequisites
Before you begin, ensure you have the following:
- A Lumigo Token, which can be found in Settings > Tracing > Manual Tracing. For more details, see the Lumigo Tokens documentation.
- Ruby version compatible with OpenTelemetry Ruby SDK.
Install OpenTelemetry Ruby Automatic Instrumentation and instrument your Ruby application using the provided packages.
1. Install OpenTelemetry Packages
Add the required OpenTelemetry packages to your Gemfile
:
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-all'
2. Enable Instrumentation Libraries
Enable the instrumentation libraries that match the libraries you’re using in your application. Create or update the configuration file at 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.service_name = '<YOUR_SERVICE_NAME>'
c.use_all() # enables all instrumentation!
end
3. Ensure All Spans Are Sent
Properly shut down the tracer to ensure that all spans are sent before the application exits
OpenTelemetry.tracer_provider.shutdown
This step is crucial in long-running applications or background jobs to avoid losing any telemetry data.
4. Record Code Exceptions (Optional)
To record code exceptions in spans manually, add the following code:
require "opentelemetry/sdk"
current_span = OpenTelemetry::Trace.current_span
begin
1/0 # something that obviously fails
rescue Exception => e
current_span.status = OpenTelemetry::Trace::Status.error("error message here!")
current_span.record_exception(e)
raise e
ensure
current_span.finish
OpenTelemetry.tracer_provider.shutdown
end
5. Run Your Ruby Application with OpenTelemetry Instrumentation
Configure the environment variables and run your Ruby application with OpenTelemetry instrumentation enabled:
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ga-otlp.lumigo-tracer-edge.golumigo.com"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=LumigoToken <YOUR LUMIGO TOKEN>"
export OTEL_SERVICE_NAME=<YOUR_SERVICE_NAME> # OPTIONAL
Replace <token>
with your Lumigo token, which is available in Settings -> Tracing -> Manual tracing
, see the Lumigo Tokens documentation.
Best Practices and Recommendations
- Use Environment Variables: Store sensitive information like the Lumigo token as environment variables for improved security.
- Keep Dependencies Updated: Ensure you're using the latest version of OpenTelemetry .NET Automatic Instrumentation.
- Enable Debug Logging (Optional): If you encounter issues, enable debug logging by setting:
OTEL\_LOG\_LEVEL=debug
This can help you troubleshoot any configuration or connectivity issues.
Updated about 4 hours ago