traces 0.1.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af4a77480dd1e8a5f9805b47410c4cfc10736776eb3d0e240256eecdb9aef998
-  data.tar.gz: 945a6a8c0fec8382d3c3770e011ec102c4be998df3af84d77b7cc99596a75c86
+  metadata.gz: 17d36e478e92a07d18262c627d9c2986004a2fe81985fd80721da6adf4d2c282
+  data.tar.gz: 44c0dd539bcda08a88d69478c56eeaa7eaa52f34b4bc2941510b7996d4b2bf28
 SHA512:
-  metadata.gz: 3410ef5b66b6d647a37c44374453759dc191c3366b614093604981a57304dc5b3ff43a026207b7364886cbad43400aeb65652ee3aef6ab68694e52379018956e
-  data.tar.gz: 73dc84b89273d731f0baa1839c8ef54d9ab292558b2ee5d99acc9c6dbf937510db3381b48a179d952faa1728c203142cff08ddd211a9960aafda05f320e5af43
+  metadata.gz: 5684c47004efb75753fed8f3c7d980cd72d6646c8eaa2eafc2fc001d25a96c80c7c3ad590d01fb7859544e8567c4318a29892cba70ec2fcaeefd81219ce6f34d
+  data.tar.gz: 8c8f7abd2de878319c61b8ffa491d8946f9fc8b782aad65911520948bc1efe4d545e10829fe0ee63b465443358ad858430429e485d3378238cd6e70e70464d06

checksums.yaml.gz.sig

@@ -0,0 +1,3 @@
+)���pGRW*M��y�CS4+� x+v?�
X���w
+�v��Ҟ��W(��|	��5�Z��>�gpYު߇�Ǒ��%i�kk*�E���7�l>�O��.S�O8AcS�}t�0\▩v\��b	D>_K�7�N7��|�[W`4?1b��>lU��\&q� �IG���>`z~�3t�/T�?n�BM(z�����B'P�o�O���@�8{�
+�o�b5x���r{H��߰2�A�1��x/����5�n�HR���w���/*�2?�j۶F�_I�W2��ֈ�F�%�у��!�¹“�m@v���/H�ˡd�O��V�Y����Б�><1'��P�V��@h]Yv��I�
�Ҭ�k"�c9'u\���l�<[�f�-M�

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.measure(self, name, **attributes) do
-				yield
+		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
+			
+			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)
+				
+				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
+		
+		# This is the default.
+		self.include(Console)
 	end
 end

data/lib/traces/backend/test.rb

@@ -20,14 +20,75 @@
 # 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)
-			yield
+		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
+			
+			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!"
+				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
+		
+		self.include(Test)
 	end
-end
+end

data/lib/traces/backend.rb

@@ -21,10 +21,14 @@
 # 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']
-			path = File.join('backend', backend)
-			require_relative(path)
+			require(backend)
 		end
 	end
 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)
+			if version == '00'
+				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,19 +23,20 @@
 require_relative 'backend'
 
 module Traces
+	# A module which contains tracing specific wrappers.
 	module Provider
-		def trace_provider
-			@trace_provider ||= Module.new
+		def traces_provider
+			@traces_provider ||= Module.new
 		end
 	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)
-			klass.prepend(Backend)
 			
-			provider = klass.trace_provider
+			provider = klass.traces_provider
 			provider.prepend(Backend)
 			
 			klass.prepend(provider)

data/lib/traces/version.rb

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

metadata

@@ -1,14 +1,42 @@
 --- !ruby/object:Gem::Specification
 name: traces
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
-cert_chain: []
-date: 2021-10-09 00:00:00.000000000 Z
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEhDCCAuygAwIBAgIBATANBgkqhkiG9w0BAQsFADA3MTUwMwYDVQQDDCxzYW11
+  ZWwud2lsbGlhbXMvREM9b3Jpb250cmFuc2Zlci9EQz1jby9EQz1uejAeFw0yMTA4
+  MTYwNjMzNDRaFw0yMjA4MTYwNjMzNDRaMDcxNTAzBgNVBAMMLHNhbXVlbC53aWxs
+  aWFtcy9EQz1vcmlvbnRyYW5zZmVyL0RDPWNvL0RDPW56MIIBojANBgkqhkiG9w0B
+  AQEFAAOCAY8AMIIBigKCAYEAyXLSS/cw+fXJ5e7hi+U/TeChPWeYdwJojDsFY1xr
+  xvtqbTTL8gbLHz5LW3QD2nfwCv3qTlw0qI3Ie7a9VMJMbSvgVEGEfQirqIgJXWMj
+  eNMDgKsMJtC7u/43abRKx7TCURW3iWyR19NRngsJJmaR51yGGGm2Kfsr+JtKKLtL
+  L188Wm3f13KAx7QJU8qyuBnj1/gWem076hzdA7xi1DbrZrch9GCRz62xymJlrJHn
+  9iZEZ7AxrS7vokhMlzSr/XMUihx/8aFKtk+tMLClqxZSmBWIErWdicCGTULXCBNb
+  E/mljo4zEVKhlTWpJklMIhr55ZRrSarKFuW7en0+tpJrfsYiAmXMJNi4XAYJH7uL
+  rgJuJwSaa/dMz+VmUoo7VKtSfCoOI+6v5/z0sK3oT6sG6ZwyI47DBq2XqNC6tnAj
+  w+XmCywiTQrFzMMAvcA7rPI4F0nU1rZId51rOvvfxaONp+wgTi4P8owZLw0/j0m4
+  8C20DYi6EYx4AHDXiLpElWh3AgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8E
+  BAMCBLAwHQYDVR0OBBYEFB6ZaeWKxQjGTI+pmz7cKRmMIywwMC4GA1UdEQQnMCWB
+  I3NhbXVlbC53aWxsaWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWB
+  I3NhbXVlbC53aWxsaWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEB
+  CwUAA4IBgQBVoM+pu3dpdUhZM1w051iw5GfiqclAr1Psypf16Tiod/ho//4oAu6T
+  9fj3DPX/acWV9P/FScvqo4Qgv6g4VWO5ZU7z2JmPoTXZtYMunRAmQPFL/gSUc6aK
+  vszMHIyhtyzRc6DnfW2AiVOjMBjaYv8xXZc9bduniRVPrLR4J7ozmGLh4o4uJp7w
+  x9KCFaR8Lvn/r0oJWJOqb/DMAYI83YeN2Dlt3jpwrsmsONrtC5S3gOUle5afSGos
+  bYt5ocnEpKSomR9ZtnCGljds/aeO1Xgpn2r9HHcjwnH346iNrnHmMlC7BtHUFPDg
+  Ts92S47PTOXzwPBDsrFiq3VLbRjHSwf8rpqybQBH9MfzxGGxTaETQYOd6b4e4Ag6
+  y92abGna0bmIEb4+Tx9rQ10Uijh1POzvr/VTH4bbIPy9FbKrRsIQ24qDbNJRtOpE
+  RAOsIl+HOBTb252nx1kIRN5hqQx272AJCbCjKx8egcUQKffFVVCI0nye09v5CK+a
+  HiLJ8VOFx6w=
+  -----END CERTIFICATE-----
+date: 2021-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -33,13 +61,11 @@ files:
 - lib/traces.rb
 - lib/traces/backend.rb
 - lib/traces/backend/console.rb
-- lib/traces/backend/datadog.rb
-- lib/traces/backend/open_telemetry.rb
 - lib/traces/backend/test.rb
 - lib/traces/context.rb
 - lib/traces/provider.rb
 - lib/traces/version.rb
-homepage: https://github.com/socketry/trace
+homepage: https://github.com/socketry/traces
 licenses:
 - MIT
 metadata: {}
@@ -58,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Application instrumentation and tracing.

data/lib/traces/backend/datadog.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
-
-require_relative '../context'
-
-require 'ddtrace'
-
-module Traces
-	module Backend
-		private
-		
-		def trace(name, parent = nil, attributes: nil, &block)
-			if parent
-				parent = ::Datadog::Context.new(
-					trace_id: parent.trace_id,
-					span_id: parent.span_id,
-					sampled: parent.sampled?,
-				)
-			end
-			
-			::Datadog.tracer.trace(name, child_of: parent, tags: attributes) do |span|
-				begin
-					if block.arity.zero?
-						yield
-					else
-						yield trace_span_context(span)
-					end
-				rescue Exception => error
-					Console.logger.error(self, error)
-					raise
-				end
-			end
-		end
-		
-		def trace_span_context(span)
-			flags = 0
-			
-			if span.sampled
-				flags |= Context::SAMPLED
-			end
-			
-			return Context.new(
-				span.trace_id,
-				span.span_id,
-				flags,
-				nil,
-				remote: false
-			)
-		end
-	end
-end

data/lib/traces/backend/open_telemetry.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-# Copyright, 2021, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
-
-require_relative '../context'
-
-require 'opentelemetry/sdk'
-
-module Traces
-	module Backend
-		private
-		
-		# Provides a backend that writes data to OpenTelemetry.
-		# See <https://github.com/open-telemetry/opentelemetry-ruby> for more details.
-		TRACER = ::OpenTelemetry.tracer_provider.tracer(Traces, Traces::VERSION)
-		
-		def trace(name, parent = nil, attributes: nil, &block)
-			if parent
-				# Convert it to the required object:
-				parent = ::OpenTelemetry::Traces::SpanContext.new(
-					trace_id: parent.trace_id,
-					span_id: parent.span_id,
-					trace_flags: ::OpenTelemetry::Traces::TracesFlags.from_byte(parent.flags),
-					tracestate: parent.state,
-					remote: parent.remote?
-				)
-			end
-			
-			span = TRACER.start_span(name, with_parent: parent, attributes: attributes)
-			
-			begin
-				if block.arity.zero?
-					yield
-				else
-					yield trace_span_context(span)
-				end
-			rescue Exception => error
-				span&.record_exception(error)
-				span&.status = ::OpenTelemetry::Traces::Status.error("Unhandled exception of type: #{error.class}")
-				raise
-			ensure
-				span&.finish
-			end
-		end
-		
-		def trace_span_context(span)
-			context = span.context
-			
-			return Context.new(
-				context.trace_id,
-				context.span_id,
-				context.trace_flags,
-				context.tracestate,
-				remote: context.remote?
-			)
-		end
-	end
-end