bug_bunny 4.8.1 → 4.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35c04cd113b0a3056cab1dcfda6d389fa996e13bb44992d4791bdef29b93fc7d
-  data.tar.gz: aa7d145fb3eb1d80f435c0541e1009df78a636019e6c6452be0e0a0515b1f1a8
+  metadata.gz: 3d8e96ff8b1993700ead4fa98d3ce5a2484e6f13b59d63dbd270374101ef8c28
+  data.tar.gz: 856e18a1802e069b6446d7bb0960f8efd6e72a93570379bd301097ea5230812d
 SHA512:
-  metadata.gz: 9efee5f3deb6a52c76a361230032e040c964e22a1b52a2419873cb3d1c06159a1c52a042f424974a697a591342e8116aea1e39dd57e0bf71aa617ed5245e0860
-  data.tar.gz: 1f569f9e8b6fdfa2b48dd2270494a9a6b8f8aec2539ebadec5e20bc27f3ccd23407a340891b15c1567fe48ce593ee45a694b843987e5078852bb14d94ad37d70
+  metadata.gz: 92ca661889aeb364e72ec79934b1d27a227e8fe7ed71e772298bcc682d53076388481a5ffaa8d0ca51935031acaa664b859b7a5a1fc69f785c210ed9f78c2a22
+  data.tar.gz: f2e781eb9b13628edd52cdb0c5aceadc655128bb67c63f70c00775b6c5411429920b46b7d63d1dcb6fe83c2d5eb4ae5e5cb9a4152ab7f13e83274c9341d34fa4

data/.agents/skills/gem-release/SKILL.md

@@ -20,7 +20,7 @@ Ejecutá `quality-code` para validar linting, tests, YARD incremental y skill.
 No asumas rutas fijas. Investigá el entorno:
 - Detectá el nombre de la gema del `.gemspec`.
 - Localizá el archivo de versión (`lib/**/version.rb`).
-- Leé la versión actual.
+- **Versión actual:** Obtené el último tag publicado en el remoto (`git tag --sort=-v:refname | head -1` o `git ls-remote --tags origin`). El tag remoto es la fuente de verdad — NO leer `version.rb` para determinar la versión actual, ya que puede estar modificado localmente.
 - **Análisis de cambios:** Revisá **todas** las fuentes de cambios:
   1. Commits desde el último tag: `git log [último-tag]...HEAD`
   2. Diff commiteado contra el tag: `git diff [último-tag]...HEAD`
@@ -50,10 +50,12 @@ No asumas rutas fijas. Investigá el entorno:
    - `git commit -m "release: v[NUEVA_VERSION]"`
    - `git tag -a v[NUEVA_VERSION] -m "Version [NUEVA_VERSION]"`
 
-### Paso 5 — Publicación (Requiere confirmación final)
-- Construí la gema: `gem build [nombre].gemspec`
-- Empujá a RubyGems: `gem push [nombre]-[NUEVA_VERSION].gem`
-- Eliminá el artefacto `.gem` local después de subirlo.
+### Paso 5 — Push (Requiere confirmación)
+Mostrá un resumen del commit y el tag creados. Esperá confirmación explícita antes de pushear.
+- `git push origin main`
+- `git push origin v[NUEVA_VERSION]`
+
+**Nota:** No es necesario hacer `gem build` ni `gem push` manualmente. Un GitHub Action se encarga de buildear y publicar la gema en RubyGems cuando detecta el tag.
 
 ---
 

data/.agents/skills/skill-builder/SKILL.md

@@ -210,11 +210,72 @@ Si el catálogo es extenso, mantener los errores más comunes acá y extraer el
 
 ## Paso 4 — Actualizar README.md
 
-Actualizá `README.md` (máx 150 líneas) con:
-- Descripción en una línea.
-- Setup básico y Quick start.
-- Features principales.
-- Link a `skill/SKILL.md` para conocimiento profundo.
+Invocá la skill `documentation-writer` para auditar y actualizar el README.
+
+**Regla fundamental:** El README es para **humanos** (devs que usan la gema/servicio). La skill (`skill/`) es para **agentes**. Son audiencias distintas. **Nunca referenciar `skill/` desde el README.**
+
+### README de una gema (máx 150 líneas)
+
+```markdown
+# [Nombre de la gema]
+
+Descripción en una línea.
+
+## Instalación
+
+gem 'nombre', '~> X.X'
+
+## Quick Start
+
+[Ejemplo mínimo funcional — copiar, pegar, funciona]
+
+## Uso
+
+[Ejemplos de las operaciones principales]
+
+## Configuración
+
+[Bloque de configuración con opciones, defaults y descripción]
+
+## Contribuir
+
+[Cómo correr tests, linting, etc.]
+```
+
+### README de un servicio (máx 150 líneas)
+
+```markdown
+# [Nombre del servicio]
+
+Descripción en una línea.
+
+## Setup
+
+[Pasos para levantar el servicio localmente: bin/setup, docker, etc.]
+
+## Endpoints / Contratos
+
+[Resumen de los endpoints o queues principales]
+
+## Variables de entorno
+
+[Lista de env vars necesarias]
+
+## Testing
+
+[Cómo correr tests]
+
+## Deploy
+
+[Cómo se despliega: branch, tag, Codefresh]
+```
+
+### Qué NO poner en el README
+- Links a `skill/` ni a `skill/SKILL.md`
+- Documentación interna para agentes
+- Diagramas ASCII extensos (esos van en la skill)
+- Catálogo completo de errores (eso va en la skill)
+- FAQ técnico detallado (eso va en la skill)
 
 ---
 

data/.agents/skills/skill-manager/SKILL.md

@@ -53,41 +53,89 @@ Si no existe `skills.yml` en la raíz, crealo detectando dependencias en el `Gem
 # skills.yml — Manifiesto único de skills del proyecto
 
 # --- MCPs requeridos ---
-# Declara qué MCPs necesita el proyecto. Las skills verifican
-# disponibilidad antes de usarlos. Si falta alguno, avisan pero no se rompen.
+# Declara qué MCPs necesita el proyecto.
 
 mcps:
   - github
   - clickup
 
-# --- Dependencias (sync) ---
+# --- Gemas ---
+# Array de nombres. El sync busca skill/ en cada gema instalada.
 
-gems:              # Skills empaquetadas en gemas (copia local)
-  - name: mi_gema
+gems:
+  - mi_gema
+  - otra_gema
 
-services:          # Skills de microservicios (GitHub → skill/)
-  - name: mi_servicio
+# --- Servicios ---
+# Hash { nombre => config }. Descarga skill/ del repo remoto.
+
+services:
+  mi_servicio:
     repo: wispro/mi_servicio
 
-skills:            # Skills de repos GitHub (con path opcional)
-  # Sin path → usa convención .agents/skills/[name]/
-  - name: gem-release
-    repo: wispro/ai_knowledge
-  - name: skill-manager
-    repo: wispro/ai_knowledge
-  # Con path → para skills.sh u otros repos con estructura distinta
-  - name: rabbitmq-expert
+# --- Skills ---
+# Hash { nombre => config }. Formato estilo docker-compose.
+# Cada skill es una clave con su configuración.
+#
+# Claves disponibles:
+# - repo (requerido): org/repo de GitHub
+# - scope (opcional): global | local (default: local)
+# - path (opcional): path custom en el repo (default: skills/[nombre])
+# - environment (opcional): configuración específica de la skill
+
+skills:
+  skill-manager:
+    repo: sequre/ai_knowledge
+    scope: global
+  quality-code:
+    repo: sequre/ai_knowledge
+    scope: global
+  gem-release:
+    repo: sequre/ai_knowledge
+  service-release:
+    repo: sequre/ai_knowledge
+  skill-builder:
+    repo: sequre/ai_knowledge
+  yard:
+    repo: sequre/ai_knowledge
+  sentry:
+    repo: sequre/ai_knowledge
+    environment:
+      url: "https://sentry.cloud.wispro.co"
+      org: "wispro"
+      projects:
+        - billing-api
+        - billing-workers
+  agent-review:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "90144913465"
+      list_id: "901415149921"
+  ai-reports:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "90144913465"
+      bug_reports_list_id: "901415148810"
+      improvements_list_id: "901415148812"
+  # Skills externas con path custom
+  documentation-writer:
+    repo: github/awesome-copilot
+    path: skills/documentation-writer
+  rabbitmq-expert:
     repo: martinholovsky/claude-skills-generator
     path: skills/rabbitmq-expert
+```
 
-# --- Configuración de skills ---
-# Cada skill puede tener su sección de configuración específica.
-# Las skills leen su sección del skills.yml del proyecto.
+### Variables de entorno en skills.yml
+El parser expande `${VAR}` con el valor de la variable de entorno. Útil para tokens o IDs sensibles:
 
-sentry:
-  projects:
-    - billing-api
-    - billing-workers
+```yaml
+skills:
+  ai-reports:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "${CLICKUP_SPACE_ID}"
+      bug_reports_list_id: "${CLICKUP_BUG_REPORTS_LIST}"
 ```
 
 *Mostrá diff y pedí confirmación.*
@@ -97,14 +145,17 @@ Asegurate de que el script de sync esté configurado para ejecutarse:
 - Agregá al final de `bin/setup`:
   ```bash
   ruby .agents/skills/skill-manager/scripts/sync.rb
+
   ```
 
 ### Paso 6 — Git
-- Agregá las skills de dependencias al `.gitignore` (cada entrada declarada en `skills.yml`):
+- Agregá `.agents/skills/` completo al `.gitignore`:
   ```gitignore
-  # Skills de dependencias (generadas por skill-manager sync)
-  .agents/skills/[dep-name]/
+  # Skills locales (descargadas por sync + propias del dev)
+  .agents/skills/
   ```
+- `.agents/skills/` es siempre local y no se commitea. Contiene skills descargadas por el sync y opcionalmente skills privadas del dev.
+- Si una skill debe ser compartida, se declara en `skills.yml` y se distribuye via sync.
 
 ### Paso 7 — CLAUDE.md
 El bloque "Knowledge Base" debe estar al **tope absoluto** del archivo:
@@ -112,7 +163,8 @@ El bloque "Knowledge Base" debe estar al **tope absoluto** del archivo:
 ## Knowledge Base
 - **Mandato Crítico:** Las skills en `.agents/skills/` incluyen conocimiento de dependencias.
 - **Protocolo de Consulta:** El agente DEBE leer la skill de una dependencia antes de responder sobre ella.
-- **Rebuild:** `ruby .agents/skills/skill-manager/scripts/sync.rb` actualiza las skills de dependencias.
+- **Rebuild:** `ruby .agents/skills/skill-manager/scripts/sync.rb
+` actualiza las skills de dependencias.
 ```
 
 ---
@@ -125,11 +177,12 @@ El script `scripts/sync.rb` lee `skills.yml` y sincroniza todas las skills de de
 |---|---|---|
 | `gems` | Gema Ruby instalada | Copia local desde `gem_dir/skill/` |
 | `services` | Repo de microservicio | GitHub API → `skill/` del repo |
-| `skills` | Repo GitHub | GitHub API → path configurable (default: `.agents/skills/[name]/`) |
+| `skills` | Repo GitHub | GitHub API → path configurable (default: `skills/[name]/`) |
 
 ### Ejecución directa
 ```bash
 ruby .agents/skills/skill-manager/scripts/sync.rb
+
 ```
 
 ### Requisitos del script

data/.agents/skills/skill-manager/scripts/sync.rb

@@ -27,7 +27,7 @@ module SkillsSync
         exit 1
       end
 
-      config = YAML.safe_load_file(config_path)
+      config = load_config(config_path)
       @local_skills_path = File.join(Dir.pwd, SKILLS_DIR)
       FileUtils.mkdir_p(@local_skills_path)
 
@@ -53,6 +53,15 @@ module SkillsSync
 
     private
 
+    # --- Config parsing ---
+
+    # Lee skills.yml y expande variables de entorno ${VAR}
+    def load_config(path)
+      content = File.read(path)
+      content = content.gsub(/\$\{(\w+)\}/) { ENV[Regexp.last_match(1)].to_s }
+      YAML.safe_load(content)
+    end
+
     # --- Lock file ---
 
     def load_lock
@@ -96,6 +105,9 @@ module SkillsSync
 
     # --- Scope resolution ---
 
+    # Retorna un hash { dest:, install: } donde install indica si hay que descargar.
+    # Si install es false (porque ya existe globalmente), dest contiene el path global
+    # para que igualmente se registre en el lock y no se borre en cleanup.
     def resolve_dest(name, scope)
       case scope
       when 'global'
@@ -109,16 +121,17 @@ module SkillsSync
           FileUtils.rm_rf(local_path)
         end
 
-        dest
+        { dest: dest, install: true }
       else # local o sin especificar
-        # Si existe global, saltear
+        # Si existe global, saltear la instalación pero registrar en el lock
         existing_global = find_global_path(name)
         if existing_global
-          puts "  #{name} — disponible globalmente en #{File.join(existing_global, name)}. Saltando."
-          return nil
+          global_dest = File.join(existing_global, name)
+          puts "  #{name} — disponible globalmente en #{global_dest}. Saltando."
+          return { dest: global_dest, install: false }
         end
 
-        File.join(@local_skills_path, name)
+        { dest: File.join(@local_skills_path, name), install: true }
       end
     end
 
@@ -139,12 +152,18 @@ module SkillsSync
 
     # --- Sync methods ---
 
+    # Nuevo formato: gems es un array de strings (nombres de gemas)
     def sync_gems(gems)
-      gems.each do |gem_config|
-        name = gem_config['name']
-        scope = gem_config['scope']
-        dest = resolve_dest(name, scope)
-        next unless dest
+      return unless gems.is_a?(Array)
+
+      gems.each do |name|
+        resolution = resolve_dest(name, 'local')
+        next unless resolution
+
+        unless resolution[:install]
+          record_lock(name, 'local', resolution[:dest])
+          next
+        end
 
         begin
           spec = Gem::Specification.find_by_name(name)
@@ -161,44 +180,71 @@ module SkillsSync
           next
         end
 
-        scope_label = scope == 'global' ? 'global' : 'local'
-        puts "  #{name} v#{spec.version} (#{scope_label})"
-        replace_dir(dest)
-        FileUtils.cp_r(Dir[File.join(skill_dir, '*')], dest)
-        record_lock(name, scope, dest)
+        puts "  #{name} v#{spec.version} (local)"
+        replace_dir(resolution[:dest])
+        FileUtils.cp_r(Dir[File.join(skill_dir, '*')], resolution[:dest])
+        record_lock(name, 'local', resolution[:dest])
       end
     end
 
+    # Nuevo formato: services es un Hash { nombre => config }
+    # Cada servicio tiene: repo (requerido), scope (opcional)
     def sync_services(services)
-      services.each do |service|
-        name = service['name']
-        scope = service['scope']
-        dest = resolve_dest(name, scope)
-        next unless dest
+      return unless services.is_a?(Hash)
+
+      services.each do |name, service_config|
+        service_config ||= {}
+        scope = service_config['scope']
+        resolution = resolve_dest(name, scope)
+        next unless resolution
+
+        unless resolution[:install]
+          record_lock(name, scope, resolution[:dest])
+          next
+        end
+
+        repo = service_config['repo']
+        unless repo
+          puts "  WARNING: service '#{name}' no tiene 'repo' definido. Saltando."
+          next
+        end
 
-        repo = service['repo']
         scope_label = scope == 'global' ? 'global' : 'local'
         puts "  #{name} (GitHub: #{repo}, skill/) [#{scope_label}]"
-        replace_dir(dest)
-        download_github_dir(repo, 'main', 'skill', dest)
-        record_lock(name, scope, dest)
+        replace_dir(resolution[:dest])
+        download_github_dir(repo, 'main', 'skill', resolution[:dest])
+        record_lock(name, scope, resolution[:dest])
       end
     end
 
+    # Nuevo formato: skills es un Hash { nombre => config }
+    # Cada skill tiene: repo (requerido), scope (opcional), path (opcional), environment (opcional)
     def sync_skills(skills)
-      skills.each do |skill|
-        name = skill['name']
-        scope = skill['scope']
-        dest = resolve_dest(name, scope)
-        next unless dest
-
-        repo = skill['repo']
-        remote_path = skill['path'] || "#{SKILLS_DIR}/#{name}"
+      return unless skills.is_a?(Hash)
+
+      skills.each do |name, skill_config|
+        skill_config ||= {}
+        scope = skill_config['scope']
+        resolution = resolve_dest(name, scope)
+        next unless resolution
+
+        unless resolution[:install]
+          record_lock(name, scope, resolution[:dest])
+          next
+        end
+
+        repo = skill_config['repo']
+        unless repo
+          puts "  WARNING: skill '#{name}' no tiene 'repo' definido. Saltando."
+          next
+        end
+
+        remote_path = skill_config['path'] || "skills/#{name}"
         scope_label = scope == 'global' ? 'global' : 'local'
         puts "  #{name} (GitHub: #{repo}, #{remote_path}/) [#{scope_label}]"
-        replace_dir(dest)
-        download_github_dir(repo, 'main', remote_path, dest)
-        record_lock(name, scope, dest)
+        replace_dir(resolution[:dest])
+        download_github_dir(repo, 'main', remote_path, resolution[:dest])
+        record_lock(name, scope, resolution[:dest])
       end
     end
 

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [4.9.0] - 2026-04-05
+
+### ✨ New Features
+* **OTel messaging semantic conventions:** BugBunny ahora emite los campos del estándar [OpenTelemetry semantic conventions for messaging](https://opentelemetry.io/docs/specs/otel/trace/semantic-conventions/messaging/) tanto en los headers AMQP de publish/reply como en los log events del consumer. Los campos emitidos son `messaging.system` (`"rabbitmq"`), `messaging.operation` (`"publish"` / `"process"`), `messaging.destination.name`, `messaging.rabbitmq.destination.routing_key` y `messaging.message.id` (cuando hay `correlation_id`). Permite que dashboards OTel-native (Tempo, Jaeger, Honeycomb) rendericen correctamente los spans de RabbitMQ y que ExisRay los consuma automáticamente desde `properties.headers`.
+* **`BugBunny::OTel` module:** Nuevo módulo con las constantes de las claves OTel y el helper `messaging_headers` para construir el hash de campos. Los headers del usuario pueden sobrescribir valores OTel como escape hatch, pero `x-http-method` sigue siendo inmutable.
+
 ## [4.8.1] - 2026-04-04
 
 ### Mejoras internas

data/CLAUDE.md

@@ -6,32 +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.
 
+## Documentación
+
+- **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.
+
 ## 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`
 
-## Entorno
+### 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
+### RuboCop
 - Usamos rubocop-rails-omakase como base.
 - Correr `bundle exec rubocop -a` antes de commitear.
 - No deshabilitar cops sin justificación en el PR.
 
-## YARD
+### YARD
 - 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
+### Testing
 - Framework: RSpec
 - Correr: `bundle exec rspec`
 - Todo código nuevo debe tener tests.
 
-## Releases
-- Gemas: `/gem-release`
-- Servicios: `/service-release build` o `/service-release deploy`
+### 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