bug_bunny 4.13.0 → 4.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1bcda002a00d8ebc93786a496f8649d43e82d58645aa2b77e3d9b72044e7e07
-  data.tar.gz: b49f4c724ae39592d6c1a1774873fc8b272cf853688d998cbfb2f22d721d3589
+  metadata.gz: 6081a471e20278bc190a7d7517b69cf6fe6d852293bca353974c5ba1cbe4e746
+  data.tar.gz: 2e1b952c9627b7f3f1f9ab1e2af25af49ca0422ff59f062ac7499c14265d6a57
 SHA512:
-  metadata.gz: 3b16b769d198b82f5455294bfca2c9c157f6dc7cb34a4cceedf9441d11677035a51c97b1d29e7cb59994d7d954072062919c24958ac340d9da018dded6c9e199
-  data.tar.gz: fdea4a6b6d49dd032787c520e5516045812d94afa5ba4dc8a6ff818e7e89bc6263f92877266e82a40a3789907a2aafd9727ecd2770949511b3e8584915cc87ab
+  metadata.gz: 6cf7de01b98c925c8f02de1e09aafc0113f24f93145498ace1616445deecf6319bde3464d9afcd89b5b461904fbe878d4bfb24ea3a2a310149a32f6f2b06f4d0
+  data.tar.gz: 2560004c6036b238456fe9c9af9bf478dde67b1ff07240fdac942ecab303467d1db04f3029c2579463e5017b7c9f25ad2e5f1c5ef2c999f86bcde0bedb42eb67

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

data/README.md

@@ -252,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/producer.rb

@@ -60,9 +60,16 @@ module BugBunny
     #   (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)
+      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
@@ -90,6 +97,7 @@ module BugBunny
       future = Concurrent::IVar.new
       @pending_requests[cid] = future
 
+      started_at = monotonic_now
       begin
         fire(request)
 
@@ -101,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
@@ -119,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,
@@ -129,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.

data/lib/bug_bunny/version.rb

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

data/skill/SKILL.md

@@ -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

data/skill/references/client-middleware.md

@@ -59,11 +59,13 @@ 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`)
 
@@ -72,6 +74,7 @@ El `Producer` es usado internamente por el `Client`. Implementa tres patrones de
 - 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)
 

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
 
@@ -252,6 +299,18 @@ RSpec.describe BugBunny::Producer do
       expect(nack_event).to be_nil
     end
 
+    it 'logea producer.confirmed con publish_duration_s, confirm_duration_s y duration_s total' do
+      confirmed_producer.confirmed(build_request)
+
+      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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 4.13.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.13.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v4.14.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: