Add instrumentation

Author: Muriel Picone Farías

instrumentation/grape/README.md

@@ -1,6 +1,14 @@
 # OpenTelemetry Grape Instrumentation
 
-Todo: Add a description.
+The Grape instrumentation is a community-maintained instrumentation for [Grape](https://github.com/ruby-grape/grape), a REST-like API framework for Ruby.
+
+It relies mostly on the Grape built-in support for `ActiveSupport::Notifications` (more info [here](https://github.com/ruby-grape/grape#active-support-instrumentation)).
+
+It currently supports the following events:
+
+- `endpoint_run.grape`
+- `endpoint_render.grape`
+- `endpoint_run_filters.grape`
 
 ## How do I get started?
 
@@ -22,6 +30,8 @@ OpenTelemetry::SDK.configure do |c|
 end
 ```
 
+Since Grape is "designed to run on Rack or complement existing web application frameworks such as Rails and Sinatra", we recommend using it along with the Rack, Rails and/or Sinatra instrumentations.
+
 Alternatively, you can also call `use_all` to install all the available instrumentation.
 
 ```ruby
@@ -30,6 +40,32 @@ OpenTelemetry::SDK.configure do |c|
 end
 ```
 
+### Configuration options
+
+#### `:ignored_events` (array)
+
+Indicate if any events should not produce spans.
+
+- Accepted values: `:endpoint_render`, `:endpoint_run_filters`.
+- Defaults to `[]` (no ignored events).
+
+Example:
+
+```ruby
+OpenTelemetry::SDK.configure do |c|
+  c.use 'OpenTelemetry::Instrumentation::Grape', { ignored_events: [:endpoint_run_filters] }
+end
+```
+
+Note that the `endpoint_run` event cannot be disabled since it is the parent event. If you need to disable the instrumentation, set `:enabled` to `false`:
+
+```ruby
+OpenTelemetry::SDK.configure do |c|
+  config = { 'OpenTelemetry::Instrumentation::Grape' => { enabled: false } }
+  c.use_all(config)
+end
+```
+
 ## Examples
 
 Example usage can be seen in the `./example/trace_demonstration.rb` file [here](https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/instrumentation/grape/example/trace_demonstration.rb)

instrumentation/grape/example/trace_demonstration.rb

@@ -9,14 +9,15 @@
 require 'opentelemetry-instrumentation-grape'
 require 'grape'
 
-# Export traces to console by default
+# Export traces to console
 ENV['OTEL_TRACES_EXPORTER'] ||= 'console'
 
 OpenTelemetry::SDK.configure do |c|
+  c.service_name = 'trace_demonstration'
   c.use 'OpenTelemetry::Instrumentation::Grape'
 end
 
-# A basic Grape endpoint example
+# A basic Grape API example
 class ExampleAPI < Grape::API
   format :json
 
@@ -27,12 +28,8 @@ class ExampleAPI < Grape::API
 
   desc 'Return information about a user'
   # Filters
-  before do
-    sleep(0.01)
-  end
-  after do
-    sleep(0.01)
-  end
+  before { sleep(0.01) }
+  after { sleep(0.01) }
   params do
     requires :id, type: Integer, desc: 'User ID'
   end
@@ -42,9 +39,8 @@ class ExampleAPI < Grape::API
 end
 
 # Set up fake Rack application
-builder = Rack::Builder.app do
-  run ExampleAPI
-end
+builder = Rack::Builder.app { run ExampleAPI }
+app = Rack::MockRequest.new(builder)
 
-Rack::MockRequest.new(builder).get('/hello')
-Rack::MockRequest.new(builder).get('/users/1')
+app.get('/hello')
+app.get('/users/1')

instrumentation/grape/lib/opentelemetry/instrumentation/grape/custom_subscribers/endpoint_run.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Grape
+      # Contains all custom subscriber classes that implement the ActiveSupport::Subscriber interface
+      # Custom subscribers are needed to create a span at the start of an event, for example.
+      module CustomSubscribers
+        # Implements the ActiveSupport::Subscriber interface to instrument the start and finish of the endpoint_run event
+        class EndpointRun
+          # Runs at the start of the event that triggers the ActiveSupport::Notification
+          def start(name, id, payload)
+            EventHandler.endpoint_run_start(name, id, payload)
+          end
+
+          # Runs at the end of the event that triggers the ActiveSupport::Notification
+          def finish(name, id, payload)
+            EventHandler.endpoint_run_finish(name, id, payload)
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/grape/lib/opentelemetry/instrumentation/grape/event_handler.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Grape
+      # Handles the events instrumented with ActiveSupport notifications.
+      # These handlers contain all the logic needed to create and connect spans.
+      class EventHandler
+        class << self
+          # Handles the start of the endpoint_run.grape event (the parent event), where the context is attached
+          def endpoint_run_start(_name, _id, payload)
+            name = span_name(payload[:endpoint])
+            span = tracer.start_span(name, attributes: run_attributes(payload), kind: :server)
+            token = OpenTelemetry::Context.attach(OpenTelemetry::Trace.context_with_span(span))
+
+            payload.merge!(
+              __opentelemetry_span: span,
+              __opentelemetry_ctx_token: token
+            )
+          end
+
+          # Handles the end of the endpoint_run.grape event (the parent event), where the context is detached
+          def endpoint_run_finish(_name, _id, payload)
+            span = payload.delete(:__opentelemetry_span)
+            token = payload.delete(:__opentelemetry_ctx_token)
+            return unless span && token
+
+            if payload[:exception_object]
+              handle_error(span, payload[:exception_object])
+            else
+              span.set_attribute(OpenTelemetry::SemanticConventions::Trace::HTTP_STATUS_CODE, payload[:endpoint].status)
+            end
+
+            span.finish
+            OpenTelemetry::Context.detach(token)
+          end
+
+          # Handles the endpoint_render.grape event
+          def endpoint_render(_name, start, _finish, _id, payload)
+            name = span_name(payload[:endpoint])
+            attributes = {
+              'component' => 'template',
+              'operation' => 'endpoint_render'
+            }
+            tracer.in_span(name, attributes: attributes, start_timestamp: start, kind: :server) do |span|
+              handle_error(span, payload[:exception_object]) if payload[:exception_object]
+            end
+          end
+
+          # Handles the endpoint_run_filters.grape events
+          def endpoint_run_filters(_name, start, finish, _id, payload)
+            filters = payload[:filters]
+            type = payload[:type]
+
+            # Prevent submitting empty filters
+            zero_length = (finish - start).zero?
+            return if (!filters || filters.empty?) || !type || zero_length
+
+            name = span_name(payload[:endpoint])
+            attributes = {
+              'component' => 'web',
+              'operation' => 'endpoint_run_filters',
+              'grape.filter.type' => type.to_s
+            }
+            tracer.in_span(name, attributes: attributes, start_timestamp: start, kind: :server) do |span|
+              handle_error(span, payload[:exception_object]) if payload[:exception_object]
+            end
+          end
+
+          private
+
+          def tracer
+            Grape::Instrumentation.instance.tracer
+          end
+
+          def span_name(endpoint)
+            "#{api_instance(endpoint)} #{request_method(endpoint)} #{path(endpoint)}"
+          end
+
+          def run_attributes(payload)
+            endpoint = payload[:endpoint]
+            path = path(endpoint)
+            {
+              'component' => 'web',
+              'operation' => 'endpoint_run',
+              'grape.route.endpoint' => api_instance(endpoint),
+              'grape.route.path' => path,
+              'grape.route.method' => endpoint.options[:method].first,
+              OpenTelemetry::SemanticConventions::Trace::HTTP_METHOD => request_method(endpoint),
+              OpenTelemetry::SemanticConventions::Trace::HTTP_ROUTE => path
+            }
+          end
+
+          def handle_error(span, exception)
+            span.record_exception(exception)
+            span.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{exception.class}")
+            return unless exception.respond_to?('status')
+
+            span.set_attribute(OpenTelemetry::SemanticConventions::Trace::HTTP_STATUS_CODE, exception.status)
+          end
+
+          def api_instance(endpoint)
+            endpoint.options[:for].base.to_s
+          end
+
+          def request_method(endpoint)
+            endpoint.options.fetch(:method).first
+          end
+
+          def path(endpoint)
+            namespace = endpoint.routes.first.namespace
+            version = endpoint.routes.first.options[:version] || ''
+            prefix = endpoint.routes.first.options[:prefix].to_s || ''
+            parts = [prefix, version] + namespace.split('/') + endpoint.options[:path]
+            parts.reject { |p| p.blank? || p.eql?('/') }.join('/').prepend('/')
+          end
+        end
+      end
+    end
+  end
+end

instrumentation/grape/lib/opentelemetry/instrumentation/grape/handler.rb

@@ -9,6 +9,7 @@ module Instrumentation
     module Grape
       # The Instrumentation class contains logic to detect and install the Grape instrumentation
       class Instrumentation < OpenTelemetry::Instrumentation::Base
+        # Minimum Grape version needed for compatibility with this instrumentation
         MINIMUM_VERSION = Gem::Version.new('1.2.0')
 
         install do |_config|
@@ -21,18 +22,10 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
         end
 
         compatible do
-          # ActiveSupport::Notifications were introduced in Grape 0.13.0
-          # https://github.com/ruby-grape/grape/blob/master/CHANGELOG.md#0130-2015810
           gem_version >= MINIMUM_VERSION
         end
 
-        # Config options available in ddog Grape instrumentation
-        option :enabled, default: true, validate: :boolean
-        option :error_statuses, default: [], validate: :array
-        # Config options necessary for OpenTelemetry::Instrumentation::ActiveSupport.subscribe called in railtie
-        # instrumentation/active_support/lib/opentelemetry/instrumentation/active_support/span_subscriber.rb#L23
-        # Used to validate if any of the payload keys are invalid
-        option :disallowed_notification_payload_keys, default: [], validate: :array
+        option :ignored_events, default: [], validate: :array
 
         private
 
@@ -41,11 +34,13 @@ def gem_version
         end
 
         def require_dependencies
-          require_relative 'handler'
+          require_relative 'subscriber'
+          require_relative 'event_handler'
+          require_relative 'custom_subscribers/endpoint_run'
         end
 
         def subscribe
-          Handler.subscribe
+          Subscriber.subscribe
         end
       end
     end