diff --git a/instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq.rb b/instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq.rb index 77fc78d76..530464dde 100644 --- a/instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq.rb +++ b/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 diff --git a/instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq/instrumentation.rb b/instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq/instrumentation.rb index 5f374c0ca..1f3fe2720 100644 --- a/instrumentation/sidekiq/lib/opentelemetry/instrumentation/sidekiq/instrumentation.rb +++ b/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 ' ', + # for example `default process`. + # - `:job_class` - The job span name will appear as ' ', + # 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 ' '. - # - `:job_class` - the span names will be set to ' '. 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