exis_ray 0.5.8 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 327a3ed9c5558bba99acba81d3a3b328a271c16f4725c88a435f08ea8b1526a8
-  data.tar.gz: 661cf580101b617b50b565ec342f8a09d8da5a4b8c4d8c11163ea5000236a64e
+  metadata.gz: f17193f5df75197d569fbe74d8b27e55b116e861bdb819f1e92526a1da79869e
+  data.tar.gz: e8e45998cb83236c3bb7cc3a981995ccd36764fdb6fbc1465e796a7966e3b354
 SHA512:
-  metadata.gz: d23f08bf5951c9efa611c09a2ba3654ae8763b5bff0e4706ae68f540f52f3668b0c8b6f9bb4c076ba9ad6aff05df50de40f3d0c2e1b69ebd0aaafed6dcdafce2
-  data.tar.gz: 9514884ededf873b309345eee8d6e217c6b16b49ba194b55d68825f8a544d907da6d6d624a620223653249da21c12a91de1efe235bb4e39ea5f97c95be15d11d
+  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,13 @@
+## [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

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/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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.5.8
+  version: 0.5.9
 platform: ruby
 authors:
 - Gabriel Edera
@@ -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