exis_ray 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10abd6a535e59a6d883a669567f45450fdbf694163699c2d5fb3cab4436a6ba9
-  data.tar.gz: c64fa72c61bc02921264714ec334ceaa8aee37b6507ebc42e9936f1f2eca86b5
+  metadata.gz: 72c313e5194f8252623ac026d98ab510c8ad50c7f4b7c7d8f362005c14d6d3e5
+  data.tar.gz: 51b8c985ab03bff4389784477e9c5eb5f27e81138766e50356414b2e88121b68
 SHA512:
-  metadata.gz: c3bda3764d45ce3de886ed7a48d79df083c62bd48e84ac42e832f77bd736d35d333a723167809b8db6d1aceb21a6b9dd3c9ae42d7b359b9a6b4bb6c78da0b5c1
-  data.tar.gz: 8e7b43e3fea6235d93365f89efa180a870785cbfb3329a380563aee4f69334c16d8703599104e12c746c5b06a1ee8af527bbccac19595e492ff172f0b85a3390
+  metadata.gz: 5bd0a72ee15676c2074306af62a71098230b30831f49d9b678bb02dd853528a687db9e2d354d0fa34f3bcf758e0bf63fbd5512a949963e256528817749163fda
+  data.tar.gz: 485e39a4b8bf41a01a099d5a75c472f77683ac4a98bb1dcfa109e9abd16be0532930f78bebfee0a94beeb2a725cbae0a3696eabafaa070b0aae2a4cd24b13937

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-12
+
+### Added
+- **Structured JSON Logging:** Introduced a centralized `ExisRay::JsonFormatter` that intercepts all application logs (HTTP, Sidekiq, and Rake tasks) and formats them into context-rich, single-line JSON objects.
+- Added `lograge` as a core dependency to condense standard Rails multi-line HTTP logs into single events.
+- Introduced the `config.log_format` configuration option (accepts `:text` or `:json`).
+- Added native support for `ActiveSupport::TaggedLogging`. Standard Rails tags (`config.log_tags`) are now automatically intercepted and injected as a `"tags"` array within the JSON payload.
+- Added support for merging Lograge's `custom_options` directly into the JSON root.
+- Expanded `README.md` with an "Advanced Logging Guide", detailing environment-specific setup and customization strategies.
+
+### Changed
+- Refactored `Sidekiq::ServerMiddleware` and `TaskMonitor` to intelligently adapt their logging behavior based on the active `log_format`, preventing redundant tagging in JSON mode.
+- Shifted the `Railtie` logging configuration to execute `after: :load_config_initializers`. This guarantees the host application's initializers are fully loaded before ExisRay determines the log format.
+- Enforced strict RuboCop compliance (`Style/StringLiterals` -> double quotes) across all internal classes, methods, and documentation examples.
+
+### Fixed
+- Fixed `NoMethodError: undefined method 'current_tags'` by ensuring `JsonFormatter` correctly includes the `ActiveSupport::TaggedLogging::Formatter` interface.
+- Resolved a race condition during Rails boot where `lograge` failed to initialize if the gem configuration was set via an initializer.
+
 ## [0.1.0] - 2025-12-23
 
 - Initial release

data/README.md

@@ -1,17 +1,18 @@
 # 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.
+**ExisRay** is a robust observability framework designed for Ruby on Rails microservices. It unifies **Distributed Tracing** (AWS X-Ray compatible), **Business Context Propagation**, **Error Reporting**, and **Structured JSON Logging** 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.
+* **Structured JSON Logging:** Optionally unifies all your application logs (HTTP requests, Sidekiq jobs, and Rake tasks) into a clean, single-line JSON format, perfect for Datadog, ELK, or CloudWatch.
+* **Unified Tagging:** If JSON logging is disabled, it automatically injects the global `Root ID` into every Rails log line.
 * **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.
+* **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`.
 
 ---
@@ -21,7 +22,7 @@ It acts as the backbone of your architecture, ensuring that every request, backg
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'exis_ray'
+gem "exis_ray"
 ```
 
 And then execute:
@@ -30,6 +31,8 @@ And then execute:
 $ bundle install
 ```
 
+*(Note: ExisRay automatically installs and configures `lograge` as a dependency to handle HTTP log condensation).*
+
 ---
 
 ## ⚙️ Configuration
@@ -42,18 +45,24 @@ Create an initializer to configure the behavior. This is crucial to link ExisRay
 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'
+  # 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'
+  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
+  config.current_class  = "Current"   # Your Context Model
+  config.reporter_class = "Choto"     # Your Sentry Wrapper
+
+  # 4. Log Format (New!)
+  # Choose the output format for your application logs.
+  # Options: :text (default Rails behavior) or :json (Structured logging).
+  # Pro-tip: Make it dynamic based on the environment!
+  config.log_format = Rails.env.production? ? :json : :text
 end
 ```
 
@@ -71,7 +80,7 @@ Inherit from `ExisRay::Current` to manage your global state. This class handles
 class Current < ExisRay::Current
   # Add app-specific attributes here
   attribute :billing_cycle, :permissions
-  
+
   # ExisRay provides: user_id, isp_id, correlation_id
 end
 ```
@@ -107,10 +116,7 @@ def set_exis_ray_context
   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.
+  Current.isp_id = request.headers["X-Isp-Id"]
 end
 ```
 
@@ -118,33 +124,30 @@ end
 
 ## 🛠 Usage Scenarios
 
-### A. Automatic Sidekiq Integration
+### A. Structured JSON Logging
+
+When `config.log_format = :json` is enabled, ExisRay transforms all your application outputs into single-line, context-rich JSON objects.
+
+**HTTP Requests (via Lograge):**
+```json
+{"time":"2026-03-12T14:30:00Z","level":"INFO","service":"App-HTTP","root_id":"Root=1-65a...bc","trace_id":"Root=1-65a...bc;Self=...","request_id":"9876-abcd-...","user_id":42,"isp_id":10,"method":"GET","path":"/api/v1/users","format":"html","controller":"UsersController","action":"index","status":200,"duration":45.2,"view":20.1,"db":15.0}
+```
+
+**Sidekiq Jobs & Rake Tasks:**
+```json
+{"time":"2026-03-12T14:31:00Z","level":"INFO","service":"Sidekiq-HardWorker","root_id":"Root=1-65a...bc","user_id":42,"message":"[ExisRay] Processing payment..."}
+```
+
+### B. 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.
+3.  **Logs:** Sidekiq logs will automatically include the propagated `Root ID` and Business Context (either as text tags or structured JSON).
 
-```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)
+### C. Background Tasks (Cron/Rake)
 
 For Rake tasks or Cron jobs (where no HTTP request exists), use `ExisRay::TaskMonitor`. It generates a fresh `Root ID`.
 
@@ -152,14 +155,13 @@ For Rake tasks or Cron jobs (where no HTTP request exists), use `ExisRay::TaskMo
 
 ```ruby
 task generate_invoices: :environment do
-  ExisRay::TaskMonitor.run('billing:generate_invoices') do
-    # Logs are tagged: [Root=1-65a...bc] [ExisRay] Starting task...
+  ExisRay::TaskMonitor.run("billing:generate_invoices") do
     InvoiceService.process_all
   end
 end
 ```
 
-### C. HTTP Clients
+### D. HTTP Clients
 
 ExisRay ensures traceability across microservices.
 
@@ -172,7 +174,7 @@ If `ActiveResource` is detected, ExisRay automatically patches it. All outgoing
 For Faraday, you must explicitly add the middleware:
 
 ```ruby
-conn = Faraday.new(url: '[https://api.internal](https://api.internal)') do |f|
+conn = Faraday.new(url: "[https://api.internal](https://api.internal)") do |f|
   f.use ExisRay::FaradayMiddleware
   f.adapter Faraday.default_adapter
 end
@@ -180,11 +182,74 @@ end
 
 ---
 
+## 📋 Advanced Logging Guide
+
+ExisRay's `JsonFormatter` is designed to be highly extensible. Here is how you can get the most out of your observability stack.
+
+### 1. Environment Best Practices
+
+For the best developer experience, we recommend using standard text logs in development and structured JSON logs in production.
+
+**File:** `config/environments/production.rb`
+```ruby
+Rails.application.configure do
+  # Force Rails to log to STDOUT so Docker/Swarm can collect the JSON output
+  if ENV["RAILS_LOG_TO_STDOUT"].present?
+    logger           = ActiveSupport::Logger.new(STDOUT)
+    logger.formatter = config.log_formatter
+    config.logger    = ActiveSupport::TaggedLogging.new(logger)
+  end
+
+  # Set an appropriate log level to avoid disk/network saturation
+  config.log_level = :info
+end
+```
+
+### 2. Extending JSON with Rails Tags (`config.log_tags`)
+
+If you are using native Rails tags, ExisRay will automatically capture them and group them into a `"tags"` array within your JSON log. This prevents the JSON structure from breaking.
+
+**File:** `config/environments/production.rb`
+```ruby
+# Add custom tags to your HTTP requests
+config.log_tags = [
+  :uuid,
+  ->(request) { request.headers["X-Custom-Header"] }
+]
+```
+**Output:**
+```json
+{"time":"2026-03-12T14:30:00Z","service":"App-HTTP","tags":["abcd-1234-uuid","CustomValue"],"method":"GET","status":200}
+```
+
+### 3. Extending JSON with Custom Properties (Lograge)
+
+If you prefer to inject key-value pairs directly into the root of the JSON (which is highly recommended for querying in Datadog, Kibana, etc.), you can leverage Lograge's `custom_options` in your host application.
+
+ExisRay will flawlessly merge these attributes with the core Trace ID and Business Context.
+
+**File:** `config/environments/production.rb`
+```ruby
+config.lograge.custom_options = lambda do |event|
+  {
+    ip_address: event.payload[:ip],
+    browser: event.payload[:user_agent]
+  }
+end
+```
+**Output:**
+```json
+{"time":"2026-03-12T14:30:00Z","service":"App-HTTP","root_id":"Root=1-65a...","method":"GET","ip_address":"192.168.1.1","browser":"Chrome","status":200}
+```
+
+---
+
 ## 🏗 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::JsonFormatter`**: The central logging engine. Intercepts HTTP, Sidekiq, and Tasks to output clean JSON.
 * **`ExisRay::TaskMonitor`**: The entry point for non-HTTP processes.
 
 ## License

data/lib/exis_ray/configuration.rb

@@ -25,12 +25,26 @@ module ExisRay
     #   @example 'Current'
     attr_accessor :current_class
 
+    # @!attribute [rw] log_format
+    #   @return [Symbol] El formato en el que se emitirán los logs de la aplicación.
+    #   Puede ser `:text` (comportamiento por defecto de Rails) o `:json` (formato estructurado).
+    #   @example :json
+    attr_accessor :log_format
+
     # 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'
+      @log_format = :text
+    end
+
+    # Indica si la aplicación está configurada para emitir logs en formato estructurado (JSON).
+    #
+    # @return [Boolean] `true` si `log_format` es `:json`, `false` en caso contrario.
+    def json_logs?
+      @log_format == :json
     end
   end
 end

data/lib/exis_ray/json_formatter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "logger"
+require "json"
+require "active_support/tagged_logging"
+
+module ExisRay
+  # Formateador global que intercepta todos los logs de la aplicación y los emite en formato JSON.
+  #
+  # Esta clase hereda de `Logger::Formatter` y tiene la responsabilidad unificada
+  # de estandarizar la salida para peticiones HTTP (procesadas previamente vía Lograge),
+  # trabajos en segundo plano (Sidekiq), tareas programadas (Rake/Cron) y cualquier
+  # mensaje arbitrario enviado explícitamente a `Rails.logger`.
+  #
+  # Automáticamente inyecta el contexto de trazabilidad ({ExisRay::Tracer})
+  # y el contexto de negocio ({ExisRay::Current}) en cada línea de log.
+  class JsonFormatter < ::Logger::Formatter
+    # Solución al NoMethodError: Garantiza que el formateador sea compatible 
+    # con el wrapper de ActiveSupport::TaggedLogging de Rails.
+    include ActiveSupport::TaggedLogging::Formatter if defined?(ActiveSupport::TaggedLogging::Formatter)
+
+    # Procesa un mensaje de log y lo formatea como una cadena estructurada en JSON.
+    #
+    # @param severity [String] El nivel de severidad del log (ej. "INFO", "ERROR", "DEBUG").
+    # @param timestamp [Time] La marca de tiempo en la que se generó el log.
+    # @param _progname [String, nil] El nombre del programa o aplicación (ignorado aquí).
+    # @param msg [String, Hash, Object] El mensaje a registrar. Puede ser un Hash (inyectado por Lograge) o un String.
+    # @return [String] Una cadena en formato JSON terminada con un salto de línea (\n).
+    def call(severity, timestamp, _progname, msg)
+      payload = {
+        time: timestamp.utc.iso8601,
+        level: severity,
+        service: ExisRay::Tracer.service_name
+      }
+
+      inject_tracer_context(payload)
+      inject_business_context(payload)
+      inject_current_tags(payload)
+      process_message(payload, msg)
+
+      # Compactamos para eliminar claves con valores nulos (nil) y generamos el JSON
+      "#{payload.compact.to_json}\n"
+    end
+
+    private
+
+    # Inyecta los identificadores de trazabilidad distribuida en el payload.
+    #
+    # @param payload [Hash] El diccionario del log donde se insertarán los datos.
+    # @return [void]
+    def inject_tracer_context(payload)
+      return unless ExisRay::Tracer.root_id
+
+      payload[:root_id]  = ExisRay::Tracer.root_id
+      payload[:trace_id] = ExisRay::Tracer.trace_id if ExisRay::Tracer.trace_id
+    end
+
+    # Inyecta el contexto de negocio (ID de usuario, ISP, ID de correlación) en el payload.
+    #
+    # @param payload [Hash] El diccionario del log donde se insertarán los datos.
+    # @return [void]
+    def inject_business_context(payload)
+      curr = ExisRay.current_class
+      return unless curr
+
+      payload[:user_id] = curr.user_id if curr.respond_to?(:user_id) && curr.user_id
+      payload[:isp_id]  = curr.isp_id  if curr.respond_to?(:isp_id)  && curr.isp_id
+
+      if curr.respond_to?(:correlation_id) && curr.correlation_id
+        payload[:correlation_id] = curr.correlation_id
+      end
+    end
+
+    # Inyecta cualquier etiqueta nativa (tags) de Rails que esté presente en el hilo actual.
+    #
+    # @param payload [Hash] El diccionario base del log.
+    # @return [void]
+    def inject_current_tags(payload)
+      if respond_to?(:current_tags) && current_tags.any?
+        payload[:tags] = current_tags
+      end
+    end
+
+    # Procesa el cuerpo del mensaje recibido y lo fusiona con el payload.
+    #
+    # Si el mensaje es un `Hash` (como el que nos pasará Lograge para peticiones HTTP),
+    # se hace un merge directo. Si es texto plano u otro objeto, se asigna a la clave `:message`.
+    #
+    # @param payload [Hash] El diccionario base del log.
+    # @param msg [String, Hash, Object] El mensaje original recibido por el logger.
+    # @return [void]
+    def process_message(payload, msg)
+      if msg.is_a?(Hash)
+        payload.merge!(msg)
+      else
+        payload[:message] = msg.to_s
+      end
+    end
+  end
+end

data/lib/exis_ray/railtie.rb

@@ -1,43 +1,62 @@
-require 'rails/railtie'
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "lograge" # Requerido globalmente para que su propio Railtie se registre en el boot
 
 module ExisRay
-  # Integración automática con Rails.
-  # Carga middlewares HTTP, tags de logs e integraciones (Sidekiq/ActiveResource).
+  # Integración automática de la gema con el ecosistema de Ruby on Rails.
+  #
+  # Se encarga de inyectar middlewares, configurar la estrategia de logging
+  # (texto plano o JSON estructurado) e instrumentar dependencias externas
+  # como Sidekiq y ActiveResource durante la fase de inicialización (`boot`) de la app.
   class Railtie < ::Rails::Railtie
     # 1. Middleware HTTP
+    # Intercepta las peticiones entrantes para hidratar el Tracer.
     initializer "exis_ray.configure_middleware" do |app|
-      require 'exis_ray/http_middleware'
+      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
+    # 2. Configuración de Estrategia de Logging (Lograge y Tags)
+    # CLAVE: Usamos `after: :load_config_initializers` para garantizar que la app
+    # ya haya leído `config/initializers/exis_ray.rb` antes de tomar esta decisión.
+    initializer "exis_ray.configure_logging", after: :load_config_initializers do |app|
+      if ExisRay.configuration.json_logs?
+        app.config.lograge.enabled = true
+        app.config.lograge.formatter = Lograge::Formatters::Raw.new
+      else
+        # Comportamiento legacy: Text Plain Tags
+        app.config.log_tags ||= []
+        app.config.log_tags << proc do
+          ExisRay::Tracer.trace_id.presence || ExisRay::Tracer.root_id.presence
         end
-      }
+      end
     end
 
-    # 3. Integraciones Post-Boot
+    # 3. Integraciones Post-Boot y Forzado de Formateadores
+    # Se ejecuta una vez que las gemas y el entorno de Rails están completamente cargados.
     config.after_initialize do
-      # ActiveResource
+      # Aplicamos el formateador JSON globalmente al logger ya instanciado de Rails
+      if ExisRay.configuration.json_logs? && Rails.logger
+        Rails.logger.formatter = ExisRay::JsonFormatter.new
+        Rails.logger.info({ message: "[ExisRay] JSON Logging unificado activado." })
+      end
+
+      # --- Instrumentación de ActiveResource ---
       if defined?(ActiveResource::Base)
-        require 'exis_ray/active_resource_instrumentation'
+        require "exis_ray/active_resource_instrumentation"
         ActiveResource::Base.send(:prepend, ExisRay::ActiveResourceInstrumentation)
-        Rails.logger.info "[ExisRay] ActiveResource instrumentado."
+
+        log_message(
+          text: "[ExisRay] ActiveResource instrumentado.",
+          json: { message: "[ExisRay] ActiveResource instrumentado." }
+        )
       end
 
-      # Sidekiq
-      # Usamos ::Sidekiq para referirnos a la Gema Global y no al módulo local ExisRay::Sidekiq
+      # --- Instrumentación de Sidekiq ---
       if defined?(::Sidekiq)
-        require 'exis_ray/sidekiq/client_middleware'
-        require 'exis_ray/sidekiq/server_middleware'
+        require "exis_ray/sidekiq/client_middleware"
+        require "exis_ray/sidekiq/server_middleware"
 
         ::Sidekiq.configure_client do |config|
           config.client_middleware do |chain|
@@ -53,7 +72,27 @@ module ExisRay
             chain.prepend ExisRay::Sidekiq::ServerMiddleware
           end
         end
-        Rails.logger.info "[ExisRay] Sidekiq Middleware integrado."
+
+        # Sidekiq maneja su propio logger. Lo forzamos a usar nuestra estructura JSON.
+        if ExisRay.configuration.json_logs? && ::Sidekiq.logger
+          ::Sidekiq.logger.formatter = ExisRay::JsonFormatter.new
+          Rails.logger.info({ message: "[ExisRay] Sidekiq Middleware y JsonFormatter integrados." })
+        else
+          Rails.logger.info "[ExisRay] Sidekiq Middleware integrado."
+        end
+      end
+    end
+
+    # Helper interno para imprimir logs de inicialización respetando el formato elegido.
+    #
+    # @param text [String] El mensaje para el formato texto.
+    # @param json [Hash] El payload para el formato JSON.
+    # @return [void]
+    def self.log_message(text:, json:)
+      if ExisRay.configuration.json_logs?
+        Rails.logger.info(json)
+      else
+        Rails.logger.info(text)
       end
     end
   end

data/lib/exis_ray/sidekiq/server_middleware.rb

@@ -1,102 +1,98 @@
+# frozen_string_literal: true
+
 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).
+    # Se ejecuta envolviendo cada trabajo (job) procesado por un Worker.
+    #
+    # Responsabilidades:
+    # 1. Recuperar el Trace ID y contexto de negocio (User, ISP) inyectados por el cliente.
+    # 2. Hidratar el entorno local (Tracer, Current, Reporter).
+    # 3. Limpiar absolutamente todo al finalizar para no contaminar el Thread Pool de Sidekiq.
     class ServerMiddleware
-      # Intercepta la ejecución del job.
+      # Intercepta la ejecución del job en el servidor Sidekiq.
       #
       # @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)
+      # @param job [Hash] El payload del trabajo (contiene argumentos y metadatos inyectados).
+      # @param _queue [String] El nombre de la cola (ignorado).
+      # @yield Ejecuta el bloque que procesa el job real.
+      # @return [void]
+      def call(worker, job, _queue)
         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 }
+        # Ejecución adaptativa de logs
+        if !ExisRay.configuration.json_logs? && Rails.logger.respond_to?(:tagged)
+          Rails.logger.tagged(ExisRay::Tracer.root_id) { 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.
+        # Limpieza vital en Sidekiq para evitar fugas de contexto entre jobs en el mismo hilo.
         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.
+      # Configura el Tracer con el ID recibido en el payload o genera uno nuevo si no existe.
+      #
+      # @param worker [Object] Instancia del worker.
+      # @param job [Hash] Payload de Sidekiq.
+      # @return [void]
       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']
+        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
         else
-          # Origen: El job nació aquí (ej: desde consola o trigger externo sin contexto)
+          # Origen: El job nació directamente aquí sin contexto previo
           ExisRay::Tracer.root_id = ExisRay::Tracer.send(:generate_new_root)
         end
       end
 
-      # Hidrata la clase Current configurada con los datos del payload.
+      # Hidrata la clase Current configurada con los datos de negocio del payload.
+      #
+      # @param job [Hash] Payload de Sidekiq.
+      # @return [void]
       def hydrate_current(job)
-        # Obtenemos la clase dinámica (ej: Current)
         klass = ExisRay.current_class
+        return unless klass && job["exis_ray_context"]
 
-        # 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']
+        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=)
+        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']
+        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.
+      # Configura etiquetas y nombres de transacción en el Reporter (Sentry).
+      #
+      # @param worker [Object] Instancia del worker.
+      # @return [void]
       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
+        return unless 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

data/lib/exis_ray/task_monitor.rb

@@ -1,44 +1,58 @@
+# frozen_string_literal: true
+
 module ExisRay
-  # Wrapper para monitorear tareas en segundo plano (Rake/Cron).
+  # Wrapper para monitorear tareas en segundo plano (Rake/Cron) o scripts aislados.
+  #
+  # Esta clase inicializa un contexto de trazabilidad simulado (ya que no hay
+  # una petición HTTP entrante) generando un nuevo `Root ID`. Luego, configura
+  # el reporte de errores y el contexto global antes de ejecutar el bloque provisto.
   module TaskMonitor
-    # Ejecuta un bloque dentro de un contexto monitoreado.
-    # @param task_name [String] Nombre identificador (ej: 'billing:generate').
+    # Ejecuta un bloque de código dentro de un contexto monitoreado por ExisRay.
+    #
+    # @param task_name [String, Symbol] Nombre identificador de la tarea (ej: "billing:generate").
+    # @yield El bloque de código que representa la lógica de la tarea.
+    # @raise [StandardError] Re-lanza cualquier excepción ocurrida tras registrarla.
+    # @return [void]
     def self.run(task_name)
       setup_tracer(task_name)
 
-      short_name = task_name.to_s.split(':').last
+      short_name = task_name.to_s.split(":").last
 
-      # Configurar Reporter
+      # Configurar Reporter (Sentry u otro)
       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
+      # Configurar Current Attributes
       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
+      log_event(:info, "Iniciando tarea: #{task_name}", task: task_name, status: "started")
 
+      # Bloque de ejecución con o sin tags dependiendo de la configuración
+      execute_with_optional_tags { yield }
+
+      log_event(:info, "Finalizada con éxito.", task: task_name, status: "success")
     rescue StandardError => e
-      Rails.logger.error "[ExisRay] Falló la tarea #{task_name}: #{e.message}"
+      log_event(:error, "Falló la tarea #{task_name}: #{e.message}", task: task_name, status: "failed", error: e.message)
       raise e
     ensure
-      # Limpieza centralizada
+      # Limpieza centralizada obligatoria para evitar filtraciones de memoria o contexto
       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
 
+    # --- Métodos Privados ---
+
+    # Inicializa el Tracer con datos específicos de la tarea y el entorno.
+    #
+    # @param task_name [String, Symbol] El nombre de la tarea en ejecución.
+    # @return [void]
     def self.setup_tracer(task_name)
-      ExisRay::Tracer.service_name = task_name.to_s.gsub(':', '-').camelize
+      ExisRay::Tracer.service_name = task_name.to_s.tr(":", "-").camelize
       ExisRay::Tracer.request_id   = SecureRandom.uuid
       ExisRay::Tracer.created_at   = Time.now.utc.to_f
 
@@ -46,10 +60,40 @@ module ExisRay
       ExisRay::Tracer.root_id = ExisRay::Tracer.send(:generate_new_root, pod_id)
     end
 
+    # Obtiene un identificador único del contenedor o máquina actual.
+    #
+    # @return [String] El sufijo del hostname o "local" por defecto.
     def self.get_pod_identifier
-      (ENV['HOSTNAME'] || 'local').split('-').last.to_s
+      (ENV["HOSTNAME"] || "local").split("-").last.to_s
+    end
+
+    # Ejecuta el bloque inyectando tags de Rails solo si estamos en modo texto.
+    # En modo JSON, JsonFormatter ya se encarga de inyectar el root_id.
+    #
+    # @yield El bloque de ejecución de la tarea.
+    # @return [void]
+    def self.execute_with_optional_tags
+      if !ExisRay.configuration.json_logs? && Rails.logger.respond_to?(:tagged)
+        Rails.logger.tagged(ExisRay::Tracer.root_id) { yield }
+      else
+        yield
+      end
+    end
+
+    # Envía un evento al logger de Rails adaptándose al formato configurado.
+    #
+    # @param level [Symbol] Nivel de severidad (:info, :error).
+    # @param message [String] Mensaje en texto plano para el modo clásico.
+    # @param payload [Hash] Datos estructurados para el modo JSON.
+    # @return [void]
+    def self.log_event(level, message, **payload)
+      if ExisRay.configuration.json_logs?
+        Rails.logger.send(level, payload.merge(message: "[ExisRay] #{message}"))
+      else
+        Rails.logger.send(level, "[ExisRay] #{message}")
+      end
     end
 
-    private_class_method :get_pod_identifier, :setup_tracer
+    private_class_method :get_pod_identifier, :setup_tracer, :execute_with_optional_tags, :log_event
   end
 end

data/lib/exis_ray/version.rb

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

data/lib/exis_ray.rb

@@ -13,6 +13,7 @@ require "exis_ray/task_monitor"
 require "exis_ray/http_middleware"
 require "exis_ray/current"
 require "exis_ray/reporter"
+require "exis_ray/json_formatter"
 
 # Integraciones Opcionales
 # Solo cargamos el middleware de Faraday si la gema está presente en el sistema.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-13 00:00:00.000000000 Z
+date: 2026-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: lograge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
 description: Gema que gestiona el contexto de request, logs y propagación de headers.
 email:
 - gab.edera@gmail.com
@@ -55,6 +69,7 @@ files:
 - lib/exis_ray/current.rb
 - lib/exis_ray/faraday_middleware.rb
 - lib/exis_ray/http_middleware.rb
+- lib/exis_ray/json_formatter.rb
 - lib/exis_ray/railtie.rb
 - lib/exis_ray/reporter.rb
 - lib/exis_ray/sidekiq/client_middleware.rb