traces 0.18.1 → 0.18.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 896d95a7ee5f38f7dd2d28f5a668b956282e7bf02f04121fece6ef134b722a39
-  data.tar.gz: fa0b7b51a14a0dc1080493eb36bb652ae38e51708a41f9adbd2131f439b01615
+  metadata.gz: 53f12f0b9d29fc4be9a9e701a4946bdf3ad74c226e3ba6059fccab724625c02d
+  data.tar.gz: 02b432f57ec9f3b2ddd2c0b793d490db2e5c4be827baeb63bee26c6e1d0a19ed
 SHA512:
-  metadata.gz: f7fce50fe5389b5f4532aeb6da21146f40128cbdc9cdaa56a584f5af30613561072ed67ec0602dedee6e588ea4cbf1b1c36e0cf9b378d1a7d98271eb0f268a9c
-  data.tar.gz: fe01635de9ddc18cf081a6744141c8d2fe264172b39ed7a61703d07f6daf7d23312c2be964374751cb4e425ef3aa6aaba485f9777e008ab6857c20cad3ee6759
+  metadata.gz: 36710faff7e4ba0a5f22318d5e74304d92ccd8f82761f89fc7c75608bbbba81e7a221996195c1eda59f37c569a3f0ed0fb6c54fd0bdd9088c01508fce0a4ab8f
+  data.tar.gz: ee106e0da529d689f268c4a92f8bc7dacfb2103fb13f15d55577c826c6ae07b495c85fd47ea67812179437074f82f0bac4affc1f836aa75e402c053295e6c550

data/context/capture.md

@@ -0,0 +1,39 @@
+# Capture
+
+This guide explains how to use `traces` for exporting traces from your application. This can be used to document all possible traces.
+
+## With Test Suite
+
+If your application defines one or more traces and emits them as part of a test suite, you can export them using the `bake traces:capture` command.
+
+```bash
+$ cd test/traces/backend/.capture/
+$ bake traces:capture run traces:capture:list output --format json
+[
+  {
+    "name": "my_trace",
+    "attributes": {
+      "foo": "baz"
+    },
+    "context": {
+      "trace_id": "038d110379a499a8ebcfb2b77cd69e1a",
+      "parent_id": "bf134b25de4f4a82",
+      "flags": 0,
+      "state": null,
+      "remote": false
+    }
+  },
+  {
+    "name": "nested",
+    "attributes": {
+    },
+    "context": {
+      "trace_id": "038d110379a499a8ebcfb2b77cd69e1a",
+      "parent_id": "2dd5510eb8fffc5f",
+      "flags": 0,
+      "state": null,
+      "remote": false
+    }
+  }
+]
+```

data/context/context-propagation.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
+~~~

data/context/getting-started.md

@@ -0,0 +1,126 @@
+# Getting Started
+
+This guide explains how to use `traces` for tracing code execution.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add traces
+~~~
+
+## Core Concepts
+
+`traces` has several core concepts:
+
+- A {ruby Traces::Provider} which implements custom logic for wrapping existing code in traces.
+- A {ruby Traces::Context} which represents the current tracing environment which can include distributed tracing.
+- A {ruby Traces::Backend} which connects traces to a specific backend system for processing.
+
+## Usage
+
+There are two main aspects to integrating within this gem.
+
+1. Libraries and applications must provide traces.
+2. Those traces must be consumed or emitted somewhere.
+
+### Providing Traces
+
+Adding tracing to libraries requires the use of {ruby Traces::Provider}:
+
+~~~ ruby
+require 'traces'
+
+class MyClass
+	def my_method
+		puts "Hello World"
+	end
+end
+
+# If tracing is disabled, this is a no-op.
+Traces::Provider(MyClass) do
+	def my_method
+		attributes = {
+			'foo' => 'bar'
+		}
+		
+		Traces.trace('my_method', attributes: attributes) do
+			super
+		end
+	end
+end
+
+MyClass.new.my_method
+~~~
+
+This code by itself will not create any traces. In order to execute it and output traces, you must set up a backend to consume them.
+
+In addition, to trace class methods:
+
+~~~ ruby
+require 'traces'
+
+class MyClass
+	def self.my_method
+		puts "Hello World"
+	end
+end
+
+# If tracing is disabled, this is a no-op.
+Traces::Provider(MyClass.singleton_class) do
+	def my_method
+		attributes = {
+			'foo' => 'bar'
+		}
+		
+		Traces.trace('my_method', attributes: attributes) do
+			super
+		end
+	end
+end
+
+MyClass.my_method
+~~~
+
+### Consuming Traces
+
+Consuming traces means proving a backend implementation which can emit those traces to some log or service. There are several options, but two backends are included by default:
+
+- `traces/backend/test` does not emit any traces, but validates the usage of the tracing interface.
+- `traces/backend/console` emits traces using the [`console`](https://github.com/socketry/console) gem.
+
+In order to use a specific backend, set the `TRACES_BACKEND` environment variable, e.g.
+
+~~~ shell
+$ TRACES_BACKEND=traces/backend/console ./my_script.rb
+~~~
+
+Separate implementations are provided for specific APMs:
+
+- [OpenTelemetry](https://github.com/socketry/traces-backend-open_telemetry)
+- [Datadog](https://github.com/socketry/traces-backend-datadog)
+- [New Relic](https://github.com/newrelic/traces-backend-newrelic)
+
+### Configuration
+
+By default, you may not have many traces available, as they are typically opt-in. To enable more traces, create a `config/traces.rb` file in your project root and require the providers you want to use:
+
+```ruby
+# config/traces.rb
+def prepare
+	require "traces/provider/async"
+	require "traces/provider/async/pool"
+end
+```
+
+To get a list of all available providers, you can use the `bake` command:
+
+~~~ shell
+$ bundle exec bake traces:provider:list
+{"async" => ["traces/provider/async/barrier.rb", "traces/provider/async/task.rb", "traces/provider/async.rb"],
+ "async-pool" => ["traces/provider/async/pool/controller.rb"],
+ "protocol-http2" => ["traces/provider/protocol/http2/framer.rb", "traces/provider/protocol/http2.rb"]}
+~~~
+
+You can then add the providers you want to use to your `config/traces.rb` file.

data/context/index.yaml

@@ -0,0 +1,23 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Application instrumentation and tracing.
+metadata:
+  documentation_uri: https://socketry.github.io/traces/
+  source_code_uri: https://github.com/socketry/traces.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `traces` for tracing code execution.
+- path: context-propagation.md
+  title: Context Propagation
+  description: This guide explains how to propagate trace context between different
+    execution contexts within your application using `Traces.current_context` and
+    `Traces.with_context`.
+- path: testing.md
+  title: Testing
+  description: This guide explains how to test traces in your code.
+- path: capture.md
+  title: Capture
+  description: This guide explains how to use `traces` for exporting traces from your
+    application. This can be used to document all possible traces.

data/context/testing.md

@@ -0,0 +1,32 @@
+# Testing
+
+This guide explains how to test traces in your code.
+
+## Expectations
+
+One approach to testing traces are emitted, is by using mocks to verify that methods are called with the expected arguments.
+
+```ruby
+it "should trace the operation" do
+	expect(Traces).to receive(:trace).with("my_controller.do_something")
+	
+	my_controller.do_something
+end
+```
+
+This is generally a good appoach for testing that specific traces are emitted.
+
+## Validation
+
+The traces gem supports a variety of backends, and each backend may have different requirements for the data that is submitted. The test backend is designed to be used for testing that the data submitted is valid.
+
+```ruby
+ENV['TRACES_BACKEND'] = 'traces/backend/test'
+
+require 'traces'
+
+Traces.trace(5) do
+	puts "Hello"
+end
+# => lib/traces/backend/test.rb:52:in `trace': Invalid name (must be String): 5! (ArgumentError)
+```

data/lib/traces/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2021-2025, by Samuel Williams.
 
 module Traces
-	VERSION = "0.18.1"
+	VERSION = "0.18.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: traces
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.18.2
 platform: ruby
 authors:
 - Samuel Williams
@@ -46,6 +46,11 @@ extra_rdoc_files: []
 files:
 - bake/traces/capture.rb
 - bake/traces/provider.rb
+- context/capture.md
+- context/context-propagation.md
+- context/getting-started.md
+- context/index.yaml
+- context/testing.md
 - lib/traces.rb
 - lib/traces/backend.rb
 - lib/traces/backend/capture.rb