Add spans

Author: muripic

instrumentation/grape/README.md

@@ -1,6 +1,15 @@
 # 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 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`
+- `format_response.grape`
 
 ## How do I get started?
 
@@ -22,6 +31,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", it is recommended to use this instrumentation 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 +41,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`, `:format_response`.
+- 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 ignored. 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,30 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Instrumentation
+    module Grape
+      # Contains custom subscribers that implement the ActiveSupport::Notifications::Fanout::Subscribers::Evented
+      # interface. Custom subscribers are needed to create a span at the start of an event, for example.
+      #
+      # Reference: https://github.com/rails/rails/blob/05cb63abdaf6101e6c8fb43119e2c0d08e543c28/activesupport/lib/active_support/notifications/fanout.rb#L320-L322
+      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,133 @@
+# 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
+
+            handle_payload_exception(span, payload[:exception_object]) if payload[:exception_object]
+
+            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_payload_exception(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
+            return if (!filters || filters.empty?) || !type || (finish - start).zero?
+
+            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_payload_exception(span, payload[:exception_object]) if payload[:exception_object]
+            end
+          end
+
+          # Handles the format_response.grape event
+          def format_response(_name, start, _finish, _id, payload)
+            endpoint = payload[:env]['api.endpoint']
+            name = span_name(endpoint)
+            attributes = {
+              'component' => 'template',
+              'operation' => 'format_response',
+              'grape.formatter.type' => formatter_type(payload[:formatter])
+            }
+            tracer.in_span(name, attributes: attributes, start_timestamp: start, kind: :server) do |span|
+              handle_payload_exception(span, payload[:exception_object]) if payload[:exception_object]
+            end
+          end
+
+          private
+
+          def tracer
+            Grape::Instrumentation.instance.tracer
+          end
+
+          def span_name(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' => endpoint.options[:for]&.base.to_s,
+              '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
+
+          # ActiveSupport::Notifications will attach a `:exception_object` to the payload if there was
+          # an error raised during the execution of the &block associated to the Notification.
+          # This can be safely added to the span for tracing.
+          def handle_payload_exception(span, exception)
+            span.record_exception(exception)
+            span.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{exception.class}")
+          end
+
+          def request_method(endpoint)
+            endpoint.options[: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
+
+          def formatter_type(formatter)
+            basename = formatter.name.split('::').last
+            # Convert from CamelCase to snake_case
+            basename.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+          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,11 @@ def gem_version
         end
 
         def require_dependencies
-          require_relative 'handler'
+          require_relative 'subscriber'
         end
 
         def subscribe
-          Handler.subscribe
+          Subscriber.subscribe
         end
       end
     end