From 56ff830daa6b018913c717abb971dc4669a62be4 Mon Sep 17 00:00:00 2001 From: Robb Kidd Date: Fri, 26 Jan 2024 13:50:16 -0500 Subject: [PATCH] docs: relocate Resque config option comments to render in Yard docs (#834) docs: move config option docs up to the Instrumentation class As formatted markdown comments on the class, the information is made visible in the Yard-generated docs without making the options appear to be class or instance variables. --- .../opentelemetry/instrumentation/resque.rb | 2 +- .../instrumentation/resque/instrumentation.rb | 80 +++++++++++++------ 2 files changed, 56 insertions(+), 26 deletions(-) diff --git a/instrumentation/resque/lib/opentelemetry/instrumentation/resque.rb b/instrumentation/resque/lib/opentelemetry/instrumentation/resque.rb index b1c3d3da7..0ffa565b6 100644 --- a/instrumentation/resque/lib/opentelemetry/instrumentation/resque.rb +++ b/instrumentation/resque/lib/opentelemetry/instrumentation/resque.rb @@ -9,7 +9,7 @@ module OpenTelemetry module Instrumentation - # Contains the OpenTelemetry instrumentation for the Resque gem + # (see OpenTelemetry::Instrumentation::Resque::Instrumentation) module Resque end end diff --git a/instrumentation/resque/lib/opentelemetry/instrumentation/resque/instrumentation.rb b/instrumentation/resque/lib/opentelemetry/instrumentation/resque/instrumentation.rb index 15cec6cea..f5f966c31 100644 --- a/instrumentation/resque/lib/opentelemetry/instrumentation/resque/instrumentation.rb +++ b/instrumentation/resque/lib/opentelemetry/instrumentation/resque/instrumentation.rb @@ -7,7 +7,61 @@ module OpenTelemetry module Instrumentation module Resque - # The Instrumentation class contains logic to detect and install the Resque instrumentation + # The {OpenTelemetry::Instrumentation::Resque::Instrumentation} class contains logic to detect and install the Resque 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. + # + # ### `:force_flush` + # + # Specifies whether spans are forcibly flushed (exported out of process) upon every job completion. + # + # - `:ask_the_job` **(default)** - Synchronously flush completed spans when a job completes if workers are + # forked for each job. + # - Determined by checking if {https://www.rubydoc.info/gems/resque/Resque%2FWorker:fork_per_job%3F Resque::Worker#fork_per_job?} + # is true. Spans must be flushed and exported before a worker process terminates or no telemetry will be sent. + # - `:always` - All completed spans will be synchronously flushed at the end of a job's execution. + # - `:never` - Job completion will not affect the export of spans out of worker processes. + # - Selecting this option will result in spans being lost if the worker process ends before + # the spans are flushed. You might select this option if you wish to coordinate the timing for flushing + # completed spans yourself. + # + # @example An explicit default configuration + # OpenTelemetry::SDK.configure do |c| + # c.use_all({ + # 'OpenTelemetry::Instrumentation::Resque' => { + # span_naming: :queue, + # propagation_style: :link + # force_flush: :ask_the_job, + # }, + # }) + # end class Instrumentation < OpenTelemetry::Instrumentation::Base install do |_config| require_dependencies @@ -18,30 +72,6 @@ class Instrumentation < OpenTelemetry::Instrumentation::Base defined?(::Resque) end - ## Supported configuration keys for the install config hash: - # - # force_flush: controls if spans are forcibly flushed upon job completion - # - :ask_the_job (default) - if `Resque::Worker#fork_per_job?` is set, - # all completed spans will be synchronously flushed at the end of a - # job's execution - # - :always - all completed spans will be synchronously flushed at the - # end of a job's execution - # - :never - the job will not intervene with the processing of spans - # - # span_naming: when `:job_class`, the span names will be set to - # ' '. When `:queue`, the span names - # will be set to ' ' - # - # propagation_style: controls how the job's execution is traced and related - # to the trace where the job was enqueued. Can be one of: - # - :link (default) - 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 :force_flush, default: :ask_the_job, validate: %I[ask_the_job always never] option :span_naming, default: :queue, validate: %I[job_class queue] option :propagation_style, default: :link, validate: %i[link child none]