traces 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8d74b7b8712105a772f7d9cde7108dc2218137570ba71f11632cd539808a740
-  data.tar.gz: 4a63fcc5efe56b48a074a6e66587bab35395daf9a0b20864e59b4987db9530e3
+  metadata.gz: 389518e7025f63c5c99a5599000e12191ca8634b38f8d05ba727fe22b0fe3aa5
+  data.tar.gz: f8648d7990686c3abbd955f4b45869cf67c88e2b644da156e914bc2cac92087d
 SHA512:
-  metadata.gz: f2291cae8c41890078266aaedbd14f760e94b18d76e55b2b32c792e6188770cee4565e96972711bf0cc83f6ddaacd1700d767eca56584423e7c55ee322ce295c
-  data.tar.gz: 33b0e8f87d219f8c4122d356b2ee1188d6df6f89aea9f8583757bf1cf288c4ed393cd2bda96804c84fb7812014d545d872923cb7bfff22a8e7152f87aeb2b8aa
+  metadata.gz: a3d9834ff556a722bb7a82dae4c824c94888af648a70954ab2a7c720e26e622ce826262838016169388734b8f9beaa6c2b74cd0a4ea9a669295fce70ae41c61c
+  data.tar.gz: 4fd9a0b83fb293e04fec5ff91431ee55ac2a6fcb86609288795d4d22486cf51fdcb16ec21610487b6e99d9b5662ab30d0999360ce5aaf430408b75a56ae077b8

data/lib/traces/backend/console.rb

@@ -20,16 +20,71 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative '../context'
+
 require 'console'
+require 'fiber'
+
+class Fiber
+	attr_accessor :traces_backend_context
+end
 
 module Traces
 	module Backend
-		private
-		
-		def trace(name, parent = nil, attributes: nil, &block)
-			Console.logger.info(self, name, attributes)
+		# A backend which logs all spans to the console logger output.
+		module Console
+			# A span which validates tag assignment.
+			class Span
+				def initialize(context, instance, name)
+					@context = context
+					@instance = instance
+					@name = name
+				end
+				
+				attr :context
+				
+				# Assign some metadata to the span.
+				# @parameter key [String] The metadata key.
+				# @parameter value [Object] The metadata value. Should be coercable to a string.
+				def []= key, value
+					::Console.logger.info(@context, @name, "#{key} = #{value}")
+				end
+			end
 			
-			yield
+			module Interface
+				# Trace the given block of code and log the execution.
+				# @parameter name [String] A useful name/annotation for the recorded span.
+				# @parameter attributes [Hash] Metadata for the recorded span.
+				def trace(name, attributes: {}, &block)
+					context = Context.nested(Fiber.current.traces_backend_context)
+					Fiber.current.traces_backend_context = context
+					
+					::Console.logger.info(self, name, attributes)
+					
+					if block.arity.zero?
+						yield
+					else
+						yield Span.new(context, self, name)
+					end
+				end
+				
+				# Assign a trace context to the current execution scope.
+				def trace_context= context
+					Fiber.current.traces_backend_context = context
+				end
+				
+				# Get a trace context from the current execution scope.
+				# @parameter span [Span] An optional span from which to extract the context.
+				def trace_context(span = nil)
+					if span
+						span.context
+					else
+						Fiber.current.traces_backend_context
+					end
+				end
+			end
 		end
+		
+		Interface = Console::Interface
 	end
 end

data/lib/traces/backend/test.rb

@@ -20,18 +20,76 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'console'
+require_relative '../context'
+require 'fiber'
+
+class Fiber
+	attr_accessor :traces_backend_context
+end
 
 module Traces
 	module Backend
-		private
-		
-		def trace(name, parent = nil, attributes: nil, &block)
-			unless name.is_a?(String)
-				raise ArgumentError, "Invalid name!"
+		# A backend which validates interface usage.
+		module Test
+			# A span which validates tag assignment.
+			class Span
+				def initialize(context)
+					@context = context
+				end
+				
+				attr :context
+				
+				# Assign some metadata to the span.
+				# @parameter key [String] The metadata key.
+				# @parameter value [Object] The metadata value. Should be coercable to a string.
+				def []= key, value
+					unless key.is_a?(String)
+						raise ArgumentError, "Invalid name!"
+					end
+					
+					unless String(value)
+						raise ArgumentError, "Invalid value!"
+					end
+				end
 			end
 			
-			yield
+			module Interface
+				# Trace the given block of code and validate the interface usage.
+				# @parameter name [String] A useful name/annotation for the recorded span.
+				# @parameter attributes [Hash] Metadata for the recorded span.
+				def trace(name, attributes: nil, &block)
+					unless name.is_a?(String)
+						raise ArgumentError, "Invalid name!"
+					end
+					
+					context = Context.nested(Fiber.current.traces_backend_context)
+					Fiber.current.traces_backend_context = context
+					
+					if block.arity.zero?
+						yield
+					else
+						span = Span.new(context)
+						yield span
+					end
+				end
+				
+				# Assign a trace context to the current execution scope.
+				def trace_context= context
+					Fiber.current.traces_backend_context = context
+				end
+				
+				# Get a trace context from the current execution scope.
+				# @parameter span [Span] An optional span from which to extract the context.
+				def trace_context(span = nil)
+					if span
+						span.context
+					else
+						Fiber.current.traces_backend_context
+					end
+				end
+			end
 		end
+		
+		Interface = Test::Interface
 	end
 end

data/lib/traces/backend.rb

@@ -21,7 +21,12 @@
 # THE SOFTWARE.
 
 module Traces
+	# Require a specific trace backend.
 	def self.require_backend(env = ENV)
+		if const_defined?(:Backend)
+			raise RuntimeError, "Backend already required!"
+		end
+		
 		if backend = env['TRACES_BACKEND']
 			require(backend)
 		end

data/lib/traces/context.rb

@@ -20,15 +20,19 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require 'securerandom'
+
 module Traces
-	# A generic representation of the current span.
-	# We follow the <https://github.com/openzipkin/b3-propagation> model.
+	# A generic representation of the current tracing context.
 	class Context
-		def self.parse(parent, state = nil)
+		# Parse a string representation of a distributed trace.
+		# @parameter parent [String] The parent trace context.
+		# @parameter state [Array(String)] Any attached trace state.
+		def self.parse(parent, state = nil, **options)
 			version, trace_id, parent_id, flags = parent.split('-')
 			
 			if version == '00'
-				flags = Integer(trace_flags, 16)
+				flags = Integer(flags, 16)
 				
 				if state.is_a?(String)
 					state = state.split(',')
@@ -38,7 +42,23 @@ module Traces
 					state = state.map{|item| item.split('=')}
 				end
 				
-				self.new(trace_id, parent_id, flags, state)
+				self.new(trace_id, parent_id, flags, state, **options)
+			end
+		end
+		
+		# Create a local trace context which is likley to be globally unique.
+		# @parameter flags [Integer] Any trace context flags.
+		def self.local(flags = 0, **options)
+			self.new(SecureRandom.hex(16), SecureRandom.hex(8), flags, **options)
+		end
+		
+		# Nest a local trace context in an optional parent context.
+		# @parameter parent [Context] An optional parent context.
+		def self.nested(parent, flags = 0)
+			if parent
+				parent.nested(flags)
+			else
+				self.local(flags)
 			end
 		end
 		
@@ -46,25 +66,40 @@ module Traces
 		
 		def initialize(trace_id, parent_id, flags, state = nil, remote: false)
 			@trace_id = trace_id
-			@parent_id = span_id
+			@parent_id = parent_id
 			@flags = flags
 			@state = state
 			@remote = remote
 		end
 		
+		# Create a new nested trace context in which spans can be recorded.
+		def nested(flags = @flags)
+			Context.new(@trace_id, SecureRandom.hex(8), flags, @state, remote: @remote)
+		end
+		
+		# 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.
 		attr :trace_id
-		attr :span_id
+		
+		# 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.
+		attr :parent_id
+		
+		# 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.
 		attr :flags
+		
+		# Provides additional vendor-specific trace identification information across different distributed tracing systems. Conveys information about the request’s position in multiple distributed tracing graphs.
 		attr :state
 		
+		# Denotes that the caller may have recorded trace data. When unset, the caller did not record trace data out-of-band.
 		def sampled?
 			@flags & SAMPLED
 		end
 		
+		# Whether this context was created from a distributed trace header.
 		def remote?
 			@remote
 		end
 		
+		# A string representation of the trace context (excluding trace state).
 		def to_s
 			"00-#{@trace_id}-#{@parent_id}-#{@flags.to_s(16)}"
 		end

data/lib/traces/provider.rb

@@ -23,6 +23,7 @@
 require_relative 'backend'
 
 module Traces
+	# A module which contains tracing specific wrappers.
 	module Provider
 		def traces_provider
 			@traces_provider ||= Module.new
@@ -30,12 +31,13 @@ module Traces
 	end
 	
 	# Bail out if there is no backend configured.
-	if Traces.const_defined?(:Backend)
+	if self.const_defined?(:Backend)
+		# Extend the specified class in order to emit traces.
 		def self.Provider(klass, &block)
 			klass.extend(Provider)
 			
 			provider = klass.traces_provider
-			provider.prepend(Backend)
+			provider.prepend(Backend::Interface)
 			
 			klass.prepend(provider)
 			

data/lib/traces/version.rb

@@ -21,5 +21,5 @@
 # THE SOFTWARE.
 
 module Traces
-	VERSION = "0.2.0"
+	VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: traces
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -36,7 +36,7 @@ cert_chain:
   RAOsIl+HOBTb252nx1kIRN5hqQx272AJCbCjKx8egcUQKffFVVCI0nye09v5CK+a
   HiLJ8VOFx6w=
   -----END CERTIFICATE-----
-date: 2021-10-17 00:00:00.000000000 Z
+date: 2021-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec