traces 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 861c8515f80fb555c1bf5015a90c6120f966e56bc9317deb3ab0fc706f222681
-  data.tar.gz: 41273d76845bb95d39632623270425a2a932fccff831d73d268b3f9d04fc9a16
+  metadata.gz: 284452f4bfc37587b942b74918b2807ad6c51ee09d5a93bd39d5eefa6ba66aa1
+  data.tar.gz: 7f2d42000701312aeeb5015b19f888d5ed5acb4d4c79322e894b584292c0aed1
 SHA512:
-  metadata.gz: cf177547ceee5e884fd4672d00fcb1db5ba0a8c4e85c4a05076b7a97b046d4f5e70998fdc5adae5b58089070a0e9c6bff161d58db6e6560fb41988297cf1467b
-  data.tar.gz: 8bdead1ff01e654ef7aa6fd0ff3dee3387652262b955a45d5c8ab90cfca1f8820fb0710248164d581961277a36220741e52f6ff8980450f5d28e88abf1fc6f2a
+  metadata.gz: b32ad9f2018cce91b418907c052b6f9c8b63b2fad08ccdc4e1abcf3dd623e0209ad3bed87b5dfdf4138c20110e0e1806caec1a1b62bbd064b2699498822e7e24
+  data.tar.gz: 41e7cd96fb1dcb21f727d2753854ba77c08378fee1ad459b9f696d2bdecc857841c7fda0f3cf2d3e3b03647bfbe6cd137a846cb1c6230a5cbcc1d149899ea031

data/lib/traces/backend/console.rb

@@ -31,6 +31,7 @@ end
 
 module Traces
 	module Backend
+		# A backend which logs all spans to the console logger output.
 		module Console
 			# A span which validates tag assignment.
 			class Span
@@ -50,41 +51,40 @@ module Traces
 				end
 			end
 			
-			private
-			
-			# 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)
+			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, resource: self, attributes: {}, &block)
+					context = Context.nested(Fiber.current.traces_backend_context)
+					Fiber.current.traces_backend_context = context
+					
+					::Console.logger.info(resource, name, attributes)
+					
+					if block.arity.zero?
+						yield
+					else
+						yield Span.new(context, self, name)
+					end
+				end
 				
-				if block.arity.zero?
-					yield
-				else
-					yield Span.new(context, self, name)
+				# Assign a trace context to the current execution scope.
+				def trace_context= context
+					Fiber.current.traces_backend_context = context
 				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
+				
+				# 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
 		
-		# This is the default.
-		self.include(Console)
+		Interface = Console::Interface
 	end
 end

data/lib/traces/backend/test.rb

@@ -29,6 +29,7 @@ end
 
 module Traces
 	module Backend
+		# A backend which validates interface usage.
 		module Test
 			# A span which validates tag assignment.
 			class Span
@@ -43,52 +44,57 @@ module Traces
 				# @parameter value [Object] The metadata value. Should be coercable to a string.
 				def []= key, value
 					unless key.is_a?(String)
-						raise ArgumentError, "Invalid name!"
+						raise ArgumentError, "Invalid name (must be String): #{key.inspect}!"
 					end
 					
 					unless String(value)
-						raise ArgumentError, "Invalid value!"
+						raise ArgumentError, "Invalid value (must be String): #{value.inspect}!"
 					end
 				end
 			end
 			
-			private
-			
-			# 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!"
+			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, resource: self.class.name, attributes: nil, &block)
+					unless name.is_a?(String)
+						raise ArgumentError, "Invalid name (must be String): #{name.inspect}!"
+					end
+					
+					if resource
+						# It should be convertable:
+						resource = resource.to_s
+					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
 				
-				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
+				# Assign a trace context to the current execution scope.
+				def trace_context= context
+					Fiber.current.traces_backend_context = context
 				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
+				
+				# 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
 		
-		self.include(Test)
+		Interface = Test::Interface
 	end
-end
+end

data/lib/traces/backend.rb

@@ -23,10 +23,6 @@
 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

@@ -49,7 +49,7 @@ module Traces
 		# 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)
+			self.new(SecureRandom.hex(16), SecureRandom.hex(8), flags, **options)
 		end
 		
 		# Nest a local trace context in an optional parent context.

data/lib/traces/provider.rb

@@ -23,6 +23,11 @@
 require_relative 'backend'
 
 module Traces
+	# @returns [Boolean] Whether there is an active backend.
+	def self.enabled?
+		self.const_defined?(:Backend)
+	end
+	
 	# A module which contains tracing specific wrappers.
 	module Provider
 		def traces_provider
@@ -31,13 +36,13 @@ module Traces
 	end
 	
 	# Bail out if there is no backend configured.
-	if self.const_defined?(:Backend)
+	if self.enabled?
 		# 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.3.1"
+	VERSION = "0.5.0"
 end

metadata

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