opentrace 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 415cb9523a3c54703221a0604c9a301eb47b9f71c99737fcc194ced1d28ea178
-  data.tar.gz: cb6d7f5a295c27bb68ff51a79b196297b18fe3ef568ac9e788c3d010828d2092
+  metadata.gz: fbe3de5afdb5f92afcef49d368b8f8b3714ca17fe453b168066f53a5b0e5e1ba
+  data.tar.gz: 8f749e943951c939e7daa8f93a454bb0c89646bc295c0550c680064ebf38db16
 SHA512:
-  metadata.gz: 5e1a1a6f4d72827d11d4d879c867afd98e96e8fead065232a1e64fd32c74c309c3db52fde64ab60f24b0a40884cac78177e5b368a998cf14b026c0ca85388277
-  data.tar.gz: 3d3c85e68ac60f2d25824a2ec687fec9f7e31f40ba25c6fb3ca3fa031c9f2abff677ffbde978a93de430538cb7adeea9e1f907ba4f8481ecf32270121dea5196
+  metadata.gz: e3ecb7c4b649951f64e1090bb7ea06da69cb603dcd44534c9a5e71d76eb697239fddf2267cd2a5e0cff2aa1bf86dc78be6733be754df8e5c6a435967d90809a8
+  data.tar.gz: 3625d9de1cd2dda011f69283b34a17964450cda3c44c0f19431fb450e2a24328f1c260a12ea9929331a54866ac90afd07addd65e16cb2eee9e42a939807f3a69

data/README.md

@@ -19,17 +19,28 @@ A thin, safe Ruby client that forwards structured application logs to an [OpenTr
 - **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
+- **Rails integration** -- auto-instruments controllers, SQL queries, ActiveJob, views, cache, and more
 - **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
 - **Context support** -- attach global metadata to every log via Hash or Proc
-- **Level filtering** -- `min_level` config to control which severities are forwarded
+- **Business events** -- `OpenTrace.event` sends typed events (e.g. `payment.completed`) that bypass level filtering
+- **Level filtering** -- `min_level` threshold or `allowed_levels` list to control which severities are forwarded
 - **Auto-enrichment** -- every log includes `hostname`, `pid`, and `git_sha` automatically
-- **Exception helper** -- `OpenTrace.error` captures class, message, and cleaned backtrace
+- **Exception helper** -- `OpenTrace.error` captures class, message, cleaned backtrace, and error fingerprint
 - **Runtime controls** -- enable/disable logging at runtime without restarting
 - **Graceful shutdown** -- pending logs are flushed automatically on process exit
+- **N+1 query detection** -- warns when a request exceeds 20 SQL queries
+- **Per-request summary** -- one rich log per request with SQL, view, cache breakdown and timeline
+- **Error fingerprinting** -- stable fingerprint for grouping identical errors across requests
+- **Deprecation tracking** -- captures Rails deprecation warnings with callsite
+- **DB pool monitoring** -- background thread reports connection pool saturation (opt-in)
+- **Job queue depth** -- monitors Sidekiq, GoodJob, or SolidQueue queue sizes (opt-in)
+- **Memory delta tracking** -- snapshots process RSS before/after each request (opt-in)
+- **External HTTP tracking** -- captures outbound Net::HTTP calls with timing (opt-in)
+- **Version negotiation** -- startup compatibility check with capability-based feature detection
+- **Distributed tracing** -- W3C Trace Context (`traceparent`) propagation across services with span IDs
 
 ## Installation
 
@@ -79,6 +90,7 @@ OpenTrace.configure do |c|
   c.timeout     = 1.0                    # HTTP timeout in seconds (default: 1.0)
   c.enabled     = true                   # default: true
   c.min_level   = :info                  # minimum level to forward (default: :debug)
+  c.allowed_levels = [:warn, :error]     # explicit level list (overrides min_level, default: nil)
   c.batch_size  = 50                     # logs per batch (default: 50)
   c.flush_interval = 5.0                 # seconds between flushes (default: 5.0)
 
@@ -95,6 +107,24 @@ OpenTrace.configure do |c|
   # SQL logging (Rails only)
   c.sql_logging = true                   # default: true
   c.sql_duration_threshold_ms = 100.0    # only log queries slower than this (default: 0.0 = all)
+
+  # Path filtering
+  c.ignore_paths = ["/health", %r{\A/assets/}]  # skip noisy paths (default: [])
+
+  # Per-request summary (Rails only)
+  c.request_summary = true               # accumulate events into one rich log (default: true)
+  c.timeline = true                      # include event timeline in summary (default: true)
+  c.timeline_max_events = 200            # cap timeline entries (default: 200)
+
+  # Background monitors (opt-in)
+  c.pool_monitoring = false              # DB connection pool stats (default: false)
+  c.pool_monitoring_interval = 30        # seconds between checks (default: 30)
+  c.queue_monitoring = false             # job queue depth monitoring (default: false)
+  c.queue_monitoring_interval = 60       # seconds between checks (default: 60)
+
+  # Advanced opt-in features
+  c.memory_tracking = false              # RSS delta per request (default: false)
+  c.http_tracking = false                # external HTTP call tracking (default: false)
 end
 ```
 
@@ -102,15 +132,21 @@ If any required field (`endpoint`, `api_key`, `service`) is missing or empty, th
 
 ### Level Filtering
 
-Control which log levels are forwarded with `min_level`:
+Control which log levels are forwarded with `min_level` (threshold) or `allowed_levels` (explicit list):
 
 ```ruby
 OpenTrace.configure do |c|
   # ...
+  # Option A: Threshold — forward this level and above
   c.min_level = :warn  # only forward WARN, ERROR, and FATAL
+
+  # Option B: Explicit list — forward only these levels (overrides min_level)
+  c.allowed_levels = [:warn, :error]  # only forward WARN and ERROR
 end
 ```
 
+When `allowed_levels` is set, it takes precedence over `min_level`. When `allowed_levels` is `nil` (the default), `min_level` is used.
+
 Available levels: `:debug`, `:info`, `:warn`, `:error`, `:fatal`
 
 ## Usage
@@ -134,7 +170,7 @@ Pass `trace_id` inside metadata and it will be promoted to a top-level field aut
 
 ### Exception Logging
 
-Use `OpenTrace.error` to log exceptions with automatic class, message, and backtrace extraction:
+Use `OpenTrace.error` to log exceptions with automatic class, message, backtrace, and fingerprint extraction:
 
 ```ruby
 begin
@@ -148,6 +184,19 @@ This captures:
 - `exception_class` -- the exception class name
 - `exception_message` -- truncated to 500 characters
 - `backtrace` -- cleaned (Rails backtrace cleaner or gem-filtered), limited to 15 frames
+- `error_fingerprint` -- 12-char hash for grouping identical errors (stable across line number changes)
+
+### Business Events
+
+Use `OpenTrace.event` to send typed business events. Events always send at `INFO` level and **bypass level filtering** — they are never suppressed by `min_level` or `allowed_levels`:
+
+```ruby
+OpenTrace.event("payment.completed", "User paid $49.99", { user_id: 42, amount: 49.99 })
+OpenTrace.event("auth.login", "Google OAuth login", { provider: "google", user_id: 7 })
+OpenTrace.event("order.shipped", "Order dispatched", { order_id: "ORD-123" })
+```
+
+Events include an `event_type` field in the payload, making them filterable on the server. They inherit context, `request_id`, and static context just like normal logs.
 
 ### Logger Wrapper
 
@@ -220,6 +269,63 @@ Request IDs are stored using `Fiber[]` (fiber-local storage), which works correc
 
 All your existing `Rails.logger.info(...)` calls automatically get forwarded to OpenTrace.
 
+### Per-Request Summary
+
+When `request_summary` is enabled (the default), the gem accumulates all events during a request -- SQL queries, view renders, cache operations, HTTP calls -- into a single rich log entry emitted at request end. This avoids flooding the queue with hundreds of individual events.
+
+Example payload:
+
+```json
+{
+  "level": "INFO",
+  "message": "GET /dashboard 200 2847ms",
+  "metadata": {
+    "request_id": "req-abc123",
+    "controller": "DashboardController",
+    "action": "index",
+    "method": "GET",
+    "path": "/dashboard",
+    "status": 200,
+    "duration_ms": 2847.3,
+
+    "request_user_agent": "Mozilla/5.0...",
+    "request_accept": "text/html",
+
+    "sql_query_count": 34,
+    "sql_total_ms": 423.1,
+    "sql_slowest_ms": 312.0,
+    "sql_slowest_name": "Order Count",
+    "n_plus_one_warning": true,
+
+    "view_render_count": 48,
+    "view_total_ms": 890.2,
+    "view_slowest_ms": 245.0,
+    "view_slowest_template": "dashboard/_activity_feed.html.erb",
+
+    "cache_reads": 8,
+    "cache_hits": 5,
+    "cache_writes": 3,
+    "cache_hit_ratio": 0.63,
+
+    "time_breakdown": {
+      "sql_pct": 14.9,
+      "view_pct": 31.3,
+      "http_pct": 0.0,
+      "other_pct": 53.8
+    },
+
+    "timeline": [
+      { "t": "sql", "n": "User Load", "ms": 1.2, "at": 0.0 },
+      { "t": "cache", "a": "read", "hit": true, "ms": 0.1, "at": 6.0 },
+      { "t": "sql", "n": "Order Count", "ms": 312.0, "at": 10.0 },
+      { "t": "view", "n": "dashboard/index.html.erb", "ms": 890.2, "at": 350.0 }
+    ]
+  }
+}
+```
+
+The timeline shows a waterfall of events in chronological order. Timeline keys are kept short to minimize payload size: `t` = type, `n` = name, `ms` = duration, `at` = offset from request start, `s` = status, `a` = action.
+
 ### Controller Subscriber
 
 Subscribes to `process_action.action_controller` and captures:
@@ -238,12 +344,26 @@ Subscribes to `process_action.action_controller` and captures:
 | `exception_class` | Exception class (if raised) |
 | `exception_message` | Exception message (if raised) |
 | `backtrace` | Cleaned backtrace (if exception raised) |
+| `error_fingerprint` | 12-char fingerprint for error grouping |
+| `request_content_type` | Request Content-Type header |
+| `request_accept` | Request Accept header |
+| `request_user_agent` | Request User-Agent (truncated to 200 chars) |
+| `request_referer` | Request Referer header |
+| `sql_query_count` | Total SQL queries in this request |
+| `sql_total_ms` | Total SQL time in this request |
+| `n_plus_one_warning` | `true` when query count exceeds 20 |
+
+When request summary is enabled, the log also includes view render stats, cache stats, time breakdown, and timeline (see above).
 
 Log levels are set automatically:
 - **ERROR** -- exceptions or 5xx status
 - **WARN** -- 4xx status
 - **INFO** -- everything else
 
+### N+1 Query Detection
+
+Every request tracks the number of SQL queries via a Fiber-local counter. When a request exceeds 20 queries, the log entry includes `n_plus_one_warning: true`. This makes it easy to query OpenTrace for requests with potential N+1 issues.
+
 ### SQL Query Subscriber
 
 Subscribes to `sql.active_record` and logs every query with:
@@ -280,12 +400,54 @@ Subscribes to `perform.active_job` and logs every job execution with:
 | `executions` | Attempt number |
 | `duration_ms` | Execution duration |
 | `job_arguments` | Serialized arguments (truncated to 512 bytes) |
+| `queue_latency_ms` | Time spent waiting in queue before execution |
+| `enqueued_at` | When the job was enqueued |
 | `exception_class` | Exception class (if failed) |
 | `exception_message` | Exception message (if failed) |
 | `backtrace` | Cleaned backtrace (if failed) |
+| `error_fingerprint` | Fingerprint for error grouping (if failed) |
 
 Failed jobs are logged as `ERROR`, successful jobs as `INFO`.
 
+### Deprecation Warning Subscriber
+
+Subscribes to `deprecation.rails` and logs all Rails deprecation warnings as `WARN`:
+
+| Field | Description |
+|---|---|
+| `deprecation_message` | The deprecation message (truncated to 500 chars) |
+| `deprecation_callsite` | File and line where the deprecated API was called |
+| `request_id` | Current request ID (if in web context) |
+
+### View Render Tracking
+
+When request summary is enabled, subscribes to `render_template.action_view` and `render_partial.action_view`. View render events are accumulated in the RequestCollector and included in the per-request summary -- **no individual log entries are emitted** for views.
+
+The summary includes:
+- `view_render_count` -- total number of templates/partials rendered
+- `view_total_ms` -- total rendering time
+- `view_slowest_ms` / `view_slowest_template` -- the bottleneck template
+
+Template paths are automatically shortened (e.g., `/Users/deploy/app/views/orders/show.html.erb` becomes `orders/show.html.erb`).
+
+### Cache Operation Tracking
+
+When request summary is enabled, subscribes to `cache_read.active_support`, `cache_write.active_support`, and `cache_delete.active_support`. Like views, cache events are accumulated -- no individual logs.
+
+The summary includes:
+- `cache_reads` / `cache_hits` / `cache_writes`
+- `cache_hit_ratio` -- hit rate (0.0 to 1.0)
+
+### Error Fingerprinting
+
+Every error (in controller requests, job failures, and `OpenTrace.error` calls) includes an `error_fingerprint` -- a 12-character hash derived from the exception class and the first application frame in the backtrace. The fingerprint is:
+
+- **Stable across deploys** -- line number changes don't affect it
+- **Same error, same fingerprint** -- different error messages at the same location produce the same fingerprint
+- **Different error, different fingerprint** -- different exception classes or different code locations produce different fingerprints
+
+Use it to group and count errors in OpenTrace.
+
 ### TaggedLogging
 
 If your wrapped logger uses `ActiveSupport::TaggedLogging`, tags are preserved and injected into the metadata:
@@ -297,6 +459,90 @@ Rails.logger.tagged("RequestID-123", "UserID-42") do
 end
 ```
 
+## Background Monitors
+
+### DB Connection Pool Monitoring
+
+Opt-in background thread that periodically reports ActiveRecord connection pool stats:
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.pool_monitoring = true
+  c.pool_monitoring_interval = 30  # seconds (default: 30)
+end
+```
+
+Reports `pool_size`, `connections_busy`, `connections_idle`, `threads_waiting`, and `checkout_timeout`. Logs at `WARN` when threads are waiting for a connection, `DEBUG` otherwise.
+
+### Job Queue Depth Monitoring
+
+Opt-in background thread that reports job queue sizes. Supports Sidekiq, GoodJob, and SolidQueue (auto-detected):
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.queue_monitoring = true
+  c.queue_monitoring_interval = 60  # seconds (default: 60)
+end
+```
+
+Reports per-queue sizes and total enqueued count. Logs at `WARN` when total exceeds 1,000.
+
+## Advanced Opt-In Features
+
+These features have measurable overhead or implementation risks. **Disabled by default.** Enable them after testing in staging.
+
+### Memory Delta Tracking
+
+Snapshots process memory (RSS) before and after each request:
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.memory_tracking = true
+end
+```
+
+Adds to the request summary:
+- `memory_before_mb` -- RSS before request
+- `memory_after_mb` -- RSS after request
+- `memory_delta_mb` -- difference (positive = memory grew)
+
+Uses `/proc/self/statm` on Linux (~10us) or `GC.stat` approximation on macOS (~5us). The delta is process-level, so concurrent requests will affect accuracy. Most accurate on single-threaded servers (Unicorn).
+
+### External HTTP Tracking
+
+Instruments outbound `Net::HTTP` calls to capture third-party API performance:
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.http_tracking = true
+end
+```
+
+Adds to the request summary:
+- `http_external_count` -- number of outbound HTTP calls
+- `http_external_total_ms` -- total time in external calls
+- `http_slowest_ms` / `http_slowest_host` -- the bottleneck
+
+Each HTTP call appears in the timeline:
+
+```json
+{ "t": "http", "n": "POST api.stripe.com", "ms": 184.0, "s": 200, "at": 55.0 }
+```
+
+Failed calls include an error type:
+
+```json
+{ "t": "http", "n": "POST api.stripe.com", "ms": 5200.0, "s": 0, "err": "Net::ReadTimeout", "at": 55.0 }
+```
+
+A recursion guard prevents OpenTrace's own HTTP calls to the server from being tracked. The `time_breakdown` in the request summary includes `http_pct` alongside `sql_pct` and `view_pct`.
+
+**Note**: This works by prepending a module to `Net::HTTP`. Libraries that use `Net::HTTP` internally (Faraday, HTTParty, RestClient) are automatically captured.
+
 ## Runtime Controls
 
 ```ruby
@@ -343,12 +589,214 @@ Your App --log()--> [In-Memory Queue] --background thread--> 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)
+- Payloads exceeding 256 KB (configurable via `max_payload_bytes`) 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
+- Failed requests are retried with exponential backoff (up to 3 attempts by default)
+- A circuit breaker stops sending when the server is unreachable, resuming after a cooldown
+- Rate-limited responses (429) trigger a backoff delay, respecting the server's `Retry-After` header
+- Authentication failures (401) suspend sending and print a one-time warning to STDERR
 - The HTTP timeout defaults to 1 second
 - Pending logs are flushed on process exit via an `at_exit` hook
 
+### Retry & Circuit Breaker
+
+Failed HTTP requests are retried with exponential backoff and jitter. Only server errors (5xx) and network failures are retried -- client errors (4xx) are not.
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.max_retries      = 2    # up to 3 total attempts (default: 2)
+  c.retry_base_delay = 0.1  # 100ms initial backoff (default: 0.1)
+  c.retry_max_delay  = 2.0  # cap backoff at 2 seconds (default: 2.0)
+end
+```
+
+A circuit breaker prevents wasting resources when the server is down. After a threshold of consecutive failures, the circuit **opens** and all sends are skipped. After a cooldown, a single **probe** request is sent. If it succeeds, the circuit closes and normal operation resumes.
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.circuit_breaker_threshold = 5   # failures before opening (default: 5)
+  c.circuit_breaker_timeout   = 30  # seconds before probe (default: 30)
+end
+```
+
+### Backpressure Handling
+
+The client responds intelligently to HTTP status codes:
+
+| Status | Behavior |
+|---|---|
+| **2xx** | Success -- circuit breaker resets |
+| **429** | Rate limited -- pauses for `Retry-After` seconds (or `rate_limit_backoff`), re-enqueues the batch |
+| **401** | Auth failed -- suspends sending, prints one-time STDERR warning. Resumes after `OpenTrace.configure` |
+| **5xx** | Server error -- retried with backoff, counts toward circuit breaker |
+| **Other 4xx** | Client error -- batch dropped silently |
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.rate_limit_backoff = 5.0  # fallback when Retry-After header is missing (default: 5.0)
+end
+```
+
+### Delivery Observability
+
+The client exposes internal delivery statistics so you can monitor the health of the log pipeline:
+
+```ruby
+OpenTrace.stats
+# => {
+#   enqueued: 15234,
+#   delivered: 15100,
+#   dropped_queue_full: 34,
+#   dropped_circuit_open: 100,
+#   dropped_auth_suspended: 0,
+#   dropped_error: 0,
+#   retries: 12,
+#   rate_limited: 2,
+#   auth_failures: 0,
+#   payload_splits: 1,
+#   batches_sent: 302,
+#   bytes_sent: 4812300,
+#   queue_size: 23,
+#   circuit_state: :closed,
+#   auth_suspended: false,
+#   uptime_seconds: 3600
+# }
+
+OpenTrace.healthy?      # true when circuit is closed and auth is not suspended
+OpenTrace.reset_stats!  # reset counters (useful after reading/reporting)
+```
+
+#### Drop Callback
+
+Register a callback to be notified when logs are dropped. The callback receives the count of dropped items and the reason:
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.on_drop = ->(count, reason) {
+    StatsD.increment("opentrace.dropped", count, tags: ["reason:#{reason}"])
+  }
+end
+```
+
+Reasons: `:queue_full`, `:circuit_open`, `:auth_suspended`, `:error`
+
+The callback is called synchronously but **exceptions are always swallowed** -- a broken callback will never affect the client.
+
+### Gzip Compression
+
+Outgoing batches are automatically gzip-compressed when they exceed the compression threshold (default: 1KB). This typically achieves 70-85% bandwidth reduction for log payloads with repetitive keys and values.
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.compression = true       # enable gzip compression (default: true)
+  c.compression_threshold = 1024  # only compress payloads > 1KB (default: 1024)
+  c.max_payload_bytes = 262_144   # max batch size before splitting (default: 256KB)
+end
+```
+
+Compression uses `Zlib::BEST_SPEED` (level 1) for minimal CPU overhead (~0.14ms per batch). The server must support `Content-Encoding: gzip` on request bodies. OpenTrace server v0.6+ includes transparent decompression middleware.
+
+### Version Negotiation
+
+On the first dispatch cycle, the client makes a lightweight `GET /api/version` call to discover the server's API version and capabilities. This runs once per process (or after fork) and never blocks `enqueue`.
+
+```ruby
+# Check server capabilities programmatically
+client = OpenTrace.send(:client)
+client.supports?(:request_summaries)  # true if server advertises it
+client.supports?(:gzip_request)       # true if server supports gzip
+```
+
+If the server requires a newer client API version, a warning is printed to STDERR:
+
+```
+[OpenTrace] Server requires API version >= 2, but this client supports version 1.
+Please upgrade the opentrace gem. Log forwarding may not work correctly.
+```
+
+Every request includes an `X-API-Version: 1` header so the server can reject incompatible clients with a clear error. Old servers without `/api/version` are handled gracefully — the check silently skips and all features remain enabled.
+
+### Distributed Tracing
+
+When `trace_propagation` is enabled (the default), the middleware extracts or generates a W3C-compatible trace context for each request:
+
+- **Incoming**: Reads `traceparent` header (W3C standard), falls back to `X-Trace-ID`, then `X-Request-ID`
+- **Outgoing**: When `http_tracking` is enabled, injects `traceparent`, `X-Trace-ID`, and `X-Request-ID` into outbound HTTP requests
+
+This enables cross-service correlation — all logs from a distributed request chain share the same `trace_id`.
+
+```ruby
+OpenTrace.configure do |c|
+  # ...
+  c.trace_propagation = true   # extract/propagate trace context (default: true)
+  c.http_tracking = true       # also inject into outgoing HTTP calls (opt-in)
+end
+```
+
+Each log entry includes `trace_id`, `span_id`, and `parent_span_id` (when available) as top-level fields. The server indexes these for fast trace lookups.
+
+### Request Summary Architecture
+
+When `request_summary` is enabled, events within a request are **accumulated** in a Fiber-local `RequestCollector` instead of being pushed to the queue individually:
+
+```
+Request Start
+  Middleware creates RequestCollector in Fiber[]
+    SQL events ──► collector.record_sql()      (no queue push)
+    View events ──► collector.record_view()    (no queue push)
+    Cache events ──► collector.record_cache()  (no queue push)
+    HTTP events ──► collector.record_http()    (no queue push)
+  Request End
+    Controller subscriber builds request_summary from collector
+    One queue push: metadata (user/request context) + request_summary (perf data)
+  Middleware cleans up RequestCollector
+```
+
+This means a request with 30 SQL queries, 50 view renders, and 10 cache operations produces **one log entry** instead of 91.
+
+### Structured Request Metrics
+
+When a `RequestCollector` is active, performance data is sent as a **separate `request_summary` field** instead of being merged into metadata. This allows the server to store it in a dedicated `request_summaries` table with indexed columns for fast analytical queries.
+
+```ruby
+# Sent automatically by the Rails subscriber — no code changes needed.
+# The payload looks like:
+{
+  "metadata": { "request_id": "req-abc", "user_id": 42 },
+  "request_summary": {
+    "controller": "InvoicesController",
+    "action": "index",
+    "method": "GET",
+    "path": "/invoices",
+    "status": 200,
+    "duration_ms": 45.2,
+    "sql_count": 3,
+    "sql_total_ms": 12.1,
+    "n_plus_one": false,
+    "view_count": 2,
+    "view_total_ms": 28.3,
+    "cache_reads": 1,
+    "cache_hits": 1,
+    "cache_hit_ratio": 1.0,
+    "timeline": [{"t": "sql", "n": "Invoice Load", "ms": 8.2, "at": 2.0}]
+  }
+}
+```
+
+You can also pass `request_summary:` manually:
+
+```ruby
+OpenTrace.log("INFO", "Custom request", { user_id: 42 },
+  request_summary: { controller: "Custom", action: "run", sql_count: 5 })
+```
+
+**Backward compatibility**: Old servers ignore the `request_summary` field. When no collector is active (background jobs, non-Rails), data falls back to metadata as before.
+
 ## Log Payload Format
 
 Each log is sent as a JSON object to `POST /api/logs`:
@@ -367,6 +815,19 @@ Each log is sent as a JSON object to `POST /api/logs`:
     "hostname": "web-01",
     "pid": 12345,
     "git_sha": "a1b2c3d"
+  },
+  "request_summary": {
+    "controller": "InvoicesController",
+    "action": "index",
+    "method": "GET",
+    "path": "/invoices",
+    "status": 200,
+    "duration_ms": 45.2,
+    "sql_count": 3,
+    "sql_total_ms": 12.1,
+    "view_count": 2,
+    "view_total_ms": 28.3,
+    "timeline": [...]
   }
 }
 ```
@@ -379,7 +840,11 @@ Each log is sent as a JSON object to `POST /api/logs`:
 | `service` | string | no |
 | `environment` | string | no |
 | `trace_id` | string | no |
+| `span_id` | string | no |
+| `parent_span_id` | string | no |
+| `event_type` | string | no |
 | `metadata` | object | no |
+| `request_summary` | object | no |
 
 The server accepts a single JSON object or an array of objects.
 

data/lib/opentrace/circuit_breaker.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OpenTrace
+  class CircuitBreaker
+    CLOSED    = :closed
+    OPEN      = :open
+    HALF_OPEN = :half_open
+
+    attr_reader :state
+
+    def initialize(failure_threshold:, recovery_timeout:)
+      @failure_threshold = failure_threshold
+      @recovery_timeout  = recovery_timeout
+      @state             = CLOSED
+      @failure_count     = 0
+      @last_failure_at   = nil
+      @mutex             = Mutex.new
+    end
+
+    def allow_request?
+      @mutex.synchronize do
+        case @state
+        when CLOSED
+          true
+        when OPEN
+          if Time.now - @last_failure_at >= @recovery_timeout
+            @state = HALF_OPEN
+            true
+          else
+            false
+          end
+        when HALF_OPEN
+          false
+        end
+      end
+    end
+
+    def record_success
+      @mutex.synchronize do
+        @failure_count = 0
+        @state = CLOSED
+      end
+    end
+
+    def record_failure
+      @mutex.synchronize do
+        @failure_count += 1
+        @last_failure_at = Time.now
+        @state = OPEN if @failure_count >= @failure_threshold
+      end
+    end
+
+    def reset!
+      @mutex.synchronize do
+        @state = CLOSED
+        @failure_count = 0
+        @last_failure_at = nil
+      end
+    end
+  end
+end