class OpenTelemetry::Trace::Tracestate

Tracestate is a part of SpanContext, represented by an immutable list of string key/value pairs and formally defined by the W3C Trace Context specification www.w3.org/TR/trace-context/

Constants

DEFAULT
MAX_MEMBER_COUNT
VALID_KEY
VALID_VALUE

Public Class Methods

create(hash) click to toggle source

@api private Returns a new Tracestate created from the Hash provided. This skips validation of the keys and values, assuming they are already valid. This method is intended only for the use of instance methods in this class.

# File lib/opentelemetry/trace/tracestate.rb, line 59
def create(hash)
  new(hash)
end
from_hash(hash) click to toggle source

Returns a Tracestate created from a Hash.

@param [Hash<String, String>] hash Key-value pairs to store in the

Tracestate. Keys and values are validated against the W3C Trace
Context specification, and any invalid members are logged at
DEBUG level and dropped.

@return [Tracestate] A new Tracestate instance or DEFAULT

# File lib/opentelemetry/trace/tracestate.rb, line 44
def from_hash(hash)
  hash = hash.select do |k, v|
    valid = VALID_KEY.match?(k) && VALID_VALUE.match?(v)
    OpenTelemetry.logger.debug("Invalid Tracestate member - #{k} : #{v}") unless valid
    valid
  end
  new(hash)
end
from_string(header) click to toggle source

Returns a newly created Tracestate parsed from the header provided.

@param [String] header Encoding of the tracestate header defined by

the W3C Trace Context specification https://www.w3.org/TR/trace-context/

@return [Tracestate] A new Tracestate instance or DEFAULT

# File lib/opentelemetry/trace/tracestate.rb, line 21
def from_string(header) # rubocop:disable Metrics/CyclomaticComplexity:
  return DEFAULT if header.nil? || header.empty?

  hash = header.split(',').each_with_object({}) do |member, memo|
    member.strip!
    kv = member.split('=')
    k, v = *kv
    next unless kv.length == 2 && VALID_KEY.match?(k) && VALID_VALUE.match?(v)

    memo[k] = v
  end
  return DEFAULT if hash.empty?

  new(hash)
end
new(hash) click to toggle source

@api private The constructor is private and only for use internally by the class. Users should use the {from_hash} or {from_string} factory methods to obtain a {Tracestate} instance.

@param [Hash<String, String>] hash Key-value pairs @return [Tracestate]

# File lib/opentelemetry/trace/tracestate.rb, line 76
def initialize(hash)
  excess = hash.size - MAX_MEMBER_COUNT
  hash = Hash[hash.drop(excess)] if excess.positive?
  @hash = hash.freeze
end

Public Instance Methods

==(other) click to toggle source

Returns true if this Tracestate equals other.

@param [Tracestate] other The Tracestate for comparison. @return [Boolean] true if this Tracestate == other, else false.

# File lib/opentelemetry/trace/tracestate.rb, line 151
def ==(other)
  @hash == other.to_h
end
[](key)
Alias for: value
delete(key) click to toggle source

Deletes the key/value pair associated with the given key.

@param [String] key The key to remove. @return [Tracestate] self, if unchanged, or a new Tracestate without

the specified key.
# File lib/opentelemetry/trace/tracestate.rb, line 115
def delete(key)
  return self unless @hash.key?(key)

  h = Hash[@hash]
  h.delete(key)
  self.class.create(h)
end
empty?() click to toggle source

Returns true if this Tracestate is empty.

@return [Boolean] true if this Tracestate is empty, else false.

# File lib/opentelemetry/trace/tracestate.rb, line 143
def empty?
  @hash.empty?
end
set_value(key, value) click to toggle source

Adds a new key/value pair or updates an existing value for a given key. Keys and values are validated against the W3C Trace Context specification, and any invalid members are logged at DEBUG level and ignored.

@param [String] key The key to add or update. @param [String] value The value to add or update. @return [Tracestate] self, if unchanged, or a new Tracestate containing

the new or updated key/value pair.
# File lib/opentelemetry/trace/tracestate.rb, line 102
def set_value(key, value)
  return self unless VALID_KEY.match?(key) && VALID_VALUE.match?(value)

  h = Hash[@hash]
  h[key] = value
  self.class.create(h)
end
to_h() click to toggle source

Returns this Tracestate as a Hash.

@return [Hash] the members of this Tracestate

# File lib/opentelemetry/trace/tracestate.rb, line 136
def to_h
  @hash.dup
end
to_s() click to toggle source

Returns this Tracestate encoded according to the W3C Trace Context specification www.w3.org/TR/trace-context/

@return [String] this Tracestate encoded as a string.

# File lib/opentelemetry/trace/tracestate.rb, line 127
def to_s
  @hash.inject(+'') do |memo, (k, v)|
    memo << k << '=' << v << ','
  end.chop! || ''
end
value(key) click to toggle source

Returns the value associated with the given key, or nil if the key is not present.

@param [String] key The key to lookup. @return [String] The value associated with the key, or nil.

# File lib/opentelemetry/trace/tracestate.rb, line 87
def value(key)
  @hash[key]
end
Also aliased as: []