diff --git a/processor/baggage/lib/opentelemetry/processor/baggage/baggage_span_processor.rb b/processor/baggage/lib/opentelemetry/processor/baggage/baggage_span_processor.rb index 58e857cef..bab951a60 100644 --- a/processor/baggage/lib/opentelemetry/processor/baggage/baggage_span_processor.rb +++ b/processor/baggage/lib/opentelemetry/processor/baggage/baggage_span_processor.rb @@ -14,12 +14,14 @@ module Baggage ALLOW_ALL_BAGGAGE_KEYS = ->(_) { true } # The BaggageSpanProcessor reads key/values stored in Baggage in the - # starting span's parent context and adds them as attributes to the span. + # starting span's parent context and adds them as attributes to the span, + # if a key matches a provided predicate lambda. # # Keys and values added to Baggage will appear on all subsequent child spans # for a trace within this service *and* will be propagated to external services # via propagation headers. If the external services also have a Baggage span - # processor, the keys and values will appear in those child spans as well. + # processor, the keys and values will appear in those child spans as well provided + # that the keys match any predicate method configured there. # # ⚠️ # To repeat: a consequence of adding data to Baggage is that the keys and @@ -27,11 +29,15 @@ module Baggage # Do not put sensitive information in Baggage. # ⚠️ # - # @example + # @example Adding the BaggageSpanProcessor to the SDK, only add attributes for keys that start with 'myapp.' + # OUR_BAGGAGE_KEY_PREFIX = 'myapp.'.freeze + # # OpenTelemetry::SDK.configure do |c| # # Add the BaggageSpanProcessor to the collection of span processors - # c.add_span_processor(OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new( - # OpenTelemetry::Processor::Baggage::ALLOW_ALL_BAGGAGE_KEYS) + # c.add_span_processor( + # OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new( + # ->(key) { key.start_with?(OUR_BAGGAGE_KEY_PREFIX) } # a constant here improves performance + # ) # ) # # # Because the span processor list is no longer empty, the SDK will not use the @@ -46,12 +52,24 @@ module Baggage # ) # ) # end + # + # @example Allow all Baggage keys to be added to the span as attributes + # OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new( + # # This processor provides a convenience predicate that allows all keys to be added as attributes. + # OpenTelemetry::Processor::Baggage::ALLOW_ALL_BAGGAGE_KEYS + # ) class BaggageSpanProcessor < OpenTelemetry::SDK::Trace::SpanProcessor # Create a new BaggageSpanProcessor that reads Baggage keys and values from the parent context # and adds them as attributes to the span. # - # @param [lambda] baggage_key_predicate A lambda that takes a baggage key and returns true if + # @param [lambda] baggage_key_predicate A lambda that takes a baggage key [String] and returns true if # the key should be added to the span as an attribute, false otherwise. + # + # @example Only add attributes for keys that start with a specific prefix + # OUR_BAGGAGE_KEY_PREFIX = 'myapp.'.freeze + # OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new( + # ->(key) { key.start_with?(OUR_BAGGAGE_KEY_PREFIX) } # a constant here improves performance + # ) def initialize(baggage_key_predicate) raise ArgumentError, 'baggage_key_predicate must respond to :call (lambda/Proc)' unless baggage_key_predicate.respond_to?(:call)