Class: OpenTelemetry::Trace::Tracestate

Inherits:
Object
  • Object
show all
Defined in:
lib/opentelemetry/trace/tracestate.rb

Overview

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/

Constant Summary collapse

DEFAULT = 
new({})

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(hash) ⇒ Tracestate

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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 OpenTelemetry::Trace::Tracestate instance.

Parameters:

  • hash (Hash<String, String>) —

    Key-value pairs



76
77
78
79
80
 
# 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

Class Method Details

.create(hash) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.



59
60
61
 
# File 'lib/opentelemetry/trace/tracestate.rb', line 59

def create(hash)
  new(hash)
end

.from_hash(hash) ⇒ Tracestate

Returns a Tracestate created from a Hash.

Parameters:

  • hash (Hash<String, String>) —

    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.

Returns:

  • (Tracestate) —

    A new Tracestate instance or DEFAULT



44
45
46
47
48
49
50
51
 
# 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) ⇒ Tracestate

Returns a newly created Tracestate parsed from the header provided.

Parameters:

Returns:

  • (Tracestate) —

    A new Tracestate instance or DEFAULT



21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# 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

Instance Method Details

#==(other) ⇒ Boolean

Returns true if this Tracestate equals other.

Parameters:

  • other (Tracestate) —

    The Tracestate for comparison.

Returns:

  • (Boolean) —

    true if this Tracestate == other, else false.



151
152
153
 
# File 'lib/opentelemetry/trace/tracestate.rb', line 151

def ==(other)
  @hash == other.to_h
end

#delete(key) ⇒ Tracestate

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

Parameters:

  • key (String) —

    The key to remove.

Returns:

  • (Tracestate) —

    self, if unchanged, or a new Tracestate without the specified key.



115
116
117
118
119
120
121
 
# 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? ⇒ Boolean

Returns true if this Tracestate is empty.

Returns:

  • (Boolean) —

    true if this Tracestate is empty, else false.



143
144
145
 
# File 'lib/opentelemetry/trace/tracestate.rb', line 143

def empty?
  @hash.empty?
end

#set_value(key, value) ⇒ Tracestate

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.

Parameters:

  • key (String) —

    The key to add or update.

  • value (String) —

    The value to add or update.

Returns:

  • (Tracestate) —

    self, if unchanged, or a new Tracestate containing the new or updated key/value pair.



102
103
104
105
106
107
108
 
# 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 ⇒ Hash

Returns this Tracestate as a Hash.

Returns:

  • (Hash) —

    the members of this Tracestate



136
137
138
 
# File 'lib/opentelemetry/trace/tracestate.rb', line 136

def to_h
  @hash.dup
end

#to_s ⇒ String

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

Returns:

  • (String) —

    this Tracestate encoded as a string.



127
128
129
130
131
 
# 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) ⇒ String Also known as: []

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

Parameters:

  • key (String) —

    The key to lookup.

Returns:

  • (String) —

    The value associated with the key, or nil.



87
88
89
 
# File 'lib/opentelemetry/trace/tracestate.rb', line 87

def value(key)
  @hash[key]
end