bug_bunny 4.3.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67cd206fe5bbd998fd71e143d5b22972d841439115209a007223b776630ebf46
-  data.tar.gz: 6647fc999934cc49b636f32e50f8cdad8c21effd4005a8ff403b233498ee75af
+  metadata.gz: 3b9386a291d7b4a4b674279d75e3a10b9b89b184daa8992150fab59a873dd055
+  data.tar.gz: e5e0db15d748fc4fee5deb06fcabc7083555b5a90803b7b7e1e916fc4efd99d2
 SHA512:
-  metadata.gz: 1cc705a67bef35d982a2c2ed1117c70fc7dc14f79a6a4b9b70e8e7549f0d6db860070e0c6b85e859ef7239f7a322988d8d5054a0ef88e6a363faf911a87dd9d7
-  data.tar.gz: 7ba4187d186d391fb9e8b42da9d1e7c0a1656f059421a6249c8c3c2c45f1fcdeddf5070a0845245d0371e17250df0a83f674cf77eb188794e95d95e79103a9e3
+  metadata.gz: 57835a7bd1b1b437c655754c70cb5e3ddd38466f64a527317b82ddec47c524c67ad9c821758698b5b553d03f484dcbff5608faea4eb2dadc96975387044236d9
+  data.tar.gz: b0a435d8c309f8bbd7f9ac748d26c6961f718955ce09d06753c13e2b23ce77877510f6aa84702df315f4b012fc52f4e7910a7905695c2438c7fae396821324da

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [4.4.0] - 2026-03-24
+
+### 📈 Standard Observability Pattern
+* **Unified Observability Module:** Adopción del patrón de observabilidad estándar para todas las gemas.
+* **Semantic Event Naming:** Todos los eventos ahora siguen el formato `clase.evento` (ej: `consumer.message_processed`, `producer.publish`) para una mejor categorización.
+* **Resilient Logging:** Implementación de `@logger` en cada componente con el método `safe_log` para garantizar que la telemetría nunca interrumpa la ejecución principal.
+* **Full Documentation Sync:** Actualización del README con los nuevos ejemplos de uso del patrón de observabilidad.
+
 ## [4.3.0] - 2026-03-24
 
 ### 📈 Observability Alignment (ExisRay Standards)

data/README.md

@@ -4,201 +4,140 @@
 
 **Active Record over AMQP.**
 
-BugBunny transforma la complejidad de la mensajería asíncrona (RabbitMQ) en una arquitectura **RESTful familiar** para desarrolladores Rails. Envía mensajes como si estuvieras usando Active Record y procésalos como si fueran Controladores de Rails, apoyado por un potente motor de enrutamiento declarativo.
+BugBunny transforma la complejidad de la mensajería asíncrona (RabbitMQ) en una arquitectura familiar RESTful. Permite que tus microservicios se comuniquen como si fueran APIs locales, utilizando controladores, rutas y modelos con una interfaz idéntica a Active Record.
 
----
+## ✨ Características
 
-## 📖 Tabla de Contenidos
-- [Introducción: La Filosofía](#-introducción-la-filosofía)
-- [Instalación](#-instalación)
-- [Configuración Inicial](#-configuración-inicial)
-- [Configuración de Infraestructura en Cascada](#-configuración-de-infraestructura-en-cascada)
-- [Modo Cliente: Recursos (ORM)](#-modo-cliente-recursos-orm)
-    - [Definición y Atributos](#1-definición-y-atributos-híbridos)
-    - [CRUD y Consultas](#2-crud-y-consultas-restful)
-    - [Contexto Dinámico (.with)](#3-contexto-dinámico-with)
-    - [Client Middleware](#4-client-middleware-interceptores)
-- [Modo Servidor: Controladores](#-modo-servidor-controladores)
-    - [Ruteo Declarativo (Rutas)](#1-ruteo-declarativo-rutas)
-    - [El Controlador](#2-el-controlador)
-    - [Manejo de Errores](#3-manejo-de-errores-declarativo)
-- [Observabilidad y Tracing](#-observabilidad-y-tracing)
-- [Guía de Producción](#-guía-de-producción)
+*   **RESTful Routing:** Define tus endpoints AMQP con un DSL estilo Rails (`get`, `post`, `resources`).
+*   **Active Record Pattern:** Modela tus recursos remotos con validaciones, callbacks y tracking de cambios.
+*   **Middleware Stack:** Arquitectura de cebolla (Onion) para interceptar peticiones, manejar errores y transformar payloads.
+*   **RPC & Pub/Sub:** Soporta nativamente tanto peticiones síncronas (Request-Response) como publicaciones asíncronas.
+*   **Observabilidad de Clase Mundial:** Integración nativa con **ExisRay** (Tracing distribuido y Logs estructurados KV).
+*   **Resiliencia Enterprise:** Reconexión automática con Backoff Exponencial y Health Checks automáticos.
 
 ---
 
-## 💡 Introducción: La Filosofía
-
-En lugar de pensar en "Exchanges" y "Queues", BugBunny inyecta verbos HTTP (`GET`, `POST`, `PUT`, `DELETE`) y rutas (`users/1`) en los headers de AMQP.
-
-* **Tu código (Cliente):** `User.create(name: 'Gabi')`
-* **Protocolo (BugBunny):** Envía `POST /users` (Header `type: users`) vía RabbitMQ.
-* **Worker (Servidor):** Recibe el mensaje, evalúa tu mapa de rutas y ejecuta `UsersController#create`.
-
----
+## 🚀 Instalación
 
-## 📦 Instalación
-
-Agrega la gema a tu `Gemfile`:
+Añade esta línea al `Gemfile` de tu aplicación:
 
 ```ruby
-gem 'bug_bunny', '~> 4.0'
+gem 'bug_bunny'
 ```
 
-Ejecuta el bundle e instala los archivos base:
+Y luego ejecuta:
+```bash
+$ bundle install
+```
 
+O instálalo manualmente:
 ```bash
-bundle install
-rails g bug_bunny:install
+$ gem install bug_bunny
 ```
 
-Esto genera:
-1.  `config/initializers/bug_bunny.rb`
-2.  `app/rabbit/controllers/`
+Luego, genera el inicializador (en Rails):
+```bash
+$ rails generate bug_bunny:install
+```
 
 ---
 
-## ⚙️ Configuración Inicial
+## 🛠️ Configuración
 
-Para entornos productivos (Puma/Sidekiq), es **obligatorio** configurar un Pool de conexiones.
+Configura la conexión a RabbitMQ y las opciones globales:
 
 ```ruby
 # config/initializers/bug_bunny.rb
-
 BugBunny.configure do |config|
-  # 1. Credenciales
-  config.host     = ENV.fetch('RABBITMQ_HOST', 'localhost')
-  config.username = ENV.fetch('RABBITMQ_USER', 'guest')
-  config.password = ENV.fetch('RABBITMQ_PASS', 'guest')
-  config.vhost    = ENV.fetch('RABBITMQ_VHOST', '/')
-
-  # 2. Timeouts y Recuperación
-  config.rpc_timeout = 10               # Segundos máx para esperar respuesta (Síncrono)
-  config.network_recovery_interval = 5  # Base del backoff de reconexión (segundos)
-  config.max_reconnect_interval    = 60 # Techo del backoff exponencial (segundos)
-  config.max_reconnect_attempts    = nil # nil = reintenta infinitamente; Integer = falla hard
-
-  # 3. Health Checks (Opcional, para Docker Swarm / K8s)
-  config.health_check_file = '/tmp/bug_bunny_health'
-
-  # 4. Logging
-  config.logger = Rails.logger
-end
-
-# 5. Connection Pool (CRÍTICO para concurrencia)
-# Define un pool global para compartir conexiones entre hilos
-BUG_BUNNY_POOL = ConnectionPool.new(size: ENV.fetch('RAILS_MAX_THREADS', 5).to_i, timeout: 5) do
-  BugBunny.create_connection
+  config.host = ENV['RABBITMQ_HOST'] || '127.0.0.1'
+  config.port = 5672
+  config.username = 'guest'
+  config.password = 'guest'
+  
+  # Resiliencia
+  config.max_reconnect_attempts = 10      # Falla tras 10 intentos (útil en K8s)
+  config.max_reconnect_interval = 60      # Máximo 60s entre reintentos
+  config.network_recovery_interval = 5    # Intervalo base para backoff
+  
+  # Infraestructura por defecto (Nivel 2)
+  config.exchange_options = { durable: true }
 end
-
-# Inyecta el pool en los recursos
-BugBunny::Resource.connection_pool = BUG_BUNNY_POOL
 ```
 
 ---
 
-## 🏗️ Configuración de Infraestructura en Cascada
+## 📦 Uso como Modelo (Consumer + Producer)
 
-BugBunny utiliza un sistema de configuración jerárquico para los parámetros de RabbitMQ (como la durabilidad de Exchanges y Colas). Las opciones se resuelven en el siguiente orden de prioridad:
+BugBunny permite definir modelos que representan recursos en otros microservicios.
 
-1.  **Defaults de la Gema:** Rápidos y efímeros (`durable: false`).
-2.  **Configuración Global:** Definida en el inicializador para todo el entorno.
-3.  **Configuración de Recurso:** Atributos de clase en modelos específicos.
-4.  **Configuración al Vuelo:** Parámetros pasados en la llamada `.with` o en el Cliente manual.
+```ruby
+class RemoteNode < BugBunny::Resource
+  # Configuración del canal
+  self.exchange = 'inventory_exchange'
+  self.resource_name = 'nodes' # Equivale al path de la URL
 
-**Ejemplo de Configuración Global (Nivel 2):**
-Útil para hacer que todos los recursos en el entorno de pruebas sean auto-borrables.
+  # Atributos (ActiveRecord style)
+  attribute :name, :string
+  attribute :status, :string
+  attribute :cpu_cores, :integer
 
-```ruby
-# config/initializers/bug_bunny.rb
-BugBunny.configure do |config|
-  if Rails.env.test?
-    config.exchange_options = { auto_delete: true }
-    config.queue_options    = { auto_delete: true }
-  end
+  # Validaciones
+  validates :name, presence: true
 end
+
+# Uso:
+node = RemoteNode.find('node-123')
+node.status = 'active'
+node.save # Realiza un PUT a inventory_exchange con routing_key 'nodes.node-123'
 ```
 
 ---
 
-## 🚀 Modo Cliente: Recursos (ORM)
+## 🛣️ Enrutamiento y Controladores (Server side)
 
-Los recursos son proxies de servicios remotos. Heredan de `BugBunny::Resource`.
-
-### 1. Definición y Atributos Híbridos
-BugBunny es **Schema-less**. Soporta atributos tipados (ActiveModel) y dinámicos simultáneamente, además de definir su propia infraestructura.
+Define cómo debe responder tu aplicación a los mensajes entrantes:
 
 ```ruby
-# app/models/manager/service.rb
-class Manager::Service < BugBunny::Resource
-  # Configuración de Transporte
-  self.exchange = 'cluster_events'
-  self.exchange_type = 'topic'
-
-  # Configuración de Infraestructura Específica (Nivel 3)
-  # Este recurso crítico sobrevivirá a reinicios del servidor RabbitMQ
-  self.exchange_options = { durable: true, auto_delete: false }
-
-  # Configuración de Ruteo (La "URL" base)
-  self.resource_name = 'services'
+# config/rabbit_routes.rb
+BugBunny.routes.draw do
+  resources :nodes do
+    member do
+      put :drain
+    end
+  end
+end
 
-  # A. Atributos Tipados (Opcional, para casting)
-  attribute :created_at, :datetime
-  attribute :replicas, :integer, default: 1
+# app/rabbit/controllers/nodes_controller.rb
+module Rabbit
+  module Controllers
+    class NodesController < BugBunny::Controller
+      def index
+        nodes = Node.all # Lógica local de tu app
+        render status: :ok, json: nodes
+      end
 
-  # B. Validaciones (Funcionan en ambos tipos)
-  validates :name, presence: true
+      def drain
+        # El ID viene automáticamente en params[:id]
+        Node.find(params[:id]).start_drain_process!
+        render status: :accepted, json: { message: "Draining started" }
+      end
+    end
+  end
 end
 ```
 
-### 2. CRUD y Consultas RESTful
+---
 
-```ruby
-# --- LEER (GET) ---
-# RPC: Espera respuesta del worker.
-# Envia: GET services/123
-service = Manager::Service.find('123')
-
-# --- BÚSQUEDAS AVANZADAS ---
-# Soporta Hashes anidados para filtros complejos.
-# Envia: GET services?q[status]=active&q[tags][]=web
-Manager::Service.where(q: { status: 'active', tags: ['web'] })
-
-# --- CREAR (POST) ---
-# RPC: Envía payload y espera el objeto persistido.
-# Payload: { "service": { "name": "nginx", "replicas": 3 } }
-svc = Manager::Service.create(name: 'nginx', replicas: 3)
-
-# --- ACTUALIZAR (PUT) ---
-# Dirty Tracking: Solo envía los campos que cambiaron.
-svc.name = 'nginx-pro'
-svc.save
-
-# --- ELIMINAR (DELETE) ---
-svc.destroy
-```
+## 🔌 Middlewares
 
-### 3. Contexto Dinámico (`.with`)
-Puedes sobrescribir la configuración de enrutamiento o infraestructura para una ejecución específica sin afectar al modelo global (Thread-Safe).
+Puedes extender el comportamiento del cliente globalmente o por recurso:
 
 ```ruby
-# Nivel 4: Configuración al vuelo. Inyectamos opciones solo para esta llamada.
-Manager::Service.with(
-  routing_key: 'high_priority',
-  exchange_options: { durable: false } # Ignora el durable: true de la clase
-).create(name: 'redis_temp')
-```
-
-### 4. Client Middleware (Interceptores)
-Intercepta peticiones de ida y respuestas de vuelta en la arquitectura del cliente.
-
-**Middlewares Incluidos (Built-ins)**
-Si usas `BugBunny::Resource`, el manejo de JSON y de errores ya está integrado automáticamente. Pero si utilizas el cliente manual (`BugBunny::Client`), puedes inyectar los middlewares incluidos para no tener que parsear respuestas manualmente:
-
-* `BugBunny::Middleware::JsonResponse`: Parsea automáticamente el cuerpo de la respuesta de JSON a un Hash de Ruby.
-* `BugBunny::Middleware::RaiseError`: Evalúa el código de estado (`status`) de la respuesta y lanza excepciones nativas (`BugBunny::NotFound`, `BugBunny::UnprocessableEntity`, `BugBunny::InternalServerError`, etc.).
+# Globalmente en el inicializador
+BugBunny.configure do |config|
+  # ...
+end
 
-```ruby
 # Uso con el cliente manual
 client = BugBunny::Client.new(pool: BUG_BUNNY_POOL) do |stack|
   stack.use BugBunny::Middleware::RaiseError
@@ -230,116 +169,47 @@ response = client.request('users/1', method: :get)
 ```
 
 **Middlewares Personalizados**
-Ideales para inyectar Auth o Headers de trazabilidad en todos los requests de un Recurso.
-
-```ruby
-class Manager::Service < BugBunny::Resource
-  client_middleware do |stack|
-    stack.use(Class.new(BugBunny::Middleware::Base) do
-      def on_request(env)
-        env.headers['Authorization'] = "Bearer #{ENV['API_TOKEN']}"
-        env.headers['X-App-Version'] = '1.0.0'
-      end
-    end)
-  end
-end
-```
-
-**Personalización Avanzada de Errores**
-Si en tu aplicación necesitas mapear códigos HTTP de negocio (ej. `402 Payment Required`) a excepciones personalizadas, la forma más limpia es usar `Module#prepend` sobre el middleware nativo en un inicializador. De esta forma inyectas tus reglas sin perder el comportamiento por defecto para los demás errores:
 
 ```ruby
-# config/initializers/bug_bunny_custom_errors.rb
-module CustomBugBunnyErrors
-  def on_complete(response)
-    status = response['status'].to_i
-
-    # 1. Reglas específicas de tu negocio
-    if status == 402
-      raise MyApp::PaymentRequiredError, response['body']['message']
-    elsif status == 403 && response['body']['reason'] == 'ip_blocked'
-      raise MyApp::IpBlockedError, response['body']['detail']
-    end
-
-    # 2. Delegar el resto de los errores (404, 422, 500) al middleware original
-    super(response)
+class MyCustomMiddleware < BugBunny::Middleware::Base
+  def call(request)
+    puts "Enviando mensaje a: #{request.path}"
+    app.call(request)
   end
 end
-
-BugBunny::Middleware::RaiseError.prepend(CustomBugBunnyErrors)
 ```
 
 ---
 
-## 📡 Modo Servidor: Controladores
-
-A partir de BugBunny v4, el enrutamiento es **declarativo** y explícito, al igual que en Rails. Se utiliza un archivo de rutas centralizado para mapear los mensajes AMQP entrantes a los Controladores adecuados.
-
-### 1. Ruteo Declarativo (Rutas)
-Crea un inicializador en tu aplicación (ej. `config/initializers/bug_bunny_routes.rb`) para definir tu mapa de rutas. BugBunny usará este DSL para extraer automáticamente parámetros dinámicos de las URLs.
+## 🔎 Observabilidad y Tracing
 
-```ruby
-# config/initializers/bug_bunny_routes.rb
+BugBunny implementa Distributed Tracing nativo y sigue los estándares de observabilidad de **ExisRay** para logs estructurados.
 
-BugBunny.routes.draw do
-  # 1. Colecciones Básicas y Filtrado
-  # Genera rutas para index, show y update únicamente
-  resources :services, only: [:index, :show, :update]
+### 1. Logs Estructurados (Key-Value)
+A partir de la v4.3.0, todos los logs internos de la gema utilizan un formato `key=value` optimizado para motores de logs (CloudWatch, Datadog, ELK).
 
-  # 2. Rutas Anidadas (Member y Collection)
-  resources :nodes, except: [:create, :destroy] do
-    # Member inyecta el parámetro :id (ej. PUT nodes/:id/drain)
-    member do
-      put :drain
-      post :restart
-    end
+*   **Data First:** Las unidades están en la llave (`_s`, `_ms`, `_count`), permitiendo que los valores sean números puros para agregaciones automáticas.
+*   **Reloj Monotónico:** Las duraciones (`duration_s`) se calculan con precisión de microsegundos usando el reloj monotónico del sistema.
+*   **Campos de Identidad:** Todos los logs incluyen `component=bug_bunny` y un `event` semántico.
 
-    # Collection opera sobre el conjunto (ej. GET nodes/stats)
-    collection do
-      get :stats
-    end
-  end
+**Ejemplos de Logs:**
+```text
+# Mensaje procesado con éxito (incluye duración y status numérico)
+component=bug_bunny event=consumer.message_processed status=200 duration_s=0.015432 controller=UsersController action=show
 
-  # 3. Rutas estáticas (Colecciones o Acciones Custom)
-  get 'health_checks/up', to: 'health_checks#up'
+# Error de ejecución (campos estandarizados)
+component=bug_bunny event=consumer.execution_error error_class=NoMethodError error_message="undefined method..." duration_s=0.008123
 
-  # 4. Extracción automática de variables dinámicas profundas
-  get 'api/v1/clusters/:cluster_id/nodes/:node_id/metrics', to: 'api/v1/metrics#show'
-end
+# Reintento de conexión con backoff (sufijos de unidad)
+component=bug_bunny event=consumer.connection_error error_message="..." attempt_count=3 retry_in_s=20
 ```
 
-### 2. El Controlador
-Ubicación: `app/rabbit/controllers/`.
-Los parámetros declarados en el archivo de rutas (como `:id` o `:cluster_id`) estarán disponibles automáticamente dentro del hash `params` de tu controlador.
-
-```ruby
-class ServicesController < BugBunny::Controller
-  # Callbacks estándar
-  before_action :set_service, only: [:show, :update]
-
-  def show
-    # Renderiza JSON que viajará de vuelta por la cola reply-to
-    render status: 200, json: { id: @service.id, state: 'running' }
-  end
-
-  def create
-    # BugBunny envuelve los params automáticamente basándose en el resource_name
-    # params[:service] => { name: '...', replicas: ... }
-    if Service.create(params[:service])
-      render status: 201, json: { status: 'created' }
-    else
-      render status: 422, json: { errors: 'Invalid' }
-    end
-  end
-
-  private
+**Ventaja en Cloud:**
+Al usar `duration_s` como un float puro, puedes realizar consultas analíticas directamente en tu motor de logs sin parsear strings:
+`stats avg(duration_s), max(duration_s) by controller, action`
 
-  def set_service
-    # params[:id] es extraído e inyectado por el BugBunny.routes
-    @service = Service.find(params[:id])
-  end
-end
-```
+### 2. Distributed Tracing
+El `correlation_id` se mantiene intacto a través de toda la cadena: `Producer -> RabbitMQ -> Consumer -> Controller`.
 
 ### 3. Manejo de Errores Declarativo
 Captura excepciones y devuélvelas como códigos de estado AMQP/HTTP.
@@ -351,7 +221,7 @@ class ApplicationController < BugBunny::Controller
   end
 
   rescue_from StandardError do |e|
-    BugBunny.configuration.logger.error(e)
+    safe_log(:error, "application.crash", **exception_metadata(e))
     render status: :internal_server_error, json: { error: "Crash" }
   end
 end
@@ -359,124 +229,6 @@ end
 
 ---
 
-## 🔎 Observabilidad y Tracing
-
-BugBunny implementa Distributed Tracing nativo. El `correlation_id` se mantiene intacto a través de toda la cadena: `Producer -> RabbitMQ -> Consumer -> Controller`.
-
-### 1. Logs Automáticos (Consumer)
-No requiere configuración. El worker envuelve la ejecución en bloques de log etiquetados con el UUID.
-
-```text
-[d41d8cd9...] [BugBunny::Consumer] 📥 Received PUT "/nodes/4bv445vgc158hk" | RK: 'dbu55...'
-[d41d8cd9...] [BugBunny::Consumer] 🎯 Routed to Rabbit::Controllers::NodesController#drain
-```
-
-### 2. Logs de Negocio (Controller)
-Inyecta contexto rico (Tenant, Usuario, IP) en los logs usando `log_tags`.
-
-```ruby
-# app/rabbit/controllers/application_controller.rb
-class ApplicationController < BugBunny::Controller
-  self.log_tags = [
-    ->(c) { c.params[:tenant_id] }, # Agrega [Tenant-55]
-    ->(c) { c.headers['X-Source'] } # Agrega [Console]
-  ]
-end
-```
-
-### 3. Inyección en el Productor
-Para que tus logs de Rails y Rabbit coincidan, usa un middleware global:
-
-```ruby
-# config/initializers/bug_bunny.rb
-# Middleware para inyectar Current.request_id de Rails al mensaje Rabbit
-class CorrelationInjector < BugBunny::Middleware::Base
-  def on_request(env)
-    env.correlation_id = Current.request_id if defined?(Current)
-  end
-end
-
-BugBunny::Client.prepend(Module.new {
-  def initialize(pool:)
-    super
-    @stack.use CorrelationInjector
-  end
-})
-```
-
----
-
-## 🧵 Guía de Producción
-
-### Connection Pooling
-Es vital usar `ConnectionPool` si usas servidores web multi-hilo (Puma) o workers (Sidekiq). BugBunny no gestiona hilos internamente; se apoya en el pool.
-
-### Fork Safety
-BugBunny incluye un `Railtie` que detecta automáticamente cuando Rails hace un "Fork" (ej: Puma en modo Cluster o Spring). Desconecta automáticamente las conexiones heredadas para evitar corrupción de datos en los sockets TCP.
-
-### RPC y "Direct Reply-To"
-Para máxima velocidad, BugBunny usa `amq.rabbitmq.reply-to`.
-* **Trade-off:** Si el cliente (Rails) se reinicia justo después de enviar un mensaje RPC pero antes de recibir la respuesta, esa respuesta se pierde.
-* **Recomendación:** Diseña tus acciones RPC (`POST`, `PUT`) para que sean **idempotentes** (seguras de reintentar ante un timeout).
-
-### Seguridad
-El Router incluye protecciones contra **Remote Code Execution (RCE)**. El Consumer verifica estrictamente que el Controlador resuelto a través del archivo de rutas herede de `BugBunny::Controller` antes de ejecutarla, impidiendo la inyección de clases arbitrarias. Además, las llamadas a rutas no registradas fallan rápido con un `404 Not Found`.
-
-### Reconexión con Backoff Exponencial
-
-Cuando el Consumer pierde la conexión a RabbitMQ, reintenta automáticamente usando un backoff exponencial basado en `network_recovery_interval`:
-
-| Intento | Espera (base = 5s, techo = 60s) |
-|---------|----------------------------------|
-| 1       | 5s                               |
-| 2       | 10s                              |
-| 3       | 20s                              |
-| 4       | 40s                              |
-| 5+      | 60s (cap)                        |
-
-Por defecto reintenta indefinidamente (`max_reconnect_attempts: nil`). En entornos orquestados (Kubernetes, Docker Swarm), es preferible dejar que el orquestador reinicie el contenedor cuando la infraestructura no está disponible:
-
-```ruby
-BugBunny.configure do |config|
-  config.network_recovery_interval = 5   # Base del backoff
-  config.max_reconnect_interval    = 60  # Techo máximo de espera
-  config.max_reconnect_attempts    = 10  # Falla hard después de 10 intentos
-end
-```
-
-Con esta configuración, si RabbitMQ no vuelve en ~10 reintentos el proceso levanta la excepción y el orquestador lo reinicia con su propia política de restart.
-
-### Health Checks en Docker Swarm / Kubernetes
-Dado que un Worker se ejecuta en segundo plano sin exponer un servidor web tradicional, orquestadores como Docker Swarm o Kubernetes no pueden usar un endpoint HTTP para verificar si el proceso está saludable.
-
-BugBunny implementa el patrón **Touchfile**. Puedes configurar la gema para que actualice la fecha de modificación de un archivo temporal en cada latido exitoso (heartbeat) hacia RabbitMQ.
-
-**1. Configurar la gema:**
-```ruby
-# config/initializers/bug_bunny.rb
-BugBunny.configure do |config|
-  # Actualizará la fecha de este archivo si la conexión a la cola está sana
-  config.health_check_file = '/tmp/bug_bunny_health'
-end
-```
-
-**2. Configurar el Orquestador (Ejemplo docker-compose.yml):**
-Con esta configuración, Docker Swarm verificará que el archivo haya sido modificado (tocado) en los últimos 15 segundos. Si el worker se bloquea o pierde la conexión de manera irrecuperable, Docker reiniciará el contenedor automáticamente.
-
-```yaml
-services:
-  worker:
-    image: my_rails_app
-    command: bundle exec rake bug_bunny:work
-    healthcheck:
-      test: ["CMD-SHELL", "test $$(expr $$(date +%s) - $$(stat -c %Y /tmp/bug_bunny_health)) -lt 15 || exit 1"]
-      interval: 10s
-      timeout: 5s
-      retries: 3
-```
-
----
-
 ## 📄 Licencia
 
 Código abierto bajo [MIT License](https://opensource.org/licenses/MIT).

data/lib/bug_bunny/consumer.rb

@@ -27,6 +27,8 @@ module BugBunny
   #     routing_key: 'users.#'
   #   )
   class Consumer
+    include BugBunny::Observability
+
     # @return [BugBunny::Session] La sesión wrapper de RabbitMQ que gestiona el canal.
     attr_reader :session
 
@@ -45,6 +47,7 @@ module BugBunny
     def initialize(connection)
       @session = BugBunny::Session.new(connection, publisher_confirms: false)
       @health_timer = nil
+      @logger = BugBunny.configuration.logger
     end
 
     # Inicia la suscripción a la cola y comienza el bucle de procesamiento.
@@ -77,8 +80,8 @@ module BugBunny
                          .merge(BugBunny.configuration.queue_options || {})
                          .merge(queue_opts || {})
 
-        BugBunny.configuration.logger.info("component=bug_bunny event=consumer_start queue=#{queue_name} queue_opts=#{final_q_opts}")
-        BugBunny.configuration.logger.info("component=bug_bunny event=consumer_bound exchange=#{exchange_name} exchange_type=#{exchange_type} routing_key=#{routing_key} exchange_opts=#{final_x_opts}")
+        safe_log(:info, "consumer.start", queue: queue_name, queue_opts: final_q_opts)
+        safe_log(:info, "consumer.bound", exchange: exchange_name, exchange_type: exchange_type, routing_key: routing_key, exchange_opts: final_x_opts)
 
         start_health_check(queue_name)
 
@@ -100,7 +103,7 @@ module BugBunny
         max_attempts = BugBunny.configuration.max_reconnect_attempts
 
         if max_attempts && attempt >= max_attempts
-          BugBunny.configuration.logger.error { "component=bug_bunny event=reconnect_exhausted max_attempts_count=#{max_attempts} error_message=#{e.message.inspect}" }
+          safe_log(:error, "consumer.reconnect_exhausted", max_attempts_count: max_attempts, **exception_metadata(e))
           raise
         end
 
@@ -109,7 +112,7 @@ module BugBunny
           BugBunny.configuration.max_reconnect_interval
         ].min
 
-        BugBunny.configuration.logger.error { "component=bug_bunny event=connection_error error_message=#{e.message.inspect} attempt_count=#{attempt} max_attempts_count=#{max_attempts || 'infinity'} retry_in_s=#{wait}" }
+        safe_log(:error, "consumer.connection_error", attempt_count: attempt, max_attempts_count: max_attempts || 'infinity', retry_in_s: wait, **exception_metadata(e))
         sleep wait
         retry
       end
@@ -132,7 +135,7 @@ module BugBunny
       path = properties.type || (properties.headers && properties.headers['path'])
 
       if path.nil? || path.empty?
-        BugBunny.configuration.logger.error('component=bug_bunny event=message_rejected reason=missing_type_header')
+        safe_log(:error, "consumer.message_rejected", reason: :missing_type_header)
         session.channel.reject(delivery_info.delivery_tag, false)
         return
       end
@@ -141,8 +144,8 @@ module BugBunny
       headers_hash = properties.headers || {}
       http_method = (headers_hash['x-http-method'] || headers_hash['method'] || 'GET').to_s.upcase
 
-      BugBunny.configuration.logger.info("component=bug_bunny event=message_received method=#{http_method} path=#{path} routing_key=#{delivery_info.routing_key}")
-      BugBunny.configuration.logger.debug { "component=bug_bunny event=message_received_body body=#{body.truncate(200).inspect}" }
+      safe_log(:info, "consumer.message_received", method: http_method, path: path, routing_key: delivery_info.routing_key)
+      safe_log(:debug, "consumer.message_received_body", body: body.truncate(200))
 
       # ===================================================================
       # 3. Ruteo Declarativo
@@ -159,7 +162,7 @@ module BugBunny
       route_info = BugBunny.routes.recognize(http_method, uri.path)
 
       if route_info.nil?
-        BugBunny.configuration.logger.warn("component=bug_bunny event=route_not_found method=#{http_method} path=#{uri.path}")
+        safe_log(:warn, "consumer.route_not_found", method: http_method, path: uri.path)
         handle_fatal_error(properties, 404, "Not Found", "No route matches [#{http_method}] \"/#{uri.path}\"")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
@@ -178,7 +181,7 @@ module BugBunny
       begin
         controller_class = controller_class_name.constantize
       rescue NameError
-        BugBunny.configuration.logger.warn("component=bug_bunny event=controller_not_found controller=#{controller_class_name}")
+        safe_log(:warn, "consumer.controller_not_found", controller: controller_class_name)
         handle_fatal_error(properties, 404, "Not Found", "Controller #{controller_class_name} not found")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
@@ -186,13 +189,13 @@ module BugBunny
 
       # Verificación estricta de Seguridad (RCE Prevention)
       unless controller_class < BugBunny::Controller
-        BugBunny.configuration.logger.error("component=bug_bunny event=security_violation reason=invalid_controller controller=#{controller_class}")
+        safe_log(:error, "consumer.security_violation", reason: :invalid_controller, controller: controller_class)
         handle_fatal_error(properties, 403, "Forbidden", "Invalid Controller Class")
         session.channel.reject(delivery_info.delivery_tag, false)
         return
       end
 
-      BugBunny.configuration.logger.debug { "component=bug_bunny event=route_matched controller=#{controller_class_name} action=#{route_info[:action]}" }
+      safe_log(:debug, "consumer.route_matched", controller: controller_class_name, action: route_info[:action])
 
       request_metadata = {
         type: path,
@@ -217,13 +220,15 @@ module BugBunny
 
       session.channel.ack(delivery_info.delivery_tag)
 
-      duration_s = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time).round(6)
-      BugBunny.configuration.logger.info("component=bug_bunny event=message_processed status=#{response_payload[:status]} duration_s=#{duration_s} controller=#{controller_class_name} action=#{route_info[:action]}")
+      safe_log(:info, "consumer.message_processed",
+               status: response_payload[:status],
+               duration_s: duration_s(start_time),
+               controller: controller_class_name,
+               action: route_info[:action])
 
     rescue StandardError => e
-      duration_s = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time).round(6)
-      BugBunny.configuration.logger.error { "component=bug_bunny event=execution_error error_class=#{e.class} error_message=#{e.message.inspect} duration_s=#{duration_s}" }
-      BugBunny.configuration.logger.debug { "component=bug_bunny event=execution_error backtrace=#{e.backtrace.first(5).join(' | ').inspect}" }
+      safe_log(:error, "consumer.execution_error", duration_s: duration_s(start_time), **exception_metadata(e))
+      safe_log(:debug, "consumer.execution_error_backtrace", backtrace: e.backtrace.first(5).join(' | '))
       handle_fatal_error(properties, 500, "Internal Server Error", e.message)
       session.channel.reject(delivery_info.delivery_tag, false)
     end
@@ -235,7 +240,7 @@ module BugBunny
     # @param correlation_id [String] ID para correlacionar la respuesta con la petición original.
     # @return [void]
     def reply(payload, reply_to, correlation_id)
-      BugBunny.configuration.logger.debug { "component=bug_bunny event=rpc_reply reply_to=#{reply_to} correlation_id=#{correlation_id}" }
+      safe_log(:debug, "consumer.rpc_reply", reply_to: reply_to, correlation_id: correlation_id)
       session.channel.default_exchange.publish(
         payload.to_json,
         routing_key: reply_to,
@@ -284,7 +289,7 @@ module BugBunny
         # 2. Si llegamos aquí, RabbitMQ y la cola están vivos. Avisamos al orquestador actualizando el archivo.
         touch_health_file(file_path) if file_path
       rescue StandardError => e
-        BugBunny.configuration.logger.warn("component=bug_bunny event=health_check_failed queue=#{q_name} error_message=#{e.message.inspect}")
+        safe_log(:warn, "consumer.health_check_failed", queue: q_name, **exception_metadata(e))
         session.close
       end
       @health_timer.execute
@@ -299,7 +304,7 @@ module BugBunny
     def touch_health_file(file_path)
       FileUtils.touch(file_path)
     rescue StandardError => e
-      BugBunny.configuration.logger.error("component=bug_bunny event=health_check_file_error path=#{file_path} error_message=#{e.message.inspect}")
+      safe_log(:error, "consumer.health_check_file_error", path: file_path, **exception_metadata(e))
     end
   end
 end

data/lib/bug_bunny/controller.rb

@@ -19,6 +19,7 @@ module BugBunny
   class Controller
     include ActiveModel::Model
     include ActiveModel::Attributes
+    include BugBunny::Observability
 
     # @!group Atributos de Instancia
 
@@ -128,6 +129,7 @@ module BugBunny
     def initialize(attributes = {})
       super
       @response_headers = {}
+      @logger = BugBunny.configuration.logger
     end
 
     # Punto de entrada principal estático llamado por el Router (`BugBunny::Consumer`).
@@ -204,8 +206,7 @@ module BugBunny
       end
 
       # Fallback genérico si la excepción no fue mapeada
-      BugBunny.configuration.logger.error { "component=bug_bunny event=unhandled_exception error_class=#{exception.class} error_message=#{exception.message.inspect}" }
-      BugBunny.configuration.logger.error { "component=bug_bunny event=unhandled_exception backtrace=#{exception.backtrace.first(5).join(' | ').inspect}" }
+      safe_log(:error, "controller.unhandled_exception", backtrace: exception.backtrace.first(5).join(" | "), **exception_metadata(exception))
 
       {
         status: 500,

data/lib/bug_bunny/observability.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BugBunny
+  # @api private
+  module Observability
+    private
+
+    # Registra un evento estructurado. Nunca eleva excepciones.
+    #
+    # @param level    [Symbol]       Nivel de log (:debug, :info, :warn, :error)
+    # @param event    [String]       Nombre del evento en formato "clase.evento"
+    # @param metadata [Hash]         Pares clave-valor adicionales
+    def safe_log(level, event, metadata = {})
+      return unless @logger
+
+      fields = { component: observability_name, event: event }.merge(metadata)
+
+      log_line = fields.map do |k, v|
+        val = %i[password token secret api_key auth].include?(k.to_sym) ? "[FILTERED]" : v
+        next if val.nil?
+
+        formatted = case val
+                    when Numeric then val
+                    when String  then val.include?(" ") ? val.inspect : val
+                    else val.to_s.include?(" ") ? val.to_s.inspect : val
+                    end
+        "#{k}=#{formatted}"
+      end.compact.join(" ")
+
+      @logger.send(level) { log_line }
+    rescue StandardError
+    end
+
+    # Genera metadatos estándar para una excepción.
+    #
+    # @param error [Exception] El objeto de error capturado.
+    # @return [Hash] Hash con error_class y error_message truncado.
+    def exception_metadata(error)
+      {
+        error_class: error.class.name,
+        error_message: error.message.gsub('"', "'")[0, 200]
+      }
+    end
+
+    # Timestamp del reloj monotónico para calcular duraciones.
+    #
+    # @return [Float] Tiempo actual del reloj monotónico.
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Duración en segundos desde un tiempo de inicio.
+    #
+    # @param start [Float] Valor devuelto por monotonic_now
+    # @return [Float] Duración en segundos redondeada a 6 decimales.
+    def duration_s(start)
+      (monotonic_now - start).round(6)
+    end
+
+    # Infiere el nombre del componente desde el namespace de la clase.
+    # Ejemplo: BugBunny::Consumer → "bug_bunny"
+    #
+    # @return [String] Nombre del componente en snake_case.
+    def observability_name
+      klass = is_a?(Class) ? self : self.class
+      klass.name.split("::").first.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    rescue StandardError
+      "unknown"
+    end
+  end
+end

data/lib/bug_bunny/producer.rb

@@ -13,6 +13,8 @@ module BugBunny
   # 3. Implementar el patrón RPC síncrono utilizando futuros (`Concurrent::IVar`).
   # 4. Gestionar la escucha de respuestas en la cola especial de RabbitMQ.
   class Producer
+    include BugBunny::Observability
+
     # Inicializa el productor.
     #
     # Prepara las estructuras de concurrencia necesarias para manejar múltiples
@@ -21,6 +23,7 @@ module BugBunny
     # @param session [BugBunny::Session] Sesión activa de Bunny (wrapper).
     def initialize(session)
       @session = session
+      @logger = BugBunny.configuration.logger
       # Mapa thread-safe para correlacionar IDs de petición con sus futuros (IVars)
       @pending_requests = Concurrent::Map.new
       @reply_listener_mutex = Mutex.new
@@ -73,7 +76,7 @@ module BugBunny
       begin
         fire(request)
 
-        BugBunny.configuration.logger.debug { "component=bug_bunny event=rpc_waiting correlation_id=#{cid} timeout_s=#{wait_timeout}" }
+        safe_log(:debug, "producer.rpc_waiting", correlation_id: cid, timeout_s: wait_timeout)
 
         # Bloqueamos el hilo aquí hasta que llegue la respuesta o expire el timeout
         response_payload = future.value(wait_timeout)
@@ -106,9 +109,9 @@ module BugBunny
                        .merge(BugBunny.configuration.exchange_options || {})
                        .merge(request.exchange_options || {})
 
-      BugBunny.configuration.logger.info("component=bug_bunny event=publish method=#{verb} path=#{target} routing_key=#{rk} correlation_id=#{id}")
-      BugBunny.configuration.logger.debug { "component=bug_bunny event=publish_detail exchange=#{request.exchange} exchange_opts=#{final_x_opts}" }
-      BugBunny.configuration.logger.debug { "component=bug_bunny event=publish_payload payload=#{payload.truncate(300).inspect}" } if payload.is_a?(String)
+      safe_log(:info, "producer.publish", method: verb, path: target, routing_key: rk, correlation_id: id)
+      safe_log(:debug, "producer.publish_detail", exchange: request.exchange, exchange_opts: final_x_opts)
+      safe_log(:debug, "producer.publish_payload", payload: payload.truncate(300)) if payload.is_a?(String)
     end
 
     # Serializa el mensaje para su transporte.
@@ -142,16 +145,16 @@ module BugBunny
       @reply_listener_mutex.synchronize do
         return if @reply_listener_started
 
-        BugBunny.configuration.logger.debug { 'component=bug_bunny event=reply_listener_start queue=amq.rabbitmq.reply-to' }
+        safe_log(:debug, "producer.reply_listener_start")
 
         # Consumimos sin ack (auto-ack) porque reply-to no soporta acks manuales de forma estándar
         @session.channel.basic_consume('amq.rabbitmq.reply-to', '', true, false, nil) do |_, props, body|
           cid = props.correlation_id.to_s
-          BugBunny.configuration.logger.debug { "component=bug_bunny event=rpc_response_received correlation_id=#{cid}" }
+          safe_log(:debug, "producer.rpc_response_received", correlation_id: cid)
           if (future = @pending_requests[cid])
             future.set(body)
           else
-            BugBunny.configuration.logger.warn("component=bug_bunny event=rpc_response_orphaned correlation_id=#{cid}")
+            safe_log(:warn, "producer.rpc_response_orphaned", correlation_id: cid)
           end
         end
         @reply_listener_started = true

data/lib/bug_bunny/session.rb

@@ -8,6 +8,7 @@ module BugBunny
   #
   # @api private
   class Session
+    include BugBunny::Observability
     # @!group Opciones por Defecto (Nivel 1: Gema)
 
     # Opciones predeterminadas de la gema para Exchanges.
@@ -31,6 +32,7 @@ module BugBunny
       @connection = connection
       @publisher_confirms = publisher_confirms
       @channel = nil
+      @logger = BugBunny.configuration.logger
     end
 
     # Obtiene el canal actual o crea uno nuevo si es necesario.
@@ -125,10 +127,10 @@ module BugBunny
     def ensure_connection!
       return if @connection.open?
 
-      BugBunny.configuration.logger.warn('component=bug_bunny event=reconnect_attempt')
+      safe_log(:warn, "session.reconnect_attempt")
       @connection.start
     rescue StandardError => e
-      BugBunny.configuration.logger.error { "component=bug_bunny event=reconnect_failed error_message=#{e.message.inspect}" }
+      safe_log(:error, "session.reconnect_failed", **exception_metadata(e))
       raise BugBunny::CommunicationError, "Could not reconnect to RabbitMQ: #{e.message}"
     end
   end

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = "4.3.0"
+  VERSION = "4.4.0"
 end

data/lib/bug_bunny.rb

@@ -5,6 +5,7 @@ require 'logger'
 require_relative 'bug_bunny/version'
 require_relative 'bug_bunny/exception'
 require_relative 'bug_bunny/configuration'
+require_relative 'bug_bunny/observability'
 require_relative 'bug_bunny/routing/route_set'
 require_relative 'bug_bunny/middleware/base'
 require_relative 'bug_bunny/middleware/stack'
@@ -22,6 +23,9 @@ require_relative 'bug_bunny/railtie' if defined?(Rails)
 # Módulo principal de la gema BugBunny.
 # Actúa como espacio de nombres y punto de configuración global.
 module BugBunny
+  extend BugBunny::Observability
+  private_class_method :safe_log, :exception_metadata, :observability_name
+
   class << self
     # @return [BugBunny::Configuration] La configuración global actual.
     attr_accessor :configuration
@@ -83,7 +87,9 @@ module BugBunny
 
     @global_connection.close if @global_connection.open?
     @global_connection = nil
-    configuration.logger.info('component=bug_bunny event=disconnect')
+    
+    @logger = configuration.logger
+    safe_log(:info, "bug_bunny.disconnect")
   end
 
   # @api private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 4.4.0
 platform: ruby
 authors:
 - gabix
@@ -243,6 +243,7 @@ files:
 - lib/bug_bunny/middleware/json_response.rb
 - lib/bug_bunny/middleware/raise_error.rb
 - lib/bug_bunny/middleware/stack.rb
+- lib/bug_bunny/observability.rb
 - lib/bug_bunny/producer.rb
 - lib/bug_bunny/railtie.rb
 - lib/bug_bunny/request.rb