Merge pull request #174 from solarwinds/NH-90184

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,51 @@ class StaticController < ApplicationController
 end
 ```
 
+`add_tracer` can add a custom span to the specified instance or class method that is already defined. It can optionally set the span kind and additional attributes provided 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:
+
+To instrument instance method
+```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
+
+  # instrument instance method create_session
+  add_tracer :create_session, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+end
+```
+
+To instrument class method
+```ruby
+class SessionsController < ApplicationController
+  def create
+    user = User.find_by(email: params[:session][:email].downcase)
+    create_session(user)
+  end
+
+  def self.create_session(user)
+  end
+
+  # 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,55 @@ def self.included(base)
       end
 
       module ClassMethods
+        # Helper method to instrument custom method
+        #
+        # `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 method 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 options include attributes and span kind e.g. {attributes: {}, kind: :consumer}
+        #
+        # === Example:
+        #
+        #   class DogfoodsController < ApplicationController
+        #     include SolarWindsAPM::API::Tracer
+        #
+        #     def create
+        #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+        #       @dogfood.save
+        #       custom_method
+        #     end
+        #
+        #     def custom_method
+        #     end
+        #     add_tracer :custom_method, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+        #
+        #   end
+        #
+        #   class DogfoodsController < ApplicationController
+        #     def create
+        #       @dogfood = Dogfood.new(params.permit(:brand, :name))
+        #       @dogfood.save
+        #       custom_method
+        #     end
+        #
+        #     def self.custom_method
+        #     end
+        #
+        #     class << self
+        #       include SolarWindsAPM::API::Tracer
+        #       add_tracer :custom_method, 'custom_name', { attributes: { 'foo' => 'bar' }, kind: :consumer }
+        #     end
+        #
+        #   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?