Add Traces.current_context and Traces.with_context.

Author: ioquatix

guides/context-propagation/readme.md

@@ -0,0 +1,212 @@
+# Context Propagation
+
+This guide explains how to propagate trace context between different execution contexts within your application using `Traces.current_context` and `Traces.with_context`.
+
+## Overview
+
+The `traces` library provides two complementary approaches for managing trace context:
+
+- **Local context propagation** (`Traces.current_context` / `Traces.with_context`): For passing context between execution contexts within the same process (threads, fibers, async tasks).
+- **Distributed context propagation** (`Traces.inject` / `Traces.extract`): For transmitting context across process and service boundaries via serialization (HTTP headers, message metadata, etc.).
+
+There is a legacy interface `Traces.trace_context` and `Traces.trace_context=` but you should prefer to use the new methods outlined above.
+
+## Local Context Propagation
+
+Local context propagation involves passing trace context between different execution contexts within the same process. This is essential for maintaining trace continuity when code execution moves between threads, fibers, async tasks, or other concurrent execution contexts. Unlike distributed propagation which requires serialization over network boundaries, local propagation uses Context objects directly.
+
+### Capturing the Current Context
+
+Use `Traces.current_context` to capture the current trace context as a Context object:
+
+~~~ ruby
+current_context = Traces.current_context
+# Returns a Traces::Context object or nil if no active trace
+~~~
+
+### Using the Context
+
+Use `Traces.with_context(context)` to execute code within a specific trace context:
+
+~~~ ruby
+# With block (automatic restoration):
+Traces.with_context(context) do
+	# Code runs with the specified context.
+end
+
+# Without block (permanent switch):
+Traces.with_context(context)
+# Context remains active.
+~~~
+
+### Use Cases
+
+#### Thread-Safe Context Propagation
+
+When spawning background threads, you often want them to inherit the current trace context:
+
+~~~ ruby
+require 'traces'
+
+# Main thread has active tracing
+Traces.trace("main_operation") do
+	# Capture current context before spawning thread:
+	current_context = Traces.current_context
+	
+	# Spawn background thread:
+	Thread.new do
+		# Restore context in the new thread:
+		Traces.with_context(current_context) do
+			# This thread now has the same trace context as main thread:
+			Traces.trace("background_work") do
+				perform_heavy_computation
+			end
+		end
+	end.join
+end
+~~~
+
+#### Fiber-Based Async Operations
+
+For fiber-based concurrency (like in async frameworks), context propagation ensures trace continuity:
+
+~~~ ruby
+require 'traces'
+
+Traces.trace("main_operation") do
+	current_context = Traces.current_context
+	
+	# Create fiber for async work:
+	fiber = Fiber.new do
+		Traces.with_context(current_context) do
+			# Fiber inherits the trace context:
+			Traces.trace("fiber_work") do
+				perform_async_operation
+			end
+		end
+	end
+	
+	fiber.resume
+end
+~~~
+
+### Context Propagation vs. New Spans
+
+Remember that context propagation maintains the same trace, while `trace()` creates new spans:
+
+~~~ ruby
+Traces.trace("parent") do
+	context = Traces.current_context
+	
+	Thread.new do
+		# This maintains the same trace context:
+		Traces.with_context(context) do
+			# This creates a NEW span within the same trace:
+			Traces.trace("child") do
+				# Child span, same trace as parent
+			end
+		end
+	end
+end
+~~~
+
+## Distributed Context Propagation
+
+Distributed context propagation involves transmitting trace context across process and service boundaries. Unlike local propagation which works within a single process, distributed propagation requires serializing context data and transmitting it over network protocols.
+
+### Injecting Context into Headers
+
+Use `Traces.inject(headers, context = nil)` to add W3C Trace Context headers to a headers hash for transmission over network boundaries:
+
+~~~ ruby
+require 'traces'
+
+# Capture current context:
+context = Traces.current_context
+headers = {'Content-Type' => 'application/json'}
+
+# Inject trace headers:
+Traces.inject(headers, context)
+# headers now contains: {'Content-Type' => '...', 'traceparent' => '00-...'}
+
+# Or use current context by default:
+Traces.inject(headers)  # Uses current trace context
+~~~
+
+### Extracting Context from Headers
+
+Use `Traces.extract(headers)` to extract trace context from W3C headers received over the network:
+
+~~~ ruby
+# Receive headers from incoming request:
+incoming_headers = request.headers
+
+# Extract context:
+context = Traces.extract(incoming_headers)
+# Returns a Traces::Context object or nil if no valid context
+
+# Use the extracted context:
+if context
+  Traces.with_context(context) do
+    # Process request with distributed trace context
+  end
+end
+~~~
+
+### Use Cases
+
+#### Outgoing HTTP Requests
+
+~~~ ruby
+require 'traces'
+
+class ApiClient
+	def make_request(endpoint, data)
+		Traces.trace("api_request", attributes: {endpoint: endpoint}) do
+			headers = {
+				'Content-Type' => 'application/json'
+			}
+			
+			# Add trace context to outgoing request:
+			Traces.inject(headers)
+			
+			http_client.post(endpoint, 
+				body: data.to_json,
+				headers: headers
+			)
+		end
+	end
+end
+~~~
+
+#### Incoming HTTP Requests
+
+~~~ ruby
+require 'traces'
+
+class WebController
+	def handle_request(request)
+		# Extract trace context from incoming headers:
+		context = Traces.extract(request.headers)
+		
+		# Process request with inherited context:
+		if context
+			Traces.with_context(context) do
+				Traces.trace("web_request", attributes: {
+					path: request.path,
+					method: request.method
+				}) do
+					process_business_logic
+				end
+			end
+		else
+			Traces.trace("web_request", attributes: {
+				path: request.path,
+				method: request.method
+			}) do
+				process_business_logic
+			end
+		end
+	end
+end
+~~~

guides/links.yaml

@@ -1,6 +1,8 @@
 getting-started:
   order: 1
-testing:
+context-propagation:
   order: 2
-capture:
+testing:
   order: 3
+capture:
+  order: 4

lib/traces.rb

@@ -5,6 +5,7 @@
 
 require_relative "traces/version"
 require_relative "traces/provider"
+require_relative "traces/context"
 
 # @namespace
 module Traces

lib/traces/backend.rb

@@ -4,23 +4,101 @@
 # Copyright, 2021-2025, by Samuel Williams.
 
 require_relative "config"
+require_relative "context"
 
 module Traces
 	# The backend implementation is responsible for recording and reporting traces.
 	module Backend
 	end
 
+	# Capture the current trace context for remote propagation.
+	#
 	# This is a default implementation, which can be replaced by the backend.
+	#
+	# You should prefer to use the new `Traces.current_context` family of methods.
+	#
 	# @returns [Object] The current trace context.
 	def self.trace_context
 		nil
 	end
 
+	# Whether there is an active trace context.
+	#
 	# This is a default implementation, which can be replaced by the backend.
+	#
 	# @returns [Boolean] Whether there is an active trace.
 	def self.active?
 		!!self.trace_context
 	end
 
+	# Capture the current trace context for local propagation between execution contexts.
+	#
+	# This method returns the current trace context that can be safely passed between threads, fibers, or other execution contexts within the same process.
+	#
+	# The returned object is opaque, in other words, you should not make assumptions about its structure.
+	#
+	# This is a default implementation, which can be replaced by the backend.
+	#
+	# @returns [Context | Nil] The current trace context, or nil if no active trace.
+	def self.current_context
+		trace_context
+	end
+	
+	# Execute a block within a specific trace context for local execution.
+	#
+	# This method is designed for propagating trace context between execution contexts within the same process (threads, fibers, etc.). It temporarily switches to the specified trace context for the duration of the block execution, then restores the previous context.
+	#
+	# When called without a block, permanently switches to the specified context. This enables manual context management for scenarios where automatic restoration isn't desired.
+	#
+	# This is a default implementation, which can be replaced by the backend.
+	#
+	# @parameter context [Context] A trace context obtained from `Traces.current_context`.
+	# @yields {...} If a block is given, the block is executed within the specified trace context.
+	def self.with_context(context)
+		if block_given?
+			# This implementation is not ideal but the best we can do with the current interface.
+			previous_context = self.trace_context
+			begin
+				self.trace_context = context
+				yield
+			ensure
+				self.trace_context = previous_context
+			end
+		else
+			self.trace_context = context
+		end
+	end
+	
+	# Inject trace context into a headers hash for distributed propagation.
+	#
+	# This method adds W3C Trace Context headers (traceparent, tracestate) and W3C Baggage headers to the provided headers hash, enabling distributed tracing across service boundaries. The headers hash is mutated in place.
+	#
+	# This is a default implementation, which can be replaced by the backend.
+	#
+	# @parameter headers [Hash] The headers object to mutate with trace context headers.
+	# @parameter context [Context] A trace context, or nil to use current context.
+	def self.inject(headers = nil, context = nil)
+		context ||= self.trace_context
+		
+		if context
+			headers ||= Hash.new
+			context.inject(headers)
+		end
+		
+		return headers
+	end
+	
+	# Extract trace context from headers for distributed propagation.
+	#
+	# The returned object is opaque, in other words, you should not make assumptions about its structure.
+	#
+	# This is a default implementation, which can be replaced by the backend.
+	#
+	# @parameter headers [Hash] The headers object containing trace context.
+	# @returns [Context, nil] The extracted trace context, or nil if no valid context found.
+	def self.extract(headers)
+		Context.extract(headers)
+	end
+	
 	Config::DEFAULT.require_backend
 end