bug_bunny 4.8.0 → 4.9.0

data/CLAUDE.md

@@ -6,235 +6,38 @@ BugBunny es una gema Ruby que implementa una capa de enrutamiento RESTful sobre
 
 **Problema que resuelve:** Eliminar el acoplamiento directo entre microservicios via HTTP, usando RabbitMQ como bus de mensajes con la misma ergonomía de un framework web.
 
-## Knowledge Base
-
-- **Docs AI:** `docs/ai/` — conocimiento estructurado para agentes
-- **Index:** `docs/ai/_index.md` — manifest con versión, audiencias y archivos
-- **Docs humanos:** `docs/_index.md` — manifest de toda la documentación (`howto/`, `concepts.md`)
-
-## Skills disponibles
-
-- `.agents/skills/rabbitmq-expert/` — arquitectura AMQP, exchanges, quorum queues, DLX, HA, clustering
-
----
-
-## Arquitectura
-
-```
-Publisher (Client/Resource)
-  └─ Producer → Session → Bunny → RabbitMQ Exchange
-                                        │
-                                   RabbitMQ Queue
-                                        │
-Consumer (subscribe loop)
-  └─ ConsumerMiddleware::Stack
-       └─ process_message
-            └─ Router → Controller → Action
-                              └─ reply (RPC)
-```
-
-### Componentes clave
-
-| Clase | Responsabilidad |
-|---|---|
-| `BugBunny::Session` | Wrapper de canal Bunny. Declara exchanges y queues. |
-| `BugBunny::Consumer` | Subscribe loop. Rutea mensajes a controladores via `BugBunny.routes`. |
-| `BugBunny::ConsumerMiddleware::Stack` | Pipeline de middlewares antes de `process_message`. |
-| `BugBunny::Producer` | Publica mensajes. Implementa RPC con `Concurrent::IVar`. |
-| `BugBunny::Client` | API de alto nivel para el publicador. Pool de conexiones. |
-| `BugBunny::Controller` | Base class tipo Rails. `around_action`, `before_action`, `render`. |
-| `BugBunny::Resource` | ActiveRecord-like sobre AMQP. `find`, `where`, `create`, etc. |
-| `BugBunny::Request` | Value object del mensaje saliente (path, method, params, headers). |
-| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log`, `exception_metadata`. |
-| `BugBunny::Configuration` | Configuración global. Logger, timeouts, middleware hooks. |
-
-### Flujo RPC completo
-
-1. `Resource.find(id)` → `Client#request` → `Producer#rpc`
-2. Producer publica en exchange con `reply_to: 'amq.rabbitmq.reply-to'`
-3. `Concurrent::IVar` bloquea el thread principal (`future.value(timeout)`)
-4. Consumer recibe → middleware stack → controller → `reply(response)`
-5. Reply listener thread setea `future.set({ body:, headers: })`
-6. Thread principal: `on_rpc_reply&.call(headers)` → `parse_response(body)`
-
-## Hooks de extensión
-
-```ruby
-# Middleware antes de process_message (ej: tracing, auth)
-BugBunny.consumer_middlewares.use MyMiddleware
-
-# Headers a inyectar en el reply RPC (ej: trace context actualizado)
-config.rpc_reply_headers = -> { { 'X-Amzn-Trace-Id' => Tracer.header } }
-
-# Callback en el thread principal al recibir el reply (ej: hidratar tracer)
-config.on_rpc_reply = ->(headers) { Tracer.hydrate(headers['X-Amzn-Trace-Id']) }
-```
-
----
-
-## Dominio y Expertise
-
-Al trabajar en esta gema aplicá expertise en:
-
-- **Ruby idiomático**: módulos, mixins, metaprogramación, `class_attribute`, `Concurrent::*`
-- **RabbitMQ / AMQP**: exchanges (direct/topic/fanout), queues, bindings, `reply_to`, `correlation_id`, `properties.headers`, publisher confirms, manual ack
-- **Bunny**: la gema Ruby que wrappea AMQP. `channel`, `basic_consume`, `basic_publish`, `IVar`
-- **Rails patterns**: `ActiveModel`, `ActiveSupport`, `class_attribute`, `concerns`, `constantize`
-- **Rack**: `Rack::Utils.parse_nested_query`, `build_nested_query`
-
----
-
-## Observability — Estándar de Logging
-
-Esta gema implementa su propio patrón de observability via `BugBunny::Observability`.
-
-### Reglas fundamentales
-
-- **Formato**: `component=x event=clase.evento [key=value ...]` — todo en una línea
-- **Nunca** llamar al logger directamente. Siempre usar `safe_log`
-- **Nunca** `Kernel#warn`, `$stderr`, `puts`
-- **Niveles**: `ERROR`=excepción, `WARN`=inesperado+continuó, `INFO`=normal, `DEBUG`=detalle
-- `DEBUG` siempre en bloque: `logger.debug { "k=#{v}" }` — `safe_log` lo maneja internamente
-- Duraciones: `Process.clock_gettime(Process::CLOCK_MONOTONIC)`, nunca `Time.now`
-- Logger failures **nunca** interrumpen el flujo — `safe_log` tiene `rescue StandardError`
-
-### Uso en clases nuevas
-
-```ruby
-class BugBunny::MiClase
-  include BugBunny::Observability
-
-  def initialize
-    @logger = BugBunny.configuration.logger
-  end
-
-  def mi_metodo
-    start = monotonic_now
-    # ...
-    safe_log(:info, "mi_clase.mi_evento", campo: valor, duration_s: duration_s(start))
-  rescue StandardError => e
-    safe_log(:error, "mi_clase.error", **exception_metadata(e))
-  end
-end
-```
-
-### Naming de eventos
-
-Formato estricto: `"clase.evento"` (string, nunca symbol)
+## Documentación
 
-| Evento | Nivel | Cuándo |
-|---|---|---|
-| `consumer.start` | INFO | Consumer inicia subscribe |
-| `consumer.bound` | INFO | Queue bindeada al exchange |
-| `consumer.message_received` | INFO | Mensaje recibido, antes del routing |
-| `consumer.route_matched` | DEBUG | Ruta encontrada |
-| `consumer.message_processed` | INFO | Procesamiento exitoso con duración |
-| `consumer.execution_error` | ERROR | Excepción en el procesamiento |
-| `producer.publish` | INFO | Mensaje publicado |
-| `producer.rpc_waiting` | DEBUG | Bloqueando esperando respuesta |
-| `producer.rpc_response_received` | DEBUG | Reply recibido (thread principal) |
+- **Para humanos**: `docs/` (5 archivos) + `README.md`. Ver README para índice.
+- **Para agentes AI**: `skill/SKILL.md` + `skill/references/`. Es la skill empaquetada que otros proyectos consumen via `skill-manager sync`.
+- **Nunca referenciar `skill/` desde `docs/` o `README.md`** — son audiencias distintas.
 
-### Campos estándar
-
-```ruby
-safe_log(:error, "clase.error", **exception_metadata(e))
-# => error_class: "RuntimeError", error_message: "..."
-
-safe_log(:info, "clase.evento", duration_s: duration_s(start_time))
-# => duration_s: 0.001234
-
-# Valores sensibles se filtran automáticamente:
-# password, token, secret, api_key, auth → [FILTERED]
-```
-
----
+## Knowledge Base
+- Las skills en `.agents/skills/` incluyen conocimiento de dependencias.
+- Leer la skill de una dependencia ANTES de responder sobre ella.
+- Rebuild: `ruby .agents/skills/skill-manager/scripts/sync.rb`
 
-## Standards de Código
+### Entorno
+- Versión de Ruby: leer `.ruby-version`
+- Versión de Rails y gemas: leer `Gemfile.lock`
+- Gestor de Ruby: chruby (no usar rvm ni rbenv)
+- Package manager: Bundler
 
 ### RuboCop
-
-Esta gema usa **rubocop-rails-omakase**. Todo código nuevo o modificado debe cumplir.
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-bundle exec rubocop
-bundle exec rubocop -a   # autocorrect
-```
-
-**No corregir código existente no tocado.** Solo el código nuevo o modificado en el PR.
+- Usamos rubocop-rails-omakase como base.
+- Correr `bundle exec rubocop -a` antes de commitear.
+- No deshabilitar cops sin justificación en el PR.
 
 ### YARD
-
-Todo método público nuevo o modificado lleva documentación YARD:
-
-```ruby
-# Descripción breve.
-#
-# Descripción extendida si es necesario.
-#
-# @param name [Type] Descripción
-# @return [Type] Descripción
-# @raise [ErrorClass] Cuándo se lanza
-# @example
-#   resultado = mi_metodo(arg)
-def mi_metodo(name)
-```
-
-```bash
-bundle exec yard doc
-bundle exec yard stats --list-undoc
-```
-
-### RSpec
-
-Tests en `spec/`. Sin mocks de dependencias externas reales (RabbitMQ se mockea con doubles de Bunny).
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-bundle exec rspec
-bundle exec rspec spec/bug_bunny/consumer_spec.rb   # archivo específico
-```
-
----
-
-## Entorno de Desarrollo
-
-### Ruby
-
-```bash
-source /opt/homebrew/opt/chruby/share/chruby/chruby.sh && chruby ruby-3.3.8
-```
-
-Nunca usar `bundle exec ruby` con el Ruby del sistema (2.6). Siempre sourcear chruby primero.
-
-### Worktrees
-
-- **Main**: `/Users/gabriel/src/gems/bug_bunny` (rama `main`)
-- **Work**: `/Users/gabriel/src/gems/worktrees/current-5n3` (ramas de feature)
-- `main` está checkeado en otro worktree — no se puede hacer `git checkout main` desde el worktree de trabajo
-
-### Push a remoto
-
-SSH está roto en este entorno. Para push siempre:
-
-```bash
-git remote set-url origin https://github.com/gedera/bug_bunny.git
-git push origin main
-git remote set-url origin git@github.com:gedera/bug_bunny.git   # restaurar
-```
-
----
-
-## Release Workflow
-
-Usá el comando `/release` para el flujo completo. Manualmente:
-
-1. Determinar tipo: `patch`=bugfix, `minor`=feature nueva, `major`=breaking change
-2. Actualizar `lib/bug_bunny/version.rb`
-3. Agregar entrada al tope de `CHANGELOG.md`
-4. Commit con mensaje convencional
-5. Desde `/Users/gabriel/src/gems/bug_bunny`: `git merge --ff-only <branch>`
-6. Push via HTTPS + restaurar SSH
-7. `git tag vX.Y.Z && git push origin vX.Y.Z`
-
-**Nunca commitear ni pushear sin permiso explícito del usuario.**
+- Documentación incremental: si tocás un método, documentalo con YARD.
+- Consultar la skill `yard` para tags y tipos correctos.
+- Verificar cobertura: `bundle exec yard stats --list-undoc`
+
+### Testing
+- Framework: RSpec
+- Correr: `bundle exec rspec`
+- Todo código nuevo debe tener tests.
+
+### Releases o Nuevas versiones
+- Usar `/gem-release` para publicar nuevas versiones.
+- El GitHub Action publica a RubyGems automáticamente al pushear un tag `v*`.

data/README.md

@@ -214,15 +214,17 @@ BugBunny.consumer_middlewares.use TracingMiddleware
 
 ## Observability
 
-All internal events are emitted as structured key=value logs compatible with Datadog, CloudWatch, and ELK.
+BugBunny implementa de forma nativa las [OpenTelemetry semantic conventions for messaging](https://opentelemetry.io/docs/specs/otel/trace/semantic-conventions/messaging/), inyectando automáticamente campos como `messaging_system`, `messaging_operation`, `messaging_destination_name` y `messaging_message_id` tanto en los headers AMQP como en los log events estructurados.
+
+Todos los eventos internos se emiten como logs `key=value` compatibles con Datadog, CloudWatch, ELK y ExisRay.
 
 ```
-component=bug_bunny event=consumer.message_processed status=200 duration_s=0.012 controller=NodesController action=show
+component=bug_bunny event=consumer.message_processed status=200 duration_s=0.012 messaging_operation=process controller=NodesController action=show
 component=bug_bunny event=consumer.execution_error error_class=RuntimeError error_message="..." duration_s=0.003
 component=bug_bunny event=consumer.connection_error attempt_count=2 retry_in_s=10 error_message="..."
 ```
 
-Sensitive keys (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) are automatically filtered to `[FILTERED]` in all log output.
+Las claves sensibles (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) se filtran automáticamente a `[FILTERED]` en toda la salida de logs.
 
 ---
 

data/lib/bug_bunny/consumer.rb

@@ -152,6 +152,15 @@ module BugBunny
     def process_message(delivery_info, properties, body)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+      # Campos OTel semantic conventions para los log events del consumer.
+      # Se mergean con ** en los safe_log de recepción y procesamiento.
+      otel_fields = BugBunny::OTel.messaging_headers(
+        operation: 'process',
+        destination: delivery_info.exchange,
+        routing_key: delivery_info.routing_key,
+        message_id: properties.correlation_id
+      )
+
       # 1. Validación de Headers (URL path)
       path = properties.type || (properties.headers && properties.headers['path'])
 
@@ -166,7 +175,7 @@ module BugBunny
       http_method = (headers_hash['x-http-method'] || headers_hash['method'] || 'GET').to_s.upcase
 
       safe_log(:info, 'consumer.message_received', method: http_method, path: path,
-                                                   routing_key: delivery_info.routing_key)
+                                                   routing_key: delivery_info.routing_key, **otel_fields)
       safe_log(:debug, 'consumer.message_received_body', body: body.truncate(200))
 
       # ===================================================================
@@ -239,10 +248,11 @@ module BugBunny
       session.channel.ack(delivery_info.delivery_tag)
 
       safe_log(:info, 'consumer.message_processed',
-               status: response_payload[:status],
+               response_status: response_payload[:status],
                duration_s: duration_s(start_time),
                controller: controller_class_name,
-               action: route_info[:action])
+               action: route_info[:action],
+               **otel_fields)
     rescue StandardError => e
       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(' | '))
@@ -257,14 +267,20 @@ 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)
-      safe_log(:debug, 'consumer.rpc_reply', reply_to: reply_to, correlation_id: correlation_id)
+      safe_log(:debug, 'consumer.rpc_reply', reply_to: reply_to, messaging_message_id: correlation_id)
+      otel_headers = BugBunny::OTel.messaging_headers(
+        operation: 'publish',
+        destination: '',
+        routing_key: reply_to,
+        message_id: correlation_id
+      )
       extra_headers = BugBunny.configuration.rpc_reply_headers&.call || {}
       session.channel.default_exchange.publish(
         payload.to_json,
         routing_key: reply_to,
         correlation_id: correlation_id,
         content_type: 'application/json',
-        headers: extra_headers
+        headers: otel_headers.transform_keys(&:to_s).merge(extra_headers)
       )
     end
 

data/lib/bug_bunny/otel.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BugBunny
+  # Helpers para emitir campos siguiendo las OTel semantic conventions for messaging.
+  # https://opentelemetry.io/docs/specs/otel/trace/semantic-conventions/messaging/
+  #
+  # Se usa tanto en el lado publisher (inyección en headers AMQP) como en el consumer
+  # (enriquecimiento de log events estructurados). Centraliza las claves para evitar
+  # strings mágicos dispersos y facilitar los tests.
+  module OTel
+    # Clave: sistema de mensajería. Siempre `"rabbitmq"` en BugBunny.
+    # Flat-naming siguiendo el patrón de ExisRay (underscore sin dots).
+    SYSTEM = :messaging_system
+    # Clave: tipo de operación (`publish`, `receive`, `process`).
+    OPERATION = :messaging_operation
+    # Clave: nombre del exchange destino.
+    DESTINATION = :messaging_destination_name
+    # Clave: routing key del mensaje (específica de RabbitMQ).
+    ROUTING_KEY = :messaging_routing_key
+    # Clave: identificador único del mensaje. En BugBunny se mapea a `correlation_id`.
+    MESSAGE_ID = :messaging_message_id
+
+    # Valor constante para {SYSTEM}.
+    SYSTEM_VALUE = 'rabbitmq'
+
+    # Construye el hash de campos OTel para messaging.
+    #
+    # Los campos son aptos tanto para inyectar en headers AMQP como para mergear
+    # en kwargs de log events estructurados.
+    #
+    # @param operation [String] Una de: `"publish"`, `"receive"`, `"process"`.
+    # @param destination [String, nil] Nombre del exchange destino (puede ser `""` para default exchange).
+    # @param routing_key [String, nil] Routing key final del mensaje.
+    # @param message_id [String, nil] Identificador del mensaje. Se omite si es `nil`.
+    # @return [Hash{String=>String}] Hash con los campos OTel de messaging.
+    def self.messaging_headers(operation:, destination:, routing_key:, message_id: nil)
+      fields = {
+        SYSTEM => SYSTEM_VALUE,
+        OPERATION => operation,
+        DESTINATION => destination.to_s,
+        ROUTING_KEY => routing_key.to_s
+      }
+      fields[MESSAGE_ID] = message_id.to_s if message_id
+      fields
+    end
+  end
+end

data/lib/bug_bunny/producer.rb

@@ -79,7 +79,7 @@ module BugBunny
       begin
         fire(request)
 
-        safe_log(:debug, 'producer.rpc_waiting', correlation_id: cid, timeout_s: wait_timeout)
+        safe_log(:debug, 'producer.rpc_waiting', messaging_message_id: cid, timeout_s: wait_timeout)
 
         # Bloqueamos el hilo aquí hasta que llegue la respuesta o expire el timeout
         result = future.value(wait_timeout)
@@ -88,7 +88,8 @@ module BugBunny
 
         BugBunny.configuration.on_rpc_reply&.call(result[:headers])
 
-        safe_log(:debug, 'producer.rpc_response_received', correlation_id: cid)
+        safe_log(:debug, 'producer.rpc_response_received',
+                 messaging_system: 'rabbitmq', messaging_operation: 'receive', messaging_message_id: cid)
 
         parse_response(result[:body])
       ensure
@@ -109,13 +110,21 @@ module BugBunny
       rk = request.final_routing_key
       id = request.correlation_id
 
+      otel_fields = BugBunny::OTel.messaging_headers(
+        operation: 'publish',
+        destination: request.exchange,
+        routing_key: rk,
+        message_id: id
+      )
+
       # 📊 LOGGING DE OBSERVABILIDAD: Calculamos las opciones finales para mostrarlas en consola
       final_x_opts = BugBunny::Session::DEFAULT_EXCHANGE_OPTIONS
                      .merge(BugBunny.configuration.exchange_options || {})
                      .merge(request.exchange_options || {})
 
-      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(:info, 'producer.publish', method: verb, path: target, **otel_fields)
+      safe_log(:debug, 'producer.publish_detail', messaging_destination_name: request.exchange,
+                                                  exchange_opts: final_x_opts)
       safe_log(:debug, 'producer.publish_payload', payload: payload.truncate(300)) if payload.is_a?(String)
     end
 

data/lib/bug_bunny/request.rb

@@ -86,10 +86,22 @@ module BugBunny
     # **Importante:** Inyecta el verbo HTTP en los headers bajo la clave `x-http-method`.
     # Esto permite al Consumer enrutar correctamente a la acción del controlador.
     #
+    # También inyecta los campos de OTel semantic conventions for messaging
+    # (ver {BugBunny::OTel}) con `operation=publish`. Los headers del usuario
+    # pueden sobrescribir los valores OTel (escape hatch); `x-http-method`
+    # nunca se pisa porque es lo último en el merge.
+    #
     # @return [Hash] Opciones listas para pasar a `exchange.publish`.
     def amqp_options
-      # Inyectamos el verbo HTTP en los headers para el Router del Consumer
-      final_headers = headers.merge('x-http-method' => method.to_s.upcase)
+      otel_headers = BugBunny::OTel.messaging_headers(
+        operation: 'publish',
+        destination: exchange,
+        routing_key: final_routing_key,
+        message_id: correlation_id
+      )
+      # Orden del merge: OTel base -> headers del usuario -> x-http-method (inmutable)
+      # OTel keys son symbols internamente; los stringificamos para Bunny AMQP headers.
+      final_headers = otel_headers.transform_keys(&:to_s).merge(headers).merge('x-http-method' => method.to_s.upcase)
 
       {
         type: final_type,

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '4.8.0'
+  VERSION = '4.9.0'
 end

data/lib/bug_bunny.rb

@@ -6,6 +6,7 @@ require_relative 'bug_bunny/version'
 require_relative 'bug_bunny/exception'
 require_relative 'bug_bunny/configuration'
 require_relative 'bug_bunny/observability'
+require_relative 'bug_bunny/otel'
 require_relative 'bug_bunny/routing/route_set'
 require_relative 'bug_bunny/middleware/base'
 require_relative 'bug_bunny/middleware/stack'