opentelemetry-processor-baggage

Baggage Span Processor

This is an OpenTelemetry span processor that reads key/values stored in Baggage in the starting span's parent context and adds them as attributes to the span.

Keys and values added to Baggage will appear on all subsequent child spans, not the current active span, 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.

⚠️ Waning ⚠️ To repeat: a consequence of adding data to Baggage is that the keys and values will appear in all outgoing HTTP headers from the application. Do not put sensitive information in Baggage.

How do I get started?

Install the gem using:

gem install opentelemetry-processor-baggage

Or, if you use bundler, include opentelemetry-processor-baggage to your Gemfile.

Version Compatibility

• OpenTelemetry API v1.0+

Usage

To install the instrumentation, add the gem to your Gemfile:

gem 'opentelemetry-processor-baggage'

Then configure the span processor to copy all baggage entries:

require 'rubygems'
require 'bundler/setup'

Bundler.require

OpenTelemetry::SDK.configure do |c|
  # Add the BaggageSpanProcessor to the collection of span processors and
  # copy all baggage entries
  c.add_span_processor(OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
    OpenTelemetry::Processor::Baggage::ALLOW_ALL_BAGGAGE_KEYS
  ))

  # Because the span processor list is no longer empty, the SDK will not use the
  # values in OTEL_TRACES_EXPORTER to instantiate exporters.
  # You'll need to declare your own here in the configure block.
  #
  # These lines setup the default: a batching OTLP exporter.
  c.add_span_processor(
    # these constructors without arguments will pull config from the environment
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new()
    )
  )
end

Alternatively, you can provide a custom baggage key predicate to select which baggage keys you want to copy.

For example, to only copy baggage entries that start with myapp.:

OUR_BAGGAGE_KEY_PREFIX = 'myapp.'.freeze
OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
  # a constant here improves performance
  ->(baggage_key) { baggage_key.start_with?(OUR_BAGGAGE_KEY_PREFIX) }
)

For example, to only copy baggage entries that match myapp., myapp1. and myapp42.:

OUR_BAGGAGE_KEY_MATCHER = /\Amyapp\d*\./
OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new(
  ->(baggage_key) { OUR_BAGGAGE_KEY_MATCHER.match?(baggage_key) }
)

How can I get involved?

The opentelemetry-processor-baggage gem source is on github, along with related gems including opentelemetry-api and opentelemetry-sdk.

The OpenTelemetry Ruby gems are maintained by the OpenTelemetry Ruby special interest group (SIG). You can get involved by joining us on our GitHub Discussions, Slack Channel or attending our weekly meeting. See the meeting calendar for dates and times. For more information on this and other language SIGs, see the OpenTelemetry community page.

License

The opentelemetry-instrumentation-sinatra gem is distributed under the Apache 2.0 license. See LICENSE for more information.