Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Fix doc for sidekiq options #825

Merged
merged 8 commits into from
Feb 8, 2024
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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