Class: Traces::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/traces/context.rb

Overview

A generic representation of the current tracing context.

Constant Summary collapse

SAMPLED = 
0x01

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(trace_id, parent_id, flags, state = nil, remote: false) ⇒ Context

Returns a new instance of Context.



50
51
52
53
54
55
56
 
# File 'lib/traces/context.rb', line 50

def initialize(trace_id, parent_id, flags, state = nil, remote: false)
	@trace_id = trace_id
	@parent_id = parent_id
	@flags = flags
	@state = state
	@remote = remote
end

Instance Attribute Details

#flags ⇒ Object (readonly)

An 8-bit field that controls tracing flags such as sampling, trace level, etc. These flags are recommendations given by the caller rather than strict rules.



70
71
72
 
# File 'lib/traces/context.rb', line 70

def flags
  @flags
end

#parent_id ⇒ Object (readonly)

The ID of this request as known by the caller (in some tracing systems, this is known as the span-id, where a span is the execution of a client request). It is represented as an 8-byte array, for example, 00f067aa0ba902b7. All bytes as zero (0000000000000000) is considered an invalid value.



67
68
69
 
# File 'lib/traces/context.rb', line 67

def parent_id
  @parent_id
end

#state ⇒ Object (readonly)

Provides additional vendor-specific trace identification information across different distributed tracing systems. Conveys information about the request’s position in multiple distributed tracing graphs.



73
74
75
 
# File 'lib/traces/context.rb', line 73

def state
  @state
end

#trace_id ⇒ Object (readonly)

The ID of the whole trace forest and is used to uniquely identify a distributed trace through a system. It is represented as a 16-byte array, for example, 4bf92f3577b34da6a3ce929d0e0e4736. All bytes as zero (00000000000000000000000000000000) is considered an invalid value.



64
65
66
 
# File 'lib/traces/context.rb', line 64

def trace_id
  @trace_id
end

Class Method Details

.local(flags = 0, **options) ⇒ Object

Create a local trace context which is likley to be globally unique.



34
35
36
 
# File 'lib/traces/context.rb', line 34

def self.local(flags = 0, **options)
	self.new(SecureRandom.hex(16), SecureRandom.hex(8), flags, **options)
end

.nested(parent, flags = 0) ⇒ Object

Nest a local trace context in an optional parent context.



40
41
42
43
44
45
46
 
# File 'lib/traces/context.rb', line 40

def self.nested(parent, flags = 0)
	if parent
		parent.nested(flags)
	else
		self.local(flags)
	end
end

.parse(parent, state = nil, **options) ⇒ Object

Parse a string representation of a distributed trace.



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/traces/context.rb', line 14

def self.parse(parent, state = nil, **options)
	version, trace_id, parent_id, flags = parent.split('-')
	
	if version == '00'
		flags = Integer(flags, 16)
		
		if state.is_a?(String)
			state = state.split(',')
		end
		
		if state
			state = state.map{|item| item.split('=')}.to_h
		end
		
		self.new(trace_id, parent_id, flags, state, **options)
	end
end

Instance Method Details

#as_json ⇒ Object 



90
91
92
93
94
95
96
97
98
 
# File 'lib/traces/context.rb', line 90

def as_json
	{
		trace_id: @trace_id,
		parent_id: @parent_id,
		flags: @flags,
		state: @state,
		remote: @remote
	}
end

#nested(flags = @flags) ⇒ Object

Create a new nested trace context in which spans can be recorded.



59
60
61
 
# File 'lib/traces/context.rb', line 59

def nested(flags = @flags)
	Context.new(@trace_id, SecureRandom.hex(8), flags, @state, remote: @remote)
end

#remote? ⇒ Boolean

Whether this context was created from a distributed trace header.

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/traces/context.rb', line 81

def remote?
	@remote
end

#sampled? ⇒ Boolean

Denotes that the caller may have recorded trace data. When unset, the caller did not record trace data out-of-band.

Returns:

  • (Boolean) 


76
77
78
 
# File 'lib/traces/context.rb', line 76

def sampled?
	(@flags & SAMPLED) != 0
end

#to_json ⇒ Object 



100
101
102
 
# File 'lib/traces/context.rb', line 100

def to_json(...)
	as_json.to_json(...)
end

#to_s ⇒ Object

A string representation of the trace context (excluding trace state).



86
87
88
 
# File 'lib/traces/context.rb', line 86

def to_s
	"00-#{@trace_id}-#{@parent_id}-#{@flags.to_s(16)}"
end