opentrace 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4a10bb3e35d7526cb02f721c1040ad9f568fa6058d17d1e7aaf1bf31d42ecd6
-  data.tar.gz: 64f7700651c457151c9d9a961a8bba205cf88d0746265e6eebaa7f928e2c0f9b
+  metadata.gz: b531ffb7419d2f4eb8a6c4acafa2b6efcfa7d051cde050fd162ddaa62df18ab1
+  data.tar.gz: 171e500952906bcc8839ede080a280cb718b08a28bb92cef2f926f19bdbc2bc3
 SHA512:
-  metadata.gz: fcd303032ee0ae96aeb6602ffdd3a60df2972e58cfff1c6499f5cc17ea57c89a0ffe6e5e092a9eb7c0ccb55f798afcfbce13f34ac789e70908d890a42da5699f
-  data.tar.gz: 54f2c8bfd37f9a36b9f32aa49b76a6846335ab0063e804fb35aa491892d18d4a560c410e9204b667ebd5e57cfe522114d677f8973b788a897084a6ce12e62bb1
+  metadata.gz: c986dcdb9bb7d82236d2d77255f207e29df203204c49f8f6c89df3a20fc550cd0bc7f409b4738d5c0a872bac24abc160dc74f33a7c545ec0ff76f0fe2a0ac148
+  data.tar.gz: 7c2954dbaf1cced147e3937d7c5e610235a15469a231cf9dde619c6bb9d4f4c4ada3b28a1520a1ecc8704dc37933e8855221e8b2b156018fcea041450adfed66

data/README.md

@@ -3,7 +3,9 @@
 [![Gem Version](https://badge.fury.io/rb/opentrace.svg)](https://rubygems.org/gems/opentrace)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-A thin, safe Ruby client that forwards structured application logs to an [OpenTrace](https://github.com/adham90/opentrace-ruby) server over HTTP.
+A thin, safe Ruby client that forwards structured application logs to an [OpenTrace](https://github.com/adham90/opentrace) server over HTTP.
+
+> **OpenTrace Server** -- This gem requires a running [OpenTrace server](https://github.com/adham90/opentrace). OpenTrace is a self-hosted observability tool for logs, database monitoring, and intelligent alerting. See the [server repo](https://github.com/adham90/opentrace) for setup instructions.
 
 **This gem will never crash or slow down your application.** All network errors are swallowed silently. If the server is unreachable, logs are dropped -- your app continues running normally.
 
@@ -14,8 +16,11 @@ A thin, safe Ruby client that forwards structured application logs to an [OpenTr
 - **Batch sending** -- groups logs into configurable batches for efficient network usage
 - **Bounded queue** -- caps at 1,000 entries to prevent memory bloat
 - **Smart truncation** -- oversized payloads are truncated instead of silently dropped
+- **Works with any server** -- Puma (threads), Unicorn (forks), Passenger, and Falcon (fibers)
+- **Fork safe** -- detects forked worker processes and re-initializes cleanly
+- **Fiber safe** -- uses `Fiber[]` storage for correct request isolation in fiber-based servers
 - **Rails integration** -- auto-instruments controllers, SQL queries, and ActiveJob via Railtie
-- **Rack middleware** -- propagates `request_id` via thread-local storage
+- **Rack middleware** -- propagates `request_id` via fiber-local storage
 - **Logger wrapper** -- drop-in replacement that forwards to OpenTrace while keeping your original logger
 - **Rails 7.1+ BroadcastLogger** -- native support via `broadcast_to`
 - **TaggedLogging** -- preserves `ActiveSupport::TaggedLogging` tags in metadata
@@ -24,6 +29,7 @@ A thin, safe Ruby client that forwards structured application logs to an [OpenTr
 - **Auto-enrichment** -- every log includes `hostname`, `pid`, and `git_sha` automatically
 - **Exception helper** -- `OpenTrace.error` captures class, message, and cleaned backtrace
 - **Runtime controls** -- enable/disable logging at runtime without restarting
+- **Graceful shutdown** -- pending logs are flushed automatically on process exit
 
 ## Installation
 
@@ -179,7 +185,7 @@ end
 # Dynamic context (evaluated on each log call)
 OpenTrace.configure do |c|
   # ...
-  c.context = -> { { request_id: Thread.current[:request_id], tenant: Current.tenant&.slug } }
+  c.context = -> { { tenant: Current.tenant&.slug } }
 end
 ```
 
@@ -205,6 +211,8 @@ The gem auto-detects Rails and provides the following integrations automatically
 
 Automatically inserted into the middleware stack. Captures `request_id` from `action_dispatch.request_id` or `HTTP_X_REQUEST_ID` and makes it available via `OpenTrace.current_request_id`. All logs within a request automatically include the `request_id`.
 
+Request IDs are stored using `Fiber[]` (fiber-local storage), which works correctly in both threaded servers (Puma) and fiber-based servers (Falcon).
+
 ### Logger Wrapping
 
 - **Rails 7.1+**: Uses `BroadcastLogger#broadcast_to` to register as a broadcast target (non-invasive)
@@ -299,7 +307,9 @@ OpenTrace.enable!   # turn back on
 
 ## Graceful Shutdown
 
-If your app needs a clean shutdown (e.g. a Sidekiq worker), drain the queue before exiting:
+An `at_exit` hook is registered automatically to flush pending logs (up to 2 seconds) when the process exits. No configuration needed.
+
+For manual control (e.g. a Sidekiq worker), you can drain the queue explicitly:
 
 ```ruby
 OpenTrace.shutdown(timeout: 5)
@@ -307,6 +317,21 @@ OpenTrace.shutdown(timeout: 5)
 
 This gives the background thread up to 5 seconds to send any remaining queued logs.
 
+## Server Compatibility
+
+OpenTrace works with any Rack-compatible Ruby web server:
+
+| Server | Concurrency | Support |
+|---|---|---|
+| **Puma** | Threads | Full support |
+| **Unicorn** | Forked workers | Full support (fork-safe) |
+| **Passenger** | Forks + threads | Full support (fork-safe) |
+| **Falcon** | Fibers | Full support (fiber-safe) |
+
+**Fork safety**: When a process forks (Puma cluster mode, Unicorn, Passenger), the background dispatch thread from the parent is dead in the child. OpenTrace detects the fork via PID check and cleanly re-initializes the queue, mutex, and thread.
+
+**Fiber safety**: Request IDs use `Fiber[]` storage instead of `Thread.current`, so concurrent requests on the same thread (as in Falcon) are correctly isolated.
+
 ## How It Works
 
 ```
@@ -315,12 +340,14 @@ Your App --log()--> [In-Memory Queue] --background thread--> POST /api/logs -->
 
 - Logs are serialized to JSON and pushed onto an in-memory queue
 - A single background thread reads from the queue and sends batches via `POST /api/logs`
+- `enqueue` is non-blocking -- it uses `try_lock` so it never waits on a mutex
 - The thread is started lazily on the first log call -- no threads are created at boot
 - If the queue exceeds 1,000 items, new logs are dropped (oldest are preserved)
 - Payloads exceeding 32 KB are intelligently truncated (backtrace, params, SQL removed first)
 - If still too large after truncation, the payload is split and retried in smaller batches
 - All network errors (timeouts, connection refused, DNS failures) are swallowed silently
 - The HTTP timeout defaults to 1 second
+- Pending logs are flushed on process exit via an `at_exit` hook
 
 ## Log Payload Format
 
@@ -358,7 +385,7 @@ The server accepts a single JSON object or an array of objects.
 
 ## Requirements
 
-- Ruby >= 3.0
+- Ruby >= 3.2 (uses `Fiber[]` for fiber-local storage)
 - Rails >= 6 (optional, auto-detected)
 
 ## License

data/lib/opentrace/client.rb

@@ -105,7 +105,7 @@ module OpenTrace
         end
 
         break if batch.size >= @config.batch_size
-        break if Time.now >= deadline && !batch.empty?
+        break if Time.now >= deadline
         break if @queue.closed?
       end
 

data/lib/opentrace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenTrace
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentrace
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - OpenTrace
@@ -52,7 +52,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="