Docs » Instrument back-end applications to send spans to Splunk APM » Instrument Ruby applications for Splunk Observability Cloud » Manually instrument Ruby applications for Splunk Observability Cloud

Manually instrument Ruby applications for Splunk Observability Cloud 🔗

Instrumenting applications automatically using the agent of the Splunk Distribution of OpenTelemetry Ruby covers most needs. Manually instrumenting your application is only necessary when, for example, you need to add custom attributes to spans or need to manually generate spans.

Libraries installation 🔗

With manual instrumentation, you can install and enable instrumentation libraries separately. This lets you control which gems Ruby retrieves when building your project.

To learn how to manually instrument a Ruby application, see https://opentelemetry.io/docs/instrumentation/ruby/manual/ at OpenTelemetry.io.

To install and enable an instrumentation library manually:

  1. Install the instrumentation library using gem install or by including it in the project’s Gemfile. For example, to install the Sinatra instrumentation, add the following to your Gemfile:

    gem "opentelemetry-instrumentation-sinatra", "~> 0.21"
    
  2. In a block passed to the Splunk::Otel.configure method, configure the SDK to use each of the instrumentation libraries. In the case of the Sinatra instrumentation, the block would look like the following example:

    require "splunk/otel"
    Splunk::Otel.configure do |c|
    c.use "OpenTelemetry::Instrumentation::Sinatra", { opt: "value" }
    end
    

Instrument a Rails application 🔗

To instrument a Ruby on Rails application, follow these steps:

  1. Add the instrumentation library it to your project’s Gemfile:

    gem "opentelemetry-instrumentation-rails", "~> 0.27"
    

    You can also install the gem using bundle:

    bundle add opentelemetry-instrumentation-rails --version "~> 0.27"
    
  2. Configure OpenTelemetry to use all available instrumentation libraries:

    # config/initializers/opentelemetry.rb
    require "splunk/otel"
    ...
    Splunk::Otel.configure do |c|
    c.use_all()
    end
    

    You can disable specific instrumentations through the use_all function. For example:

    Splunk::Otel.configure do |c|
    c.use_all({ 'OpenTelemetry::Instrumentation::ActiveRecord' => { enabled: false } })
    end
    
  3. To enable only Rails, you can use a single c.use statement:

    Splunk::Otel.configure do |c|
    c.use 'OpenTelemetry::Instrumentation::Rails'
    end
    

For an example, see Rails 7 example.

Manual instrumentation for spans and events 🔗

For examples of manual instrumentation for Ruby, see the official OpenTelemetry documentation.

Note

Manual OTel instrumentation is fully compatible with Splunk automatic Ruby instrumentation and is fully supported by Splunk.