exis_ray 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a79e0a93c6efad500f943dad46daa5d429f133d8144db2fd1ce1e32e2b07ac68
-  data.tar.gz: 243915edbd6405a89656457b1371b34971efa5f377def03093d4a024ca73b661
+  metadata.gz: d66d71924fff9cf19c12e42d411963948739da61e6b223db1444c16633a3158e
+  data.tar.gz: 26c599899ecf1f87388c73e1b4a183370e0902893c09e40c24c7796c973c0d96
 SHA512:
-  metadata.gz: 6877511e716b0fb3ec6fe55a4542b7129163da596344ec1b98f8042d9bdedd9b514c2fe80ec78af474a4d18d5fd9b70bacd84669d3c467ecd2c69904555a6d94
-  data.tar.gz: cc0356850bfd66654bd241e3aa2654c5114ea2e3a6fbac91eab248e5b4cb5f10affd2ccfdf62065b5f70cbe6f6d362018572299cb307d365db20cd7d2e7c03b7
+  metadata.gz: 60c34361234b638c3758b3b51d38933efcbf5db19fb8e1a9365f53f1e21bcfc42e680ceb37755c792663e7146826af2453d862b7ae526481870f65518a84b311
+  data.tar.gz: e3cb2ffc12e45d5bdd6f3c1d1a864bc9884b7709c531fa2780923834f0ca4d4766c75148c6afd15aac4d6a6dbf716a151042620474127b544b779fa86ec9c62b

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.5.6] - 2026-03-26
+
+### Added
+- **BugBunny Integration:** Added `ExisRay::BugBunny::PublisherTracing` middleware for `BugBunny::Client` and `BugBunny::Resource`. Injects the active trace context into the `x-trace-id` AMQP header on every published message.
+- **BugBunny Integration:** Added `ExisRay::BugBunny::ConsumerTracing` concern for `BugBunny::Controller`. Restores the ExisRay trace context from `x-trace-id` header via `around_action`, enabling end-to-end distributed tracing across RabbitMQ message boundaries.
+
 ## [0.5.5] - 2026-03-24
 
 ### Added

data/README.md

@@ -14,6 +14,7 @@ It acts as the backbone of your architecture, ensuring that every request, backg
 * **Sidekiq Integration:** Automatic context propagation (User/ISP/Trace) and log formatting between the Enqueuer and the Worker.
 * **Task Monitor:** A specialized monitor for Rake/Cron tasks to initialize traces and format logs where no HTTP request exists.
 * **HTTP Clients:** Automatically patches `ActiveResource` and provides middleware for `Faraday`.
+* **BugBunny Integration:** Propagates the trace context across RabbitMQ message boundaries via a publisher middleware and a consumer concern.
 
 ---
 
@@ -200,6 +201,40 @@ conn = Faraday.new(url: "[https://api.internal](https://api.internal)") do |f|
 end
 ```
 
+### E. BugBunny (RabbitMQ)
+
+If your app publishes messages via [BugBunny](https://github.com/gedera/bug_bunny), ExisRay can propagate the active trace context through the `x-trace-id` AMQP header, and restore it on the consumer side so every log line during message processing shares the same `root_id` as the original HTTP request.
+
+#### Publisher — inject the trace header
+
+Add `ExisRay::BugBunny::PublisherTracing` to your client middleware stack. Works with both `BugBunny::Client` and `BugBunny::Resource`.
+
+```ruby
+client = BugBunny::Client.new(pool: connection_pool) do |stack|
+  stack.use ExisRay::BugBunny::PublisherTracing
+  stack.use BugBunny::Middleware::JsonResponse
+end
+```
+
+If no trace context is active (e.g. a standalone script), the middleware does nothing.
+
+#### Consumer — restore the trace context
+
+Include `ExisRay::BugBunny::ConsumerTracing` in your base controller. It registers an `around_action` that reads `x-trace-id` from the message headers and hydrates `ExisRay::Tracer` before your action runs. The context is always reset in `ensure`, preventing leaks between messages.
+
+```ruby
+class ApplicationController < BugBunny::Controller
+  include ExisRay::BugBunny::ConsumerTracing
+end
+```
+
+**How it works end-to-end:**
+1. **Publish:** The publisher middleware injects `x-trace-id` into the AMQP headers of every outgoing message.
+2. **Consume:** The consumer concern reads that header, restores the trace context, and sets `source=system`.
+3. **Logs:** Every log line emitted during the controller action carries the original `root_id` and `correlation_id` from the upstream HTTP request.
+
+If a message arrives without `x-trace-id` (published without ExisRay), the concern is a no-op.
+
 ---
 
 ## 📋 Advanced Logging Guide

data/lib/exis_ray/bug_bunny/consumer_tracing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module ExisRay
+  module BugBunny
+    # Concern para BugBunny::Controller que restaura el trace context de ExisRay
+    # a partir del header 'x-trace-id' inyectado por el publicador.
+    #
+    # Permite que todos los logs emitidos durante el procesamiento de un mensaje
+    # incluyan el mismo root_id y correlation_id que el request HTTP original,
+    # logrando trazabilidad distribuida de punta a punta.
+    #
+    # El contexto se limpia siempre en `ensure`, garantizando que un error en el
+    # controller no contamine el procesamiento del siguiente mensaje.
+    #
+    # @example Incluir en el ApplicationController de BugBunny
+    #   class ApplicationController < BugBunny::Controller
+    #     include ExisRay::BugBunny::ConsumerTracing
+    #   end
+    module ConsumerTracing
+      extend ActiveSupport::Concern
+
+      # Header AMQP desde el cual se lee el trace context propagado.
+      TRACE_HEADER = 'x-trace-id'
+
+      included do
+        around_action :exis_ray_trace_context
+      end
+
+      private
+
+      # Restaura el contexto de trazabilidad y lo limpia al finalizar,
+      # independientemente de si el controller levantó una excepción.
+      #
+      # @yieldreturn [void]
+      def exis_ray_trace_context
+        setup_exis_ray_context
+        yield
+      ensure
+        ExisRay::Tracer.reset rescue nil
+      end
+
+      # Hidrata el Tracer con el header de traza recibido en el mensaje.
+      # Si el header no está presente (mensaje sin trace context), no hace nada.
+      #
+      # @return [void]
+      def setup_exis_ray_context
+        trace_header = headers[TRACE_HEADER]
+        return unless trace_header.present?
+
+        ExisRay::Tracer.hydrate(trace_id: trace_header, source: 'system')
+        ExisRay.sync_correlation_id
+      rescue StandardError
+        # El tracing nunca debe interrumpir el procesamiento del mensaje.
+      end
+    end
+  end
+end

data/lib/exis_ray/bug_bunny/publisher_tracing.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ExisRay
+  module BugBunny
+    # Middleware de publicación para BugBunny::Client.
+    #
+    # Inyecta el header de trazabilidad de ExisRay en cada mensaje publicado,
+    # permitiendo la propagación del trace context a los servicios consumidores.
+    # Esto hace posible correlacionar un request HTTP original con todos los mensajes
+    # y logs que genera en el ecosistema de microservicios.
+    #
+    # @example Configuración en el cliente
+    #   client = BugBunny::Client.new(pool: pool) do |stack|
+    #     stack.use ExisRay::BugBunny::PublisherTracing
+    #   end
+    #
+    # @example Configuración en un BugBunny::Resource
+    #   class UserResource < BugBunny::Resource
+    #     middleware do |stack|
+    #       stack.use ExisRay::BugBunny::PublisherTracing
+    #     end
+    #   end
+    class PublisherTracing < ::BugBunny::Middleware::Base
+      # Header AMQP personalizado para propagar el trace context entre servicios.
+      TRACE_HEADER = 'x-trace-id'
+
+      # Inyecta el header de traza antes de publicar el mensaje.
+      # Solo actúa si hay un trace context activo (root_id presente).
+      #
+      # @param env [BugBunny::Request] El objeto request del mensaje saliente.
+      # @return [void]
+      def on_request(env)
+        return unless ExisRay::Tracer.root_id.present?
+
+        env.headers[TRACE_HEADER] = ExisRay::Tracer.generate_trace_header
+      rescue StandardError
+        # La propagación de tracing nunca debe interrumpir la publicación de mensajes.
+      end
+    end
+  end
+end

data/lib/exis_ray/http_middleware.rb

@@ -8,20 +8,14 @@ module ExisRay
 
     def call(env)
       # 1. Hidratar Infraestructura
-      ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      ExisRay::Tracer.source     = "http"
-
-      trace_header_key = ExisRay.configuration.trace_header
-
-      ExisRay::Tracer.trace_id     = env[trace_header_key]
-      ExisRay::Tracer.request_id   = env['action_dispatch.request_id']
-      ExisRay::Tracer.parse_trace_id
+      ExisRay::Tracer.hydrate(
+        trace_id: env[ExisRay.configuration.trace_header],
+        source:   "http"
+      )
+      ExisRay::Tracer.request_id = env['action_dispatch.request_id']
 
       # 2. Hidratar Negocio
-      # Usamos el helper centralizado para obtener la clase Current
-      if (curr = ExisRay.current_class) && curr.respond_to?(:correlation_id=) && ExisRay::Tracer.root_id.present?
-        curr.correlation_id = ExisRay::Tracer.correlation_id
-      end
+      ExisRay.sync_correlation_id
 
       @app.call(env)
     end

data/lib/exis_ray/sidekiq/server_middleware.rb

@@ -46,17 +46,16 @@ module ExisRay
       # @param job [Hash] Payload de Sidekiq.
       # @return [void]
       def hydrate_tracer(worker, job)
-        ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         ExisRay::Tracer.sidekiq_job = worker.class.name
-        ExisRay::Tracer.source      = "sidekiq"
 
         if job["exis_ray_trace"]
           # Continuidad: Usamos la traza propagada desde el cliente (Web/Cron)
-          ExisRay::Tracer.trace_id = job["exis_ray_trace"]
-          ExisRay::Tracer.parse_trace_id
+          ExisRay::Tracer.hydrate(trace_id: job["exis_ray_trace"], source: "sidekiq")
         else
           # Origen: El job nació directamente aquí sin contexto previo
-          ExisRay::Tracer.root_id = ExisRay::Tracer.send(:generate_new_root)
+          ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ExisRay::Tracer.source     = "sidekiq"
+          ExisRay::Tracer.root_id    = ExisRay::Tracer.send(:generate_new_root)
         end
       end
 

data/lib/exis_ray/tracer.rb

@@ -61,6 +61,20 @@ module ExisRay
       (current_duration_s * 1000).round
     end
 
+    # Hidrata el Tracer con un trace header entrante y registra el inicio del contexto.
+    # Centraliza la inicialización de contexto de trazabilidad para todos los entrypoints
+    # (HTTP, Sidekiq, BugBunny, etc.), eliminando duplicación entre middlewares.
+    #
+    # @param trace_id [String] El header de traza entrante (formato AWS X-Ray).
+    # @param source [String] El entrypoint de ejecución ('http', 'sidekiq', 'task', 'system').
+    # @return [void]
+    def self.hydrate(trace_id:, source:)
+      self.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      self.source     = source
+      self.trace_id   = trace_id
+      parse_trace_id
+    end
+
     # Calcula el tiempo transcurrido en segundos desde el inicio de la request.
     # Cumple con el estándar Wispro-Observability-Spec (v1).
     #

data/lib/exis_ray/version.rb

@@ -2,5 +2,5 @@
 
 module ExisRay
   # Versión actual de la gema.
-  VERSION = "0.5.5"
+  VERSION = "0.5.6"
 end

data/lib/exis_ray.rb

@@ -24,6 +24,13 @@ require "exis_ray/faraday_middleware" if defined?(Faraday)
 # Solo cargamos la instrumentación si ActiveResource está presente.
 require "exis_ray/active_resource_instrumentation" if defined?(ActiveResource::Base)
 
+# Integraciones BugBunny: publisher middleware y consumer concern.
+# Solo se cargan si la gema BugBunny está presente.
+if defined?(::BugBunny)
+  require "exis_ray/bug_bunny/publisher_tracing"
+  require "exis_ray/bug_bunny/consumer_tracing"
+end
+
 # Integración automática con Rails
 # Solo cargamos el Railtie si la constante Rails está definida.
 require "exis_ray/railtie" if defined?(Rails)
@@ -96,6 +103,17 @@ module ExisRay
       end
     end
 
+    # Sincroniza el correlation_id del Tracer en la clase Current configurada.
+    # Debe llamarse después de hidratar el Tracer (post `hydrate` o `parse_trace_id`).
+    #
+    # @return [void]
+    def sync_correlation_id
+      curr = current_class
+      return unless curr&.respond_to?(:correlation_id=) && Tracer.root_id.present?
+
+      curr.correlation_id = Tracer.correlation_id
+    end
+
     private
 
     def resolve_class(klass_name)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -54,6 +54,8 @@ files:
 - Rakefile
 - lib/exis_ray.rb
 - lib/exis_ray/active_resource_instrumentation.rb
+- lib/exis_ray/bug_bunny/consumer_tracing.rb
+- lib/exis_ray/bug_bunny/publisher_tracing.rb
 - lib/exis_ray/configuration.rb
 - lib/exis_ray/current.rb
 - lib/exis_ray/faraday_middleware.rb