datadog 2.38.0 → 2.47.0

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative '../../core/utils'
-require_relative 'helpers'
+require_relative "helpers"
+require_relative "trace_state"
 
 module Datadog
   module Tracing
@@ -10,9 +10,9 @@ module Datadog
       # The trace is propagated through two fields: `traceparent` and `tracestate`.
       # @see https://www.w3.org/TR/trace-context/
       class TraceContext
-        TRACEPARENT_KEY = 'traceparent'
-        TRACESTATE_KEY = 'tracestate'
-        SPEC_VERSION = '00'
+        TRACEPARENT_KEY = "traceparent"
+        TRACESTATE_KEY = "tracestate"
+        SPEC_VERSION = "00"
 
         def initialize(
           fetcher:,
@@ -30,7 +30,7 @@ module Datadog
           if (traceparent = build_traceparent(digest))
             data[@traceparent_key] = traceparent
 
-            if (tracestate = build_tracestate(digest))
+            if (tracestate = TraceState.serialize_digest(digest))
               data[@tracestate_key] = tracestate
             end
           end
@@ -45,11 +45,12 @@ module Datadog
 
           return unless trace_id # Could not parse traceparent
 
-          tracestate, sampling_priority, origin, ts_parent_id, tags, unknown_fields = extract_tracestate(
-            fetcher[@tracestate_key]
-          )
+          trace_state = TraceState.extract(fetcher[@tracestate_key])
+          dd = trace_state.datadog
+          ot = trace_state.open_telemetry
 
-          sampling_priority = parse_priority_sampling(sampled, sampling_priority) do |decision|
+          tags = dd.tags
+          sampling_priority = parse_priority_sampling(sampled, dd.sampling_priority) do |decision|
             case decision
             when String
               tags ||= {}
@@ -61,17 +62,20 @@ module Datadog
 
           tags ||= {}
           tags[Tracing::Metadata::Ext::Distributed::TAG_DD_PARENT_ID] =
-            ts_parent_id || Tracing::Metadata::Ext::Distributed::DD_PARENT_ID_DEFAULT
+            dd.ts_parent_id || Tracing::Metadata::Ext::Distributed::DD_PARENT_ID_DEFAULT
 
           TraceDigest.new(
             span_id: parent_id,
             trace_id: trace_id,
-            trace_origin: origin,
+            trace_origin: dd.origin,
             trace_sampling_priority: sampling_priority,
             trace_distributed_tags: tags,
             trace_flags: trace_flags,
-            trace_state: tracestate,
-            trace_state_unknown_fields: unknown_fields,
+            trace_state: trace_state.unknown_vendors,
+            trace_state_unknown_fields: dd.unknown_fields,
+            trace_otel_random_value: ot.random_value,
+            trace_otel_threshold: ot.threshold,
+            trace_otel_unknown_fields: ot.unknown_fields,
             span_remote: true,
           )
         end
@@ -121,133 +125,6 @@ module Datadog
           trace_flags
         end
 
-        # @see https://www.w3.org/TR/trace-context/#tracestate-header
-        def build_tracestate(digest)
-          tracestate = +'dd='
-          append_dd(tracestate, last_dd_parent_id(digest))
-          append_dd(tracestate, "s:#{digest.trace_sampling_priority};") if digest.trace_sampling_priority
-          append_dd(tracestate, "o:#{serialize_origin(digest.trace_origin)};") if digest.trace_origin
-
-          # Replacing this by safe navigation seems to have a different behaviour on Rubies <= 3.0.
-          # It cause a LocalJumpError in the CI.
-          if digest.trace_distributed_tags # rubocop:disable Style/SafeNavigation
-            digest.trace_distributed_tags.each do |name, value|
-              tag = "t.#{serialize_tag_key(name)}:#{serialize_tag_value(value)};"
-
-              # If tracestate size limit is exceeded, drop the remaining data.
-              break unless append_dd(tracestate, tag)
-            end
-          end
-
-          append_dd(tracestate, digest.trace_state_unknown_fields) if digest.trace_state_unknown_fields
-          vendors = split_tracestate(digest.trace_state)
-
-          # Is there any Datadog-specific information to propagate.
-          # Check for > 3 size because the empty prefix `dd=` has 3 characters.
-          if tracestate.bytesize > 3
-            # Propagate upstream tracestate with `dd=...` appended to the list
-            tracestate.chop! # Removes trailing `;` from Datadog trace state string.
-
-            if vendors && !vendors.empty?
-              # Delete existing `dd=` tracestate fields, if present.
-              vendors.reject! { |v| v.start_with?('dd=') }
-
-              # Ensure the list has at most 31 elements, as we need to prepend Datadog's
-              # entry and the limit is 32 elements total.
-              vendors.first(TRACESTATE_MAX_LIST_MEMBERS - 1).each do |vendor|
-                break if tracestate.bytesize + vendor.bytesize + 1 > TRACESTATE_MAX_SIZE_LIMIT
-
-                tracestate << ',' << vendor
-              end
-            end
-
-            tracestate.to_s
-          elsif vendors && !vendors.empty?
-            vendors.join(',')
-          end
-        end
-
-        # Appends a Datadog tracestate field when it fits.
-        def append_dd(tracestate, field)
-          return true if field.empty?
-
-          # We add 1 to the limit because of the trailing semicolon, which will be removed before returning.
-          return false if tracestate.bytesize + field.bytesize > (TRACESTATE_VALUE_SIZE_LIMIT + 1)
-
-          tracestate << field
-          true
-        end
-
-        def last_dd_parent_id(digest)
-          if !digest.span_remote
-            span_id = digest.span_id || 0 # Fall back to zero (invalid) if not present
-            "p:#{format("%016x", span_id)};"
-          elsif digest.trace_distributed_tags&.key?(Tracing::Metadata::Ext::Distributed::TAG_DD_PARENT_ID)
-            "p:#{digest.trace_distributed_tags[Tracing::Metadata::Ext::Distributed::TAG_DD_PARENT_ID]};"
-          else
-            ''
-          end
-        end
-
-        # If any characters in <origin_value> are invalid, replace each invalid character with 0x5F (underscore).
-        # Invalid characters are: characters outside the ASCII range 0x20 to 0x7E,
-        # 0x2C (comma), 0x3B (semi-colon), and 0x7E (tilde).
-        # Then, remap 0x3D (equals) to 0x7E (tilde)
-        def serialize_origin(value)
-          # DEV: It's unlikely that characters will be out of range, as they mostly
-          # DEV: come from Datadog-controlled sources.
-          # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
-          value = if INVALID_ORIGIN_CHARS.match?(value)
-            value.gsub(INVALID_ORIGIN_CHARS, '_')
-          else
-            value
-          end
-
-          if REMAP_ORIGIN_CHARS.match?(value)
-            value.gsub(REMAP_ORIGIN_CHARS, '~')
-          else
-            value
-          end
-        end
-
-        # Serialize `_dd.p.{key}` by first removing the `_dd.p.` prefix.
-        # Then replacing invalid characters with `_`.
-        #
-        # The argument `name` is always frozen.
-        # Returns a new String object for the serialized key.
-        def serialize_tag_key(name)
-          key = name.delete_prefix(Tracing::Metadata::Ext::Distributed::TAGS_PREFIX)
-
-          # DEV: It's unlikely that characters will be out of range, as they mostly
-          # DEV: come from Datadog-controlled sources.
-          # DEV: Trying to `match?` is measurably faster than a `gsub!` that does not match.
-          key.gsub!(INVALID_TAG_KEY_CHARS, '_') if INVALID_TAG_KEY_CHARS.match?(key)
-
-          key
-        end
-
-        # Replaces invalid characters with `_`, then replaces `=` with `~`.
-        #
-        # The argument `value` belongs to {TraceDigest}, thus should not be directly modified.
-        # Returns a new String object for the serialized value.
-        def serialize_tag_value(value)
-          # DEV: It's unlikely that characters will be out of range, as they mostly
-          # DEV: come from Datadog-controlled sources.
-          # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
-          ret = if INVALID_TAG_VALUE_CHARS.match?(value)
-            value.gsub(INVALID_TAG_VALUE_CHARS, '_')
-          else
-            value
-          end
-
-          # DEV: Checking for an unlikely '=' is faster than a no-op `tr`.
-          if ret.include?('=')
-            ret.tr('=', '~')
-          else
-            ret
-          end
-        end
-
         def extract_traceparent(traceparent)
           trace_id, parent_id, trace_flags = parse_traceparent_string(traceparent)
 
@@ -265,11 +142,11 @@ module Datadog
 
           traceparent = traceparent.strip
 
-          version, trace_id, parent_id, trace_flags, extra = traceparent.split('-', 5)
+          version, trace_id, parent_id, trace_flags, extra = traceparent.split("-", 5)
 
           return unless version && trace_id && parent_id && trace_flags
           return if version.size != 2 || trace_id.size != 32 || parent_id.size != 16 || trace_flags.size != 2
-          return if version[0] < '0' || version[0] > 'f' || version[1] < '0' || version[1] > 'f'
+          return if version[0] < "0" || version[0] > "f" || version[1] < "0" || version[1] > "f"
 
           return if version == INVALID_VERSION
 
@@ -285,78 +162,6 @@ module Datadog
           trace_flags & TRACE_FLAGS_SAMPLED
         end
 
-        # @return [nil] when the tracestate is absent or has no vendor entries.
-        # @return [String] when no `dd=` entry is present, the joined vendor list.
-        # @return [Array(String, Integer, String, String, Hash, String)] when a `dd=`
-        #   entry is present: [tracestate without `dd=`, sampling_priority, origin,
-        #   ts_parent_id, tags, unknown_fields]. All elements past the first may be nil.
-        def extract_tracestate(tracestate)
-          vendors = split_tracestate(tracestate)
-          return unless vendors && !vendors.empty?
-
-          tracestate = vendors.join(',')
-
-          # Find Datadog's `dd=` tracestate field.
-          idx = vendors.index { |v| v.start_with?('dd=') }
-          return tracestate unless idx
-
-          # Delete `dd=` prefix
-          dd_tracestate = vendors.delete_at(idx)
-          dd_tracestate.slice!(0..2)
-
-          origin, sampling_priority, ts_parent_id, tags, unknown_fields = extract_datadog_fields(dd_tracestate)
-
-          [vendors.join(','), sampling_priority, origin, ts_parent_id, tags, unknown_fields]
-        end
-
-        def extract_datadog_fields(dd_tracestate)
-          sampling_priority = nil
-          origin = nil
-          ts_parent_id = nil
-          tags = nil
-          unknown_fields = nil
-
-          # DEV: Since Ruby 2.6 `split` can receive a block, so `each` can be removed then.
-          dd_tracestate.split(';').each do |pair|
-            key, value = pair.split(':', 2)
-            case key
-            when 's'
-              sampling_priority = begin
-                Integer(value)
-              rescue
-                nil
-              end
-            when 'o'
-              origin = value
-            when 'p'
-              ts_parent_id = value
-            when /^t\./
-              key.slice!(0..1) # Delete `t.` prefix
-
-              # Ignore the high order 64 bit trace id propagation tag to avoid confusion,
-              # the single source of truth is from traceparent
-              next if key == Tracing::Metadata::Ext::Distributed::TID
-
-              value = deserialize_tag_value(value)
-
-              tags ||= {}
-              tags["#{Tracing::Metadata::Ext::Distributed::TAGS_PREFIX}#{key}"] = value
-            else
-              unknown_fields ||= +''
-              unknown_fields << pair
-              unknown_fields << ';'
-            end
-          end
-
-          [origin, sampling_priority, ts_parent_id, tags, unknown_fields]
-        end
-
-        # Restore `~` back to `=`.
-        def deserialize_tag_value(value)
-          value.tr!('~', '=')
-          value
-        end
-
         # If `sampled` and `sampling_priority` disagree, `sampled` overrides the decision.
         # @return [Integer] one of the {Datadog::Tracing::Sampling::Ext::Priority} values
         # @yieldparam the new decision maker (either :drop or a new decision maker String value).
@@ -382,50 +187,12 @@ module Datadog
           end
         end
 
-        # We MUST NOT propagate partial members, but we SHOULD try
-        # to parse as much of the tracestate as possible.
-        def split_tracestate(tracestate)
-          return unless tracestate
-
-          remove_last_member = false
-          if tracestate.bytesize > TRACESTATE_MAX_SIZE_LIMIT
-            # We parse 1 byte over the limit to detect if the last member
-            # is a partial member (toss) or ends exactly at the limit (keep).
-            remove_last_member = tracestate.byteslice(TRACESTATE_MAX_SIZE_LIMIT, 1) != ','
-
-            # To ensure we don't have a trailing partial UTF-8 codepoint, we keep one extra byte
-            # and safely remove it with `#chop`.
-            # `#chop` walks back the string until it finds a valid character boundary and deletes
-            # from there.
-            tracestate = tracestate.byteslice(0, TRACESTATE_MAX_SIZE_LIMIT + 1) #: String
-            tracestate = tracestate.chop
-          end
-
-          tracestate = ::Datadog::Core::Utils.utf8_encode(tracestate, placeholder: nil)
-          return unless tracestate
-
-          vendors = tracestate.split(',', TRACESTATE_MAX_LIST_MEMBERS + 1)
-          if vendors.length > TRACESTATE_MAX_LIST_MEMBERS || remove_last_member
-            vendors.pop
-          end
-
-          vendors.each(&:strip!)
-          vendors.pop while vendors.last == ''
-          vendors
-        end
-
         TRACEPARENT_MAX_SIZE_LIMIT = 512
         private_constant :TRACEPARENT_MAX_SIZE_LIMIT
 
-        TRACESTATE_MAX_SIZE_LIMIT = 512
-        private_constant :TRACESTATE_MAX_SIZE_LIMIT
-
-        TRACESTATE_MAX_LIST_MEMBERS = 32
-        private_constant :TRACESTATE_MAX_LIST_MEMBERS
-
         # Version 0xFF is invalid as per spec
         # @see https://www.w3.org/TR/trace-context/#version
-        INVALID_VERSION = 'ff'
+        INVALID_VERSION = "ff"
         private_constant :INVALID_VERSION
 
         # Empty 8-bit `trace-flags`.
@@ -437,30 +204,6 @@ module Datadog
         # @see https://www.w3.org/TR/trace-context/#trace-flags
         TRACE_FLAGS_SAMPLED = 0b00000001
         private_constant :TRACE_FLAGS_SAMPLED
-
-        # The limit is inclusive: sizes *greater* than 256 are disallowed.
-        # @see https://www.w3.org/TR/trace-context/#value
-        TRACESTATE_VALUE_SIZE_LIMIT = 256
-        private_constant :TRACESTATE_VALUE_SIZE_LIMIT
-
-        # Replace all characters with `_`, except ASCII characters 0x20-0x7E.
-        # Additionally, `,`, ';', and `~` must also be replaced by `_`.
-        INVALID_ORIGIN_CHARS = /[\u0000-\u0019,;~\u007F-\u{10FFFF}]/.freeze
-        private_constant :INVALID_ORIGIN_CHARS
-
-        # Additionally, remap `=` to `~`
-        REMAP_ORIGIN_CHARS = /=/.freeze
-        private_constant :REMAP_ORIGIN_CHARS
-
-        # Replace all characters with `_`, except ASCII characters 0x21-0x7E.
-        # Additionally, `,` and `=` must also be replaced by `_`.
-        INVALID_TAG_KEY_CHARS = /[\u0000-\u0020,=\u007F-\u{10FFFF}]/.freeze
-        private_constant :INVALID_TAG_KEY_CHARS
-
-        # Replace all characters with `_`, except ASCII characters 0x20-0x7D.
-        # Additionally, `,` and `;` must also be replaced by `_`.
-        INVALID_TAG_VALUE_CHARS = /[\u0000-\u001F,;\u007E-\u{10FFFF}]/.freeze
-        private_constant :INVALID_TAG_VALUE_CHARS
       end
     end
   end

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require_relative "ext"
+
+module Datadog
+  module Tracing
+    module Distributed
+      class TraceState
+        # Encodes and decodes Datadog propagation state.
+        class Datadog
+          class << self
+            def from_digest(digest)
+              ts_parent_id = if !digest.span_remote
+                format("%016x", digest.span_id || 0)
+              elsif digest.trace_distributed_tags&.key?(Tracing::Metadata::Ext::Distributed::TAG_DD_PARENT_ID)
+                digest.trace_distributed_tags[Tracing::Metadata::Ext::Distributed::TAG_DD_PARENT_ID]
+              end
+
+              new(
+                sampling_priority: digest.trace_sampling_priority,
+                origin: digest.trace_origin,
+                ts_parent_id: ts_parent_id,
+                tags: digest.trace_distributed_tags,
+                unknown_fields: digest.trace_state_unknown_fields,
+              )
+            end
+
+            def from_tracestate_member(value)
+              return new unless value
+
+              # @type var sampling_priority: ::Integer?
+              # @type var origin: ::String?
+              # @type var ts_parent_id: ::String?
+              # @type var tags: ::Hash[::String, ::String]?
+              # @type var unknown_fields: ::String?
+              sampling_priority = nil
+              origin = nil
+              ts_parent_id = nil
+              tags = nil
+              unknown_fields = nil
+
+              value.split(";").each do |pair|
+                key, field = pair.split(":", 2)
+                case key
+                when "s"
+                  sampling_priority = begin
+                    Integer(field)
+                  rescue
+                    nil
+                  end
+                when "o"
+                  origin = field
+                when "p"
+                  ts_parent_id = field
+                when /^t\./
+                  key = key.to_s
+                  field = field.to_s
+                  key.slice!(0..1)
+                  next if key == Tracing::Metadata::Ext::Distributed::TID
+
+                  field.tr!("~", "=")
+                  current_tags = tags || {}
+                  current_tags["#{Tracing::Metadata::Ext::Distributed::TAGS_PREFIX}#{key}"] = field
+                  tags = current_tags
+                else
+                  current_unknown_fields = unknown_fields || +""
+                  current_unknown_fields << pair << ";"
+                  unknown_fields = current_unknown_fields
+                end
+              end
+
+              new(
+                sampling_priority: sampling_priority,
+                origin: origin,
+                ts_parent_id: ts_parent_id,
+                tags: tags,
+                unknown_fields: unknown_fields,
+              )
+            end
+
+            # 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 encode(tags)
+              tags.map do |raw_key, raw_value|
+                key = raw_key.to_s
+                value = raw_value.to_s
+
+                unless Ext::Datadog::VALID_KEY_CHARS.match?(key)
+                  raise EncodingError, "Invalid key `#{key}` for value `#{value}`"
+                end
+                unless Ext::Datadog::VALID_VALUE_CHARS.match?(value)
+                  raise EncodingError, "Invalid value `#{value}` for key `#{key}`"
+                end
+
+                "#{key}=#{value.strip}"
+              end.join(",")
+            rescue => e
+              raise EncodingError, "Error encoding tags `#{tags}`: `#{e.class}: #{e.message}`"
+            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 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 Ext::Datadog::VALID_KEY_CHARS.match?(key)
+                  raise DecodingError, "Invalid value: #{value}" unless Ext::Datadog::VALID_VALUE_CHARS.match?(value)
+
+                  value.strip!
+                end
+              end).to_h
+
+              raise DecodingError, "Invalid empty tags: #{string}" if result.empty? && !string.empty?
+
+              result
+            end
+          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
+
+          attr_reader :sampling_priority, :origin, :ts_parent_id, :tags, :unknown_fields
+
+          def initialize(sampling_priority: nil, origin: nil, ts_parent_id: nil, tags: nil, unknown_fields: nil)
+            @sampling_priority = sampling_priority
+            @origin = origin
+            @ts_parent_id = ts_parent_id
+            @tags = tags
+            @unknown_fields = unknown_fields
+          end
+
+          # Builds the `dd=` tracestate member.
+          def to_s
+            vendor = +"dd="
+            if ts_parent_id
+              field = "p:#{ts_parent_id};"
+              vendor << field if vendor.bytesize + field.bytesize <= (Ext::TRACESTATE_VALUE_SIZE_LIMIT + 1)
+            end
+            if sampling_priority
+              field = "s:#{sampling_priority};"
+              vendor << field if vendor.bytesize + field.bytesize <= (Ext::TRACESTATE_VALUE_SIZE_LIMIT + 1)
+            end
+            if origin
+              field = "o:#{serialize_origin(origin)};"
+              vendor << field if vendor.bytesize + field.bytesize <= (Ext::TRACESTATE_VALUE_SIZE_LIMIT + 1)
+            end
+
+            # Replacing this with safe navigation causes a LocalJumpError on Rubies <= 3.0.
+            if tags # rubocop:disable Style/SafeNavigation
+              tags.each do |name, value|
+                tag_field = "t.#{serialize_tag_key(name)}:#{serialize_tag_value(value)};"
+                break if vendor.bytesize + tag_field.bytesize > (Ext::TRACESTATE_VALUE_SIZE_LIMIT + 1)
+
+                vendor << tag_field
+              end
+            end
+
+            if unknown_fields && vendor.bytesize + unknown_fields.bytesize <= (Ext::TRACESTATE_VALUE_SIZE_LIMIT + 1)
+              vendor << unknown_fields
+            end
+            return "" if vendor.bytesize == 3
+
+            vendor.chop!
+            vendor
+          end
+
+          private
+
+          # If any characters in <origin_value> are invalid, replace each invalid character with 0x5F (underscore).
+          # Invalid characters are: characters outside the ASCII range 0x20 to 0x7E,
+          # 0x2C (comma), 0x3B (semi-colon), and 0x7E (tilde).
+          # Then, remap 0x3D (equals) to 0x7E (tilde)
+          def serialize_origin(value)
+            # DEV: It's unlikely that characters will be out of range, as they mostly
+            # DEV: come from Datadog-controlled sources.
+            # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
+            invalid_chars = Ext::Datadog::INVALID_ORIGIN_CHARS
+            value = invalid_chars.match?(value) ? value.gsub(invalid_chars, "_") : value
+            remapped_chars = Ext::Datadog::REMAP_ORIGIN_CHARS
+            remapped_chars.match?(value) ? value.gsub(remapped_chars, "~") : value
+          end
+
+          # Serialize `_dd.p.{key}` by first removing the `_dd.p.` prefix.
+          # Then replacing invalid characters with `_`.
+          #
+          # The argument `name` is always frozen.
+          # Returns a new String object for the serialized key.
+          def serialize_tag_key(name)
+            key = name.delete_prefix(Tracing::Metadata::Ext::Distributed::TAGS_PREFIX)
+
+            # DEV: It's unlikely that characters will be out of range, as they mostly
+            # DEV: come from Datadog-controlled sources.
+            # DEV: Trying to `match?` is measurably faster than a `gsub!` that does not match.
+            invalid_chars = Ext::Datadog::INVALID_TAG_KEY_CHARS
+            key.gsub!(invalid_chars, "_") if invalid_chars.match?(key)
+            key
+          end
+
+          # Replaces invalid characters with `_`, then replaces `=` with `~`.
+          #
+          # The argument `value` belongs to {TraceDigest}, thus should not be directly modified.
+          # Returns a new String object for the serialized value.
+          def serialize_tag_value(value)
+            # DEV: It's unlikely that characters will be out of range, as they mostly
+            # DEV: come from Datadog-controlled sources.
+            # DEV: Trying to `match?` is measurably faster than a `gsub` that does not match.
+            invalid_chars = Ext::Datadog::INVALID_TAG_VALUE_CHARS
+            serialized = invalid_chars.match?(value) ? value.gsub(invalid_chars, "_") : value
+            # DEV: Checking for an unlikely '=' is faster than a no-op `tr`.
+            serialized.include?("=") ? serialized.tr("=", "~") : serialized
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "../../sampling/ext"
+
+module Datadog
+  module Tracing
+    module Distributed
+      class TraceState
+        module Ext
+          TRACESTATE_MAX_SIZE_LIMIT = 512
+          TRACESTATE_MAX_LIST_VENDORS = 32
+          TRACESTATE_VALUE_SIZE_LIMIT = 256
+
+          module Datadog
+            # 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
+            INVALID_ORIGIN_CHARS = /[\u0000-\u0019,;~\u007F-\u{10FFFF}]/.freeze
+            REMAP_ORIGIN_CHARS = /=/.freeze
+            INVALID_TAG_KEY_CHARS = /[\u0000-\u0020,=\u007F-\u{10FFFF}]/.freeze
+            INVALID_TAG_VALUE_CHARS = /[\u0000-\u001F,;\u007E-\u{10FFFF}]/.freeze
+          end
+
+          module OpenTelemetry
+            MAX_THRESHOLD = 1 << 56
+            MAX_ENCODABLE_THRESHOLD = MAX_THRESHOLD - 1
+            UINT64_MODULO = 1 << 64
+            UINT64_MASK = UINT64_MODULO - 1
+            VALID_THRESHOLD = /\A[0-9a-f]{1,14}\z/
+            VALID_RANDOM_VALUE = /\A[0-9a-f]{14}\z/
+            NON_PROBABILITY_DECISIONS = Set[
+              Sampling::Ext::Decision::MANUAL,
+              Sampling::Ext::Decision::ASM,
+              Sampling::Ext::Decision::AI_GUARD,
+            ].freeze
+          end
+        end
+      end
+    end
+  end
+end