exis_ray 0.5.7 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa3229011d1a59fbd0d65ec137d7a5223f70bd3c3f69add47c27bc965a3e62f1
-  data.tar.gz: f08f78169685640fc2c6f1dbfb51c5e64826e4e776c4c1b66ee5d4196592697d
+  metadata.gz: f17193f5df75197d569fbe74d8b27e55b116e861bdb819f1e92526a1da79869e
+  data.tar.gz: e8e45998cb83236c3bb7cc3a981995ccd36764fdb6fbc1465e796a7966e3b354
 SHA512:
-  metadata.gz: cc5941334d4f7a7241ba6629d5e27f08ac93ce6e704aaa31b90868a5353ff92143795b3b21cb6426d6b47172fa457de3e834899212b9b8ef1a8b28c4a1d81895
-  data.tar.gz: 3d9113cc7e2ed5790723290ff9c635b15bb8d4ec6b649c55cf3aab406a8e12d3598dff59d2f2c12d310d256a3f535fda4f816ee66d196e752c5ffb9e8d9d33e3
+  metadata.gz: 39999ff8baa584c7dd35a9b090feca1c410eedffcec72aba429ab65fe3d983c17517dff97363f4209c303d36252e3f46e1ad569ab908f2362c677064f43b54dc
+  data.tar.gz: d2b8d38f83a0bccdda315c5148d90a8d0b93821424fdb11b106ea322bcea09e3537d42c371a5cd266aa0c63a0e7f73c2d6285f302c7e444cfbf59f98c9451909

data/.claude/commands/release.md

@@ -0,0 +1,64 @@
+---
+name: release
+description: Prepare a new ExisRay release — bump version, update CHANGELOG, commit, push to main, and create git tag.
+argument-hint: <version> (e.g. 0.5.9)
+allowed-tools: [Read, Edit, Write, Bash, Glob, Grep]
+---
+
+# Release ExisRay $ARGUMENTS
+
+Seguí estos pasos para preparar y publicar la versión `$ARGUMENTS`.
+
+## 1. Verificar cambios pendientes
+
+Revisá qué cambios hay desde el último release:
+
+```bash
+git log --oneline $(git describe --tags --abbrev=0)..HEAD
+git diff --stat
+```
+
+## 2. Verificar que los tests pasan
+
+```bash
+bundle exec rspec
+```
+
+Si hay fallos, detenerse y resolverlos antes de continuar.
+
+## 3. Bump de versión
+
+Editá `lib/exis_ray/version.rb`:
+```ruby
+VERSION = "$ARGUMENTS"
+```
+
+## 4. Actualizar CHANGELOG.md
+
+Agregá una nueva entrada al tope del CHANGELOG con el formato:
+
+```markdown
+## [$ARGUMENTS] - FECHA_HOY
+
+### Added / Changed / Fixed / Removed
+- **Componente:** Descripción del cambio.
+```
+
+Basate en los commits desde el último tag para identificar qué va en cada sección.
+
+## 5. Commit
+
+```bash
+git add lib/exis_ray/version.rb CHANGELOG.md [otros archivos modificados]
+git commit -m "chore: bump version to $ARGUMENTS and update CHANGELOG"
+```
+
+## 6. Push a main y tag
+
+```bash
+git push origin HEAD:main
+git tag v$ARGUMENTS
+git push origin v$ARGUMENTS
+```
+
+El tag dispara el build automático en RubyGems vía CI.

data/.claude/skills/opentelemetry/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: opentelemetry
+description: This skill should be used when adding new log fields, designing new telemetry events, or reviewing field naming in this gem. Activates when the user mentions "otel", "opentelemetry", "semantic conventions", "field naming", "span", "trace", or asks about how to name a new log field.
+version: 1.0.0
+---
+
+# OpenTelemetry Alignment — ExisRay
+
+ExisRay sigue el **OpenTelemetry Log Data Model**. Cuando se agregan campos nuevos, priorizar los nombres de OTel Semantic Conventions antes de inventar nombres propios.
+
+## Mapeo de Campos ExisRay → OTel
+
+| Campo ExisRay  | OTel Semantic Convention    | Tipo   |
+| :------------- | :-------------------------- | :----- |
+| `body`         | `body`                      | String |
+| `level`        | `severity_text`             | String |
+| `duration_s`   | `duration` (en segundos)    | Float  |
+| `method`       | `http.request.method`       | String |
+| `status`       | `http.response.status_code` | Integer|
+| `path`         | `url.path`                  | String |
+| `user_id`      | `user.id`                   | String/Integer |
+
+## Convenciones de Naming
+
+- **`snake_case`** siempre para keys
+- **Unidades en la key, número en el valor:**
+  - `duration_s=1.25` (Float) — nunca `duration="1.25s"`
+  - `duration_ms=42` (Integer)
+  - `record_count=500` (Integer)
+  - `memory_mb=128` (Integer)
+- **`_human`** para representación legible opcional: `duration_human="2 minutes"`
+
+## Campos Reservados
+
+No usar estos nombres para otros propósitos — tienen semántica fija en ExisRay:
+
+`time`, `level`, `service`, `root_id`, `trace_id`, `source`, `correlation_id`,
+`user_id`, `isp_id`, `sidekiq_job`, `task`, `body`, `tags`
+
+## Log Body vs Campos Estructurados
+
+- **Texto libre** → va en `body` (OTel log body)
+- **Datos estructurados** → elevar al nivel raíz via KV string o Hash
+
+```ruby
+# Correcto — datos estructurados al nivel raíz
+logger.info "component=sync event=complete status=success duration_s=1.25"
+# → {"component":"sync","event":"complete","status":"success","duration_s":1.25}
+
+# Correcto — texto libre va en body
+logger.info "Esto es un mensaje de texto libre"
+# → {"body":"Esto es un mensaje de texto libre"}
+```
+
+## Trace Context (AWS X-Ray compatible)
+
+ExisRay usa el formato AWS X-Ray pero es compatible con OTel trace context:
+
+- `root_id` → equivalente a `trace_id` en OTel (solo el ID raíz, sin prefijos)
+- `trace_id` → header completo X-Ray: `Root=1-...;Self=...;CalledFrom=...`
+- `source` → entrypoint de ejecución (no tiene equivalente directo en OTel)

data/.claude/skills/rails-expert/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: rails-expert
+description: This skill should be used when writing or reviewing any Rails integration code in this gem — Railtie, middleware, CurrentAttributes, initializers, ActiveSupport notifications, or compatibility across Rails 6/7/8. Activates when the user mentions "railtie", "middleware", "initializer", "after_initialize", "current_attributes", "cache_classes", "enable_reloading", "log_subscriber", "tagged_logging", or asks about Rails compatibility.
+version: 1.0.0
+---
+
+# Rails Expert — ExisRay Context
+
+Este skill cubre las integraciones de ExisRay con Rails y las reglas de compatibilidad entre versiones.
+
+## Compatibilidad de Versiones
+
+### Rails 7.1+ vs 6/7.0
+
+**Reloading:**
+```ruby
+# Correcto — compatible con Rails 6, 7 y 8
+def cache_classes?
+  config = Rails.application.config
+  if config.respond_to?(:enable_reloading)
+    !config.enable_reloading  # Rails 7.1+ (semántica inversa)
+  else
+    config.cache_classes      # Rails 6/7.0
+  end
+end
+```
+
+**Notifications (ActiveSupport):**
+```ruby
+# Correcto — siempre usar respond_to? guard
+if notifier.respond_to?(:all_listeners_for)
+  notifier.all_listeners_for(pattern)   # Rails 7.1+
+else
+  notifier.listeners_for(pattern)       # Rails 6/7.0
+end
+```
+
+## Railtie — Orden de Inicialización
+
+ExisRay usa tres puntos de inicialización con propósitos distintos:
+
+```
+1. initializer "exis_ray.configure_middleware"
+   → Inserta HttpMiddleware en el stack Rack
+   → Corre antes de que la app arranque
+
+2. initializer "exis_ray.configure_logging", after: :load_config_initializers
+   → Lee config/initializers/exis_ray.rb antes de decidir la estrategia
+   → Configura log_tags para modo texto
+
+3. config.after_initialize
+   → Todo lo demás: JsonFormatter, LogSubscriber, BugBunny, Sidekiq, ActiveResource
+   → Garantiza que TODAS las gemas están cargadas (defined?(::BugBunny) funciona)
+```
+
+**Regla crítica:** Cualquier integración condicional (`defined?(::GemaExterna)`) DEBE ir en `after_initialize`, no en `initializer`. De lo contrario la condición puede evaluarse antes de que la gema esté cargada.
+
+## CurrentAttributes
+
+`ExisRay::Tracer` extiende `ActiveSupport::CurrentAttributes` — es thread-local y se resetea automáticamente al final de cada request HTTP (via `ActionDispatch::Executor`).
+
+Para contextos no-HTTP (Sidekiq, BugBunny, Rake), siempre hacer reset manual en `ensure`:
+```ruby
+ensure
+  ExisRay::Tracer.reset rescue nil
+end
+```
+
+## LogSubscriber
+
+`ExisRay::LogSubscriber` usa `ActiveSupport::Notifications`. Solo se instala con `json_logs: true`.
+
+```ruby
+ExisRay::LogSubscriber.install!
+# Internamente: subscribe a process_action.action_controller
+# y desuscribe los subscribers por defecto de Rails
+```
+
+## TaggedLogging (modo texto)
+
+En modo texto (`json_logs: false`), el contexto se inyecta via `log_tags`:
+```ruby
+app.config.log_tags << proc { ExisRay::Tracer.trace_id.presence || ExisRay::Tracer.root_id.presence }
+```
+Solo funciona dentro del ciclo de un HTTP request. Procesos background (Sidekiq, BugBunny) no tienen este contexto en modo texto.

data/.claude/skills/readme-writer/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: readme-writer
+description: This skill should be used when updating README.md or CHANGELOG.md after adding a new feature, fixing a bug, or releasing a version. Activates when the user mentions "readme", "changelog", "documentation", "release notes", "document this feature", or asks to update the docs.
+version: 1.0.0
+---
+
+# README & CHANGELOG Writer — ExisRay
+
+## README.md — Estructura y Estilo
+
+El README de ExisRay sigue esta estructura fija. No reorganizar secciones existentes — solo agregar o actualizar.
+
+### Tono y Estilo
+- Conciso y técnico — el lector es un dev Rails que quiere integrar la gema rápido
+- Ejemplos de código reales, no abstractos
+- Mostrar el output (JSON) cuando sea relevante para entender el valor
+- Español para texto corrido, inglés para nombres de clases/métodos/campos
+
+### Secciones del README
+1. **Badges + descripción una línea**
+2. **Features** — lista bullets con las capacidades principales
+3. **Installation** — Gemfile + bundle
+4. **Configuration** — initializer con todos los options documentados
+5. **Usage por integración** — una subsección por integración (HTTP, Sidekiq, BugBunny, etc.)
+6. **Advanced** — subclassing Current, Reporter, LogSubscriber
+
+### Cómo documentar una nueva integración
+
+```markdown
+## E. NombreIntegración
+
+Descripción en 1-2 oraciones de qué hace y por qué es útil.
+
+### Setup
+
+\`\`\`ruby
+# Código mínimo para activar la integración
+\`\`\`
+
+### Output
+
+\`\`\`json
+{
+  "time": "...",
+  "root_id": "...",
+  "component": "...",
+  "event": "..."
+}
+\`\`\`
+```
+
+---
+
+## CHANGELOG.md — Formato
+
+Seguir [Keep a Changelog](https://keepachangelog.com/). Cada entrada en orden cronológico inverso.
+
+### Estructura de una entrada
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- **NombreFeature:** Descripción clara de qué se agregó y por qué es útil.
+  Mencionar el componente afectado y el beneficio para el usuario.
+
+### Changed
+- **NombreComponente:** Qué cambió y por qué (motivación técnica o de UX).
+
+### Fixed
+- **Descripción del bug:** Qué fallaba, en qué condición, cómo se resolvió.
+
+### Removed
+- **NombreComponente:** Qué se eliminó y qué lo reemplaza (si aplica).
+```
+
+### Reglas
+- Una entrada por item significativo — no agrupar cosas no relacionadas
+- Mencionar el nombre del componente en **negrita** al inicio
+- Describir el beneficio para el usuario, no solo el cambio técnico
+- Si hay breaking change, marcarlo explícitamente: `⚠️ Breaking:`
+- Versiones de patch (0.5.x): bugs y fixes pequeños
+- Versiones minor (0.x.0): features nuevas, integraciones
+- Versiones major (x.0.0): breaking changes

data/.claude/skills/rubocop-omakase/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: rubocop-omakase
+description: This skill should be used when writing or reviewing Ruby code in this gem to ensure it follows RuboCop Rails Omakase conventions. Activates when writing new methods, refactoring existing code, or when the user mentions "rubocop", "style", "convention", "cop", or "omakase".
+version: 1.0.0
+---
+
+# RuboCop Rails Omakase — ExisRay
+
+Todo código nuevo o modificado debe seguir las convenciones de `rubocop-rails-omakase`. Solo aplicar a código que se está escribiendo o modificando — nunca sugerir fixes en código existente no tocado.
+
+## Reglas Principales
+
+**Strings:**
+```ruby
+# Frozen string literal obligatorio en todos los archivos
+# frozen_string_literal: true
+
+# Comillas dobles para strings
+"hola mundo"   # correcto
+'hola mundo'   # incorrecto
+```
+
+**Métodos:**
+```ruby
+# Sin paréntesis en definición si no hay argumentos
+def reset
+  # ...
+end
+
+# Con paréntesis cuando hay argumentos
+def hydrate(trace_id:, source:)
+  # ...
+end
+```
+
+**Bloques:**
+```ruby
+# { } para bloques de una línea
+[1, 2].map { |n| n * 2 }
+
+# do/end para bloques multilínea
+[1, 2].each do |n|
+  puts n
+  puts n * 2
+end
+```
+
+**Condicionales:**
+```ruby
+# Guard clauses para retornos tempranos
+def process(value)
+  return unless value.present?
+  return "[FILTERED]" if sensitive?(value)
+
+  do_something(value)
+end
+
+# Ternario solo cuando es genuinamente simple
+result = condition ? "yes" : "no"
+```
+
+**Espaciado:**
+```ruby
+# Línea en blanco después de definición de clase/módulo
+class MyClass
+  # línea en blanco aquí si hay métodos
+
+  def my_method
+  end
+end
+```
+
+**Hash:**
+```ruby
+# Ruby 3.1+ shorthand cuando key == variable
+{ name:, value: }  # en lugar de { name: name, value: value }
+
+# Rocket syntax solo para keys no-símbolo
+{ "string-key" => value }
+{ symbol_key: value }
+```
+
+## Patterns Comunes en ExisRay
+
+```ruby
+# Módulos con solo métodos de clase — usar module_function o class << self
+module ExisRay
+  module TaskMonitor
+    class << self
+      def run(task_name)
+        # ...
+      end
+    end
+  end
+end
+
+# Rescue en métodos que no deben interrumpir el flujo
+def setup_context
+  do_risky_thing
+rescue StandardError
+  # silenciar
+end
+
+# Lambdas con -> para bloques cortos
+transformer = ->(value) { value.to_s.downcase }
+```
+
+## Verificación
+
+Antes de proponer código, mentalmente verificar:
+1. `# frozen_string_literal: true` presente
+2. Strings con comillas dobles
+3. Guard clauses en lugar de if anidados
+4. `rescue StandardError` en operaciones de logging/tracing

data/.claude/skills/yard/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: yard
+description: This skill should be used when writing or reviewing Ruby documentation in this gem. Activates when adding new methods, classes, or modules, or when the user mentions "yard", "documentation", "docstring", "@param", "@return", "@example", or asks how to document something.
+version: 1.0.0
+---
+
+# YARD Documentation — ExisRay Style
+
+Toda clase, módulo y método público de ExisRay debe estar documentado con YARD. Los métodos privados solo se documentan si la lógica no es autoevidente.
+
+## Estructura de una Clase/Módulo
+
+```ruby
+# Descripción en una línea.
+#
+# Párrafo de contexto opcional explicando el propósito y comportamiento general.
+# Mencionar dependencias importantes o patrones de uso.
+#
+# @example Uso básico
+#   ExisRay::Tracer.hydrate(trace_id: header, source: 'http')
+class ExisRay::Tracer < ActiveSupport::CurrentAttributes
+```
+
+## Métodos de Clase
+
+```ruby
+# Descripción concisa del método en una línea.
+#
+# Párrafo opcional con detalles de comportamiento, casos edge, o efectos secundarios.
+#
+# @param trace_id [String] El header de traza entrante (formato AWS X-Ray).
+# @param source [String] El entrypoint de ejecución ('http', 'sidekiq', 'task', 'system').
+# @return [void]
+def self.hydrate(trace_id:, source:)
+```
+
+## Tipos Comunes en ExisRay
+
+| Tipo YARD | Cuándo usarlo |
+|:----------|:-------------|
+| `[String]` | Strings simples |
+| `[String, nil]` | Puede ser nil |
+| `[Boolean]` | true/false |
+| `[Hash]` | Hash genérico |
+| `[Hash{Symbol => Object}]` | Hash con tipos de keys/values |
+| `[Class, nil]` | Clase o nil (para current_class, reporter_class) |
+| `[void]` | Métodos sin valor de retorno significativo |
+| `[Float]` | Duraciones en segundos |
+| `[Integer]` | Duraciones en ms, counts |
+
+## Atributos con attr_accessor
+
+```ruby
+# @!attribute [rw] trace_header
+#   @return [String] La key del header HTTP (formato Rack) para el Trace ID entrante.
+#   Por defecto es 'HTTP_X_AMZN_TRACE_ID'.
+attr_accessor :trace_header
+```
+
+## Métodos Privados
+
+Solo documentar si la lógica no es obvia:
+```ruby
+# Limpia el Request ID para cumplir con los 24 caracteres hex de AWS X-Ray.
+#
+# @api private
+# @return [String]
+def self.clean_request_id
+```
+
+## Reglas
+
+- Primera línea: siempre una oración completa terminada en punto
+- `@example` cuando el uso no es obvio desde la firma
+- `@api private` para métodos que usan `private_class_method`
+- No documentar código que no fue modificado
+- No agregar `@author` ni `@since` — no es el estilo del proyecto

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [0.5.9] - 2026-03-31
+
+### Fixed
+- **JSON Object Coercion:** `JsonFormatter` ahora intenta parsear como JSON cualquier valor string que comience con `{` o `[` al procesar KV strings. Esto permite que campos como `queue_opts` y `exchange_opts` emitidos por BugBunny como JSON compacto se serialicen como objetos reales en lugar de strings escapados.
+
+### Added
+- **CLAUDE.md:** Documentación completa del proyecto actualizada a v0.5.9: arquitectura, componentes, métodos clave, campos auto-inyectados, reglas de ejecución y guía de testing en consola.
+- **`.claude/skills/`:** Skills de proyecto para rails-expert, YARD, OpenTelemetry, RuboCop Omakase y README writer — disponibles automáticamente para cualquier dev que use Claude Code en este repo.
+- **`.claude/commands/release`:** Comando `/release` para automatizar el flujo de versioning.
+
+## [0.5.8] - 2026-03-31
+
+### Added
+- **`ExisRay::BugBunny::ConsumerTracingMiddleware`:** Nuevo middleware para el consumer stack de BugBunny. Corre antes de que la gema procese cada mensaje (antes de `consumer.message_received`), garantizando que todos los logs internos de BugBunny — `consumer.message_received`, `consumer.route_matched`, `consumer.rpc_reply`, `consumer.message_processed` — incluyan `root_id`, `trace_id` y `source`. Si el mensaje no trae header de traza, genera un `root_id` nuevo automáticamente.
+- **Propagación RPC bidireccional:** El `Railtie` registra automáticamente dos callbacks en BugBunny: `rpc_reply_headers` inyecta el trace header actualizado (`Self`, `TotalTimeSoFar`, `CalledFrom`) en el reply del consumer; `on_rpc_reply` hidrata el tracer en el thread del publisher al recibir la respuesta, permitiendo que `producer.rpc_response_received` y `request_complete` reflejen el viaje completo por el ecosistema de microservicios.
+
+### Changed
+- **BugBunny auto-instrumentado:** La integración BugBunny se mueve al `after_initialize` del `Railtie`, resolviendo el problema de orden de carga. Con ambas gemas en el `Gemfile`, todo se configura automáticamente sin intervención del desarrollador.
+- **MANIFEST.md:** Documentación completa del estándar de observabilidad: semántica de niveles de log, block form obligatorio para DEBUG, medición de duraciones con reloj monotónico, filtrado de claves sensibles, resiliencia del logger, y tabla completa de campos auto-inyectados con condiciones de activación.
+
+### Removed
+- **`ExisRay::BugBunny::ConsumerTracing`:** Concern eliminado. Reemplazado por `ConsumerTracingMiddleware` que cubre el ciclo completo del mensaje, no solo el action del controller.
+
 ## [0.5.7] - 2026-03-27
 
 ### Fixed

data/CLAUDE.md

@@ -1,38 +1,158 @@
-# ExisRay Project Memory
-
-## Architecture & Components
-- `ExisRay::Tracer`: Distributed tracing (AWS X-Ray). Uses `CurrentAttributes` for thread-safety.
-- `ExisRay::Current`: Business context (User, ISP). Abstract base class for host app subclassing.
-- `ExisRay::Reporter`: Sentry wrapper. Abstract base class for host app subclassing.
-- `ExisRay::JsonFormatter`: Core engine. Handles Hash, KV strings, and free-text with automatic masking and **Type Casting**.
-- `ExisRay::LogSubscriber`: Native HTTP logger since v0.4.0. Replaces Lograge.
-- `ExisRay::TaskMonitor`: Lifecycle manager for non-HTTP processes.
-
-## Technical Knowledge & Compatibility
-
-### Wispro Observability Spec (v1)
-- **Manifest:** All logging MUST follow the rules defined in `MANIFEST.md`.
-- **Metrics:** Always use `_s` suffix for durations (Float) and `count` for volumes (Integer). Never include units in values.
-- **Type-Awareness:** `JsonFormatter` automatically casts numeric KV values to Float/Integer. Emit raw numbers in KV strings.
-- **Automatic Fields:** Do not manually log `time`, `level`, `service`, `source`, `root_id`, `correlation_id`, `sidekiq_job` or `task`. These are handled by the library.
-
-### Rails Compatibility (6, 7, 8)
-- **Reloading:** Use `cache_classes?` helper (checks `respond_to?(:enable_reloading)`) to avoid deprecation warnings in Rails 7.1+.
-- **Notifications:** Rails 7.1+ uses `all_listeners_for`, while 6/7.0 uses `listeners_for`. Always use `respond_to?` guards when manipulating subscribers.
-
-### Distributed Tracing (AWS X-Ray)
-- **Propagation:** Use `propagation_trace_header` (standard HTTP format) for outgoing requests.
-- **Parsing:** `trace_header` (Rack format) is ONLY for incoming request parsing.
-
-## Security & Privacy
-- **Sensitive Key Filtering:** `JsonFormatter` auto-filters keys matching `password|pass|passwd|secret|token|api_key|auth` → replaced with `[FILTERED]`.
-- **Header Injection Prevention:** `ExisRay::Current` sanitizes values via `sanitize_header_value` before storing user/ISP identity.
-- **No PII in Logs:** Never log raw user data. Only IDs (`user_id`, `isp_id`) are permitted.
-
-## Execution Rules
-- **No Lograge:** Do not suggest or re-add the Lograge dependency.
-- **Pure Data Logging:** Internal logs use KV strings (`component=exis_ray event=...`).
-- **OTel Compliance:** Always follow the guidelines in `.gemini/docs/TELEMETRY_GUIDELINES.md` and alignment in `MANIFEST.md`. Use OTel Semantic Conventions for new attributes.
-- **Resilience:** All logging operations must be wrapped in `rescue StandardError`.
-- **Automatic Fields:** NEVER manually log `time`, `level`, `service`, `source`, `root_id`, `correlation_id`, `sidekiq_job` or `task`. These are handled by the library.
-- **Source Values:** Valid values for `source` field: `http`, `sidekiq`, `task`, `system`.
+# ExisRay — Project Intelligence
+
+## Qué es esta gema
+
+ExisRay es la capa de observabilidad y trazabilidad distribuida del ecosistema Wispro. Se integra con Rails para emitir logs estructurados en JSON, propagar trace context entre servicios (HTTP, Sidekiq, RabbitMQ), y mantener identidad de negocio (user_id, isp_id, correlation_id) en cada línea de log.
+
+El estándar de logging que implementa está definido en `MANIFEST.md`. Ese documento es la fuente de verdad — cualquier duda sobre formato, campos, o semántica de niveles se resuelve ahí.
+
+---
+
+## Arquitectura & Componentes
+
+### Core
+- **`ExisRay::Tracer`** — Contexto de trazabilidad distribuida (AWS X-Ray). Extiende `ActiveSupport::CurrentAttributes` para thread-safety. Campos: `trace_id`, `root_id`, `self_id`, `source`, `created_at`, `request_id`, `sidekiq_job`, `task`.
+- **`ExisRay::JsonFormatter`** — Formateador global. Acepta Hash, KV strings (`key=value`) y texto libre. Inyecta automáticamente el contexto del Tracer y del Current en cada línea. Castea valores numéricos y filtra claves sensibles.
+- **`ExisRay::Current`** — Contexto de negocio (user_id, isp_id, correlation_id). Clase abstracta — la app host la subclasifica.
+- **`ExisRay::Reporter`** — Wrapper de Sentry. Clase abstracta — la app host la subclasifica.
+- **`ExisRay::Configuration`** — Configuración global con defaults para AWS X-Ray.
+
+### Integraciones HTTP
+- **`ExisRay::HttpMiddleware`** — Rack middleware. Hidrata el Tracer con el header entrante. Se inserta automáticamente después de `ActionDispatch::RequestId`.
+- **`ExisRay::LogSubscriber`** — Logger nativo de requests HTTP. Reemplaza Lograge. Solo activo con `json_logs: true`.
+- **`ExisRay::FaradayMiddleware`** — Inyecta `propagation_trace_header` en requests salientes via Faraday.
+- **`ExisRay::ActiveResourceInstrumentation`** — Ídem para ActiveResource.
+
+### Integraciones Sidekiq
+- **`ExisRay::Sidekiq::ClientMiddleware`** — Inyecta `exis_ray_trace` en el payload del job antes de encolarlo.
+- **`ExisRay::Sidekiq::ServerMiddleware`** — Hidrata el Tracer al inicio de cada job. Genera root_id nuevo si el job no trae trace.
+
+### Integraciones BugBunny (RabbitMQ)
+- **`ExisRay::BugBunny::PublisherTracing`** — Middleware para `BugBunny::Client`/`BugBunny::Resource`. Inyecta `propagation_trace_header` en cada mensaje publicado.
+- **`ExisRay::BugBunny::ConsumerTracingMiddleware`** — Consumer middleware. Corre antes de todos los logs internos de BugBunny. Hidrata el Tracer desde el header AMQP entrante o genera root_id nuevo.
+- **Railtie hooks** — `rpc_reply_headers` inyecta el trace actualizado en el reply del consumer. `on_rpc_reply` hidrata el Tracer en el thread del publisher al recibir la respuesta.
+
+### Procesos en Background
+- **`ExisRay::TaskMonitor`** — Lifecycle manager para Rake/Cron. Genera root_id, loguea `task_started`/`task_finished` con `duration_s` y `status`.
+
+---
+
+## Métodos Clave
+
+```ruby
+# Hidratar el Tracer (HTTP, Sidekiq, BugBunny consumer)
+ExisRay::Tracer.hydrate(trace_id: header_string, source: 'http')
+
+# Sincronizar correlation_id al Current configurado
+ExisRay.sync_correlation_id
+
+# Generar header de propagación para el siguiente servicio
+ExisRay::Tracer.generate_trace_header
+# => "Root=1-abc123-...;Self=...;CalledFrom=wispro_agent;TotalTimeSoFar=42ms"
+
+# Acceder a la configuración
+ExisRay.configuration.propagation_trace_header  # => 'X-Amzn-Trace-Id'
+ExisRay.configuration.json_logs?                # => true/false
+```
+
+---
+
+## Campos Auto-Inyectados
+
+`JsonFormatter` inyecta estos campos automáticamente. **Nunca** incluirlos manualmente en logs:
+
+| Campo | Condición |
+|:------|:----------|
+| `time` | Siempre |
+| `level` | Siempre |
+| `service` | Siempre |
+| `root_id` | Cuando hay trace context activo |
+| `trace_id` | Cuando hay trace context activo |
+| `source` | Cuando hay trace context activo |
+| `correlation_id` | Cuando `Current.correlation_id` está presente |
+| `user_id` | Cuando `Current.user_id` está presente |
+| `isp_id` | Cuando `Current.isp_id` está presente |
+| `sidekiq_job` | Solo en procesos Sidekiq |
+| `task` | Solo en procesos TaskMonitor |
+| `tags` | Solo si hay Rails tagged logging activo |
+
+---
+
+## Reglas de Ejecución
+
+### Logging
+- Todo log interno usa KV strings: `component=exis_ray event=algo`
+- `component` siempre en `snake_case`
+- DEBUG siempre en block form: `logger.debug { "k=#{v}" }`
+- Nunca `Kernel#warn` ni `$stderr`
+- Toda operación de logging envuelta en `rescue StandardError`
+- Duraciones con `Process.clock_gettime(Process::CLOCK_MONOTONIC)`, nunca `Time.now`
+
+### Seguridad
+- Claves sensibles (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]`
+- Nunca loguear PII. Solo `user_id`, `isp_id`
+
+### Source válidos
+`http` | `sidekiq` | `task` | `system`
+
+### Propagación de headers
+- **Entrante HTTP:** `trace_header` (formato Rack: `HTTP_X_AMZN_TRACE_ID`) — solo en `HttpMiddleware`
+- **Saliente (todos los transportes):** `propagation_trace_header` (formato HTTP: `X-Amzn-Trace-Id`)
+
+### Prohibiciones
+- No Lograge — reemplazado por `LogSubscriber`
+- No loguear manualmente: `time`, `level`, `service`, `source`, `root_id`, `trace_id`, `correlation_id`, `sidekiq_job`, `task`
+- No referenciar `.gemini/` — obsoleto
+
+---
+
+## Compatibilidad Rails
+
+- **Reloading:** Usar `cache_classes?` helper (verifica `respond_to?(:enable_reloading)`) para Rails 7.1+
+- **Notifications:** Rails 7.1+ usa `all_listeners_for`, Rails 6/7.0 usa `listeners_for` — siempre usar `respond_to?` guards
+- **Soporte:** Rails 6, 7 y 8
+
+---
+
+## Integración Automática (Railtie)
+
+El `Railtie` en `after_initialize` detecta y auto-instrumenta sin intervención del desarrollador:
+
+| Gema detectada | Qué hace |
+|:---------------|:---------|
+| `BugBunny` | Registra `PublisherTracing` no — ese va en el cliente. Registra `ConsumerTracingMiddleware` y los hooks RPC |
+| `Sidekiq` | Registra client + server middleware |
+| `ActiveResource` | Prepend de `ActiveResourceInstrumentation` |
+| `Faraday` | Disponible como middleware opcional |
+
+---
+
+## Configuración Mínima
+
+```ruby
+# config/initializers/exis_ray.rb
+ExisRay.configure do |config|
+  config.log_format              = :json              # :text por defecto
+  config.trace_header            = 'HTTP_X_AMZN_TRACE_ID'
+  config.propagation_trace_header = 'X-Amzn-Trace-Id'
+  config.current_class           = 'Current'
+  config.reporter_class          = 'Reporter'
+end
+
+# BugBunny publisher — debe agregarse manualmente al cliente
+BugBunny::Client.new(pool: pool) do |stack|
+  stack.use ExisRay::BugBunny::PublisherTracing
+end
+```
+
+---
+
+## Testing en Consola
+
+```ruby
+# Inicializar trace context para probar desde rails console
+ExisRay::Tracer.hydrate(
+  trace_id: "Root=1-#{Time.now.to_i.to_s(16)}-#{SecureRandom.hex(12)}",
+  source: 'system'
+)
+```

data/MANIFEST.md

@@ -5,81 +5,185 @@ Este documento define el estándar obligatorio de telemetría y logging estructu
 ## Objetivo
 Transformar el logging tradicional en un **flujo de eventos de datos**. Esto permite que herramientas de análisis puedan generar dashboards de rendimiento, alertas inteligentes y rastreo de errores sin necesidad de procesamiento manual de texto o transformaciones complejas.
 
+---
+
 ## Reglas Fundamentales
 
-### 1. Unidad en la Key, Número en el Valor (Data First)
-La regla de oro para que las métricas sean operables es separar la unidad del dato numérico. **Nunca** incluir unidades dentro de los valores de los logs.
-*   Incorrecto: `duration="0.5s"`, `memory="128MB"`.
-*   Correcto: `duration_s=0.5`, `memory_mb=128`.
+### 1. Formato de Mensaje
+
+Todo log debe emitirse como una línea de pares `key=value` en el siguiente orden:
+
+```
+component=x event=y [campos adicionales]
+```
+
+- `component`: nombre de la gema, librería o módulo responsable (ej: `exis_ray`, `storage_engine`). Siempre en `snake_case`.
+- `event`: nombre puntual de la acción o hito (ej: `http_request`, `sync_complete`). Siempre en `snake_case`.
+- Los campos adicionales van a continuación, en cualquier orden.
+
+Valores con espacios deben ir entre comillas dobles: `error_message="Server reset connection"`.
+
+### 2. Niveles de Log
+
+Cada nivel tiene una semántica estricta. Usar el nivel incorrecto es un error.
+
+| Nivel   | Cuándo usarlo |
+| :------ | :------------ |
+| `ERROR` | Se lanzó una excepción o el sistema no pudo completar una operación crítica. |
+| `WARN`  | Ocurrió algo inesperado pero la ejecución continuó. |
+| `INFO`  | Flujo normal del sistema. Eventos relevantes para el negocio u operaciones. |
+| `DEBUG` | Detalle técnico interno. Solo útil durante desarrollo o diagnóstico. |
+
+**Regla de DEBUG:** Siempre usar block form para evitar interpolación innecesaria:
+```ruby
+# Correcto
+logger.debug { "component=cache event=miss key=#{key}" }
+
+# Incorrecto — evalúa la interpolación aunque DEBUG esté desactivado
+logger.debug "component=cache event=miss key=#{key}"
+```
+
+**Prohibido:** Nunca usar `Kernel#warn` ni escribir directamente a `$stderr`. Todo output debe ir por el logger configurado.
+
+### 3. Unidad en la Key, Número en el Valor (Data First)
+
+La regla de oro para que las métricas sean operables es separar la unidad del dato numérico. **Nunca** incluir unidades dentro de los valores.
+
+```
+# Incorrecto
+duration="0.5s"   memory="128MB"
+
+# Correcto
+duration_s=0.5    memory_mb=128
+```
 
-**Sufijos de unidad recomendados:**
-- `_s`: Segundos (Float). Estándar para duraciones y latencias visibles al negocio.
+**Sufijos de unidad:**
+- `_s`: Segundos (Float). Estándar para duraciones y latencias.
 - `_ms`: Milisegundos (Integer). Para precisión técnica interna de alta frecuencia.
 - `_count`: Cantidades o volúmenes (Integer). Ej: `record_count`, `retry_count`.
 - `_bytes` / `_kb` / `_mb`: Unidades de almacenamiento o memoria.
-- `_human`: (Opcional) Texto explicativo legible para humanos (ej: `duration_human="2 hours"`).
+- `_human`: (Opcional) Texto legible para humanos. Ej: `duration_human="2 minutes 5 seconds"`.
+
+### 4. Medición de Duraciones
+
+Las duraciones **siempre** deben medirse con reloj monotónico. Nunca con `Time.now` (susceptible a saltos de reloj del sistema).
+
+```ruby
+# Correcto
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+# ... operación ...
+duration_s = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+
+# Incorrecto
+start = Time.now
+duration_s = Time.now - start
+```
+
+### 5. Source: Entrypoint de Ejecución
 
-### 2. Contexto de Identidad
-Cada línea de log debe llevar los metadatos necesarios para identificar su origen técnico de forma inmediata:
-*   `component`: Nombre de la gema, librería o módulo responsable (ej: `exis_ray`, `storage_engine`).
-*   `event`: Nombre de la acción puntual o hito alcanzado (ej: `http_request`, `engine.complete`).
-*   `source`: El punto de entrada de la ejecución (`http`, `sidekiq`, `task`, `system`).
+El campo `source` identifica el punto de entrada del proceso. Es obligatorio y solo acepta estos valores:
 
-### 3. Convenciones de Naming & Tipos
-- **Naming:** Las llaves (keys) deben usar siempre `snake_case`. Para campos estándar, se prefiere seguir las **OpenTelemetry Semantic Conventions**.
-- **Valores Numéricos:** Deben emitirse como números reales (sin sufijos de texto) para permitir que el motor de logs realice el casting automático.
-- **Formato:** Pares `key=value` en una sola línea estructurada.
+| Valor      | Cuándo usarlo |
+| :--------- | :------------ |
+| `http`     | Request HTTP entrante (procesado por Rack/Rails). |
+| `sidekiq`  | Job procesado por Sidekiq. |
+| `task`     | Tarea programada o proceso de larga duración (Rake, Cron, TaskMonitor). |
+| `system`   | Ejecución iniciada por otro sistema interno (ej: consumidor RabbitMQ/BugBunny). |
+
+`source` es inyectado automáticamente por el middleware correspondiente. **No lo incluyas manualmente.**
+
+### 6. Seguridad y Privacidad
+
+**Filtrado de claves sensibles:** Cualquier campo cuya key coincida con el patrón `password|pass|passwd|secret|token|api_key|auth` debe reemplazar su valor por `[FILTERED]`. Esto es aplicado automáticamente por `ExisRay::JsonFormatter` en todos los logs.
+
+**Sin PII:** Nunca loguear datos crudos de usuarios. Solo se permiten identificadores: `user_id`, `isp_id`.
+
+```
+# Incorrecto
+component=auth event=login email=user@example.com password=abc123
+
+# Correcto
+component=auth event=login user_id=42 password=[FILTERED]
+```
+
+### 7. Resiliencia del Logger
+
+Un fallo en el logging nunca debe interrumpir el flujo principal de la aplicación. Toda operación de logging debe estar protegida:
+
+```ruby
+# Correcto
+begin
+  logger.info "component=sync event=complete duration_s=#{duration_s}"
+rescue StandardError
+  # silenciar — el log es accesorio, no crítico
+end
+```
+
+### 8. Convenciones de Naming
+
+- Keys siempre en `snake_case`.
+- Valores numéricos emitidos como números reales (sin comillas) para que el motor de logs realice casting automático.
+- Para campos estándar, seguir las **OpenTelemetry Semantic Conventions** donde sea posible.
+
+---
 
 ## 🔭 Alineación con OpenTelemetry
 
-Para garantizar la interoperabilidad, `exis_ray` sigue el **OpenTelemetry Log Data Model**. Siempre que sea posible, los campos deben mapearse a las convenciones semánticas oficiales:
+`exis_ray` sigue el **OpenTelemetry Log Data Model**. Los campos se mapean a las convenciones semánticas oficiales:
 
-| Campo ExisRay | OTel Semantic Convention | Descripción |
-| :--- | :--- | :--- |
-| `body` | `body` | El contenido principal del log. |
-| `level` | `severity_text` | Nivel de importancia. |
-| `duration_s` | `duration` (en segundos) | Tiempo de ejecución. |
-| `method` | `http.request.method` | Método HTTP. |
-| `status` | `http.response.status_code` | Código de respuesta. |
-| `path` | `url.path` | Ruta del request. |
-| `user_id` | `user.id` | Identificador del usuario. |
+| Campo ExisRay  | OTel Semantic Convention    | Descripción              |
+| :------------- | :-------------------------- | :----------------------- |
+| `body`         | `body`                      | Contenido principal del log (texto libre). |
+| `level`        | `severity_text`             | Nivel de importancia.    |
+| `duration_s`   | `duration` (en segundos)    | Tiempo de ejecución.     |
+| `method`       | `http.request.method`       | Método HTTP.             |
+| `status`       | `http.response.status_code` | Código de respuesta HTTP.|
+| `path`         | `url.path`                  | Ruta del request.        |
+| `user_id`      | `user.id`                   | Identificador del usuario.|
 
-## 🏗 Infraestructura de Datos (Automática)
+---
 
-Para evitar logs redundantes y pesados, **NUNCA** incluyas manualmente las siguientes llaves en tus mensajes de log. La capa de infraestructura (`exis_ray`) las inyecta automáticamente en el nivel raíz del JSON:
+## 🏗 Campos Auto-Inyectados por ExisRay
 
-| Llave | Descripción | Por qué no incluirla |
-| :--- | :--- | :--- |
-| `time` | Timestamp ISO8601 | Lo añade el Logger base. |
-| `level` | INFO, ERROR, etc. | Lo añade el Logger base. |
-| `service` | Nombre de la App | Se obtiene de la configuración global. |
-| `source` | Entrypoint (http, task) | Lo inyecta el middleware/monitor correspondiente. |
-| `root_id` | Trace ID (AWS X-Ray) | Se gestiona a nivel de hilo/petición. |
-| `correlation_id`| ID de rastreo cruzado | Se genera automáticamente al inicio de la ejecución. |
-| `user_id` / `isp_id`| Contexto de negocio | Se extrae del estado global de la petición. |
-| `sidekiq_job` | Clase del Worker | Inyectado automáticamente en procesos Sidekiq. |
-| `task` | Nombre de la tarea | Inyectado automáticamente por el TaskMonitor. |
+**NUNCA** incluyas manualmente los siguientes campos. `ExisRay::JsonFormatter` los inyecta automáticamente en cada línea de log:
 
-> **Regla de Oro:** Tu log manual solo debe contener datos de **tu lógica de negocio**. La infraestructura ya sabe quién eres, de dónde vienes y cuál es tu ID de traza.
+| Campo            | Descripción                        | Condición                                      |
+| :--------------- | :--------------------------------- | :--------------------------------------------- |
+| `time`           | Timestamp ISO8601 UTC              | Siempre                                        |
+| `level`          | Nivel de severidad                 | Siempre                                        |
+| `service`        | Nombre de la aplicación            | Siempre                                        |
+| `root_id`        | Trace ID raíz (AWS X-Ray)          | Cuando hay trace context activo                |
+| `trace_id`       | Trace ID completo (formato X-Ray)  | Cuando hay trace context activo                |
+| `source`         | Entrypoint de ejecución            | Cuando hay trace context activo                |
+| `correlation_id` | ID de rastreo cruzado              | Cuando `Current.correlation_id` está presente  |
+| `user_id`        | ID del usuario autenticado         | Cuando `Current.user_id` está presente         |
+| `isp_id`         | ID del ISP                         | Cuando `Current.isp_id` está presente          |
+| `sidekiq_job`    | Clase del Worker Sidekiq           | Solo en procesos Sidekiq                       |
+| `task`           | Nombre de la tarea                 | Solo en procesos TaskMonitor                   |
+| `tags`           | Tags de Rails TaggedLogging        | Solo si hay tags activos en el hilo            |
+
+> **Regla de Oro:** Tu log manual solo debe contener datos de **tu lógica de negocio**. La infraestructura ya sabe quién eres, de dónde venís y cuál es tu ID de traza.
 
 ---
 
 ## 🛰 Ciclo de Vida del Evento
 
-## Ciclo de Vida del Evento
-
 ### Procesos, Trabajos y Tareas (Jobs/Tasks)
+
 Todo proceso aislado debe reportar su inicio y su finalización con una estructura consistente:
+
 - `event`: Identificador de estado (ej: `task_started`, `task_finished`).
-- `status`: Resultado final de la operación (`success`, `failed`, `aborted`). En contexto de tareas/jobs, siempre es un string semántico, no un código HTTP.
-- `duration_s`: Tiempo total de ejecución (calculado con reloj monotónico).
+- `status`: Resultado final (`success`, `failed`, `aborted`). Siempre string semántico, nunca código HTTP.
+- `duration_s`: Tiempo total de ejecución (reloj monotónico).
 - `error_class` / `error_message`: Obligatorios solo en caso de fallo.
 
-### Peticiones de Interfaz (APIs/HTTP)
-Los logs de cierre de peticiones deben estandarizar el reporte de rendimiento para telemetría:
-- `status`: Código de respuesta HTTP (Integer). En contexto HTTP siempre es el código numérico (ej: `200`, `404`, `500`).
+### Peticiones HTTP
+
+Los logs de cierre de petición deben estandarizar el reporte de rendimiento:
+
+- `status`: Código HTTP (Integer). Ej: `200`, `404`, `500`.
 - `duration_s`: Tiempo total de respuesta del servidor.
-- `[subsystem]_runtime_s`: Desglose opcional de tiempos por capa (ej: `db_runtime_s`, `view_runtime_s`).
+- `[subsystem]_runtime_s`: Desglose opcional por capa (ej: `db_runtime_s`, `view_runtime_s`).
 
 ---
 
@@ -87,26 +191,32 @@ Los logs de cierre de peticiones deben estandarizar el reporte de rendimiento pa
 
 **En el código fuente:**
 ```ruby
-# Reporte de éxito con métricas integradas
-logger.info "component=data_processor event=sync_complete status=success duration_s=1.25 record_count=500"
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+# ... operación ...
+duration_s = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
 
-# Reporte de error con contexto técnico
-logger.error "component=data_processor event=sync_complete status=failed error_class=Timeout error_message=\"Server reset\""
+logger.info "component=data_processor event=sync_complete status=success duration_s=#{duration_s} record_count=500"
+
+# En caso de error:
+rescue => e
+  logger.error "component=data_processor event=sync_complete status=failed error_class=#{e.class} error_message=\"#{e.message}\""
+end
 ```
 
-**Resultado JSON unificado:**
+**Resultado JSON unificado (emitido por ExisRay):**
 ```json
 {
   "time": "2026-03-24T14:00:00Z",
   "level": "INFO",
   "service": "my_application",
+  "root_id": "1-abc123",
+  "trace_id": "Root=1-abc123",
+  "source": "task",
+  "correlation_id": "my_application;1-abc123",
   "component": "data_processor",
   "event": "sync_complete",
   "status": "success",
   "duration_s": 1.25,
-  "record_count": 500,
-  "source": "task",
-  "root_id": "Root=1-...",
-  "correlation_id": "my_application;Root=..."
+  "record_count": 500
 }
 ```

data/lib/exis_ray/bug_bunny/consumer_tracing_middleware.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ExisRay
+  module BugBunny
+    # Consumer middleware para BugBunny que establece el trace context de ExisRay
+    # antes de que la gema empiece a procesar el mensaje.
+    #
+    # Al correr en el consumer middleware stack (antes de `consumer.message_received`),
+    # garantiza que **todos** los logs internos de BugBunny y del controller action
+    # incluyan `root_id`, `trace_id` y `source`.
+    #
+    # Se registra automáticamente al cargar ExisRay con BugBunny presente.
+    # El usuario final no necesita configuración adicional.
+    #
+    # @example Registro automático (ocurre en Railtie#after_initialize)
+    #   BugBunny.consumer_middlewares.use ExisRay::BugBunny::ConsumerTracingMiddleware
+    class ConsumerTracingMiddleware < ::BugBunny::ConsumerMiddleware::Base
+      # Inyecta el trace context antes de delegar al siguiente middleware.
+      # Limpia el contexto en `ensure` para no contaminar el próximo mensaje.
+      #
+      # @param delivery_info [Bunny::DeliveryInfo]
+      # @param properties    [Bunny::MessageProperties]
+      # @param body          [String]
+      def call(delivery_info, properties, body)
+        setup_trace_context(properties)
+        @app.call(delivery_info, properties, body)
+      ensure
+        ExisRay::Tracer.reset rescue nil
+      end
+
+      private
+
+      # Hidrata el Tracer con el header de traza del mensaje entrante.
+      # Si no hay header (mensaje publicado sin trace context), genera un root_id nuevo
+      # para que los logs siempre tengan contexto de trazabilidad.
+      #
+      # @param properties [Bunny::MessageProperties]
+      # @return [void]
+      def setup_trace_context(properties)
+        trace_header = properties.headers&.[](ExisRay.configuration.propagation_trace_header)
+
+        if trace_header.present?
+          ExisRay::Tracer.hydrate(trace_id: trace_header, source: 'system')
+        else
+          ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ExisRay::Tracer.source     = 'system'
+          ExisRay::Tracer.root_id    = ExisRay::Tracer.send(:generate_new_root)
+        end
+
+        ExisRay.sync_correlation_id
+      rescue StandardError
+        # El tracing nunca debe interrumpir el procesamiento del mensaje.
+      end
+    end
+  end
+end

data/lib/exis_ray/json_formatter.rb

@@ -148,7 +148,7 @@ module ExisRay
     end
 
     # Filtra un valor si la clave se considera sensible.
-    # Si no es sensible, intenta castear el valor a número si corresponde.
+    # Si no es sensible, intenta castear el valor a número o a objeto JSON si corresponde.
     #
     # @param key [String, Symbol]
     # @param value [Object]
@@ -159,10 +159,24 @@ module ExisRay
       case value
       when /\A\d+\z/ then value.to_i
       when /\A\d+\.\d+\z/ then value.to_f
-      else value
+      else try_parse_json(value)
       end
     end
 
+    # Intenta parsear un string como JSON si parece un objeto o array.
+    # Permite que valores como queue_opts={"exclusive":false} se emitan como
+    # objetos JSON en lugar de strings escapados.
+    #
+    # @param value [Object]
+    # @return [Object] El objeto parseado o el valor original si no es JSON válido.
+    def try_parse_json(value)
+      return value unless value.is_a?(String) && (value.start_with?("{") || value.start_with?("["))
+
+      JSON.parse(value)
+    rescue JSON::ParserError
+      value
+    end
+
     # Filtra recursivamente un Hash que contenga claves sensibles.
     # Maneja valores anidados de tipo Hash o Array.
     #

data/lib/exis_ray/railtie.rb

@@ -44,6 +44,31 @@ module ExisRay
         log_boot("component=exis_ray event=json_logging_enabled")
       end
 
+      # --- Integración BugBunny ---
+      if defined?(::BugBunny)
+        require "exis_ray/bug_bunny/publisher_tracing"
+        require "exis_ray/bug_bunny/consumer_tracing_middleware"
+        ::BugBunny.consumer_middlewares.use ExisRay::BugBunny::ConsumerTracingMiddleware
+        ::BugBunny.configuration.rpc_reply_headers = lambda {
+          next {} unless ExisRay::Tracer.root_id.present?
+
+          { ExisRay.configuration.propagation_trace_header => ExisRay::Tracer.generate_trace_header }
+        }
+        ::BugBunny.configuration.on_rpc_reply = lambda { |headers|
+          begin
+            trace_header = headers&.[](ExisRay.configuration.propagation_trace_header)
+            next unless trace_header.present?
+
+            # Solo actualizamos trace_id — no tocamos created_at ni source del publisher.
+            ExisRay::Tracer.trace_id = trace_header
+            ExisRay::Tracer.parse_trace_id
+            ExisRay.sync_correlation_id
+          rescue StandardError
+          end
+        }
+        log_boot("component=exis_ray event=bug_bunny_instrumented")
+      end
+
       # --- Instrumentación de ActiveResource ---
       if defined?(ActiveResource::Base)
         require "exis_ray/active_resource_instrumentation"

data/lib/exis_ray/version.rb

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

data/lib/exis_ray.rb

@@ -24,13 +24,6 @@ require "exis_ray/faraday_middleware" if defined?(Faraday)
 # Solo cargamos la instrumentación si ActiveResource está presente.
 require "exis_ray/active_resource_instrumentation" if defined?(ActiveResource::Base)
 
-# Integraciones BugBunny: publisher middleware y consumer concern.
-# Solo se cargan si la gema BugBunny está presente.
-if defined?(::BugBunny)
-  require "exis_ray/bug_bunny/publisher_tracing"
-  require "exis_ray/bug_bunny/consumer_tracing"
-end
-
 # Integración automática con Rails
 # Solo cargamos el Railtie si la constante Rails está definida.
 require "exis_ray/railtie" if defined?(Rails)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.9
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -45,6 +45,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/commands/release.md"
+- ".claude/skills/opentelemetry/SKILL.md"
+- ".claude/skills/rails-expert/SKILL.md"
+- ".claude/skills/readme-writer/SKILL.md"
+- ".claude/skills/rubocop-omakase/SKILL.md"
+- ".claude/skills/yard/SKILL.md"
 - ".gemini/docs/TELEMETRY_GUIDELINES.md"
 - CHANGELOG.md
 - CLAUDE.md
@@ -54,7 +60,7 @@ files:
 - Rakefile
 - lib/exis_ray.rb
 - lib/exis_ray/active_resource_instrumentation.rb
-- lib/exis_ray/bug_bunny/consumer_tracing.rb
+- lib/exis_ray/bug_bunny/consumer_tracing_middleware.rb
 - lib/exis_ray/bug_bunny/publisher_tracing.rb
 - lib/exis_ray/configuration.rb
 - lib/exis_ray/current.rb

data/lib/exis_ray/bug_bunny/consumer_tracing.rb

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