cw-datadog 2.23.0.2

data/lib/datadog/tracing/diagnostics/health.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'ext'
+
+module Datadog
+  module Tracing
+    module Diagnostics
+      # Health-related diagnostics
+      module Health
+        # Health metrics for diagnostics
+        module Metrics
+          def self.extended(base)
+            base.class_eval do
+              count :api_errors, Ext::Health::Metrics::METRIC_API_ERRORS
+              count :api_requests, Ext::Health::Metrics::METRIC_API_REQUESTS
+              count :api_responses, Ext::Health::Metrics::METRIC_API_RESPONSES
+              count :error_context_overflow, Ext::Health::Metrics::METRIC_ERROR_CONTEXT_OVERFLOW
+              count :error_instrumentation_patch, Ext::Health::Metrics::METRIC_ERROR_INSTRUMENTATION_PATCH
+              count :error_span_finish, Ext::Health::Metrics::METRIC_ERROR_SPAN_FINISH
+              count :error_unfinished_spans, Ext::Health::Metrics::METRIC_ERROR_UNFINISHED_SPANS
+              count :instrumentation_patched, Ext::Health::Metrics::METRIC_INSTRUMENTATION_PATCHED
+              count :queue_accepted, Ext::Health::Metrics::METRIC_QUEUE_ACCEPTED
+              count :queue_accepted_lengths, Ext::Health::Metrics::METRIC_QUEUE_ACCEPTED_LENGTHS
+              count :queue_dropped, Ext::Health::Metrics::METRIC_QUEUE_DROPPED
+              count :traces_filtered, Ext::Health::Metrics::METRIC_TRACES_FILTERED
+              count :transport_trace_too_large, Ext::Health::Metrics::METRIC_TRANSPORT_TRACE_TOO_LARGE
+              count :transport_chunked, Ext::Health::Metrics::METRIC_TRANSPORT_CHUNKED
+              count :writer_cpu_time, Ext::Health::Metrics::METRIC_WRITER_CPU_TIME
+
+              gauge :queue_length, Ext::Health::Metrics::METRIC_QUEUE_LENGTH
+              gauge :queue_max_length, Ext::Health::Metrics::METRIC_QUEUE_MAX_LENGTH
+              gauge :queue_spans, Ext::Health::Metrics::METRIC_QUEUE_SPANS
+              gauge :sampling_service_cache_length, Ext::Health::Metrics::METRIC_SAMPLING_SERVICE_CACHE_LENGTH
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/b3_multi.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'helpers'
+require_relative '../trace_digest'
+require_relative '../utils'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # B3 multi header-style trace propagation.
+      # @see https://github.com/openzipkin/b3-propagation#multiple-headers
+      class B3Multi
+        B3_TRACE_ID_KEY = 'x-b3-traceid'
+        B3_SPAN_ID_KEY = 'x-b3-spanid'
+        B3_SAMPLED_KEY = 'x-b3-sampled'
+
+        def initialize(
+          fetcher:,
+          trace_id_key: B3_TRACE_ID_KEY,
+          span_id_key: B3_SPAN_ID_KEY,
+          sampled_key: B3_SAMPLED_KEY
+        )
+          @trace_id_key = trace_id_key
+          @span_id_key = span_id_key
+          @sampled_key = sampled_key
+          @fetcher = fetcher
+        end
+
+        def inject!(digest, data = {})
+          return if digest.nil?
+
+          # DEV: We need these to be hex encoded
+          data[@trace_id_key] = format('%032x', digest.trace_id)
+          data[@span_id_key] = format('%016x', digest.span_id || 0) # # Fall back to zero (invalid) if not present
+
+          if digest.trace_sampling_priority
+            sampling_priority = Helpers.clamp_sampling_priority(
+              digest.trace_sampling_priority
+            )
+            data[@sampled_key] = sampling_priority.to_s
+          end
+
+          data
+        end
+
+        def extract(data)
+          # DEV: B3 doesn't have "origin"
+          fetcher = @fetcher.new(data)
+
+          trace_id = Helpers.parse_hex_id(fetcher[@trace_id_key])
+
+          # Return early if this propagation is not valid
+          return if trace_id.nil? || trace_id <= 0 || trace_id > Tracing::Utils::TraceId::MAX
+
+          span_id = Helpers.parse_hex_id(fetcher[@span_id_key])
+
+          # Return early if this propagation is not valid
+          return if span_id.nil? || span_id <= 0 || span_id > Tracing::Utils::EXTERNAL_MAX_ID
+
+          # We don't need to try and convert sampled since B3 supports 0/1 (AUTO_REJECT/AUTO_KEEP)
+          sampling_priority = Helpers.parse_decimal_id(fetcher[@sampled_key])
+
+          TraceDigest.new(
+            trace_id: trace_id,
+            span_id: span_id,
+            trace_sampling_priority: sampling_priority,
+            span_remote: true,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/b3_single.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'helpers'
+require_relative '../trace_digest'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # B3 single header-style trace propagation.
+      #
+      # DEV: Format:
+      # DEV:   b3: {TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}
+      # DEV: https://github.com/apache/incubator-zipkin-b3-propagation/tree/7c6e9f14d6627832bd80baa87ac7dabee7be23cf#single-header
+      # DEV: `{SamplingState}` and `{ParentSpanId}` are optional
+      #
+      # @see https://github.com/openzipkin/b3-propagation#single-header
+      class B3Single
+        B3_SINGLE_HEADER_KEY = 'b3'
+
+        def initialize(fetcher:, key: B3_SINGLE_HEADER_KEY)
+          @key = key
+          @fetcher = fetcher
+        end
+
+        def inject!(digest, env)
+          return if digest.nil?
+
+          span_id = digest.span_id || 0 # Fall back to zero (invalid) if not present
+
+          # DEV: We need these to be hex encoded
+          value = "#{format("%032x", digest.trace_id)}-#{format("%016x", span_id)}"
+
+          if digest.trace_sampling_priority
+            sampling_priority = Helpers.clamp_sampling_priority(
+              digest.trace_sampling_priority
+            )
+            value += "-#{sampling_priority}"
+          end
+
+          env[@key] = value
+          env
+        end
+
+        def extract(env)
+          fetcher = @fetcher.new(env)
+          value = fetcher[@key]
+
+          return unless value
+
+          parts = value.split('-')
+          trace_id = Helpers.parse_hex_id(parts[0]) unless parts.empty?
+          # Return early if this propagation is not valid
+          return if trace_id.nil? || trace_id <= 0 || trace_id > Tracing::Utils::TraceId::MAX
+
+          span_id = Helpers.parse_hex_id(parts[1]) if parts.length > 1
+          # Return early if this propagation is not valid
+          return if span_id.nil? || span_id <= 0 || span_id > Tracing::Utils::EXTERNAL_MAX_ID
+
+          sampling_priority = Helpers.parse_decimal_id(parts[2]) if parts.length > 2
+
+          TraceDigest.new(
+            span_id: span_id,
+            trace_id: trace_id,
+            trace_sampling_priority: sampling_priority,
+            span_remote: true,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/baggage.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative '../metadata/ext'
+require_relative '../trace_digest'
+require_relative 'datadog_tags_codec'
+require_relative '../utils'
+require_relative 'helpers'
+require 'uri'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # W3C Baggage propagator implementation.
+      # The baggage header is propagated through `baggage`.
+      # @see https://www.w3.org/TR/baggage/
+      class Baggage
+        BAGGAGE_KEY = 'baggage'
+        DD_TRACE_BAGGAGE_MAX_ITEMS = 64
+        DD_TRACE_BAGGAGE_MAX_BYTES = 8192
+        BAGGAGE_TAG_KEYS_MATCH_ALL = ['*'].freeze
+        SAFE_CHARACTERS_KEY = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$!#&'*+-.^_`|~"
+        SAFE_CHARACTERS_VALUE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$!#&'()*+-./:<>?@[]^_`{|}~"
+
+        def initialize(
+          fetcher:,
+          baggage_key: BAGGAGE_KEY,
+          baggage_tag_keys: ::Datadog.configuration.tracing.baggage_tag_keys
+        )
+          @baggage_key = baggage_key
+          @fetcher = fetcher
+          @baggage_tag_keys = baggage_tag_keys
+        end
+
+        def inject!(digest, data)
+          return if digest.nil? || digest.baggage.nil?
+
+          baggage_items = digest.baggage.reject { |k, v| k.nil? || v.nil? }
+          return if baggage_items.empty?
+
+          begin
+            if baggage_items.size > DD_TRACE_BAGGAGE_MAX_ITEMS
+              ::Datadog.logger.warn("Baggage item limit (#{DD_TRACE_BAGGAGE_MAX_ITEMS}) exceeded, dropping excess items")
+              # Record telemetry for item count truncation
+              record_telemetry_metric(
+                'context_header.truncated',
+                1,
+                {'header_style' => 'baggage', 'truncation_reason' => 'baggage_item_count_exceeded'}
+              )
+              baggage_items = baggage_items.first(DD_TRACE_BAGGAGE_MAX_ITEMS)
+            end
+
+            encoded_items = []
+            total_size = 0
+
+            baggage_items.each do |key, value|
+              item = "#{encode_item(key, SAFE_CHARACTERS_KEY)}=#{encode_item(value, SAFE_CHARACTERS_VALUE)}"
+              item_size = item.bytesize + (encoded_items.empty? ? 0 : 1) # +1 for comma if not first item
+              if total_size + item_size > DD_TRACE_BAGGAGE_MAX_BYTES
+                ::Datadog.logger.warn("Baggage header size (#{DD_TRACE_BAGGAGE_MAX_BYTES}) exceeded, dropping excess items")
+                # Record telemetry for byte count truncation
+                record_telemetry_metric(
+                  'context_header.truncated',
+                  1,
+                  {'header_style' => 'baggage', 'truncation_reason' => 'baggage_byte_count_exceeded'}
+                )
+                break # stop adding items when size limit is reached
+              end
+              encoded_items << item
+              total_size += item_size
+            end
+
+            # edge case where a single item is too large
+            return if encoded_items.empty?
+
+            data[@baggage_key] = encoded_items.join(',')
+
+            # Record telemetry for successful injection
+            record_telemetry_metric('context_header_style.injected', 1, {'header_style' => 'baggage'})
+          rescue => e
+            ::Datadog.logger.warn("Failed to encode and inject baggage header: #{e.class}: #{e}")
+          end
+        end
+
+        def extract(data)
+          fetcher = @fetcher.new(data)
+          data = fetcher[@baggage_key]
+          return unless data
+
+          baggage = parse_baggage_header(fetcher[@baggage_key])
+          return unless baggage
+
+          # Convert selected baggage items to span tags based on configuration
+          baggage_tags = build_baggage_tags(baggage)
+
+          # Record telemetry for successful extraction only if baggage is not empty
+          unless baggage.empty?
+            record_telemetry_metric('context_header_style.extracted', 1, {'header_style' => 'baggage'})
+          end
+
+          TraceDigest.new(
+            baggage: baggage,
+            trace_distributed_tags: baggage_tags
+          )
+        end
+
+        private
+
+        def encode_item(item, safe_characters)
+          # Strip whitespace and URL-encode the item
+          result = URI.encode_www_form_component(item.strip)
+          # Replace '+' with '%20' for space encoding consistency with W3C spec
+          result = result.gsub('+', '%20')
+          # Selectively decode percent-encoded characters that are considered "safe" in W3C Baggage spec
+          result.gsub(/%[0-9A-F]{2}/) do |encoded|
+            if encoded.size >= 3 && encoded[1..2] =~ /\A[0-9A-F]{2}\z/
+              hex_str = encoded[1..2]
+              next encoded unless hex_str && !hex_str.empty?
+
+              # Convert hex representation back to character
+              char = [hex_str.hex].pack('C')
+              # Keep the character as-is if it's in the safe character set, otherwise keep it encoded
+              safe_characters.include?(char) ? char : encoded
+            else
+              encoded
+            end
+          end
+        end
+
+        # Parses a W3C Baggage header string into a hash of key-value pairs
+        # The header format follows the W3C Baggage specification:
+        # - Multiple baggage items are separated by commas
+        # - Each baggage item is a key-value pair separated by '='
+        # - Keys and values are URL-encoded
+        # - Returns an empty hash if the baggage header is malformed
+        #
+        # @param baggage_header [String] The W3C Baggage header string to parse
+        # @return [Hash<String, String>] A hash of decoded baggage items
+        def parse_baggage_header(baggage_header)
+          baggage = {}
+          baggages = baggage_header.split(',')
+          baggages.each do |key_value|
+            key, value = key_value.split('=', 2)
+            # If baggage is malformed, return an empty hash
+            if key.nil? || value.nil?
+              # Record telemetry for malformed header
+              record_telemetry_metric('context_header_style.malformed', 1, {'header_style' => 'baggage'})
+              return {}
+            end
+
+            key = URI.decode_www_form_component(key.strip)
+            value = URI.decode_www_form_component(value.strip)
+            if key.empty? || value.empty?
+              # Record telemetry for malformed header
+              record_telemetry_metric('context_header_style.malformed', 1, {'header_style' => 'baggage'})
+              return {}
+            end
+
+            baggage[key] = value
+          end
+          baggage
+        end
+
+        # Convert selected baggage items to span tags
+        # Baggage carries important contextual information (like user.id, session.id) across distributed services,
+        # but isn't searchable by default.
+        def build_baggage_tags(baggage)
+          return {} if baggage.empty?
+
+          # Get the configuration for which baggage keys should become span tags
+          baggage_tag_keys = @baggage_tag_keys
+          return {} if baggage_tag_keys.empty?
+
+          # If wildcard is specified, use all baggage keys
+          baggage_tag_keys = baggage if baggage_tag_keys == BAGGAGE_TAG_KEYS_MATCH_ALL
+
+          tags = {}
+
+          baggage_tag_keys.each do |key, _| # rubocop:disable Style/HashEachMethods
+            value = baggage[key]
+            next if value.nil? || value.empty?
+
+            tags["baggage.#{key}"] = value
+          end
+
+          tags
+        end
+
+        # Record telemetry metrics for baggage operations
+        def record_telemetry_metric(metric_name, value, tags)
+          telemetry = ::Datadog.send(:components).telemetry
+          telemetry.inc('instrumentation_telemetry_data.tracers', metric_name, value, tags: tags)
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/datadog.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require_relative '../metadata/ext'
+require_relative '../trace_digest'
+require_relative 'datadog_tags_codec'
+require_relative '../utils'
+require_relative 'helpers'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Datadog-style trace propagation.
+      class Datadog
+        TRACE_ID_KEY = 'x-datadog-trace-id'
+        PARENT_ID_KEY = 'x-datadog-parent-id'
+        SAMPLING_PRIORITY_KEY = 'x-datadog-sampling-priority'
+        ORIGIN_KEY = 'x-datadog-origin'
+        # Distributed trace-level tags
+        TAGS_KEY = 'x-datadog-tags'
+
+        # Prefix used by all Datadog-specific distributed tags
+        TAGS_PREFIX = 'x-datadog-'
+
+        def initialize(
+          fetcher:,
+          trace_id_key: TRACE_ID_KEY,
+          parent_id_key: PARENT_ID_KEY,
+          sampling_priority_key: SAMPLING_PRIORITY_KEY,
+          origin_key: ORIGIN_KEY,
+          tags_key: TAGS_KEY
+        )
+          @trace_id_key = trace_id_key
+          @parent_id_key = parent_id_key
+          @sampling_priority_key = sampling_priority_key
+          @origin_key = origin_key
+          @tags_key = tags_key
+          @fetcher = fetcher
+        end
+
+        def inject!(digest, data)
+          return if digest.nil?
+
+          data[@trace_id_key] = Tracing::Utils::TraceId.to_low_order(digest.trace_id).to_s
+
+          data[@parent_id_key] = digest.span_id.to_s if digest.span_id
+          data[@sampling_priority_key] = digest.trace_sampling_priority.to_s if digest.trace_sampling_priority
+          data[@origin_key] = digest.trace_origin.to_s if digest.trace_origin
+
+          build_tags(digest).tap do |tags|
+            inject_tags!(tags, data) unless tags.empty?
+          end
+          data
+        end
+
+        def extract(data)
+          fetcher = @fetcher.new(data)
+
+          trace_id = parse_trace_id(fetcher)
+          parent_id = parse_parent_id(fetcher)
+
+          sampling_priority = Helpers.parse_decimal_id(fetcher[@sampling_priority_key])
+          origin = fetcher[@origin_key]
+
+          # Return early if this propagation is not valid
+          # DEV: To be valid we need to have a trace id and a parent id or an origin id.
+          # DEV: `Fetcher#id` will not return 0
+          return if trace_id.nil? || parent_id.nil? && origin.nil?
+
+          trace_distributed_tags = extract_tags(fetcher)
+
+          # If trace id is 128 bits long,
+          # Concatentated high order 64 bit hex-encoded `tid` tag
+          trace_id = extract_trace_id!(trace_id, trace_distributed_tags)
+
+          TraceDigest.new(
+            span_id: parent_id,
+            trace_id: trace_id,
+            trace_origin: origin,
+            trace_sampling_priority: sampling_priority,
+            trace_distributed_tags: trace_distributed_tags,
+            span_remote: true,
+          )
+        end
+
+        private
+
+        def parse_trace_id(fetcher_object)
+          trace_id = Helpers.parse_decimal_id(fetcher_object[@trace_id_key])
+
+          return unless trace_id
+          return if trace_id <= 0 || trace_id > Tracing::Utils::EXTERNAL_MAX_ID
+
+          trace_id
+        end
+
+        def parse_parent_id(fetcher_object)
+          parent_id = Helpers.parse_decimal_id(fetcher_object[@parent_id_key])
+
+          return unless parent_id
+          return if parent_id <= 0 || parent_id > Tracing::Utils::EXTERNAL_MAX_ID
+
+          parent_id
+        end
+
+        def build_tags(digest)
+          high_order = Tracing::Utils::TraceId.to_high_order(digest.trace_id)
+          tags = digest.trace_distributed_tags || {}
+
+          return tags if high_order == 0
+
+          tags.merge(Tracing::Metadata::Ext::Distributed::TAG_TID => format('%016x', high_order))
+        end
+
+        # Side effect: Remove high order 64 bit hex-encoded `tid` tag from distributed tags
+        def extract_trace_id!(trace_id, tags)
+          return trace_id unless tags
+          return trace_id unless (high_order = tags.delete(Tracing::Metadata::Ext::Distributed::TAG_TID))
+          return trace_id unless high_order.size == 16
+          return trace_id unless /\A[0-9a-f]+\z/i.match?(high_order)
+
+          Tracing::Utils::TraceId.concatenate(high_order.to_i(16), trace_id)
+        end
+
+        # Export trace distributed tags through the `x-datadog-tags` key.
+        #
+        # DEV: This method accesses global state (the active trace) to record its error state as a trace tag.
+        # DEV: This means errors cannot be reported if there's not active span.
+        # DEV: Ideally, we'd have a dedicated error reporting stream for all of datadog.
+        def inject_tags!(tags, data)
+          return set_tags_propagation_error(reason: 'disabled') if tags_disabled?
+
+          encoded_tags = DatadogTagsCodec.encode(tags)
+
+          return set_tags_propagation_error(reason: 'inject_max_size') if tags_too_large?(
+            encoded_tags.size,
+            scenario: 'inject'
+          )
+
+          data[@tags_key] = encoded_tags
+        rescue => e
+          set_tags_propagation_error(reason: 'encoding_error')
+          ::Datadog.logger.warn(
+            "Failed to inject x-datadog-tags: #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+          )
+        end
+
+        # Import `x-datadog-tags` tags as trace distributed tags.
+        # Only tags that have the `_dd.p.` prefix are processed.
+        #
+        # DEV: This method accesses global state (the active trace) to record its error state as a trace tag.
+        # DEV: This means errors cannot be reported if there's not active span.
+        # DEV: Ideally, we'd have a dedicated error reporting stream for all of datadog.
+        def extract_tags(fetcher)
+          tags = fetcher[@tags_key]
+
+          return if !tags || tags.empty?
+          return set_tags_propagation_error(reason: 'disabled') if tags_disabled?
+          return set_tags_propagation_error(reason: 'extract_max_size') if tags_too_large?(tags.size, scenario: 'extract')
+
+          tags_hash = DatadogTagsCodec.decode(tags)
+          # Only extract keys with the expected Datadog prefix
+          tags_hash.select! do |key, _|
+            key.start_with?(Tracing::Metadata::Ext::Distributed::TAGS_PREFIX) && key != EXCLUDED_TAG
+          end
+          tags_hash
+        rescue => e
+          set_tags_propagation_error(reason: 'decoding_error')
+          ::Datadog.logger.warn(
+            "Failed to extract x-datadog-tags: #{e.class.name} #{e.message} at #{Array(e.backtrace).first}"
+          )
+        end
+
+        def set_tags_propagation_error(reason:)
+          active_trace = Tracing.active_trace
+          active_trace&.set_tag('_dd.propagation_error', reason)
+          nil
+        end
+
+        def tags_disabled?
+          ::Datadog.configuration.tracing.x_datadog_tags_max_length <= 0
+        end
+
+        def tags_too_large?(size, scenario:)
+          return false if size <= ::Datadog.configuration.tracing.x_datadog_tags_max_length
+
+          ::Datadog.logger.warn(
+            "Failed to #{scenario} x-datadog-tags: tags are too large for configured limit (size:#{size} >= " \
+              "limit:#{::Datadog.configuration.tracing.x_datadog_tags_max_length}). This limit can be configured " \
+              'through the DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH environment variable.'
+          )
+
+          true
+        end
+
+        # We want to exclude tags that we don't want to propagate downstream.
+        EXCLUDED_TAG = '_dd.p.upstream_services'
+        private_constant :EXCLUDED_TAG
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/datadog_tags_codec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Encodes and decodes distributed 'x-datadog-tags' tags for transport
+      # to and from external processes.
+      module DatadogTagsCodec
+        # Backport `Regexp::match?` because it is measurably the most performant
+        # way to check if a string matches a regular expression.
+        module RefineRegexp
+          unless Regexp.method_defined?(:match?)
+            refine ::Regexp do
+              def match?(*args)
+                !match(*args).nil?
+              end
+            end
+          end
+        end
+        using RefineRegexp
+
+        # ASCII characters 32-126, except `,`, `=`, and ` `. At least one character.
+        VALID_KEY_CHARS = /\A(?:(?![,= ])[\u0020-\u007E])+\Z/.freeze
+        # ASCII characters 32-126, except `,`. At least one character.
+        VALID_VALUE_CHARS = /\A(?:(?!,)[\u0020-\u007E])+\Z/.freeze
+
+        # Serializes a {Hash<String,String>} into a `x-datadog-tags`-compatible
+        # String.
+        #
+        # @param tags [Hash<String,String>] trace tag hash
+        # @return [String] serialized tags hash
+        # @raise [EncodingError] if tags cannot be serialized to the `x-datadog-tags` format
+        def self.encode(tags)
+          tags.map do |raw_key, raw_value|
+            key = raw_key.to_s
+            value = raw_value.to_s
+
+            raise EncodingError, "Invalid key `#{key}` for value `#{value}`" unless VALID_KEY_CHARS.match?(key)
+            raise EncodingError, "Invalid value `#{value}` for key `#{key}`" unless VALID_VALUE_CHARS.match?(value)
+
+            "#{key}=#{value.strip}"
+          end.join(',')
+        rescue => e
+          raise EncodingError, "Error encoding tags `#{tags}`: `#{e}`"
+        end
+
+        # Deserializes a `x-datadog-tags`-formatted String into a {Hash<String,String>}.
+        #
+        # @param string [String] tags as serialized by {#encode}
+        # @return [Hash<String,String>] decoded input as a hash of strings
+        # @raise [DecodingError] if string does not conform to the `x-datadog-tags` format
+        def self.decode(string)
+          result = (string.split(',').map do |raw_tag|
+            raw_tag.split('=', 2).tap do |raw_key, raw_value|
+              key = raw_key.to_s
+              value = raw_value.to_s
+
+              raise DecodingError, "Invalid key: #{key}" unless VALID_KEY_CHARS.match?(key)
+              raise DecodingError, "Invalid value: #{value}" unless VALID_VALUE_CHARS.match?(value)
+
+              value.strip!
+            end
+          end).to_h
+
+          raise DecodingError, "Invalid empty tags: #{string}" if result.empty? && !string.empty?
+
+          result
+        end
+
+        # An error occurred during distributed tags encoding.
+        # See {#message} for more information.
+        class EncodingError < StandardError
+        end
+
+        # An error occurred during distributed tags decoding.
+        # See {#message} for more information.
+        class DecodingError < StandardError
+        end
+      end
+    end
+  end
+end

data/lib/datadog/tracing/distributed/fetcher.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'helpers'
+
+module Datadog
+  module Tracing
+    module Distributed
+      # Common fetcher that retrieves fields from a Hash data input
+      class Fetcher
+        # @param data [Hash]
+        def initialize(data)
+          @data = data
+        end
+
+        def [](key)
+          @data[key]
+        end
+      end
+    end
+  end
+end