docs: Fix doc for sidekiq options (#825)

* docs: ✏️ fix yard for sidekiq instrumentation options

* docs: Refactor Sidekiq instrumentation and add configuration options

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

Co-authored-by: Kayla Reopelle (she/her) <87386821+kaylareopelle@users.noreply.github.com>

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

Co-authored-by: Kayla Reopelle (she/her) <87386821+kaylareopelle@users.noreply.github.com>

---------

Co-authored-by: Ariel Valentin <arielvalentin@users.noreply.github.com>
Co-authored-by: Kayla Reopelle (she/her) <87386821+kaylareopelle@users.noreply.github.com>

instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq.rb

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

instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq/instrumentation.rb

@@ -7,8 +7,81 @@
 module OpenTelemetry
   module Instrumentation
     module Sidekiq
-      # The Instrumentation class contains logic to detect and install the Sidekiq
-      # instrumentation
+      # The `OpenTelemetry::Instrumentation::Sidekiq::Instrumentation` class contains logic to detect and install the Sidekiq 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
+      #
+      # ### `:span_naming`
+      #
+      # Specifies how the span names are set. Can be one of:
+      #
+      # - `:queue` **(default)** - The job span name will appear as '<destination / queue name> <operation>',
+      #   for example `default process`.
+      # - `:job_class` - The job span name will appear as '<job class name> <operation>',
+      #   for example `SimpleJob process`.
+      #
+      # ### `:propagation_style`
+      #
+      # Specifies how the job's execution is traced and related to the trace where the job was enqueued.
+      #
+      # - `:link` **(default)** - The job will be represented by a separate trace from the span that enqueued the job.
+      #     - The initial span of the job trace will be associated with the span that enqueued the job, via a
+      #       {https://opentelemetry.io/docs/concepts/signals/traces/#span-links Span Link}.
+      # - `:child` - The job will be represented within the same logical trace, as a direct
+      #   child of the span that enqueued the job.
+      # - `:none` - The job will be represented by a separate trace from the span that enqueued the job.
+      #   There will be no explicit relationship between the job trace and the trace containing the span that
+      #   enqueued the job.
+      #
+      # ### `:trace_launcher_heartbeat`
+      #
+      # Allows tracing Sidekiq::Launcher#heartbeat.
+      #
+      # - `false` **(default)** - Sidekiq::Launcher#heartbeat will not be traced.
+      # - `true` - Sidekiq::Launcher#heartbeat will be traced.
+      #
+      # ### `:trace_poller_enqueue`
+      #
+      # Allows tracing Sidekiq::Scheduled#enqueue.
+      #
+      # - `false` **(default)** - Sidekiq::Scheduled#enqueue will not be traced.
+      # - `true` - Sidekiq::Scheduled#enqueue will be traced.
+      #
+      # ### `:trace_poller_wait`
+      #
+      # Allows tracing Sidekiq::Scheduled#wait.
+      #
+      # - `false` **(default)** - Sidekiq::Scheduled#wait will not be traced.
+      # - `true` - Sidekiq::Scheduled#wait will be traced.
+      #
+      # ### `:trace_processor_process_one`
+      #
+      # Allows tracing Sidekiq::Processor#process_one.
+      #
+      # - `false` **(default)** - Sidekiq::Processor#process_one will not be traced.
+      # - `true` - Sidekiq::Processor#process_one will be traced.
+      #
+      # ### `:peer_service`
+      #
+      # Sets service name of the remote service.
+      #
+      # - `nil` **(default)**
+      #
+      # @example An explicit default configuration
+      #   OpenTelemetry::SDK.configure do |c|
+      #     c.use_all({
+      #       'OpenTelemetry::Instrumentation::Sidekiq' => {
+      #         span_naming: :queue,
+      #         propagation_style: :link,
+      #         trace_launcher_heartbeat: true,
+      #       },
+      #     })
+      #   end
       class Instrumentation < OpenTelemetry::Instrumentation::Base
         MINIMUM_VERSION = Gem::Version.new('4.2.10')
 
@@ -27,59 +100,13 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base
           gem_version >= MINIMUM_VERSION
         end
 
-        # @!group Instrumentation Options
-        # @!macro
-        #   @!method $1
-        #   @instrumentation_option_default `:$2`
-        #   @!scope class
-        #
-        #   Specify how the span names are set. Can be one of:
-        #
-        #   - `:queue` - the span names will be set to '<destination / queue name> <operation>'.
-        #   - `:job_class` - the span names will be set to '<job class name> <operation>'.
         option :span_naming,                 default: :queue, validate: %I[job_class queue]
-        #   Controls how the job's execution is traced and related
-        #   to the trace where the job was enqueued. Can be one of:
-        #
-        #   - `:link` - the job will be executed in a separate trace. The
-        #     initial span of the execution trace will be linked to the span that
-        #     enqueued the job, via a Span Link.
-        #   - `:child` - the job will be executed in the same logical trace, as a direct
-        #     child of the span that enqueued the job.
-        #   - `:none` - the job's execution will not be explicitly linked to the span that
-        #     enqueued the job.
         option :propagation_style,           default: :link,  validate: %i[link child none]
-        # @!macro
-        #   @!method $1
-        #   @instrumentation_option_default `:$2`
-        #   @!scope class
-        #   Allows tracing Sidekiq::Launcher#heartbeat.
         option :trace_launcher_heartbeat,    default: false, validate: :boolean
-        # @!macro
-        #   @!method $1
-        #   @instrumentation_option_default $2
-        #   @!scope class
-        #   Allows tracing Sidekiq::Scheduled#enqueue.
         option :trace_poller_enqueue,        default: false, validate: :boolean
-        # @!macro
-        #   @!method $1
-        #   @instrumentation_option_default $2
-        #   @!scope class
-        #   Allows trasing Sidekiq::Scheduled#wait
         option :trace_poller_wait,           default: false, validate: :boolean
-        # @!macro
-        #   @!method $1
-        #   @instrumentation_option_default $2
-        #   @!scope class
-        #   Allows tracing Sidekiq::Processor#process_one.
         option :trace_processor_process_one, default: false, validate: :boolean
-        # @!macro
-        #   @!method $1
-        #   @instrumentation_option_default $2
-        #   @!scope class
-        #   Sets service name of the remote service.
         option :peer_service,                default: nil,   validate: :string
-        # @!endgroup
 
         private