traces 0.13.1 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e413f837413b357d84594db5b48e6be8d5033db0896c042a0806ec1f6b6e493
-  data.tar.gz: fa2aed0ec28362aaf84983d13da4ae1e55738728b7f86045cf919b93599c23bc
+  metadata.gz: 8026283fe7d321e24324a4672e7aaf8575897c066364b44bda087c9801815647
+  data.tar.gz: 6debcfc4f4ca487fe30c0e704c771bf50c56cfa7df6ee512d94fbe9e865a3560
 SHA512:
-  metadata.gz: 85f20fe132bf1a07bb0d9633ce2793776ab1e7fe56cc3320b0db3b400b9f6723faf9a4a6c7b781e0dc4d5b210af8bcd24cfa4846ef02ce285edb93b2ed25bf94
-  data.tar.gz: 360152f3404776023b846b42dbced2ed16e533add3072d57e21c6c49cb590f3b2fcffb66daf313c09984760b9f64e87e495b888c166cb43a9968a7e55076548c
+  metadata.gz: 55987e8c56f6b60f8985d9682b1d262b06b1badce6cf6d17a2aea5e27a9bafc8bc75c8385b0c1a7d91f67e9e6f23d9a518d082c57c77b47ac0d4a8c2ba206210
+  data.tar.gz: f4dd535ff8dbcfecc3a1fe2c79a5f32a77aaa643751ac337975af98d2e8f6a5f331433281ebea851e4f2705730dc4fa8ba2e8ca02d11f50b843b3fb11ca7a1cf

data/lib/traces/backend/capture.rb

@@ -7,9 +7,7 @@ require_relative '../context'
 
 require 'fiber'
 
-class Fiber
-	attr_accessor :traces_backend_context
-end
+Fiber.attr_accessor :traces_backend_context
 
 module Traces
 	module Backend
@@ -17,6 +15,11 @@ module Traces
 		module Capture
 			# A span which validates tag assignment.
 			class Span
+				# Initialize a new span.
+				# @parameter context [Context] The context in which the span is recorded.
+				# @parameter name [String] A useful name/annotation for the recorded span.
+				# @parameter resource [String] The "resource" that the span is associated with.
+				# @parameter attributes [Hash] Metadata for the recorded span.
 				def initialize(context, name, resource, attributes)
 					@context = context
 					@name = name
@@ -36,6 +39,7 @@ module Traces
 					@attributes[key] = value
 				end
 				
+				# Convert the span to a JSON representation.
 				def as_json
 					{
 						name: @name,
@@ -45,15 +49,18 @@ module Traces
 					}
 				end
 				
+				# Convert the span to a JSON string.
 				def to_json(...)
 					as_json.to_json(...)
 				end
 			end
 			
+			# All captured spans.
 			def self.spans
 				@spans ||= []
 			end
 			
+			# The capture backend interface.
 			module Interface
 				# Trace the given block of code and log the execution.
 				# @parameter name [String] A useful name/annotation for the recorded span.

data/lib/traces/backend/console.rb

@@ -8,9 +8,7 @@ require_relative '../context'
 require 'console'
 require 'fiber'
 
-class Fiber
-	attr_accessor :traces_backend_context
-end
+Fiber.attr_accessor :traces_backend_context
 
 module Traces
 	module Backend
@@ -18,11 +16,15 @@ module Traces
 		module Console
 			# A span which validates tag assignment.
 			class Span
+				# Initialize a new span.
+				# @parameter context [Context] The context in which the span is recorded.
+				# @parameter name [String] A useful name/annotation for the recorded span.
 				def initialize(context, name)
 					@context = context
 					@name = name
 				end
 				
+				# @attribute [Context] The context in which the span is recorded.
 				attr :context
 				
 				# Assign some metadata to the span.
@@ -33,6 +35,7 @@ module Traces
 				end
 			end
 			
+			# The console backend interface.
 			module Interface
 				# Trace the given block of code and log the execution.
 				# @parameter name [String] A useful name/annotation for the recorded span.

data/lib/traces/backend/test.rb

@@ -4,11 +4,10 @@
 # Copyright, 2021-2023, by Samuel Williams.
 
 require_relative '../context'
+
 require 'fiber'
 
-class Fiber
-	attr_accessor :traces_backend_context
-end
+Fiber.attr_accessor :traces_backend_context
 
 module Traces
 	module Backend
@@ -16,10 +15,13 @@ module Traces
 		module Test
 			# A span which validates tag assignment.
 			class Span
+				# Initialize a new span.
+				# @parameter context [Context] The context in which the span is recorded.
 				def initialize(context)
 					@context = context
 				end
 				
+				# @attribute [Context] The context in which the span is recorded.
 				attr :context
 				
 				# Assign some metadata to the span.
@@ -38,6 +40,7 @@ module Traces
 				end
 			end
 			
+			# The test backend interface.
 			module Interface
 				# Trace the given block of code and validate the interface usage.
 				# @parameter name [String] A useful name/annotation for the recorded span.

data/lib/traces/backend.rb

@@ -3,27 +3,12 @@
 # Released under the MIT License.
 # Copyright, 2021-2023, by Samuel Williams.
 
-require 'console/event/failure'
+require_relative 'config'
 
 module Traces
+	# The backend implementation is responsible for recording and reporting traces.
 	module Backend
-		# Require a specific trace backend.
-		def self.require_backend(env = ENV)
-			if backend = env['TRACES_BACKEND']
-				begin
-					require(backend)
-				rescue LoadError => error
-					::Console::Event::Failure.for(error).emit(self, "Unable to load traces backend!", backend: backend, severity: :warn)
-					
-					return false
-				end
-				
-				Traces.extend(Backend::Interface)
-				
-				return true
-			end
-		end
 	end
+	
+	Config::DEFAULT.require_backend
 end
-
-Traces::Backend.require_backend

data/lib/traces/config.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+module Traces
+	# Represents a configuration for the traces library.
+	class Config
+		DEFAULT_PATH = ENV.fetch("TRACES_CONFIG_DEFAULT_PATH", "config/traces.rb")
+		
+		# Load the configuration from the given path.
+		# @parameter path [String] The path to the configuration file.
+		# @returns [Config] The loaded configuration.
+		def self.load(path)
+			config = self.new
+			
+			if File.exist?(path)
+				config.instance_eval(File.read(path), path)
+			end
+			
+			return config
+		end
+		
+		# Load the default configuration.
+		# @returns [Config] The default configuration.
+		def self.default
+			@default ||= self.load(DEFAULT_PATH)
+		end
+		
+		# Prepare the backend, e.g. by loading additional libraries or instrumentation.
+		def prepare
+		end
+		
+		# Require a specific traces backend implementation.
+		def require_backend(env = ENV)
+			if backend = env['TRACES_BACKEND']
+				begin
+					if require(backend)
+						Traces.extend(Backend::Interface)
+						
+						return true
+					end
+				rescue LoadError => error
+					warn "Unable to load traces backend: #{backend.inspect}!"
+				end
+			end
+			
+			return false
+		end
+		
+		# Load the default configuration.
+		DEFAULT = self.default
+	end
+end

data/lib/traces/context.rb

@@ -47,6 +47,12 @@ module Traces
 		
 		SAMPLED = 0x01
 		
+		# Initialize the trace context.
+		# @parameter trace_id [String] The ID of the whole trace forest.
+		# @parameter parent_id [String] The ID of this operation as known by the caller (sometimes referred to as the span ID).
+		# @parameter flags [Integer] An 8-bit field that controls tracing flags such as sampling, trace level, etc.
+		# @parameter state [Hash] Additional vendor-specific trace identification information.
+		# @parameter remote [Boolean] Whether this context was created from a distributed trace header.
 		def initialize(trace_id, parent_id, flags, state = nil, remote: false)
 			@trace_id = trace_id
 			@parent_id = parent_id
@@ -63,13 +69,13 @@ module Traces
 		# 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
 		
-		# 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.
+		# The ID of this operation 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 operation). 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.
+		# Provides additional vendor-specific trace identification information across different distributed tracing systems. Conveys information about the operation'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.
@@ -87,6 +93,7 @@ module Traces
 			"00-#{@trace_id}-#{@parent_id}-#{@flags.to_s(16)}"
 		end
 		
+		# Convert the trace context to a JSON representation, including trace state.
 		def as_json
 			{
 				trace_id: @trace_id,
@@ -97,6 +104,7 @@ module Traces
 			}
 		end
 		
+		# Convert the trace context to a JSON string.
 		def to_json(...)
 			as_json.to_json(...)
 		end

data/lib/traces/provider.rb

@@ -11,6 +11,7 @@ module Traces
 		Backend.const_defined?(:Interface)
 	end
 	
+	# @namespace
 	module Provider
 	end
 	
@@ -35,6 +36,8 @@ module Traces
 			
 			return provider
 		end
+		
+		Config::DEFAULT.prepare
 	else
 		def self.Provider(klass, &block)
 			# Tracing disabled.

data/lib/traces/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2021-2023, by Samuel Williams.
 
 module Traces
-	VERSION = "0.13.1"
+	VERSION = "0.14.1"
 end

data/lib/traces.rb

@@ -5,3 +5,7 @@
 
 require_relative 'traces/version'
 require_relative 'traces/provider'
+
+# @namespace
+module Traces
+end

data/readme.md

@@ -11,7 +11,21 @@ Capture nested traces during code execution in a vendor agnostic way.
 
 ## Usage
 
-Please see the [project documentation](https://socketry.github.io/traces).
+Please see the [project documentation](https://socketry.github.io/traces/) for more details.
+
+  - [Getting Started](https://socketry.github.io/traces/guides/getting-started/index) - This guide explains how to use `traces` for tracing code execution.
+
+  - [Testing](https://socketry.github.io/traces/guides/testing/index) - This guide explains how to test traces in your code.
+
+  - [Capture](https://socketry.github.io/traces/guides/capture/index) - This guide explains how to use `traces` for exporting traces from your application. This can be used to document all possible traces.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/traces/releases/index) for all releases.
+
+### v0.14.0
+
+  - [Introduce `Traces::Config` to Expose `prepare` Hook](https://socketry.github.io/traces/releases/index#introduce-traces::config-to-expose-prepare-hook)
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,18 @@
+# Releases
+
+## v0.14.0
+
+### Introduce `Traces::Config` to Expose `prepare` Hook
+
+The `traces` gem uses aspect-oriented programming to wrap existing methods to emit traces. However, while there are some reasonable defaults for emitting traces, it can be useful to customize the behavior and level of detail. To that end, the `traces` gem now optionally loads a `config/traces.rb` which includes a `prepare` hook that can be used to load additional providers.
+
+``` ruby
+# config/traces.rb
+
+def prepare
+	require 'traces/provider/async'
+	require 'traces/provider/async/http'
+end
+```
+
+The `prepare` method is called immediately after the traces backend is loaded. You can require any provider you want in this file, or even add your own custom providers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: traces
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,7 +38,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-11-05 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -51,11 +51,13 @@ files:
 - lib/traces/backend/capture.rb
 - lib/traces/backend/console.rb
 - lib/traces/backend/test.rb
+- lib/traces/config.rb
 - lib/traces/context.rb
 - lib/traces/provider.rb
 - lib/traces/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/traces
 licenses:
 - MIT

metadata.gz.sig

@@ -1,2 +1,3 @@
-��cu]�	�~�W���'`�j�c�˘Iy*�?����L<Ƽ���iw����r!����ZZ�x�������P�ٰ�
�/BF�"���\�5���\�5�
-2T���{r�;�vd�_-Ȭ�E
+���eUEmjѥW��>Z�9�.
+��'�BO���"�
+gv��_h"��/vf�