exis_ray 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10abd6a535e59a6d883a669567f45450fdbf694163699c2d5fb3cab4436a6ba9
+  data.tar.gz: c64fa72c61bc02921264714ec334ceaa8aee37b6507ebc42e9936f1f2eca86b5
+SHA512:
+  metadata.gz: c3bda3764d45ce3de886ed7a48d79df083c62bd48e84ac42e832f77bd736d35d333a723167809b8db6d1aceb21a6b9dd3c9ae42d7b359b9a6b4bb6c78da0b5c1
+  data.tar.gz: 8e7b43e3fea6235d93365f89efa180a870785cbfb3329a380563aee4f69334c16d8703599104e12c746c5b06a1ee8af527bbccac19595e492ff172f0b85a3390

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-23
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 gabriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# ExisRay
+
+**ExisRay** is a robust observability framework designed for Ruby on Rails microservices. It unifies **Distributed Tracing** (AWS X-Ray compatible), **Business Context Propagation**, and **Error Reporting** into a single, cohesive gem.
+
+It acts as the backbone of your architecture, ensuring that every request, background task (Sidekiq/Cron), log line, and external API call carries the necessary context to debug issues across a distributed system.
+
+## 🚀 Features
+
+* **Distributed Tracing:** Automatically parses, generates, and propagates Trace headers (compatible with AWS ALB `X-Amzn-Trace-Id`).
+* **Unified Logging:** Injects the global `Root ID` into every Rails log line automatically, making Kibana/CloudWatch filtering effortless.
+* **Context Management:** Thread-safe storage for business identity (`User`, `ISP`, `CorrelationId`) with automatic cleanup.
+* **Error Reporting:** A wrapper for Sentry (Legacy & Modern SDKs) that enriches errors with the full trace and business context.
+* **Sidekiq Integration:** Automatic context propagation (User/ISP/Trace) between the Enqueuer and the Worker.
+* **Task Monitor:** A specialized monitor for Rake/Cron tasks to initialize traces where no HTTP request exists.
+* **HTTP Clients:** Automatically patches `ActiveResource` and provides middleware for `Faraday`.
+
+---
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exis_ray'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+---
+
+## ⚙️ Configuration
+
+Create an initializer to configure the behavior. This is crucial to link ExisRay with your specific application logic.
+
+**File:** `config/initializers/exis_ray.rb`
+
+```ruby
+ExisRay.configure do |config|
+  # 1. Trace Header (Incoming)
+  # The HTTP header used to read the Trace ID from the Load Balancer (Rack format).
+  # Default: 'HTTP_X_AMZN_TRACE_ID' (AWS Standard).
+  config.trace_header = 'HTTP_X_WP_TRACE_ID'
+
+  # 2. Propagation Header (Outgoing)
+  # The header sent to downstream services via ActiveResource/Faraday.
+  config.propagation_trace_header = 'X-Wp-Trace-Id'
+
+  # 3. Dynamic Classes (Required)
+  # Link your app's specific classes to the gem.
+  # We use Strings to avoid "uninitialized constant" errors during boot.
+  config.current_class  = 'Current'   # Your Context Model
+  config.reporter_class = 'Choto'     # Your Sentry Wrapper
+end
+```
+
+---
+
+## 📖 Implementation Guide
+
+### 1. Define Business Context (`Current`)
+
+Inherit from `ExisRay::Current` to manage your global state. This class handles thread-safety and ensures data is wiped after every request.
+
+**File:** `app/models/current.rb`
+
+```ruby
+class Current < ExisRay::Current
+  # Add app-specific attributes here
+  attribute :billing_cycle, :permissions
+  
+  # ExisRay provides: user_id, isp_id, correlation_id
+end
+```
+
+### 2. Define Error Reporter (`Reporter`)
+
+Inherit from `ExisRay::Reporter` to standardize error handling. This wrapper automatically attaches the `Trace ID`, `User`, `ISP`, and `Tags` to every Sentry event.
+
+**File:** `app/models/choto.rb`
+
+```ruby
+class Choto < ExisRay::Reporter
+  # Optional hook to add service-specific context
+  def self.build_custom_context
+    if ExisRay.current_class.respond_to?(:olt)
+      add_tags(olt_id: ExisRay.current_class.olt&.id)
+    end
+  end
+end
+```
+
+### 3. Hydrate Context (Controller)
+
+In your `ApplicationController`, verify the incoming request and set the context. ExisRay handles the Trace ID automatically, you just handle the Business Logic.
+
+**File:** `app/controllers/application_controller.rb`
+
+```ruby
+before_action :set_exis_ray_context
+
+def set_exis_ray_context
+  # 1. User Context (e.g., from Devise)
+  Current.user = current_user if current_user
+
+  # 2. ISP Context (e.g., from Headers)
+  Current.isp_id = request.headers['X-Isp-Id']
+
+  # Note: Setting these automatically prepares headers for ActiveResource
+  # and tags for Sentry.
+end
+```
+
+---
+
+## 🛠 Usage Scenarios
+
+### A. Automatic Sidekiq Integration
+
+If `Sidekiq` is present, ExisRay automatically configures Client and Server middlewares. **No code changes are required in your workers.**
+
+**How it works:**
+1.  **Enqueue:** When you call `Worker.perform_async`, the current `Trace ID` and `Current` attributes are injected into the job payload.
+2.  **Process:** When the worker executes, `Current` is hydrated with the original data.
+3.  **Logs:** Sidekiq logs will show the same `[Root=...]` ID as the web request.
+
+```ruby
+# Controller
+def create
+  # Trace ID: A, User: 42
+  HardWorker.perform_async(100)
+end
+
+# Worker
+class HardWorker
+  include Sidekiq::Worker
+  def perform(amount)
+    puts Current.user_id # => 42 (Restored!)
+    Rails.logger.info "Processing" # => [Root=A] Processing...
+  end
+end
+```
+
+### B. Background Tasks (Cron/Rake)
+
+For Rake tasks or Cron jobs (where no HTTP request exists), use `ExisRay::TaskMonitor`. It generates a fresh `Root ID`.
+
+**File:** `lib/tasks/billing.rake`
+
+```ruby
+task generate_invoices: :environment do
+  ExisRay::TaskMonitor.run('billing:generate_invoices') do
+    # Logs are tagged: [Root=1-65a...bc] [ExisRay] Starting task...
+    InvoiceService.process_all
+  end
+end
+```
+
+### C. HTTP Clients
+
+ExisRay ensures traceability across microservices.
+
+#### ActiveResource (Automatic)
+If `ActiveResource` is detected, ExisRay automatically patches it. All outgoing requests will include:
+* `X-Wp-Trace-Id` (Trace Header)
+* `UserId`, `IspId`, `CorrelationId`
+
+#### Faraday (Manual)
+For Faraday, you must explicitly add the middleware:
+
+```ruby
+conn = Faraday.new(url: '[https://api.internal](https://api.internal)') do |f|
+  f.use ExisRay::FaradayMiddleware
+  f.adapter Faraday.default_adapter
+end
+```
+
+---
+
+## 🏗 Architecture
+
+* **`ExisRay::Tracer`**: The infrastructure layer. Handles AWS X-Ray format parsing and ID generation.
+* **`ExisRay::Current`**: The business layer. Manages domain identity (`User`, `ISP`).
+* **`ExisRay::Reporter`**: The observability layer. Bridges the gap between your app and Sentry.
+* **`ExisRay::TaskMonitor`**: The entry point for non-HTTP processes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/lib/exis_ray/active_resource_instrumentation.rb

@@ -0,0 +1,39 @@
+module ExisRay
+  # Módulo diseñado para interceptar e instrumentar las peticiones HTTP salientes realizadas con ActiveResource.
+  # Utiliza el patrón `prepend` para envolver el método `headers` original sin romper la cadena de herencia.
+  #
+  # Su función principal es inyectar automáticamente el header de trazabilidad (Trace ID)
+  # en todas las peticiones salientes para mantener la traza distribuida entre microservicios.
+  module ActiveResourceInstrumentation
+    # Sobrescribe el método `headers` de ActiveResource para inyectar el Trace ID actual.
+    #
+    # Lógica de inyección:
+    # 1. Obtiene los headers definidos originalmente por el modelo o la request.
+    # 2. Verifica si existe un contexto de traza activo (Root ID).
+    # 3. Si existe, genera el header formateado (AWS/Wispro) y lo fusiona con los headers originales.
+    #
+    # @return [Hash] Un hash de headers HTTP que incluye el header de trazabilidad si corresponde.
+    def headers
+      # 1. Obtenemos los headers originales (si los hay)
+      original_headers = super
+
+      # 2. Verificación Universal:
+      # Usamos `root_id` en lugar de `trace_id`.
+      # - trace_id: Solo existe si recibimos una petición Web (viene del header entrante).
+      # - root_id: Existe SIEMPRE que haya traza (sea Web o sea un Cron generado por TaskMonitor).
+      if ExisRay::Tracer.root_id.present?
+        # Generamos el string propagable: "Root=...;Parent=...;Sampled=..."
+        trace_header_value = ExisRay::Tracer.generate_trace_header
+
+        # Buscamos la key configurada (ej: 'HTTP_X_AMZN_TRACE_ID' o custom)
+        trace_header_key = ExisRay.configuration.trace_header
+
+        # Retornamos un nuevo hash combinado (merge) para no mutar el original por error
+        original_headers.merge(trace_header_key => trace_header_value)
+      else
+        # Si no hay traza activa, devolvemos los headers tal cual
+        original_headers
+      end
+    end
+  end
+end

data/lib/exis_ray/configuration.rb

@@ -0,0 +1,36 @@
+module ExisRay
+  # Clase de configuración global para la gema.
+  # Permite personalizar los headers de trazabilidad y definir las clases de la aplicación host
+  # que la gema utilizará para gestionar el contexto (Current) y el reporte de errores (Reporter).
+  class Configuration
+    # @!attribute [rw] trace_header
+    #   @return [String] La key del header HTTP (formato Rack) donde se buscará el Trace ID entrante.
+    #   Por defecto es 'HTTP_X_AMZN_TRACE_ID'.
+    attr_accessor :trace_header
+
+    # @!attribute [rw] propagation_trace_header
+    #   @return [String] La key del header HTTP que se enviará a otros servicios (formato estándar).
+    #   Por defecto es 'X-Amzn-Trace-Id'.
+    attr_accessor :propagation_trace_header
+
+    # @!attribute [rw] reporter_class
+    #   @return [String, Class, nil] El nombre de la clase de la aplicación host que hereda de {ExisRay::Reporter}.
+    #   Se recomienda usar un String para evitar problemas de carga (autoloading) durante la inicialización.
+    #   @example 'Choto'
+    attr_accessor :reporter_class
+
+    # @!attribute [rw] current_class
+    #   @return [String, Class, nil] El nombre de la clase de la aplicación host que hereda de {ExisRay::Current}.
+    #   Se utiliza para inyectar/leer user_id, isp_id y correlation_id.
+    #   @example 'Current'
+    attr_accessor :current_class
+
+    # Inicializa la configuración con valores por defecto compatibles con AWS X-Ray.
+    def initialize
+      @trace_header = 'HTTP_X_AMZN_TRACE_ID'
+      @propagation_trace_header = 'X-Amzn-Trace-Id'
+      @reporter_class = 'Reporter'
+      @current_class = 'Current'
+    end
+  end
+end

data/lib/exis_ray/current.rb

@@ -0,0 +1,112 @@
+require 'active_support/current_attributes'
+
+module ExisRay
+  # Clase base para la gestión del contexto de negocio (User, ISP, Correlation).
+  # Debe ser heredada por la aplicación host (ej: class Current < ExisRay::Current).
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :user_id, :isp_id, :correlation_id
+
+    # Callback nativo de Rails: Se ejecuta automáticamente al llamar a Current.reset
+    resets do
+      @user = nil
+      @isp  = nil
+
+      if defined?(PaperTrail)
+        PaperTrail.request.whodunnit = nil
+        PaperTrail.request.controller_info = {}
+      end
+
+      if defined?(ActiveResource::Base)
+        ActiveResource::Base.headers.delete('UserId')
+        ActiveResource::Base.headers.delete('IspId')
+        ActiveResource::Base.headers.delete('CorrelationId')
+      end
+    end
+
+    # --- Setters con Hooks ---
+
+    def user_id=(id)
+      super
+      if defined?(ActiveResource::Base)
+        ActiveResource::Base.headers['UserId'] = id.to_s
+      end
+      if defined?(PaperTrail)
+        PaperTrail.request.whodunnit = id
+      end
+    end
+
+    def isp_id=(id)
+      super
+      @isp = nil # Invalida cache
+      if defined?(ActiveResource::Base)
+        ActiveResource::Base.headers['IspId'] = id.to_s
+      end
+    end
+
+    def correlation_id=(id)
+      super
+
+      if defined?(::Session)
+        ::Session.request_id = id # Deprecated legacy support
+      end
+
+      if defined?(ActiveResource::Base)
+        ActiveResource::Base.headers['CorrelationId'] = id.to_s
+      end
+
+      if defined?(PaperTrail)
+        PaperTrail.request.controller_info = { correlation_id: id }
+      end
+
+      # Integración con el Reporter configurado
+      if (reporter = ExisRay.reporter_class) && reporter.respond_to?(:add_tags)
+        reporter.add_tags(correlation_id: id)
+      end
+    end
+
+    # --- Helpers de Objetos (Lazy Loading) ---
+    # Estos métodos asumen que la app host tiene modelos ::User e ::Isp
+
+    def user=(object)
+      @user = object
+      self.user_id = object&.id
+    end
+
+    def user
+      return @user if defined?(@user) && @user
+
+      if user_id && defined?(::User) && ::User.respond_to?(:find_by)
+        @user = ::User.find_by(id: user_id)
+      else
+        nil
+      end
+    end
+
+    def isp=(object)
+      @isp = object
+      self.isp_id = object&.id
+    end
+
+    def isp
+      return @isp if defined?(@isp) && @isp
+
+      if isp_id && defined?(::Isp) && ::Isp.respond_to?(:find_by)
+        @isp = ::Isp.find_by(id: isp_id)
+      else
+        nil
+      end
+    end
+
+    def user?
+      user_id.present?
+    end
+
+    def isp?
+      isp_id.present?
+    end
+
+    def correlation_id?
+      correlation_id.present?
+    end
+  end
+end

data/lib/exis_ray/faraday_middleware.rb

@@ -0,0 +1,19 @@
+require 'faraday'
+
+module ExisRay
+  # Middleware para Faraday que inyecta el header de trazabilidad saliente.
+  class FaradayMiddleware < Faraday::Middleware
+    def call(env)
+      if ExisRay::Tracer.root_id.present?
+        # Generamos el valor de traza
+        header_value = ExisRay::Tracer.generate_trace_header
+        # Obtenemos la key configurada para propagación
+        header_key = ExisRay.configuration.propagation_trace_header
+
+        env.request_headers[header_key] = header_value
+      end
+      @app.call(env)
+    end
+  end
+end
+

data/lib/exis_ray/http_middleware.rb

@@ -0,0 +1,30 @@
+module ExisRay
+  # Middleware de Rack para interceptar peticiones HTTP.
+  # Inicializa el Tracer y sincroniza el Correlation ID con la clase Current configurada.
+  class HttpMiddleware
+    def initialize(app)
+      @app = app
+      @base_service_name = defined?(Rails) ? Rails.application.class.module_parent_name : 'App'
+    end
+
+    def call(env)
+      # 1. Hidratar Infraestructura
+      ExisRay::Tracer.created_at   = Time.now.utc.to_f
+      ExisRay::Tracer.service_name = "#{@base_service_name}-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
+
+      # 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
+
+      @app.call(env)
+    end
+  end
+end

data/lib/exis_ray/railtie.rb

@@ -0,0 +1,60 @@
+require 'rails/railtie'
+
+module ExisRay
+  # Integración automática con Rails.
+  # Carga middlewares HTTP, tags de logs e integraciones (Sidekiq/ActiveResource).
+  class Railtie < ::Rails::Railtie
+    # 1. Middleware HTTP
+    initializer "exis_ray.configure_middleware" do |app|
+      require 'exis_ray/http_middleware'
+      app.middleware.insert_after ActionDispatch::RequestId, ExisRay::HttpMiddleware
+    end
+
+    # 2. Logs Tags
+    initializer "exis_ray.configure_log_tags" do |app|
+      app.config.log_tags ||= []
+      app.config.log_tags << proc {
+        if ExisRay::Tracer.trace_id.present?
+          ExisRay::Tracer.trace_id
+        elsif ExisRay::Tracer.root_id.present?
+          ExisRay::Tracer.root_id
+        else
+          nil
+        end
+      }
+    end
+
+    # 3. Integraciones Post-Boot
+    config.after_initialize do
+      # ActiveResource
+      if defined?(ActiveResource::Base)
+        require 'exis_ray/active_resource_instrumentation'
+        ActiveResource::Base.send(:prepend, ExisRay::ActiveResourceInstrumentation)
+        Rails.logger.info "[ExisRay] ActiveResource instrumentado."
+      end
+
+      # Sidekiq
+      # Usamos ::Sidekiq para referirnos a la Gema Global y no al módulo local ExisRay::Sidekiq
+      if defined?(::Sidekiq)
+        require 'exis_ray/sidekiq/client_middleware'
+        require 'exis_ray/sidekiq/server_middleware'
+
+        ::Sidekiq.configure_client do |config|
+          config.client_middleware do |chain|
+            chain.add ExisRay::Sidekiq::ClientMiddleware
+          end
+        end
+
+        ::Sidekiq.configure_server do |config|
+          config.client_middleware do |chain|
+            chain.add ExisRay::Sidekiq::ClientMiddleware
+          end
+          config.server_middleware do |chain|
+            chain.prepend ExisRay::Sidekiq::ServerMiddleware
+          end
+        end
+        Rails.logger.info "[ExisRay] Sidekiq Middleware integrado."
+      end
+    end
+  end
+end

data/lib/exis_ray/reporter.rb

@@ -0,0 +1,187 @@
+require 'active_support/current_attributes'
+
+module ExisRay
+  # Clase base híbrida para reporte de errores.
+  # Soporta integración moderna (Sentry SDK) y legacy (Raven/Session).
+  class Reporter < ActiveSupport::CurrentAttributes
+    attribute :contexts, :tags, :transaction_name, :fingerprint
+
+    resets do
+      self.contexts         = {}
+      self.tags             = {}
+      self.fingerprint      = []
+      self.transaction_name = nil
+
+      # Invocamos limpieza legacy si existe.
+      # Usamos self.class porque clean_legacy_session! es método de clase.
+      self.class.clean_legacy_session!
+    end
+
+    # --- Métodos Públicos ---
+
+    def self.report(message, context: {}, tags: {}, fingerprint: [], transaction_name: nil)
+      prepare_scope(context, tags, fingerprint, transaction_name)
+      if report_to_new_sentry?
+        report_to_new_sentry(message)
+      else
+        report_to_old_sentry(message)
+      end
+    end
+
+    def self.exception(excep, context: {}, tags: {}, fingerprint: [], transaction_name: nil)
+      prepare_scope(context, tags, fingerprint, transaction_name)
+      add_tags(exception: excep.class.to_s)
+
+      Rails.logger.error(excep) unless Rails.env.production?
+
+      if report_to_new_sentry?
+        exception_to_new_sentry(excep)
+      else
+        exception_to_old_sentry(excep)
+      end
+    end
+
+    # --- Builders de Datos ---
+
+    def self.add_fingerprint(value)
+      current_values = fingerprint || []
+      current_values << value
+      self.fingerprint = current_values.flatten.compact.uniq
+    end
+
+    def self.add_context(attrs)
+      return if attrs.blank?
+
+      self.contexts = (contexts || {}).merge(attrs.as_json)
+    end
+
+    def self.add_tags(attrs)
+      return if attrs.blank?
+      self.tags = (tags || {}).merge(attrs.as_json)
+    end
+
+    def self.build_custom_context
+      # Hook para subclases
+    end
+
+    # --- Lógica Legacy ---
+    def self.clean_legacy_session!
+      return unless defined?(::Session) && ::Session.respond_to?(:clean!)
+
+      ::Session.clean!
+    end
+
+    def self.session_tag!
+      return unless defined?(::Session)
+
+      ::Session.tags_context ||= {}
+
+      if fingerprint.present?
+        str_fingerprint = fingerprint.flatten.join(',')
+        ::Session.tags_context.merge!(fingerprint: str_fingerprint)
+      end
+      if transaction_name.present?
+        ::Session.tags_context.merge!(transaction_name: transaction_name)
+      end
+      ::Session.tags_context.merge!(tags) if tags.present?
+    end
+
+    def self.session_context!
+      return unless contexts.present? && defined?(::Session)
+
+      ::Session.extra_context ||= {}
+      ::Session.extra_context.merge!(contexts)
+    end
+
+    def self.report_to_old_sentry(message)
+      session_tag!
+      session_context!
+      Sentry.send_event(message) if defined?(Sentry)
+    end
+
+    def self.exception_to_old_sentry(exception)
+      session_tag!
+      session_context!
+
+      if defined?(Sentry)
+        Sentry.populate_context(contexts) if contexts.present?
+        Sentry.notify(exception)
+      end
+    end
+
+    # --- Lógica Moderna ---
+
+    def self.report_to_new_sentry?
+      defined?(::NEW_SENTRY) && ::NEW_SENTRY
+    end
+
+    def self.report_to_new_sentry(message)
+      send_to_new_sentry { Sentry.capture_message(message, fingerprint: fingerprint) }
+    end
+
+    def self.exception_to_new_sentry(exception)
+      send_to_new_sentry { Sentry.capture_exception(exception, level: 'error', fingerprint: fingerprint) }
+    end
+
+    def self.send_to_new_sentry
+      return unless defined?(Sentry)
+
+      Sentry.with_scope do |scope|
+        scope.set_transaction_name(transaction_name) if transaction_name.present?
+        if contexts.present?
+          contexts.each do |key, value|
+            val = value.is_a?(Hash) ? value : { value: value }
+            scope.set_context(key, val)
+          end
+        end
+        scope.set_tags(tags) if tags.present?
+        yield(scope)
+      end
+    end
+
+    # --- Inicialización de Contexto ---
+
+    private_class_method def self.prepare_scope(context, tags, fingerprint, transaction_name)
+      add_context(context)
+      add_tags(tags)
+      add_fingerprint(fingerprint)
+      self.transaction_name = transaction_name if transaction_name.present?
+
+      build_from_tracer
+      build_from_current
+      build_custom_context
+    end
+
+    def self.build_from_tracer
+      return unless defined?(ExisRay::Tracer)
+
+      if ExisRay::Tracer.root_id.present?
+        add_tags(correlation_id: ExisRay::Tracer.root_id)
+        add_context(trace: {
+          root_id: ExisRay::Tracer.root_id,
+          request_id: ExisRay::Tracer.request_id
+        })
+      end
+    end
+
+    def self.build_from_current
+      klass = ExisRay.current_class
+      return unless klass
+
+      add_tags(user_id: klass.user_id) if klass.respond_to?(:user_id?) && klass.user_id?
+      add_tags(isp_id: klass.isp_id)   if klass.respond_to?(:isp_id?)  && klass.isp_id?
+
+      if klass.respond_to?(:user) && klass.user.present?
+        user_json = klass.user.respond_to?(:as_json) ? klass.user.as_json : { id: klass.user_id }
+        add_context(user: user_json)
+      end
+
+      if klass.respond_to?(:isp) && klass.isp.present?
+        isp_json = klass.isp.respond_to?(:as_json) ? klass.isp.as_json : { id: klass.isp_id }
+        add_context(isp: isp_json)
+      end
+    end
+
+    private_class_method :build_from_current, :build_from_tracer
+  end
+end

data/lib/exis_ray/sidekiq/client_middleware.rb

@@ -0,0 +1,31 @@
+module ExisRay
+  module Sidekiq
+    class ClientMiddleware
+      # Intercepta el push del trabajo a Redis.
+      # @param worker_class [String, Class] La clase del worker.
+      # @param job [Hash] El payload del trabajo (aquí inyectamos datos).
+      # @param queue [String] Nombre de la cola.
+      # @param redis_pool [Object] Pool de conexión (Legacy v6).
+      def call(worker_class, job, queue, redis_pool = nil)
+        # Solo inyectamos si hay una traza activa (viniendo de Web o Cron)
+        if ExisRay::Tracer.root_id.present?
+          # 1. Inyectamos la traza (usamos generate_trace_header para mantener la cadena)
+          job['exis_ray_trace'] = ExisRay::Tracer.generate_trace_header
+
+          # 2. Inyectamos el contexto de negocio (Current)
+          # Esto permite saber qué Usuario o ISP disparó el job.
+          if ExisRay.current_class.present?
+            context = {}
+            context[:user_id] = ExisRay.current_class.user_id if ExisRay.current_class.respond_to?(:user_id)
+            context[:isp_id]  = ExisRay.current_class.isp_id if ExisRay.current_class.respond_to?(:isp_id)
+            context[:correlation_id] = ExisRay.current_class.correlation_id if ExisRay.current_class.respond_to?(:correlation_id)
+
+            job['exis_ray_context'] = context
+          end
+        end
+
+        yield
+      end
+    end
+  end
+end

data/lib/exis_ray/sidekiq/server_middleware.rb

@@ -0,0 +1,103 @@
+module ExisRay
+  module Sidekiq
+    # Middleware de Servidor para Sidekiq.
+    # Se ejecuta alrededor de cada trabajo (job) procesado por un Worker.
+    #
+    # Su responsabilidad es:
+    # 1. Recuperar el Trace ID y contexto (User, ISP) inyectados por el cliente.
+    # 2. Configurar el entorno (Tracer, Current, Reporter).
+    # 3. Limpiar todo al finalizar para no contaminar el thread (Thread Pooling).
+    class ServerMiddleware
+      # Intercepta la ejecución del job.
+      #
+      # @param worker [Object] La instancia del worker que procesará el job.
+      # @param job [Hash] El payload del trabajo (contiene argumentos y metadatos).
+      # @param queue [String] El nombre de la cola.
+      def call(worker, job, queue)
+        # 1. Hidratación de Infraestructura (Tracer)
+        hydrate_tracer(worker, job)
+
+        # 2. Hidratación de Negocio (Current Class configurada)
+        hydrate_current(job)
+
+        # 3. Configuración de Reporte (Sentry/Reporter Class configurada)
+        setup_reporter(worker)
+
+        # 4. Ejecución con Logs Taggeados
+        # Inyectamos el Root ID en los logs de Rails para correlacionarlos con Sidekiq.
+        tags = [ExisRay::Tracer.root_id]
+
+        if Rails.logger.respond_to?(:tagged)
+          Rails.logger.tagged(*tags) { yield }
+        else
+          yield
+        end
+
+      ensure
+        # 5. Limpieza Total (Vital en Sidekiq)
+        # Sidekiq reutiliza threads. Si no limpiamos, el contexto de un job
+        # (ej: usuario actual) podría filtrarse al siguiente job.
+        ExisRay::Tracer.reset
+
+        # Limpieza usando los helpers centralizados (sin hardcodear Current)
+        ExisRay.current_class&.reset  if ExisRay.current_class.respond_to?(:reset)
+        ExisRay.reporter_class&.reset if ExisRay.reporter_class.respond_to?(:reset)
+      end
+
+      private
+
+      # Configura el Tracer con el ID recibido o genera uno nuevo.
+      def hydrate_tracer(worker, job)
+        ExisRay::Tracer.created_at = Time.now.utc.to_f
+        ExisRay::Tracer.service_name = "Sidekiq-#{worker.class.name}"
+
+        if job['exis_ray_trace']
+          # Continuidad: Usamos la traza que viene del cliente (Web/Cron)
+          ExisRay::Tracer.trace_id = job['exis_ray_trace']
+          ExisRay::Tracer.parse_trace_id
+        else
+          # Origen: El job nació aquí (ej: desde consola o trigger externo sin contexto)
+          ExisRay::Tracer.root_id = ExisRay::Tracer.send(:generate_new_root)
+        end
+      end
+
+      # Hidrata la clase Current configurada con los datos del payload.
+      def hydrate_current(job)
+        # Obtenemos la clase dinámica (ej: Current)
+        klass = ExisRay.current_class
+
+        # Salimos si no hay clase configurada o no hay contexto en el job
+        return unless klass && job['exis_ray_context']
+
+        ctx = job['exis_ray_context']
+
+        # Asignación segura usando la clase dinámica
+        klass.user_id = ctx['user_id'] if ctx['user_id'] && klass.respond_to?(:user_id=)
+        klass.isp_id  = ctx['isp_id']  if ctx['isp_id']  && klass.respond_to?(:isp_id=)
+
+        if ctx['correlation_id'] && klass.respond_to?(:correlation_id=)
+          klass.correlation_id = ctx['correlation_id']
+        end
+      end
+
+      # Configura tags y nombres de transacción en el Reporter.
+      def setup_reporter(worker)
+        klass = ExisRay.reporter_class
+        return unless klass
+
+        # Nombre de transacción para Sentry: "Sidekiq/HardWorker"
+        if klass.respond_to?(:transaction_name=)
+          klass.transaction_name = "Sidekiq/#{worker.class.name}"
+        end
+
+        # Tags adicionales de infraestructura Sidekiq
+        if klass.respond_to?(:add_tags)
+          klass.add_tags(
+            sidekiq_queue: worker.class.get_sidekiq_options['queue'],
+            retry_count: worker.respond_to?(:retry_count) ? worker.retry_count : 0
+          )
+        end
+      end
+    end
+  end
+end

data/lib/exis_ray/task_monitor.rb

@@ -0,0 +1,55 @@
+module ExisRay
+  # Wrapper para monitorear tareas en segundo plano (Rake/Cron).
+  module TaskMonitor
+    # Ejecuta un bloque dentro de un contexto monitoreado.
+    # @param task_name [String] Nombre identificador (ej: 'billing:generate').
+    def self.run(task_name)
+      setup_tracer(task_name)
+
+      short_name = task_name.to_s.split(':').last
+
+      # Configurar Reporter
+      if (rep = ExisRay.reporter_class) && rep.respond_to?(:transaction_name=)
+        rep.transaction_name = short_name
+        rep.add_tags(service: :cron, task: short_name) if rep.respond_to?(:add_tags)
+      end
+
+      # Configurar Current
+      if (curr = ExisRay.current_class) && curr.respond_to?(:correlation_id=)
+        curr.correlation_id = ExisRay::Tracer.correlation_id
+      end
+
+      # Logs con Root ID
+      tags = [ExisRay::Tracer.root_id]
+      Rails.logger.tagged(*tags) do
+        Rails.logger.info "[ExisRay] Iniciando tarea: #{task_name}"
+        yield
+        Rails.logger.info "[ExisRay] Finalizada con éxito."
+      end
+
+    rescue StandardError => e
+      Rails.logger.error "[ExisRay] Falló la tarea #{task_name}: #{e.message}"
+      raise e
+    ensure
+      # Limpieza centralizada
+      ExisRay::Tracer.reset
+      ExisRay.current_class&.reset  if ExisRay.current_class.respond_to?(:reset)
+      ExisRay.reporter_class&.reset if ExisRay.reporter_class.respond_to?(:reset)
+    end
+
+    def self.setup_tracer(task_name)
+      ExisRay::Tracer.service_name = task_name.to_s.gsub(':', '-').camelize
+      ExisRay::Tracer.request_id   = SecureRandom.uuid
+      ExisRay::Tracer.created_at   = Time.now.utc.to_f
+
+      pod_id = get_pod_identifier
+      ExisRay::Tracer.root_id = ExisRay::Tracer.send(:generate_new_root, pod_id)
+    end
+
+    def self.get_pod_identifier
+      (ENV['HOSTNAME'] || 'local').split('-').last.to_s
+    end
+
+    private_class_method :get_pod_identifier, :setup_tracer
+  end
+end

data/lib/exis_ray/tracer.rb

@@ -0,0 +1,111 @@
+require 'active_support/current_attributes'
+require 'securerandom'
+
+module ExisRay
+  # Gestiona el contexto de trazabilidad distribuida (Distributed Tracing).
+  # Utiliza `ActiveSupport::CurrentAttributes` para mantener el estado de la petición actual
+  # de forma segura entre hilos (thread-safe).
+  #
+  # Esta clase parsea headers de AWS X-Ray y genera nuevos headers para la propagación.
+  #
+  # @see https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html Documentación de AWS X-Ray
+  class Tracer < ActiveSupport::CurrentAttributes
+    attribute :trace_id, :request_id, :root_id, :self_id, :called_from, :total_time_so_far, :created_at, :service_name
+
+    # Devuelve el nombre del servicio actual.
+    # Si no se ha definido manualmente, hace fallback al nombre de la aplicación Rails.
+    #
+    # @return [String] El nombre del servicio (ej: "Wispro", "Wispro-Worker", "App").
+    def self.service_name
+      super || (defined?(Rails) ? Rails.application.class.module_parent_name : 'App')
+    end
+
+    # Genera un ID de correlación compuesto, útil para logs y auditoría.
+    #
+    # @example
+    #   ExisRay::Tracer.correlation_id #=> "Wispro-HTTP;1-5759...-..."
+    #
+    # @return [String] Cadena compuesta "ServiceName;RootID".
+    def self.correlation_id
+      "#{service_name};#{root_id}"
+    end
+
+    # Parsea el string de trazabilidad recibido y popula los atributos individuales.
+    # Maneja el formato estándar de AWS: "Root=...;Self=...;CalledFrom=...;TotalTimeSoFar=..."
+    #
+    # @return [void]
+    def self.parse_trace_id
+      return unless trace_id.present?
+
+      # Fallback para desarrollo: Si el header no trae Root, generamos uno nuevo.
+      self.trace_id = generate_new_root(trace_id) if trace_id.exclude?('Root')
+
+      # Parseo a Hash
+      data = trace_id.split(';').map { |part| part.split('=', 2) }.to_h
+
+      self.root_id     = data['Root']
+      self.self_id     = data['Self']
+      self.called_from = data['CalledFrom']
+
+      if data['TotalTimeSoFar']
+        self.total_time_so_far = data['TotalTimeSoFar'].gsub(/ms$/i, '').to_i
+      else
+        self.total_time_so_far = 0
+      end
+    end
+
+    # Calcula el tiempo transcurrido en milisegundos desde el inicio de la request.
+    #
+    # @return [Integer] Duración en ms.
+    def self.current_duration_ms
+      return 0 unless created_at
+      ((Time.now.utc.to_f - created_at) * 1000).round
+    end
+
+    # Construye el header de trazabilidad para enviar al siguiente servicio.
+    #
+    # @return [String] Header formateado: "Root=...;Self=...;CalledFrom=...;TotalTimeSoFar=...ms"
+    def self.generate_trace_header
+      safe_root = if root_id.present?
+                    root_id.start_with?('Root=') ? root_id : "Root=#{root_id}"
+                  else
+                    generate_new_root
+                  end
+
+      total_acc_time = (total_time_so_far || 0) + current_duration_ms
+
+      # Nuevo ID para el span actual
+      my_new_id = "1-#{Time.now.to_i.to_s(16)}-#{clean_request_id}"
+
+      "#{safe_root};Self=#{my_new_id};CalledFrom=#{service_name};TotalTimeSoFar=#{total_acc_time}ms"
+    end
+
+    # Genera un nuevo Root ID compatible con AWS X-Ray.
+    #
+    # @api private
+    # @param suffix_id [String, nil] Sufijo opcional (ej: ID del Pod).
+    # @return [String] Formato: 1-TimestampHex-RandomHex
+    def self.generate_new_root(suffix_id = nil)
+      timestamp_hex = Time.now.to_i.to_s(16)
+
+      if suffix_id.present?
+        suffix_hex = suffix_id.to_i.to_s(16).rjust(8, '0')
+        unique_part = SecureRandom.hex(8) + suffix_hex
+      else
+        unique_part = SecureRandom.hex(12)
+      end
+
+      "Root=1-#{timestamp_hex}-#{unique_part}"
+    end
+
+    # Limpia el Request ID para cumplir con los 24 caracteres hex de AWS.
+    #
+    # @api private
+    # @return [String]
+    def self.clean_request_id
+      (request_id || SecureRandom.hex).delete('-').first(24)
+    end
+
+    private_class_method :clean_request_id, :generate_new_root
+  end
+end

data/lib/exis_ray/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ExisRay
+  # Versión actual de la gema.
+  VERSION = "0.1.0"
+end

data/lib/exis_ray.rb

@@ -0,0 +1,88 @@
+require "exis_ray/version"
+
+# Dependencias externas
+# Necesario para 'safe_constantize', 'present?', y 'CurrentAttributes'
+require "active_support"
+require "active_support/core_ext/string/inflections" # Para safe_constantize
+require "active_support/current_attributes"
+
+# Componentes internos del Core
+require "exis_ray/configuration"
+require "exis_ray/tracer"
+require "exis_ray/task_monitor"
+require "exis_ray/http_middleware"
+require "exis_ray/current"
+require "exis_ray/reporter"
+
+# Integraciones Opcionales
+# Solo cargamos el middleware de Faraday si la gema está presente en el sistema.
+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)
+
+# Integración automática con Rails
+# Solo cargamos el Railtie si la constante Rails está definida.
+require "exis_ray/railtie" if defined?(Rails)
+
+# Namespace principal de la gema ExisRay.
+# Contiene la configuración global y los helpers de resolución de clases dinámicas.
+module ExisRay
+  class Error < StandardError; end
+
+  class << self
+    # @!attribute [w] configuration
+    attr_writer :configuration
+
+    # Accesor para la configuración global de la gema.
+    # Inicializa una nueva instancia de {Configuration} si no existe.
+    #
+    # @return [ExisRay::Configuration] La instancia de configuración actual.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Bloque de configuración para inicializar la gema.
+    #
+    # @example Configurar en un initializer de Rails
+    #   ExisRay.configure do |config|
+    #     config.trace_header = 'HTTP_X_WP_TRACE_ID'
+    #     config.current_class = 'Current'
+    #     config.reporter_class = 'Choto'
+    #   end
+    #
+    # @yieldparam config [ExisRay::Configuration] El objeto de configuración.
+    def configure
+      yield(configuration)
+    end
+
+    # --- Helpers Centralizados de Resolución de Clases ---
+
+    # Resuelve y retorna la clase configurada para manejar el contexto de negocio (Current).
+    # Convierte el String configurado (ej: 'Current') en la clase real constante.
+    #
+    # @return [Class, nil] La clase constante (ej: Current) o nil si no se encuentra/configura.
+    def current_class
+      return nil unless configuration
+
+      klass_name = configuration.current_class
+      return nil unless klass_name.present?
+
+      # Si es String, lo convertimos a constante de forma segura.
+      klass_name.is_a?(String) ? klass_name.safe_constantize : klass_name
+    end
+
+    # Resuelve y retorna la clase configurada para el reporte de errores (Reporter).
+    # Convierte el String configurado (ej: 'Choto') en la clase real constante.
+    #
+    # @return [Class, nil] La clase constante (ej: Choto) o nil si no se encuentra/configura.
+    def reporter_class
+      return nil unless configuration
+
+      klass_name = configuration.reporter_class
+      return nil unless klass_name.present?
+
+      klass_name.is_a?(String) ? klass_name.safe_constantize : klass_name
+    end
+  end
+end

data/sig/exis_ray.rbs

@@ -0,0 +1,4 @@
+module ExisRay
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: exis_ray
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gabriel Edera
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Gema que gestiona el contexto de request, logs y propagación de headers.
+email:
+- gab.edera@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/exis_ray.rb
+- lib/exis_ray/active_resource_instrumentation.rb
+- lib/exis_ray/configuration.rb
+- lib/exis_ray/current.rb
+- lib/exis_ray/faraday_middleware.rb
+- lib/exis_ray/http_middleware.rb
+- lib/exis_ray/railtie.rb
+- lib/exis_ray/reporter.rb
+- lib/exis_ray/sidekiq/client_middleware.rb
+- lib/exis_ray/sidekiq/server_middleware.rb
+- lib/exis_ray/task_monitor.rb
+- lib/exis_ray/tracer.rb
+- lib/exis_ray/version.rb
+- sig/exis_ray.rbs
+homepage: https://github.com/gedera/exis_ray
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Trazabilidad distribuida entre microservicios (AWS X-Ray style).
+test_files: []