traces-backend-open_telemetry 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a6e7b852d0e639afb7711bb341ff286b03c6551f93c7bad739d925e970bdf0b
-  data.tar.gz: 66e01999506279ab1934878f9728c54d71f0fa1bb2b79b9ae14043c6eaac85f7
+  metadata.gz: b87e401f00f7dadeb4c3030d9abfd80be9a7343f7a61b8088886ff6ece86b9a2
+  data.tar.gz: 0ef5ed27b0a48492f672b7f4fc3b867387bffef46cf665fccf624252da8fbb04
 SHA512:
-  metadata.gz: d6ff7a3fd2e174c1ed038dae1c1bbb7cc76cfd9e1c61d46b3a3ec9f4d6c3b43266b6249e95fecd27b71c46799ddaa84e880f0f862f74f0d0a0a794f5310cedc3
-  data.tar.gz: ea506e7dc7d917947c0fbfdeb9e287a5b8abaa6d1b8b69668dbbb21234604214aed7ad6772311fdde90e9e9a25fa68612c879002b0f86a51893fb1c59c549da0
+  metadata.gz: '0023923b237b02779db6c6bb35a9013b9751e04a9e3ea8098eb08de28db4b5797068abc2ec4ff2ea83dba2b5cf2fda6938710d99c07c39ed91eaac56f6f2e42d'
+  data.tar.gz: 5846bf33abdb432cd5c3d26334eb81891e98a43430fe005b41b01ee38b7ec9373e903b41fd945c0c8e3f35dba1550c32e32233ab1c3b951269a9cda29266f9ac

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

@@ -15,26 +15,49 @@ 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)
-					span_context = ::OpenTelemetry::Trace::SpanContext.new(
-						trace_id: context.trace_id,
-						span_id: context.parent_id,
-						trace_flags: ::OpenTelemetry::Trace::TraceFlags.from_byte(context.flags),
-						tracestate: context.state,
-						remote: context.remote?
-					)
-					
-					span = ::OpenTelemetry::Trace.non_recording_span(span_context)
-					context = ::OpenTelemetry::Trace.context_with_span(span)
-					::OpenTelemetry::Context.attach(context)
+					if context
+						span_context = ::OpenTelemetry::Trace::SpanContext.new(
+							trace_id: context.trace_id,
+							span_id: context.parent_id,
+							trace_flags: ::OpenTelemetry::Trace::TraceFlags.from_byte(context.flags),
+							tracestate: context.state,
+							remote: context.remote?
+						)
+						
+						span = ::OpenTelemetry::Trace.non_recording_span(span_context)
+						context = ::OpenTelemetry::Trace.context_with_span(span)
+						::OpenTelemetry::Context.attach(context)
+					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
 						
@@ -51,6 +74,53 @@ 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
+							yield
+						end
+					else
+						::OpenTelemetry::Context.attach(context)
+					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
+					
+					count = headers.count
+					
+					::OpenTelemetry.propagation.inject(headers, context: context)
+					
+					if count == headers.count
+						# No injection was performed, so return nil:
+						headers = nil
+					end
+					
+					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
 			end
 		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.2.0"
+			VERSION = "0.4.0"
 		end
 	end
 end

data/readme.md

@@ -12,9 +12,30 @@ $ bundle add traces-backend-open_telemetry
 
 ## Usage
 
-``` shell
-$ TRACES_BACKEND=traces/backend/open_telemetry ./my_script.rb
-```
+Please see the [project documentation](https://github.com/socketry/traces-backend-open_telemetry) for more details.
+
+  - [Getting Started](https://github.com/socketry/traces-backend-open_telemetryguides/getting-started/index) - This guide explains how to get started with `traces-backend-open_telemetry` to send application traces to OpenTelemetry.
+
+## Releases
+
+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)
+
+### v0.2.0
+
+  - Prefer to use `Tracer#in_span`.
+
+### v0.1.0
+
+  - Complete implementation of traces backend for OpenTelemetry.
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,25 @@
+# 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
+
+This release adds comprehensive support for OpenTelemetry's context propagation system, enabling efficient inter-process and intra-process tracing with full W3C compliance.
+
+  - `Traces.current_context` - Capture the current trace context for local propagation between execution contexts (threads, fibers).
+  - `Traces.with_context(context)` - Execute code within a specific trace context, with automatic restoration when used with blocks.
+  - `Traces.inject(headers = nil, context = nil)` - Inject W3C Trace Context and Baggage headers into a headers hash for distributed propagation.
+  - `Traces.extract(headers)` - Extract trace context from W3C Trace Context headers.
+
+## v0.2.0
+
+  - Prefer to use `Tracer#in_span`.
+
+## v0.1.0
+
+  - Complete implementation of traces backend for OpenTelemetry.

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: traces-backend-open_telemetry
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -37,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-01-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -67,8 +66,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.10'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -78,12 +75,12 @@ files:
 - lib/traces/backend/open_telemetry/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/traces-backend-open_telemetry
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/socketry/traces-backend-open_telemetry.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -91,15 +88,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A traces backend for Open Telemetry.
 test_files: []