feat: Make Rack install optional for sinatra (#1019)

* feat: Make Rack install optional for sinatra

This allows for scenarios when there are multiple Rack Applications mounted in the same builder and you want to avoid installing the Rack Events middleware multiple times in the stack.

A common example is a Rails application that mounts a Sinatra App in the routes file:

```ruby

Rails.application.routes.draw do
  mount Sinatra::Application, at: '/sinatra'
end

```

This results in the Rack middleware being installed multiple times.

Once by the Rails ActionPack instrumentation and then by the Sinatra application leading to multiple Rack spans being created in the same trace.

This change allows you to avoid this by setting the install_rack option to false when using Sinatra instrumentation and allowing users to manually configure the middleware in the stack as they see fit.

* very strange

* squash: will this work

* squash: wtf

* squash: fix tests

* squash: Add docs PR feedback

* squash: add example

* squash: add more test

* Update instrumentation/sinatra/lib/opentelemetry/instrumentation/sinatra/instrumentation.rb

Co-authored-by: Kayla Reopelle (she/her) <[email protected]>

* Update instrumentation/sinatra/test/opentelemetry/instrumentation/sinatra_test.rb

Co-authored-by: Kayla Reopelle (she/her) <[email protected]>

---------

Co-authored-by: Kayla Reopelle (she/her) <[email protected]>

Author: arielvalentin

instrumentation/sinatra/Appraisals

@@ -15,3 +15,7 @@ end
 appraise 'sinatra-2.x' do
   gem 'sinatra', '~> 2.1'
 end
+
+appraise 'sinatra-latest' do
+  gem 'sinatra'
+end

instrumentation/sinatra/example/config.ru

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Example rack application that manually manages tracer middleware
+
+require 'rubygems'
+require 'bundler/setup'
+
+Bundler.require
+
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
+OpenTelemetry::SDK.configure do |c|
+  c.use_all({
+    'OpenTelemetry::Instrumentation::Rack' => { },
+    'OpenTelemetry::Instrumentation::Sinatra' => { install_rack: false }
+  })
+end
+
+# Example application for the Sinatra instrumentation
+class App < Sinatra::Base
+  set :show_exceptions, false
+
+  template :example_render do
+    'Example Render'
+  end
+
+  get '/example' do
+    'Sinatra Instrumentation Example'
+  end
+
+  # Uses `render` method
+  get '/example_render' do
+    erb :example_render
+  end
+
+  get '/thing/:id' do
+    'Thing 1'
+  end
+
+  get '/error' do
+    raise 'Panic!'
+  end
+end
+
+use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
+run App

instrumentation/sinatra/lib/opentelemetry/instrumentation/sinatra.rb

@@ -9,7 +9,7 @@
 
 module OpenTelemetry
   module Instrumentation
-    # Contains the OpenTelemetry instrumentation for the Sinatra gem
+    # (see OpenTelemetry::Instrumentation::Sinatra::Instrumentation)
     module Sinatra
     end
   end

instrumentation/sinatra/lib/opentelemetry/instrumentation/sinatra/extensions/tracer_extension.rb

@@ -13,23 +13,25 @@ module Extensions
         # Sinatra extension that installs TracerMiddleware and provides
         # tracing for template rendering
         module TracerExtension
-          # Sinatra hook after extension is registered
-          def self.registered(app)
-            # Create tracing `render` method
-            ::Sinatra::Base.module_eval do
-              def render(_engine, data, *)
-                template_name = data.is_a?(Symbol) ? data : :literal
+          # Contants patches for `render` method
+          module RenderPatches
+            def render(_engine, data, *)
+              template_name = data.is_a?(Symbol) ? data : :literal
 
-                Sinatra::Instrumentation.instance.tracer.in_span(
-                  'sinatra.render_template',
-                  attributes: { 'sinatra.template_name' => template_name.to_s }
-                ) do
-                  super
-                end
+              Sinatra::Instrumentation.instance.tracer.in_span(
+                'sinatra.render_template',
+                attributes: { 'sinatra.template_name' => template_name.to_s }
+              ) do
+                super
               end
             end
-            app.use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
-            app.use(Middlewares::TracerMiddleware)
+          end
+
+          # Sinatra hook after extension is registered
+          def self.registered(app)
+            # Create tracing `render` method
+            ::Sinatra::Base.prepend(RenderPatches)
+            Sinatra::Instrumentation.instance.install_middleware(app)
           end
         end
       end

instrumentation/sinatra/lib/opentelemetry/instrumentation/sinatra/instrumentation.rb

@@ -9,18 +9,51 @@
 module OpenTelemetry
   module Instrumentation
     module Sinatra
-      # The Instrumentation class contains logic to detect and install the Sinatra
-      # instrumentation
+      # The {OpenTelemetry::Instrumentation::Sinatra::Instrumentation} class contains logic to detect and install the Sinatra instrumentation
+      #
+      # Installation and configuration of this instrumentation is done within the
+      # {https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK#configure-instance_method OpenTelemetry::SDK#configure}
+      # block, calling {https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry%2FSDK%2FConfigurator:use use()}
+      # or {https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry%2FSDK%2FConfigurator:use_all use_all()}.
+      #
+      # ## Configuration keys and options
+      #
+      # ### `:install_rack`
+      #
+      # Default is `true`. Specifies whether or not to install the Rack instrumentation as part of installing the Sinatra instrumentation.
+      # This is useful in cases where you have multiple Rack applications but want to manually specify where to insert the tracing middleware.
+      #
+      # @example Manually install Rack instrumentation.
+      #   OpenTelemetry::SDK.configure do |c|
+      #     c.use_all({
+      #       'OpenTelemetry::Instrumentation::Rack' => { },
+      #       'OpenTelemetry::Instrumentation::Sinatra' => {
+      #         install_rack: false
+      #       },
+      #     })
+      #   end
+      #
       class Instrumentation < OpenTelemetry::Instrumentation::Base
-        install do |_|
-          OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.install({})
+        install do |config|
+          OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.install({}) if config[:install_rack]
+
+          unless OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.installed?
+            OpenTelemetry.logger.warn('Rack instrumentation is required for Sinatra but not installed. Please see the docs for more details: https://opentelemetry.io/docs/languages/ruby/libraries/')
+          end
 
           ::Sinatra::Base.register Extensions::TracerExtension
         end
 
+        option :install_rack, default: true, validate: :boolean
+
         present do
           defined?(::Sinatra)
         end
+
+        def install_middleware(app)
+          app.use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args) if config[:install_rack]
+          app.use(Middlewares::TracerMiddleware)
+        end
       end
     end
   end

instrumentation/sinatra/test/opentelemetry/instrumentation/sinatra_test.rb

@@ -11,6 +11,7 @@
 
   let(:instrumentation) { OpenTelemetry::Instrumentation::Sinatra::Instrumentation.instance }
   let(:exporter) { EXPORTER }
+  let(:config) { {} }
 
   class CustomError < StandardError; end
 
@@ -66,7 +67,14 @@ class CustomError < StandardError; end
   end
 
   before do
-    instrumentation.install
+    Sinatra::Base.reset!
+
+    OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.instance_variable_set(:@installed, false)
+    OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.config.clear
+
+    instrumentation.instance_variable_set(:@installed, false)
+    instrumentation.config.clear
+    instrumentation.install(config)
     exporter.reset
   end
 
@@ -169,4 +177,48 @@ class CustomError < StandardError; end
       _(exporter.finished_spans.first.events[0].attributes['exception.message']).must_equal('custom message')
     end
   end
+
+  describe 'when install_rack is set to false' do
+    let(:config) { { install_rack: false } }
+
+    describe 'missing rack installation' do
+      it 'disables tracing' do
+        get '/one/endpoint'
+
+        _(exporter.finished_spans).must_be_empty
+      end
+    end
+
+    describe 'when rack is manually installed' do
+      let(:app) do
+        apps_to_build = apps
+        Rack::Builder.new do
+          use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
+
+          apps_to_build.each do |root, app|
+            map root do
+              run app
+            end
+          end
+        end.to_app
+      end
+
+      before do
+        OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.install
+      end
+
+      it 'creates a span' do
+        get '/one/endpoint'
+
+        _(exporter.finished_spans.first.attributes).must_equal(
+          'http.method' => 'GET',
+          'http.host' => 'example.org',
+          'http.scheme' => 'http',
+          'http.target' => '/one/endpoint',
+          'http.route' => '/endpoint',
+          'http.status_code' => 200
+        )
+      end
+    end
+  end
 end