bug_bunny 4.12.0 → 4.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e38ff38727e34da253f669937054e58f4bda0d5a42ce270cc9ac1e7853d8feb
-  data.tar.gz: 47b090304aaf7743addd2136c963d82ea8fd67bb82a17aad8958551047b79015
+  metadata.gz: 6081a471e20278bc190a7d7517b69cf6fe6d852293bca353974c5ba1cbe4e746
+  data.tar.gz: 2e1b952c9627b7f3f1f9ab1e2af25af49ca0422ff59f062ac7499c14265d6a57
 SHA512:
-  metadata.gz: 1811143e41e170668c68f8a4b57721c4e9e6111145c253f62e09c5653027e75ee32d6432ac950a54b80a5e4f282ca1a64f184535935c5b1dad7f8df4bac12593
-  data.tar.gz: b896459d25cea7925eaa3a010aa85cd5bcd302ab6f4551eb5b6d4cad554f4478050476e7cd9a4980590343d6a65e9822b10a7f864378117778b543f665ce9eb2
+  metadata.gz: 6cf7de01b98c925c8f02de1e09aafc0113f24f93145498ace1616445deecf6319bde3464d9afcd89b5b461904fbe878d4bfb24ea3a2a310149a32f6f2b06f4d0
+  data.tar.gz: 2560004c6036b238456fe9c9af9bf478dde67b1ff07240fdac942ecab303467d1db04f3029c2579463e5017b7c9f25ad2e5f1c5ef2c999f86bcde0bedb42eb67

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [4.14.0] - 2026-05-12
+
+### Nuevas funcionalidades
+- **Duraciones medidas internamente en el Producer:** BugBunny ahora emite `duration_s` automáticamente en los eventos del publisher siguiendo las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`Float` en segundos). El código de aplicación ya no necesita envolver `client.publish` con `Process.clock_gettime`. — @Gabriel
+  - `producer.published` (INFO): `duration_s` del `basic_publish` (TCP enqueue al broker, sin esperar ACK).
+  - `producer.confirmed` (INFO): tres duraciones desglosadas — `publish_duration_s`, `confirm_duration_s` (espera de `wait_for_confirms`) y `duration_s` total. Útil para distinguir latencia de red vs latencia del confirm policy del broker.
+  - `producer.rpc_response_received`: ahora incluye `duration_s` con el round-trip RPC completo (publish + procesamiento remoto + reply).
+
+### Cambios de comportamiento
+- **`producer.rpc_response_received` promovido de DEBUG a INFO.** No es breaking de API pero aumenta el volumen de logs en clientes RPC. Si el cambio impacta tu pipeline de observabilidad, filtralo por nivel.
+
+### Documentación
+- README + `skill/SKILL.md` + `skill/references/client-middleware.md` actualizados con el catálogo completo de eventos de log emitidos por la gema y la tabla de qué mide cada `duration_s`. Mensaje explícito en ambas audiencias (humana + agente) advirtiendo no duplicar la medición en código de aplicación.
+
+## [4.13.0] - 2026-05-11
+
+### Nuevas funcionalidades
+- **NACK explícito como excepción en modo `:confirmed` (#37):** `Producer#confirmed` ahora levanta `BugBunny::PublishNacked` cuando el broker NACKea la publicación, en lugar de retornar 202 silenciosamente. La excepción expone `path` y `nacked_count` para que callers críticos (auditoría, billing, RADIUS accounting) puedan escalar a HTTP 5xx y permitir retries upstream. Configurable globalmente vía `BugBunny.configuration.nack_raise` (default `true`) y por request via `client.publish(..., nack_raise: false)`. El evento `producer.confirms_nacked` se sigue logueando para observabilidad. — @Gabriel
+
+### Cambios de comportamiento (semi-breaking)
+- **Default `nack_raise: true`:** Publicaciones con `confirmed: true` que reciben NACK del broker ahora levantan excepción por default. En 4.12.0, el NACK se logueaba pero retornaba 202 igualmente — comportamiento que ocultaba pérdida de mensajes desde la perspectiva del publisher. Para mantener el comportamiento previo: `BugBunny.configuration.nack_raise = false` o `nack_raise: false` per request.
+
 ## [4.12.0] - 2026-05-11
 
 ### Nuevas funcionalidades

data/README.md

@@ -220,6 +220,9 @@ client.publish('acct.start',
 | `confirmed` | Boolean | `false` | Block until `wait_for_confirms` returns. |
 | `mandatory` | Boolean | `false` | Broker returns the message if it cannot be routed to any queue. Requires `confirmed: true` to be useful. |
 | `confirm_timeout` | Float | `nil` | Seconds to wait for the broker ACK. Raises `BugBunny::RequestTimeout` if exceeded. |
+| `nack_raise` | Boolean | `nil` | Per-request override of `config.nack_raise`. When `nil`, falls back to the global flag. |
+
+If the broker NACKs the publish (explicit rejection — disk full, internal confirm policy, etc.), the call raises `BugBunny::PublishNacked` by default. The exception exposes `path` and `nacked_count`. Critical publishers (audit, billing, RADIUS accounting) can let it bubble up to translate into HTTP 5xx so upstream systems retry. To restore the legacy "log-only" behaviour, set `BugBunny.configuration.nack_raise = false` globally or pass `nack_raise: false` per request.
 
 Unroutable returned messages are handled by a single global callback (see `config.on_return` below). The default handler logs them as `session.broker_return` at `warn` level — nothing is dropped silently.
 
@@ -249,11 +252,27 @@ BugBunny implementa de forma nativa las [OpenTelemetry semantic conventions for
 Todos los eventos internos se emiten como logs `key=value` compatibles con Datadog, CloudWatch, ELK y ExisRay.
 
 ```
+component=bug_bunny event=producer.publish method=POST path=acct/publish messaging_destination_name=acct_x messaging_routing_key=acct.start.42
+component=bug_bunny event=producer.published method=POST path=acct/publish routing_key=acct.start.42 messaging_message_id=corr-1 duration_s=0.000812
+component=bug_bunny event=producer.confirmed method=POST path=acct/publish routing_key=acct.start.42 publish_duration_s=0.000812 confirm_duration_s=0.012 duration_s=0.013
+component=bug_bunny event=producer.rpc_response_received method=GET path=users/42 duration_s=0.034 messaging_operation=receive
 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="..."
 ```
 
+### Duraciones medidas internamente
+
+BugBunny mide y emite duraciones automáticamente — **no es necesario envolver llamadas a `client.publish` con `Process.clock_gettime` en el código de aplicación**. Las unidades siguen las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`s`, segundos como `Float`).
+
+| Evento | Duración | Mide |
+|---|---|---|
+| `producer.published` | `duration_s` | Solo el `basic_publish` (TCP enqueue al broker). |
+| `producer.confirmed` | `publish_duration_s` + `confirm_duration_s` + `duration_s` (total) | Publish + espera de ACK del broker. |
+| `producer.rpc_response_received` | `duration_s` | Round-trip RPC completo (publish + procesamiento remoto + reply). |
+| `consumer.message_processed` | `duration_s` | Procesamiento del mensaje (router + controller + reply). |
+| `consumer.execution_error` | `duration_s` | Tiempo transcurrido hasta el error. |
+
 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/client.rb

@@ -93,9 +93,12 @@ module BugBunny
     # @option args [Boolean] :mandatory Si `true`, el broker retorna el mensaje si no es ruteable.
     #   Para procesar retornos, configurar {BugBunny.configuration.on_return}.
     # @option args [Float] :confirm_timeout Segundos a esperar el confirm. `nil` espera indefinidamente.
+    # @option args [Boolean] :nack_raise Override per-request del flag
+    #   `BugBunny.configuration.nack_raise`. Si `nil` (default), se usa la configuración global.
     # @yield [req] Bloque para configurar el objeto Request.
     # @return [Hash] `{ 'status' => 202, 'body' => nil }`.
     # @raise [BugBunny::RequestTimeout] Si `confirmed: true` y el broker no confirma a tiempo.
+    # @raise [BugBunny::PublishNacked] Si `confirmed: true`, el broker NACKea, y `nack_raise` resuelto es true.
     def publish(url, **args)
       send(url, **args) do |req|
         req.delivery_mode = args[:confirmed] ? :confirmed : :publish
@@ -175,6 +178,7 @@ module BugBunny
     def apply_publisher_confirms_args(req, args)
       req.mandatory       = args[:mandatory]       if args.key?(:mandatory)
       req.confirm_timeout = args[:confirm_timeout] if args.key?(:confirm_timeout)
+      req.nack_raise      = args[:nack_raise]      if args.key?(:nack_raise)
     end
 
     # Recupera o crea la Session asociada al slot de conexión dado.

data/lib/bug_bunny/configuration.rb

@@ -153,6 +153,15 @@ module BugBunny
     #     }
     attr_accessor :on_return
 
+    # @return [Boolean] Si `true` (default), {BugBunny::Producer#confirmed} levanta
+    #   {BugBunny::PublishNacked} cuando el broker NACKea la publicación. Si `false`,
+    #   el NACK solo se logea como `producer.confirms_nacked` y la llamada retorna
+    #   `{ 'status' => 202 }` (modo legacy).
+    #
+    #   El valor puede sobreescribirse por request pasando `nack_raise:` en
+    #   `Client#publish`.
+    attr_accessor :nack_raise
+
     # @!endgroup
 
     # Inicializa la configuración con valores por defecto seguros.
@@ -194,9 +203,7 @@ module BugBunny
       @queue_options = {}
 
       @consumer_middlewares = ConsumerMiddleware::Stack.new
-      @rpc_reply_headers = nil
-      @on_rpc_reply = nil
-      @on_return = nil
+      init_callback_defaults
     end
 
     # Construye la URL de conexión AMQP basada en los atributos configurados.
@@ -223,6 +230,17 @@ module BugBunny
 
     private
 
+    # Defaults para callbacks y flags relacionados con publish/RPC.
+    # Extraído de {#initialize} para mantener el ABC size dentro de los límites.
+    #
+    # @return [void]
+    def init_callback_defaults
+      @rpc_reply_headers = nil
+      @on_rpc_reply = nil
+      @on_return = nil
+      @nack_raise = true
+    end
+
     def validate_required!(attr, value, rules)
       return unless rules[:required]
       return unless value.nil? || (value.is_a?(String) && value.empty?)

data/lib/bug_bunny/exception.rb

@@ -19,6 +19,37 @@ module BugBunny
   # Protege contra vulnerabilidades de RCE validando la herencia de las clases enrutadas.
   class SecurityError < Error; end
 
+  # Error lanzado cuando el broker responde NACK a una publicación en modo `:confirmed`.
+  #
+  # Un NACK significa que el broker rechazó explícitamente el mensaje (ej: política de
+  # confirms interna, disk full, replicación insuficiente). El mensaje no fue aceptado
+  # y se considera no entregado — equivalente a un fallo de transporte desde la
+  # perspectiva del publisher.
+  #
+  # Se levanta por default desde {BugBunny::Producer#confirmed}. Para opt-out,
+  # configurar `BugBunny.configuration.nack_raise = false` o pasar
+  # `nack_raise: false` por request.
+  #
+  # @example
+  #   rescue BugBunny::PublishNacked => e
+  #     e.path         # => 'acct.start'
+  #     e.nacked_count # => 1
+  class PublishNacked < Error
+    # @return [String] La ruta del request cuyo publish fue NACKeado.
+    attr_reader :path
+
+    # @return [Integer] Cantidad de mensajes NACKeados según `Bunny::Channel#nacked_set`.
+    attr_reader :nacked_count
+
+    # @param path [String] Ruta lógica del request (ej: 'acct.start').
+    # @param nacked_count [Integer] Cantidad de NACKs reportados por el broker.
+    def initialize(path:, nacked_count:)
+      @path = path
+      @nacked_count = nacked_count
+      super("broker NACK on path=#{path} (nacked=#{nacked_count})")
+    end
+  end
+
   # ==========================================
   # Categoría: Errores del Cliente (4xx)
   # ==========================================

data/lib/bug_bunny/producer.rb

@@ -52,14 +52,24 @@ module BugBunny
     # A diferencia de {#rpc} (que espera la respuesta de un Consumer remoto), aquí solo se
     # espera el ACK del propio broker — no hay round-trip al servicio destino.
     #
-    # @param request [BugBunny::Request] Request con `mandatory`, `confirm_timeout` y/o `on_return` opcionales.
+    # @param request [BugBunny::Request] Request con `mandatory`, `confirm_timeout`, `nack_raise`
+    #   y/o `on_return` opcionales.
     # @return [Hash] `{ 'status' => 202, 'body' => nil }` si el broker confirmó la recepción.
     # @raise [BugBunny::RequestTimeout] Si el broker no confirma dentro de `confirm_timeout` segundos.
+    # @raise [BugBunny::PublishNacked] Si el broker NACKea la publicación y `nack_raise` está activo
+    #   (default `true` — ver {BugBunny::Configuration#nack_raise}).
     # @raise [BugBunny::CommunicationError] Si el canal AMQP falla durante la publicación o confirm.
     def confirmed(request)
-      publish_message(request)
-      wait_for_confirms!(request)
-      log_nacks_if_any(request)
+      started_at = monotonic_now
+      publish_duration = publish_message(request)
+
+      confirm_started_at = monotonic_now
+      acked = wait_for_confirms!(request)
+      confirm_duration = duration_s(confirm_started_at)
+
+      handle_confirm_result(request, acked)
+      log_confirmed(request, publish_duration, confirm_duration, started_at)
+
       { 'status' => 202, 'body' => nil }
     rescue BugBunny::Error
       raise
@@ -87,6 +97,7 @@ module BugBunny
       future = Concurrent::IVar.new
       @pending_requests[cid] = future
 
+      started_at = monotonic_now
       begin
         fire(request)
 
@@ -98,11 +109,7 @@ module BugBunny
         raise BugBunny::RequestTimeout, "Timeout waiting for RPC: #{request.path} [#{request.method}]" if result.nil?
 
         BugBunny.configuration.on_rpc_reply&.call(result[:headers])
-
-        safe_log(:debug, 'producer.rpc_response_received',
-                 messaging_system: 'rabbitmq', messaging_operation: 'receive', messaging_message_id: cid,
-                 response_body: result[:body]&.truncate(500),
-                 response_headers: result[:headers]&.to_json&.truncate(300))
+        log_rpc_response_received(request, cid, result, started_at)
 
         parse_response(result[:body])
       ensure
@@ -116,8 +123,11 @@ module BugBunny
     # Resuelve exchange, serializa payload, logea y publica el mensaje.
     # Compartido por {#fire} y {#confirmed}.
     #
+    # Emite `producer.publish` antes y `producer.published` después con `duration_s`
+    # midiendo solo el `basic_publish` (TCP enqueue al broker, sin esperar ACK).
+    #
     # @param request [BugBunny::Request]
-    # @return [void]
+    # @return [Float] duración del publish en segundos.
     def publish_message(request)
       x = @session.exchange(
         name: request.exchange,
@@ -126,7 +136,43 @@ module BugBunny
       )
       payload = serialize_message(request.body)
       log_request(request, payload)
+
+      started_at = monotonic_now
       x.publish(payload, request.amqp_options.merge(routing_key: request.final_routing_key))
+      publish_duration = duration_s(started_at)
+
+      log_published(request, publish_duration)
+      publish_duration
+    end
+
+    # @api private
+    def log_published(request, publish_duration_s)
+      safe_log(:info, 'producer.published',
+               method: request.method.to_s.upcase, path: request.path,
+               routing_key: request.final_routing_key,
+               messaging_message_id: request.correlation_id,
+               duration_s: publish_duration_s)
+    end
+
+    # @api private
+    def log_rpc_response_received(request, cid, result, started_at)
+      safe_log(:info, 'producer.rpc_response_received',
+               method: request.method.to_s.upcase, path: request.path,
+               messaging_system: 'rabbitmq', messaging_operation: 'receive', messaging_message_id: cid,
+               duration_s: duration_s(started_at),
+               response_body: result[:body]&.truncate(500),
+               response_headers: result[:headers]&.to_json&.truncate(300))
+    end
+
+    # @api private
+    def log_confirmed(request, publish_duration_s, confirm_duration_s, started_at)
+      safe_log(:info, 'producer.confirmed',
+               method: request.method.to_s.upcase, path: request.path,
+               routing_key: request.final_routing_key,
+               messaging_message_id: request.correlation_id,
+               publish_duration_s: publish_duration_s,
+               confirm_duration_s: confirm_duration_s,
+               duration_s: duration_s(started_at))
     end
 
     # Espera la confirmación del broker con timeout opcional.
@@ -154,20 +200,44 @@ module BugBunny
             "Timeout (#{timeout}s) waiting for publisher confirms: #{request.path}"
     end
 
-    # Logea las nack-eadas del canal si las hay.
-    # NACK no es un error fatal: el broker rechazó rutear (ej. confirm policy interna),
-    # pero el mensaje no se perdió silenciosamente — queda en el set para auditoría.
+    # Procesa el resultado de `wait_for_confirms`.
+    #
+    # Si el broker NACKeó (`acked == false`), logea el evento `producer.confirms_nacked`
+    # y opcionalmente levanta {BugBunny::PublishNacked} según el flag `nack_raise`
+    # resuelto desde el request o la configuración global.
     #
     # @param request [BugBunny::Request]
+    # @param acked [Boolean] Resultado de `wait_for_confirms` (true = todos los confirms positivos).
+    # @raise [BugBunny::PublishNacked] Si hay NACK y `nack_raise?` es true.
     # @return [void]
-    def log_nacks_if_any(request)
+    def handle_confirm_result(request, acked)
+      return if acked
+
+      count = nacked_count
+      safe_log(:warn, 'producer.confirms_nacked', count: count, path: request.path)
+      return unless nack_raise?(request)
+
+      raise BugBunny::PublishNacked.new(path: request.path, nacked_count: count)
+    end
+
+    # Cuenta los delivery tags NACKeados reportados por el canal.
+    #
+    # @return [Integer]
+    def nacked_count
       ch = @session.channel
-      return unless ch.respond_to?(:nacked_set)
+      return 0 unless ch.respond_to?(:nacked_set)
+
+      ch.nacked_set&.size || 0
+    end
 
-      nacked = ch.nacked_set
-      return if nacked.nil? || nacked.empty?
+    # Resuelve el flag `nack_raise` con prioridad request > configuración global.
+    #
+    # @param request [BugBunny::Request]
+    # @return [Boolean]
+    def nack_raise?(request)
+      return request.nack_raise unless request.nack_raise.nil?
 
-      safe_log(:warn, 'producer.confirms_nacked', count: nacked.size, path: request.path)
+      BugBunny.configuration.nack_raise
     end
 
     # Registra la petición en el log calculando las opciones de infraestructura.

data/lib/bug_bunny/request.rb

@@ -27,6 +27,8 @@ module BugBunny
   #   vía {BugBunny.configuration.on_return}.
   # @attr confirm_timeout [Float, nil] Segundos máximos a esperar el `wait_for_confirms`.
   #   `nil` espera indefinidamente.
+  # @attr nack_raise [Boolean, nil] Override per-request del flag global
+  #   `BugBunny.configuration.nack_raise`. `nil` (default) delega a la configuración global.
   class Request
     attr_accessor :body, :headers, :params, :path, :method, :exchange, :exchange_type, :routing_key, :timeout,
                   :delivery_mode, :queue_options
@@ -35,7 +37,7 @@ module BugBunny
     attr_accessor :exchange_options
 
     # Publisher Confirms (delivery_mode = :confirmed)
-    attr_accessor :mandatory, :confirm_timeout
+    attr_accessor :mandatory, :confirm_timeout, :nack_raise
 
     # Metadatos AMQP Estándar
     attr_accessor :app_id, :content_type, :content_encoding, :priority,
@@ -63,6 +65,7 @@ module BugBunny
       # Defaults para Publisher Confirms (modo :confirmed)
       @mandatory = false
       @confirm_timeout = nil
+      @nack_raise = nil
     end
 
     # Combina el path con los params como query string.

data/lib/bug_bunny/version.rb

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

data/skill/SKILL.md

@@ -15,7 +15,7 @@ Skill de conocimiento completo sobre BugBunny. Consultame para cualquier pregunt
 **Session** — `BugBunny::Session` envuelve canales de Bunny con thread-safety y double-checked locking.
 **RPC** — Patrón síncrono que usa la pseudo-cola `amq.rabbitmq.reply-to` para respuestas sin crear queues temporales.
 **Fire-and-Forget** — Patrón asíncrono donde el producer publica y continúa sin esperar respuesta. Retorna `{ 'status' => 202 }`.
-**Publisher Confirms** — Extensión de RabbitMQ que confirma al publisher que el broker recibió el mensaje. BugBunny lo expone como `confirmed: true` en `Client#publish`: el publish bloquea hasta `wait_for_confirms`. NACK no es fatal; se logea pero el método retorna 202.
+**Publisher Confirms** — Extensión de RabbitMQ que confirma al publisher que el broker recibió el mensaje. BugBunny lo expone como `confirmed: true` en `Client#publish`: el publish bloquea hasta `wait_for_confirms`. NACK del broker (rechazo explícito) levanta `BugBunny::PublishNacked` por default; configurable via `config.nack_raise = false` o `nack_raise: false` per request para volver al modo log-only.
 **Mandatory** — Flag de `basic.publish` que pide al broker retornar el mensaje al publisher si no es ruteable a ninguna cola. Se procesa via `basic.return` (no es respuesta del request).
 **basic.return** — Evento asincrónico que Bunny dispatcha por exchange (`Bunny::Exchange#on_return`). BugBunny registra un handler único por nombre de exchange al resolverlo en `Session#exchange` y lo delega a `Configuration#on_return` o al default que logea.
 **Resource** — ORM tipo ActiveRecord que mapea operaciones CRUD a llamadas AMQP.
@@ -97,6 +97,37 @@ BugBunny implementa las [OpenTelemetry semantic conventions for messaging](https
 - **Consumer:** Extrae los campos de los logs estructurados sin mutar los headers originales. Los eventos `consumer.message_received` y `consumer.message_processed` incluyen estos campos automáticamente.
 - **RPC Reply:** El consumer inyecta los mismos campos en el reply para cerrar el ciclo de traza del lado del cliente.
 
+### Eventos de log y duraciones internas
+
+BugBunny mide y emite duraciones automáticamente. **No envolver llamadas a `client.publish` con `Process.clock_gettime` en código de aplicación** — duplica el trabajo. Las duraciones siguen las [OpenTelemetry metric semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/) (`duration_s` como `Float` en segundos).
+
+| Evento | Nivel | Emitido por | Campos clave |
+|---|---|---|---|
+| `producer.publish` | INFO | `Producer#publish_message` (pre) | `method`, `path`, `messaging_*` |
+| `producer.publish_payload` | INFO | `Producer#publish_message` | `payload` (truncado), `body_size` |
+| `producer.publish_detail` | DEBUG | `Producer#publish_message` | `exchange_opts` final |
+| `producer.published` | INFO | `Producer#publish_message` (post) | `method`, `path`, `routing_key`, `messaging_message_id`, **`duration_s`** (publish solo) |
+| `producer.confirmed` | INFO | `Producer#confirmed` (post-ACK) | `method`, `path`, `routing_key`, **`publish_duration_s`**, **`confirm_duration_s`**, **`duration_s`** (total) |
+| `producer.confirms_nacked` | WARN | `Producer#confirmed` (NACK) | `count`, `path` |
+| `producer.rpc_waiting` | DEBUG | `Producer#rpc` | `messaging_message_id`, `timeout_s` |
+| `producer.rpc_response_received` | INFO | `Producer#rpc` (reply recibido) | `method`, `path`, **`duration_s`** (round-trip total), `response_body` |
+| `producer.rpc_response_orphaned` | WARN | reply listener | `correlation_id` |
+| `consumer.message_received` | INFO | `Consumer#process_message` | `method`, `path`, `messaging_*` |
+| `consumer.message_processed` | INFO | `Consumer#process_message` (post) | `response_status`, **`duration_s`**, `controller`, `action`, `messaging_*` |
+| `consumer.execution_error` | ERROR | `Consumer#process_message` (rescue) | **`duration_s`**, `error_class`, `error_message` |
+| `consumer.route_not_found` | WARN | `Consumer#process_message` | `method`, `path` |
+| `consumer.connection_error` | ERROR | `Consumer#subscribe` (retry loop) | `attempt_count`, `retry_in_s`, `error_*` |
+| `session.broker_return` | WARN | `Session` (mandatory unrouted) | `reply_code`, `reply_text`, `exchange`, `routing_key` |
+
+**Resumen de qué mide cada `duration_s`:**
+
+- `producer.published.duration_s` — solo el `basic_publish` (TCP enqueue al broker).
+- `producer.confirmed.publish_duration_s` — el publish.
+- `producer.confirmed.confirm_duration_s` — la espera del ACK del broker (`wait_for_confirms`).
+- `producer.confirmed.duration_s` — total (publish + ACK).
+- `producer.rpc_response_received.duration_s` — round-trip RPC completo (publish + procesamiento remoto + reply).
+- `consumer.message_processed.duration_s` — procesamiento server-side (router + controller + reply).
+
 ---
 
 ## API: Configuración Global
@@ -202,7 +233,8 @@ client.publish('events', method: :post, body: { type: 'order.placed' })
 client.publish('acct.start', exchange: 'acct_x', body: payload,
                confirmed: true, mandatory: true, confirm_timeout: 0.5)
 # → { 'status' => 202, 'body' => nil }   # broker ACK confirmado
-# Si broker NACK: logea `producer.confirms_nacked` y retorna 202 igual (NACK ≠ pérdida).
+# Si broker NACK: logea `producer.confirms_nacked` y raise BugBunny::PublishNacked
+#   (default — opt-out con config.nack_raise = false o nack_raise: false per request).
 # Si timeout: raise BugBunny::RequestTimeout.
 # Si mandatory + no ruteable: dispara `Configuration#on_return` (default: logea `session.broker_return`).
 ```

data/skill/references/client-middleware.md

@@ -46,6 +46,7 @@ end
 | `confirmed` | Boolean | `false` | En `Client#publish`, flipea `delivery_mode` a `:confirmed`. Bloquea hasta `wait_for_confirms`. |
 | `mandatory` | Boolean | `false` | Pide al broker retornar el mensaje si no es ruteable. Solo útil con `confirmed: true`. |
 | `confirm_timeout` | Float | `nil` | Segundos máximos a esperar el ACK. `nil` = espera indefinida. Excedido → `BugBunny::RequestTimeout`. |
+| `nack_raise` | Boolean | `nil` | Override per-request de `config.nack_raise`. `nil` = usa flag global. |
 
 ## Producer (bajo nivel)
 
@@ -58,19 +59,22 @@ El `Producer` es usado internamente por el `Client`. Implementa tres patrones de
 - Reply listener (`basic_consume`) auto-iniciado en el primer RPC.
 - Double-checked locking mutex para seguridad del listener.
 - Timeout lanza `BugBunny::RequestTimeout`.
+- **Emite `producer.rpc_response_received` (INFO) con `duration_s` = round-trip total** (publish + procesamiento remoto + reply). No medir en código de aplicación.
 
 ### Fire-and-Forget (`Producer#fire`)
 
 - Publica en el exchange y retorna `{ 'status' => 202 }` inmediatamente.
 - Sin confirmación de procesamiento.
+- **Emite `producer.published` (INFO) con `duration_s`** = solo el `basic_publish` (TCP enqueue al broker).
 
 ### Confirmed (`Producer#confirmed`)
 
 - Publica y bloquea hasta `channel.wait_for_confirms` del broker.
 - Bunny 2.x **no soporta timeout** nativo en `wait_for_confirms` — BugBunny envuelve la llamada en un hilo auxiliar y usa `Concurrent::IVar#value(timeout)` como reloj. Si `confirm_timeout` expira → `BugBunny::RequestTimeout`.
-- NACK del broker no es fatal: se logea `producer.confirms_nacked` con `count` y `path`, y retorna 202 igual.
+- Si `wait_for_confirms` devuelve `false` (broker NACKea), se logea `producer.confirms_nacked` con `count` y `path`. Por default (`config.nack_raise = true`) levanta `BugBunny::PublishNacked` con `path` y `nacked_count`. Para opt-out: `config.nack_raise = false` o pasar `nack_raise: false` per request — en ese caso solo logea y retorna 202.
 - Si `mandatory: true` y el mensaje no es ruteable, el broker dispara `basic.return`. El handler se atacha vía `Bunny::Exchange#on_return` en `Session#exchange` la primera vez que se resuelve cada exchange (cacheado por nombre, una sola vez por canal) y delega a `Configuration#on_return` o al logger por default.
 - Errores del canal se envuelven en `BugBunny::CommunicationError`; errores `BugBunny::Error` pre-existentes se propagan sin envolver.
+- **Emite `producer.confirmed` (INFO) con tres duraciones desglosadas**: `publish_duration_s` (TCP enqueue), `confirm_duration_s` (`wait_for_confirms`), `duration_s` (total). Útil para distinguir latencia de red vs latencia de confirm policy del broker.
 
 ## Middleware Stack (Client-side, Onion Architecture)
 
@@ -164,6 +168,7 @@ req.timestamp             # Time.now.to_i
 req.content_type          # 'application/json'
 req.mandatory             # Boolean — solo modo :confirmed
 req.confirm_timeout       # Float|nil — solo modo :confirmed
+req.nack_raise            # Boolean|nil — override per-request de config.nack_raise (solo modo :confirmed)
 ```
 
 Cuando `mandatory == true`, `Request#amqp_options` inyecta `mandatory: true` en el hash que va a `basic_publish`.
@@ -182,7 +187,10 @@ Producer#confirmed
    │
    ├──> wait_for_confirms!  (espera ACK del broker, con timeout opcional)
    │
-   └──> log_nacks_if_any    (si nacked_set no está vacío → log WARN)
+   └──> handle_confirm_result
+            ├─ acked == true  → return { status: 202 }
+            └─ acked == false → log WARN producer.confirms_nacked
+                                  └─ raise BugBunny::PublishNacked  (si config.nack_raise || req.nack_raise)
 
 Asíncronamente, si el broker no pudo rutear:
    broker ──basic.return──> Exchange#on_return ──> Session handler ──> Configuration#on_return
@@ -221,7 +229,7 @@ Excepciones del callback se capturan y se logean como `session.on_return_failed`
 | Auditoría, billing, eventos críticos | `:confirmed` (con `mandatory: true` si es ruteable) |
 | Request-response síncrono | `:rpc` |
 
-`:confirmed` cuesta un round-trip al broker pero **no** al consumer remoto — más rápido que RPC, con garantía de entrega al broker. NACK del broker es raro (típicamente por confirm policies internas) y no implica pérdida del mensaje.
+`:confirmed` cuesta un round-trip al broker pero **no** al consumer remoto — más rápido que RPC, con garantía de entrega al broker. NACK del broker es raro (típicamente por confirm policies internas, disk full, replicación insuficiente) pero **sí** implica que el mensaje no fue aceptado. Por default BugBunny levanta `BugBunny::PublishNacked` para que el caller pueda escalar (ej: convertir a HTTP 503 y dejar que el sistema upstream reintente). Opt-out con `config.nack_raise = false` o `nack_raise: false` per request.
 
 ## Cascada de Configuración (3 niveles)
 

data/skill/references/errores.md

@@ -8,6 +8,7 @@ StandardError
     ├── BugBunny::CommunicationError
     ├── BugBunny::ConfigurationError
     ├── BugBunny::SecurityError
+    ├── BugBunny::PublishNacked
     ├── BugBunny::ClientError (4xx)
     │   ├── BugBunny::BadRequest (400)
     │   ├── BugBunny::NotFound (404)
@@ -37,6 +38,12 @@ StandardError
 **Cuándo:** El consumer resuelve la clase pero falla la validación `is_a?(BugBunny::Controller)`.
 **Resolución:** Verificar que el controlador herede de `BugBunny::Controller` y que `config.controller_namespace` sea correcto.
 
+### BugBunny::PublishNacked
+**Causa:** El broker NACKea explícitamente una publicación en modo `:confirmed` (`Client#publish(..., confirmed: true)`). Indica que el mensaje no fue aceptado — disk full, replicación insuficiente, confirm policy interna, etc.
+**Cuándo:** `Producer#confirmed` detecta `wait_for_confirms == false`. Se levanta por default (`config.nack_raise = true`).
+**Atributos:** `path` (ruta del request) y `nacked_count` (cantidad de delivery tags NACKeados).
+**Resolución:** Para casos críticos (auditoría, billing, RADIUS accounting), dejar que la excepción bubble para que el caller upstream reintente (ej: HTTP 503 → retry). Para tolerar NACKs (eventos best-effort), `BugBunny.configuration.nack_raise = false` global o `nack_raise: false` per request — en ese caso solo se logea `producer.confirms_nacked`.
+
 ## Errores de Cliente (4xx)
 
 ### BugBunny::BadRequest (400)

data/spec/unit/configuration_spec.rb

@@ -162,6 +162,18 @@ RSpec.describe BugBunny::Configuration do
     end
   end
 
+  describe 'nack_raise flag' do
+    it 'tiene default true (raise PublishNacked en NACK)' do
+      expect(BugBunny::Configuration.new.nack_raise).to be(true)
+    end
+
+    it 'acepta false para opt-out (modo legacy)' do
+      configure_with(nack_raise: false)
+
+      expect(BugBunny.configuration.nack_raise).to be(false)
+    end
+  end
+
   describe '.validate! directamente' do
     it 'es invocable directamente sobre la instancia' do
       config = BugBunny::Configuration.new

data/spec/unit/producer_spec.rb

@@ -95,6 +95,31 @@ RSpec.describe BugBunny::Producer do
           messaging_destination_name: 'events_x'
         )
       end
+
+      it 'producer.published incluye duration_s y campos de routing' do
+        request = BugBunny::Request.new('users')
+        request.exchange = 'users_x'
+        request.method = :post
+        request.correlation_id = 'corr-1'
+
+        fake_exchange = double('exchange')
+        allow(session).to receive(:exchange).and_return(fake_exchange)
+        allow(fake_exchange).to receive(:publish)
+
+        producer.fire(request)
+
+        published_event = logged_events.find { |e| e[:event] == 'producer.published' }
+        expect(published_event).not_to be_nil
+        expect(published_event[:level]).to eq(:info)
+        expect(published_event[:kwargs]).to include(
+          method: 'POST',
+          path: 'users',
+          routing_key: 'users',
+          messaging_message_id: 'corr-1'
+        )
+        expect(published_event[:kwargs][:duration_s]).to be_a(Numeric)
+        expect(published_event[:kwargs][:duration_s]).to be >= 0
+      end
     end
 
     describe '#rpc — log events incluyen campos OTel' do
@@ -182,6 +207,28 @@ RSpec.describe BugBunny::Producer do
           messaging_message_id: 'corr-reply-test'
         )
       end
+
+      it 'producer.rpc_response_received incluye duration_s total' do
+        request = BugBunny::Request.new('users')
+        request.exchange = 'users_x'
+        request.method = :get
+
+        allow(rpc_producer).to receive(:ensure_reply_listener!)
+
+        ivar = Concurrent::IVar.new
+        allow(Concurrent::IVar).to receive(:new).and_return(ivar)
+
+        request.correlation_id = 'corr-dur'
+        rpc_producer.instance_variable_get(:@pending_requests)['corr-dur'] = ivar
+
+        Thread.new { ivar.set({ body: '{"ok":true}', headers: {} }) }.join(0.1)
+
+        rpc_producer.rpc(request)
+
+        response_event = logged_events.find { |e| e[:event] == 'producer.rpc_response_received' }
+        expect(response_event[:kwargs][:duration_s]).to be_a(Numeric)
+        expect(response_event[:kwargs][:duration_s]).to be >= 0
+      end
     end
   end
 
@@ -245,21 +292,71 @@ RSpec.describe BugBunny::Producer do
       )
     end
 
-    it 'logea producer.confirms_nacked cuando hay nacks' do
-      allow(mock_channel).to receive(:nacked_set).and_return(Set.new([1, 2]))
-
+    it 'NO logea producer.confirms_nacked cuando wait_for_confirms devuelve true' do
       confirmed_producer.confirmed(build_request)
 
       nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
-      expect(nack_event).not_to be_nil
-      expect(nack_event[:kwargs]).to include(count: 2, path: 'acct.start')
+      expect(nack_event).to be_nil
     end
 
-    it 'NO logea producer.confirms_nacked cuando nacked_set está vacío' do
+    it 'logea producer.confirmed con publish_duration_s, confirm_duration_s y duration_s total' do
       confirmed_producer.confirmed(build_request)
 
-      nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
-      expect(nack_event).to be_nil
+      ev = logged_events.find { |e| e[:event] == 'producer.confirmed' }
+      expect(ev).not_to be_nil
+      expect(ev[:level]).to eq(:info)
+      expect(ev[:kwargs]).to include(method: 'POST', path: 'acct.start', routing_key: 'acct.start')
+      expect(ev[:kwargs][:publish_duration_s]).to be_a(Numeric)
+      expect(ev[:kwargs][:confirm_duration_s]).to be_a(Numeric)
+      expect(ev[:kwargs][:duration_s]).to be_a(Numeric)
+    end
+
+    context 'cuando el broker NACKea (wait_for_confirms devuelve false)' do
+      before do
+        allow(mock_channel).to receive(:wait_for_confirms).and_return(false)
+        allow(mock_channel).to receive(:nacked_set).and_return(Set.new([1, 2]))
+      end
+
+      it 'levanta BugBunny::PublishNacked por default (config.nack_raise = true)' do
+        expect { confirmed_producer.confirmed(build_request) }.to raise_error(BugBunny::PublishNacked) do |err|
+          expect(err.path).to eq('acct.start')
+          expect(err.nacked_count).to eq(2)
+        end
+      end
+
+      it 'logea producer.confirms_nacked antes de levantar' do
+        expect { confirmed_producer.confirmed(build_request) }.to raise_error(BugBunny::PublishNacked)
+
+        nack_event = logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }
+        expect(nack_event).not_to be_nil
+        expect(nack_event[:kwargs]).to include(count: 2, path: 'acct.start')
+      end
+
+      it 'no levanta si el request override `nack_raise = false`' do
+        req = build_request
+        req.nack_raise = false
+
+        result = confirmed_producer.confirmed(req)
+
+        expect(result).to eq('status' => 202, 'body' => nil)
+        expect(logged_events.find { |e| e[:event] == 'producer.confirms_nacked' }).not_to be_nil
+      end
+
+      it 'no levanta si la configuración global tiene `nack_raise = false`' do
+        allow(BugBunny.configuration).to receive(:nack_raise).and_return(false)
+
+        result = confirmed_producer.confirmed(build_request)
+
+        expect(result).to eq('status' => 202, 'body' => nil)
+      end
+
+      it 'el override per-request gana sobre la configuración global' do
+        allow(BugBunny.configuration).to receive(:nack_raise).and_return(false)
+        req = build_request
+        req.nack_raise = true
+
+        expect { confirmed_producer.confirmed(req) }.to raise_error(BugBunny::PublishNacked)
+      end
     end
 
     it 'levanta BugBunny::RequestTimeout si wait_for_confirms excede confirm_timeout' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.12.0
+  version: 4.14.0
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -303,7 +303,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.12.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.14.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: