traces 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e413f837413b357d84594db5b48e6be8d5033db0896c042a0806ec1f6b6e493
-  data.tar.gz: fa2aed0ec28362aaf84983d13da4ae1e55738728b7f86045cf919b93599c23bc
+  metadata.gz: 618c28f794dbd7fa30d3d211b50bb81a4bf785d8877f4512379d1f9bfc588032
+  data.tar.gz: 0e7dcc6c4e0f88a1721a06cf4225093d9375a15cfc2bf09ec3aa67e16448453b
 SHA512:
-  metadata.gz: 85f20fe132bf1a07bb0d9633ce2793776ab1e7fe56cc3320b0db3b400b9f6723faf9a4a6c7b781e0dc4d5b210af8bcd24cfa4846ef02ce285edb93b2ed25bf94
-  data.tar.gz: 360152f3404776023b846b42dbced2ed16e533add3072d57e21c6c49cb590f3b2fcffb66daf313c09984760b9f64e87e495b888c166cb43a9968a7e55076548c
+  metadata.gz: 8cf0fe5b427eca45083760ea6e5428f6b9a36ec00019ca55e4b505cd0edddd72c10c5d52fdca990a8e7676652cd72529f2f25a29298351625210702a9eb6111d
+  data.tar.gz: fe0a03d14440673a637843065cb48ff9a54be1c315e5c08b0117875e0b42642e268b6b087d2cb4d5f541abc6085aaf589fb23650eacffdd5f137abd90cf9c321

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,56 @@
+# 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)
+						
+						self.prepare
+						
+						return true
+					end
+				rescue LoadError => error
+					::Console::Event::Failure.for(error).emit(self, "Unable to load traces backend!", backend: backend, severity: :warn)
+				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
 	

data/lib/traces/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2021-2023, by Samuel Williams.
 
 module Traces
-	VERSION = "0.13.1"
+	VERSION = "0.14.0"
 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 control tracing behavior](https://socketry.github.io/traces/releases/index#introduce-traces::config-to-control-tracing-behavior)
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,18 @@
+# Releases
+
+## v0.14.0
+
+### Introduce `Traces::Config` to control tracing behavior
+
+There are some reasonable defaults for tracing, but sometimes you want to change them. Adding a `config/traces.rb` file to your project will allow you to do that.
+
+``` ruby
+# config/traces.rb
+
+def prepare
+	require 'traces/provider/async'
+	require 'traces/provider/async/http'
+end
+```
+
+The `prepare` method is called before the tracing is started but after the backend is required. 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.0
 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