NH-90184: add doc for add_tracer api call

README.md

@@ -64,9 +64,11 @@ Note that if `OpenTelemetry::SDK.configure` is used to set up a `TracerProvider`
 
 Several convenience and vendor-specific APIs are availabe to an application where `solarwinds_apm` has been loaded, below is a quick overview of the features provided. The full reference can be found at the [RubyDoc page for this gem](https://rubydoc.info/github/solarwinds/apm-ruby).
 
-#### Convenience Method for in_span
+#### Convenience Method: `in_span` and `add_tracer`
 
-This method acquires the correct `Tracer` so a new span can be created in a single call, below is a simple Rails controller example:
+`in_span` acquires the correct `Tracer` so a new span can be created in a single call.
+
+For example, using it in a Rails controller:
 
 ```ruby
 class StaticController < ApplicationController
@@ -78,6 +80,40 @@ class StaticController < ApplicationController
 end
 ```
 
+`add_tracer` can add a custom span to the specified instance or class method that is already defined. It requires the custom span name and optionally takes the span kind and additional attributes in hash format:
+
+```ruby
+add_tracer :method_name, 'custom_span_name', { attributes: { 'any' => 'attributes' }, kind: :span_kind }
+```
+
+For example, if you want to instrument class or instance method `create_session` inside an application controller:
+
+```ruby
+class SessionsController < ApplicationController
+  include SolarWindsAPM::API::Tracer
+
+  def create
+    user = User.find_by(email: params[:session][:email].downcase)
+    create_session(user)
+  end
+
+  def create_session(user)
+  end
+
+  def self.create_session(user)
+  end
+
+  # instrument instance method create_session
+  add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+
+  # instrument class method create_session
+  class << self
+    include SolarWindsAPM::API::Tracer
+    add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+  end
+end
+```
+
 #### Get Curent Trace Context Information
 
 The `current_trace_info` method returns a `TraceInfo` object containing string representations of the current trace context that can be used in logging or manual propagation of context. This is a convenience method that wraps the OTel API `::OpenTelemetry::Trace.current_span`.

lib/solarwinds_apm/api/custom_instrumentation.rb

@@ -14,6 +14,37 @@ def self.included(base)
       end
 
       module ClassMethods
+        # Helper function to instrument custom function
+        #
+        # `add_tracer` can add a custom span to the specified instance or class method that is already defined.
+        # It requires the custom span name and optionally takes the span kind and additional attributes
+        # in hash format.
+        #
+        # === Argument:
+        #
+        # * +method_name+ - (String) A non-empty string that match the function name that need to be instrumented
+        # * +span_name+ - (String, optional, default = method_name) A non-empty string that define the span name (default to method_name)
+        # * +options+ - (Hash, optional, default = {}) A hash with desired attributes
+        #
+        # === Example:
+        #
+        #   class DogfoodsController < ApplicationController
+        #
+        #     def create
+        #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+        #       @dogfood.save
+        #       custom_function
+        #     end
+        #
+        #     def custom_function
+        #     end
+        #     add_tracer :custom_function, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+        #
+        #   end
+        #
+        # === Returns:
+        # * nil
+        #
         def add_tracer(method_name, span_name = nil, options = {})
           span_name = name.nil? ? "#{to_s.split(':').last&.tr('>', '')}/#{__method__}" : "#{name}/#{__method__}" if span_name.nil?
 

test/run_tests.sh

@@ -19,7 +19,6 @@ check_status() {
 
 gemfiles=(
   "gemfiles/unit.gemfile"
-  "gemfiles/rails_6x.gemfile"
 )
 
 ##