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.