traces-backend-open_telemetry 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e827995b4fdb7c14068483b4a7796eb958378f4ad093c59f7d86be165d8b91f2
-  data.tar.gz: 1fa19c544b849a9a761ae757ec9198767432517106187d801d6f0e0f836522a1
+  metadata.gz: b87e401f00f7dadeb4c3030d9abfd80be9a7343f7a61b8088886ff6ece86b9a2
+  data.tar.gz: 0ef5ed27b0a48492f672b7f4fc3b867387bffef46cf665fccf624252da8fbb04
 SHA512:
-  metadata.gz: 3d08dd5e72d329c9f114e7f10bad100144ca856f52d2e966cc52161a6cbf59c3c4bfa4ed4b5653e33c6c036f96ca6b4b71fa534ef944d5b68176a08623a0444c
-  data.tar.gz: d7115c5989a4ecb957a285382744b61e565cf9951668998cc0edd4596bd35507cde8f913b5fd34c95a2f2788d9891182d3f7e8e02462a3f68e0eeff33eff7091
+  metadata.gz: '0023923b237b02779db6c6bb35a9013b9751e04a9e3ea8098eb08de28db4b5797068abc2ec4ff2ea83dba2b5cf2fda6938710d99c07c39ed91eaac56f6f2e42d'
+  data.tar.gz: 5846bf33abdb432cd5c3d26334eb81891e98a43430fe005b41b01ee38b7ec9373e903b41fd945c0c8e3f35dba1550c32e32233ab1c3b951269a9cda29266f9ac

data/lib/traces/backend/open_telemetry/interface.rb

@@ -15,11 +15,19 @@ module Traces
 			# See <https://github.com/open-telemetry/opentelemetry-ruby> for more details.
 			TRACER = ::OpenTelemetry.tracer_provider.tracer(Traces::Backend::OpenTelemetry.name, Traces::Backend::OpenTelemetry::VERSION)
 			
+			# Provides the interface implementation for OpenTelemetry tracing backend.
 			module Interface
+				# Creates a trace span with the given name and attributes.
+				# @parameter name [String] The name of the trace span.
+				# @parameter attributes [Hash | Nil] Optional attributes to attach to the span.
+				# @yields {|span| ...} The block to execute within the trace span.
+				# @returns [Object] The result of the block execution.
 				def trace(name, attributes: nil, &block)
 					TRACER.in_span(name, attributes: attributes&.transform_keys(&:to_s), &block)
 				end
 				
+				# Sets the current trace context.
+				# @parameter context [Traces::Context | Nil] The trace context to set as current.
 				def trace_context=(context)
 					if context
 						span_context = ::OpenTelemetry::Trace::SpanContext.new(
@@ -36,7 +44,20 @@ module Traces
 					end
 				end
 				
+				# Checks if there is currently an active trace span.
+				# @returns [Boolean] `true` if there is an active trace span, `false` otherwise.
+				def active?
+					# Check if there's a real active trace using OpenTelemetry's INVALID span:
+					::OpenTelemetry::Trace.current_span != ::OpenTelemetry::Trace::Span::INVALID
+				end
+				
+				# Gets the current trace context from the active span.
+				# @parameter span [OpenTelemetry::Trace::Span] The span to extract context from, defaults to current span.
+				# @returns [Traces::Context | Nil] The trace context, or `nil` if no active trace.
 				def trace_context(span = ::OpenTelemetry::Trace.current_span)
+					# Return nil if no active trace (using INVALID span check):
+					return nil if span == ::OpenTelemetry::Trace::Span::INVALID
+					
 					if span_context = span.context
 						flags = 0
 						
@@ -54,10 +75,16 @@ module Traces
 					end
 				end
 				
+				# Gets the current OpenTelemetry context.
+				# @returns [OpenTelemetry::Context] The current OpenTelemetry context.
 				def current_context
 					::OpenTelemetry::Context.current
 				end
 				
+				# Executes code within the given context or attaches the context.
+				# @parameter context [OpenTelemetry::Context] The context to use.
+				# @yields {|| ...} Optional block to execute within the context.
+				# @returns [Object] The result of the block if given, otherwise the detach token.
 				def with_context(context)
 					if block_given?
 						::OpenTelemetry::Context.with_current(context) do
@@ -68,6 +95,10 @@ module Traces
 					end
 				end
 				
+				# Injects trace context into headers for propagation.
+				# @parameter headers [Hash | Nil] Optional headers hash to inject into, defaults to new hash.
+				# @parameter context [OpenTelemetry::Context | Nil] Optional context to inject, defaults to current context.
+				# @returns [Hash | Nil] The headers with injected trace context, or `nil` if no injection occurred.
 				def inject(headers = nil, context = nil)
 					context ||= ::OpenTelemetry::Context.current
 					headers ||= Hash.new
@@ -84,6 +115,9 @@ module Traces
 					return headers
 				end
 				
+				# Extracts trace context from headers.
+				# @parameter headers [Hash] The headers to extract trace context from.
+				# @returns [OpenTelemetry::Context] The extracted context.
 				def extract(headers)
 					::OpenTelemetry.propagation.extract(headers)
 				end

data/lib/traces/backend/open_telemetry/version.rb

@@ -3,10 +3,13 @@
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
 
+# @namespace
 module Traces
+	# @namespace
 	module Backend
+		# @namespace
 		module OpenTelemetry
-			VERSION = "0.3.0"
+			VERSION = "0.4.0"
 		end
 	end
 end

data/readme.md

@@ -20,6 +20,11 @@ Please see the [project documentation](https://github.com/socketry/traces-backen
 
 Please see the [project releases](https://github.com/socketry/traces-backend-open_telemetryreleases/index) for all releases.
 
+### v0.4.0
+
+  - Fixed `Traces.active?` to correctly return `false` when there is no active trace, instead of always returning `true`.
+  - Fixed `Traces.trace_context` to return `nil` when there is no active trace, instead of returning invalid Context objects.
+
 ### v0.3.0
 
   - [New Context Propagation Interface](https://github.com/socketry/traces-backend-open_telemetryreleases/index#new-context-propagation-interface)

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.4.0
+
+  - Fixed `Traces.active?` to correctly return `false` when there is no active trace, instead of always returning `true`.
+  - Fixed `Traces.trace_context` to return `nil` when there is no active trace, instead of returning invalid Context objects.
+
 ## v0.3.0
 
 ### New Context Propagation Interface

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: traces-backend-open_telemetry
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams