exis_ray 0.5.4 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13877001eee2022a6c6de0d2709ef5080b0cc2e43459d5e81ea99d9f28f9b216
-  data.tar.gz: c6b551a316813a3671ae980a0fc8061b32fc1b585bc39b49a5c761a73c3af145
+  metadata.gz: d66d71924fff9cf19c12e42d411963948739da61e6b223db1444c16633a3158e
+  data.tar.gz: 26c599899ecf1f87388c73e1b4a183370e0902893c09e40c24c7796c973c0d96
 SHA512:
-  metadata.gz: e41a2bc99ab67896aac64e6eb8becca74fd03217807fa16e24ed434477109b053f9d9580b206a2c4f4123fefa6beca5f580b934e22c468175d20fa808179a7eb
-  data.tar.gz: 80bc6a49ea2b9ed2e4b45aa3f4e501752edb2d5873a8871cce6ba3b4e1bf4f925fb793a3ba5ab1a0f9c717d4ee63c9411bc1d738ab7d9a742ed48585071664fd
+  metadata.gz: 60c34361234b638c3758b3b51d38933efcbf5db19fb8e1a9365f53f1e21bcfc42e680ceb37755c792663e7146826af2453d862b7ae526481870f65518a84b311
+  data.tar.gz: e3cb2ffc12e45d5bdd6f3c1d1a864bc9884b7709c531fa2780923834f0ca4d4766c75148c6afd15aac4d6a6dbf716a151042620474127b544b779fa86ec9c62b

data/.gemini/docs/TELEMETRY_GUIDELINES.md

@@ -0,0 +1,32 @@
+# OpenTelemetry Implementation Guidelines
+
+This document provides expert guidance for aligning code and logs with OpenTelemetry (OTel) standards. Follow these rules for all new instrumentation.
+
+## 1. Log Data Model
+- **Body:** Use `body` for the primary log message.
+- **Attributes:** Metadata must be flat Key-Value pairs.
+- **Severity:** `level` maps to `severity_text`.
+
+## 2. Semantic Conventions
+When adding attributes, check the official OTel [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/).
+
+### HTTP Attributes
+- `http.request.method`: GET, POST, etc.
+- `http.response.status_code`: 200, 404, etc.
+- `url.path`: The request path.
+- `user_agent.original`: The raw User-Agent string.
+
+### Database Attributes
+- `db.system`: postgresql, redis, etc.
+- `db.operation`: select, update, etc.
+- `db.collection.name`: table or collection name.
+
+## 3. Metrics & Units
+- Always use the lowest common denominator for units (seconds, bytes).
+- Use `_s` suffix for time duration.
+- Avoid compound strings like `"10ms"`. Use `duration_s=0.01`.
+
+## 4. Distributed Tracing
+- **TraceID:** 16-byte array, represented as a 32-char lowercase hex string.
+- **SpanID:** 8-byte array, represented as a 16-char lowercase hex string.
+- **Context Propagation:** Follow W3C Trace Context (traceparent) when possible, or maintain AWS X-Ray compatibility as per project requirements.

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.5.6] - 2026-03-26
+
+### Added
+- **BugBunny Integration:** Added `ExisRay::BugBunny::PublisherTracing` middleware for `BugBunny::Client` and `BugBunny::Resource`. Injects the active trace context into the `x-trace-id` AMQP header on every published message.
+- **BugBunny Integration:** Added `ExisRay::BugBunny::ConsumerTracing` concern for `BugBunny::Controller`. Restores the ExisRay trace context from `x-trace-id` header via `around_action`, enabling end-to-end distributed tracing across RabbitMQ message boundaries.
+
+## [0.5.5] - 2026-03-24
+
+### Added
+- **Deep Security Filtering:** The `JsonFormatter` now recursively filters sensitive data within `Array` and nested `Hash` structures.
+- **OTel Semantic Mapping:** Added formal mapping of ExisRay fields to OpenTelemetry Semantic Conventions in `MANIFEST.md`.
+- **Test Hardening:** Expanded test suite to cover deep filtering and ensure correct numeric type-casting in logs.
+
 ## [0.5.4] - 2026-03-24
 
 ### Changed

data/CLAUDE.md

@@ -32,6 +32,7 @@
 ## Execution Rules
 - **No Lograge:** Do not suggest or re-add the Lograge dependency.
 - **Pure Data Logging:** Internal logs use KV strings (`component=exis_ray event=...`).
+- **OTel Compliance:** Always follow the guidelines in `.gemini/docs/TELEMETRY_GUIDELINES.md` and alignment in `MANIFEST.md`. Use OTel Semantic Conventions for new attributes.
 - **Resilience:** All logging operations must be wrapped in `rescue StandardError`.
 - **Automatic Fields:** NEVER manually log `time`, `level`, `service`, `source`, `root_id`, `correlation_id`, `sidekiq_job` or `task`. These are handled by the library.
 - **Source Values:** Valid values for `source` field: `http`, `sidekiq`, `task`, `system`.

data/MANIFEST.md

@@ -26,10 +26,24 @@ Cada línea de log debe llevar los metadatos necesarios para identificar su orig
 *   `source`: El punto de entrada de la ejecución (`http`, `sidekiq`, `task`, `system`).
 
 ### 3. Convenciones de Naming & Tipos
-- **Naming:** Las llaves (keys) deben usar siempre `snake_case`.
+- **Naming:** Las llaves (keys) deben usar siempre `snake_case`. Para campos estándar, se prefiere seguir las **OpenTelemetry Semantic Conventions**.
 - **Valores Numéricos:** Deben emitirse como números reales (sin sufijos de texto) para permitir que el motor de logs realice el casting automático.
 - **Formato:** Pares `key=value` en una sola línea estructurada.
 
+## 🔭 Alineación con OpenTelemetry
+
+Para garantizar la interoperabilidad, `exis_ray` sigue el **OpenTelemetry Log Data Model**. Siempre que sea posible, los campos deben mapearse a las convenciones semánticas oficiales:
+
+| Campo ExisRay | OTel Semantic Convention | Descripción |
+| :--- | :--- | :--- |
+| `body` | `body` | El contenido principal del log. |
+| `level` | `severity_text` | Nivel de importancia. |
+| `duration_s` | `duration` (en segundos) | Tiempo de ejecución. |
+| `method` | `http.request.method` | Método HTTP. |
+| `status` | `http.response.status_code` | Código de respuesta. |
+| `path` | `url.path` | Ruta del request. |
+| `user_id` | `user.id` | Identificador del usuario. |
+
 ## 🏗 Infraestructura de Datos (Automática)
 
 Para evitar logs redundantes y pesados, **NUNCA** incluyas manualmente las siguientes llaves en tus mensajes de log. La capa de infraestructura (`exis_ray`) las inyecta automáticamente en el nivel raíz del JSON:

data/README.md

@@ -14,6 +14,7 @@ It acts as the backbone of your architecture, ensuring that every request, backg
 * **Sidekiq Integration:** Automatic context propagation (User/ISP/Trace) and log formatting between the Enqueuer and the Worker.
 * **Task Monitor:** A specialized monitor for Rake/Cron tasks to initialize traces and format logs where no HTTP request exists.
 * **HTTP Clients:** Automatically patches `ActiveResource` and provides middleware for `Faraday`.
+* **BugBunny Integration:** Propagates the trace context across RabbitMQ message boundaries via a publisher middleware and a consumer concern.
 
 ---
 
@@ -200,6 +201,40 @@ conn = Faraday.new(url: "[https://api.internal](https://api.internal)") do |f|
 end
 ```
 
+### E. BugBunny (RabbitMQ)
+
+If your app publishes messages via [BugBunny](https://github.com/gedera/bug_bunny), ExisRay can propagate the active trace context through the `x-trace-id` AMQP header, and restore it on the consumer side so every log line during message processing shares the same `root_id` as the original HTTP request.
+
+#### Publisher — inject the trace header
+
+Add `ExisRay::BugBunny::PublisherTracing` to your client middleware stack. Works with both `BugBunny::Client` and `BugBunny::Resource`.
+
+```ruby
+client = BugBunny::Client.new(pool: connection_pool) do |stack|
+  stack.use ExisRay::BugBunny::PublisherTracing
+  stack.use BugBunny::Middleware::JsonResponse
+end
+```
+
+If no trace context is active (e.g. a standalone script), the middleware does nothing.
+
+#### Consumer — restore the trace context
+
+Include `ExisRay::BugBunny::ConsumerTracing` in your base controller. It registers an `around_action` that reads `x-trace-id` from the message headers and hydrates `ExisRay::Tracer` before your action runs. The context is always reset in `ensure`, preventing leaks between messages.
+
+```ruby
+class ApplicationController < BugBunny::Controller
+  include ExisRay::BugBunny::ConsumerTracing
+end
+```
+
+**How it works end-to-end:**
+1. **Publish:** The publisher middleware injects `x-trace-id` into the AMQP headers of every outgoing message.
+2. **Consume:** The consumer concern reads that header, restores the trace context, and sets `source=system`.
+3. **Logs:** Every log line emitted during the controller action carries the original `root_id` and `correlation_id` from the upstream HTTP request.
+
+If a message arrives without `x-trace-id` (published without ExisRay), the concern is a no-op.
+
 ---
 
 ## 📋 Advanced Logging Guide

data/lib/exis_ray/bug_bunny/consumer_tracing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module ExisRay
+  module BugBunny
+    # Concern para BugBunny::Controller que restaura el trace context de ExisRay
+    # a partir del header 'x-trace-id' inyectado por el publicador.
+    #
+    # Permite que todos los logs emitidos durante el procesamiento de un mensaje
+    # incluyan el mismo root_id y correlation_id que el request HTTP original,
+    # logrando trazabilidad distribuida de punta a punta.
+    #
+    # El contexto se limpia siempre en `ensure`, garantizando que un error en el
+    # controller no contamine el procesamiento del siguiente mensaje.
+    #
+    # @example Incluir en el ApplicationController de BugBunny
+    #   class ApplicationController < BugBunny::Controller
+    #     include ExisRay::BugBunny::ConsumerTracing
+    #   end
+    module ConsumerTracing
+      extend ActiveSupport::Concern
+
+      # Header AMQP desde el cual se lee el trace context propagado.
+      TRACE_HEADER = 'x-trace-id'
+
+      included do
+        around_action :exis_ray_trace_context
+      end
+
+      private
+
+      # Restaura el contexto de trazabilidad y lo limpia al finalizar,
+      # independientemente de si el controller levantó una excepción.
+      #
+      # @yieldreturn [void]
+      def exis_ray_trace_context
+        setup_exis_ray_context
+        yield
+      ensure
+        ExisRay::Tracer.reset rescue nil
+      end
+
+      # Hidrata el Tracer con el header de traza recibido en el mensaje.
+      # Si el header no está presente (mensaje sin trace context), no hace nada.
+      #
+      # @return [void]
+      def setup_exis_ray_context
+        trace_header = headers[TRACE_HEADER]
+        return unless trace_header.present?
+
+        ExisRay::Tracer.hydrate(trace_id: trace_header, source: 'system')
+        ExisRay.sync_correlation_id
+      rescue StandardError
+        # El tracing nunca debe interrumpir el procesamiento del mensaje.
+      end
+    end
+  end
+end

data/lib/exis_ray/bug_bunny/publisher_tracing.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ExisRay
+  module BugBunny
+    # Middleware de publicación para BugBunny::Client.
+    #
+    # Inyecta el header de trazabilidad de ExisRay en cada mensaje publicado,
+    # permitiendo la propagación del trace context a los servicios consumidores.
+    # Esto hace posible correlacionar un request HTTP original con todos los mensajes
+    # y logs que genera en el ecosistema de microservicios.
+    #
+    # @example Configuración en el cliente
+    #   client = BugBunny::Client.new(pool: pool) do |stack|
+    #     stack.use ExisRay::BugBunny::PublisherTracing
+    #   end
+    #
+    # @example Configuración en un BugBunny::Resource
+    #   class UserResource < BugBunny::Resource
+    #     middleware do |stack|
+    #       stack.use ExisRay::BugBunny::PublisherTracing
+    #     end
+    #   end
+    class PublisherTracing < ::BugBunny::Middleware::Base
+      # Header AMQP personalizado para propagar el trace context entre servicios.
+      TRACE_HEADER = 'x-trace-id'
+
+      # Inyecta el header de traza antes de publicar el mensaje.
+      # Solo actúa si hay un trace context activo (root_id presente).
+      #
+      # @param env [BugBunny::Request] El objeto request del mensaje saliente.
+      # @return [void]
+      def on_request(env)
+        return unless ExisRay::Tracer.root_id.present?
+
+        env.headers[TRACE_HEADER] = ExisRay::Tracer.generate_trace_header
+      rescue StandardError
+        # La propagación de tracing nunca debe interrumpir la publicación de mensajes.
+      end
+    end
+  end
+end

data/lib/exis_ray/http_middleware.rb

@@ -8,20 +8,14 @@ module ExisRay
 
     def call(env)
       # 1. Hidratar Infraestructura
-      ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      ExisRay::Tracer.source     = "http"
-
-      trace_header_key = ExisRay.configuration.trace_header
-
-      ExisRay::Tracer.trace_id     = env[trace_header_key]
-      ExisRay::Tracer.request_id   = env['action_dispatch.request_id']
-      ExisRay::Tracer.parse_trace_id
+      ExisRay::Tracer.hydrate(
+        trace_id: env[ExisRay.configuration.trace_header],
+        source:   "http"
+      )
+      ExisRay::Tracer.request_id = env['action_dispatch.request_id']
 
       # 2. Hidratar Negocio
-      # Usamos el helper centralizado para obtener la clase Current
-      if (curr = ExisRay.current_class) && curr.respond_to?(:correlation_id=) && ExisRay::Tracer.root_id.present?
-        curr.correlation_id = ExisRay::Tracer.correlation_id
-      end
+      ExisRay.sync_correlation_id
 
       @app.call(env)
     end

data/lib/exis_ray/json_formatter.rb

@@ -163,17 +163,34 @@ module ExisRay
     end
 
     # Filtra recursivamente un Hash que contenga claves sensibles.
+    # Maneja valores anidados de tipo Hash o Array.
     #
     # @param hash [Hash]
     # @return [Hash]
     def filter_sensitive_hash(hash)
       hash.each_with_object({}) do |(k, v), result|
-        result[k] = if v.is_a?(Hash)
-                      filter_sensitive_hash(v)
-                    else
-                      cast_value(k, v)
+        result[k] = case v
+                    when Hash  then filter_sensitive_hash(v)
+                    when Array then filter_sensitive_array(k, v)
+                    else            cast_value(k, v)
                     end
       end
     end
+
+    # Filtra recursivamente los elementos de un Array, propagando la clave padre
+    # para que el filtrado de claves sensibles se aplique a hashes anidados.
+    #
+    # @param key [String, Symbol] Clave padre (para filtrado si el array no contiene hashes).
+    # @param array [Array]
+    # @return [Array]
+    def filter_sensitive_array(key, array)
+      array.map do |element|
+        case element
+        when Hash  then filter_sensitive_hash(element)
+        when Array then filter_sensitive_array(key, element)
+        else            cast_value(key, element)
+        end
+      end
+    end
   end
 end

data/lib/exis_ray/sidekiq/server_middleware.rb

@@ -46,17 +46,16 @@ module ExisRay
       # @param job [Hash] Payload de Sidekiq.
       # @return [void]
       def hydrate_tracer(worker, job)
-        ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         ExisRay::Tracer.sidekiq_job = worker.class.name
-        ExisRay::Tracer.source      = "sidekiq"
 
         if job["exis_ray_trace"]
           # Continuidad: Usamos la traza propagada desde el cliente (Web/Cron)
-          ExisRay::Tracer.trace_id = job["exis_ray_trace"]
-          ExisRay::Tracer.parse_trace_id
+          ExisRay::Tracer.hydrate(trace_id: job["exis_ray_trace"], source: "sidekiq")
         else
           # Origen: El job nació directamente aquí sin contexto previo
-          ExisRay::Tracer.root_id = ExisRay::Tracer.send(:generate_new_root)
+          ExisRay::Tracer.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ExisRay::Tracer.source     = "sidekiq"
+          ExisRay::Tracer.root_id    = ExisRay::Tracer.send(:generate_new_root)
         end
       end
 

data/lib/exis_ray/tracer.rb

@@ -61,6 +61,20 @@ module ExisRay
       (current_duration_s * 1000).round
     end
 
+    # Hidrata el Tracer con un trace header entrante y registra el inicio del contexto.
+    # Centraliza la inicialización de contexto de trazabilidad para todos los entrypoints
+    # (HTTP, Sidekiq, BugBunny, etc.), eliminando duplicación entre middlewares.
+    #
+    # @param trace_id [String] El header de traza entrante (formato AWS X-Ray).
+    # @param source [String] El entrypoint de ejecución ('http', 'sidekiq', 'task', 'system').
+    # @return [void]
+    def self.hydrate(trace_id:, source:)
+      self.created_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      self.source     = source
+      self.trace_id   = trace_id
+      parse_trace_id
+    end
+
     # Calcula el tiempo transcurrido en segundos desde el inicio de la request.
     # Cumple con el estándar Wispro-Observability-Spec (v1).
     #

data/lib/exis_ray/version.rb

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

data/lib/exis_ray.rb

@@ -24,6 +24,13 @@ require "exis_ray/faraday_middleware" if defined?(Faraday)
 # Solo cargamos la instrumentación si ActiveResource está presente.
 require "exis_ray/active_resource_instrumentation" if defined?(ActiveResource::Base)
 
+# Integraciones BugBunny: publisher middleware y consumer concern.
+# Solo se cargan si la gema BugBunny está presente.
+if defined?(::BugBunny)
+  require "exis_ray/bug_bunny/publisher_tracing"
+  require "exis_ray/bug_bunny/consumer_tracing"
+end
+
 # Integración automática con Rails
 # Solo cargamos el Railtie si la constante Rails está definida.
 require "exis_ray/railtie" if defined?(Rails)
@@ -96,6 +103,17 @@ module ExisRay
       end
     end
 
+    # Sincroniza el correlation_id del Tracer en la clase Current configurada.
+    # Debe llamarse después de hidratar el Tracer (post `hydrate` o `parse_trace_id`).
+    #
+    # @return [void]
+    def sync_correlation_id
+      curr = current_class
+      return unless curr&.respond_to?(:correlation_id=) && Tracer.root_id.present?
+
+      curr.correlation_id = Tracer.correlation_id
+    end
+
     private
 
     def resolve_class(klass_name)

data/spec/exis_ray/json_formatter_spec.rb

@@ -92,11 +92,10 @@ RSpec.describe ExisRay::JsonFormatter do
         expect(result).to include(
           "component"   => "orders",
           "event"       => "invoice_generated",
-          "duration_ms" => "42.5",
-          "retries"     => "0"
+          "duration_ms" => 42.5,
+          "retries"     => 0
         )
       end
-    end
 
       it "cae a body si el string parece kv pero no produce ningún par" do
         result = call("key=")
@@ -156,10 +155,10 @@ RSpec.describe ExisRay::JsonFormatter do
   end
 
   describe "#parse_kv_string (privado)" do
-    it "retorna un hash con claves symbol" do
+    it "retorna un hash con claves symbol y valores casteados" do
       result = formatter.send(:parse_kv_string, "a=1 b=2")
 
-      expect(result).to eq({ a: "1", b: "2" })
+      expect(result).to eq({ a: 1, b: 2 })
     end
 
     it "desenvuelve las comillas dobles de los valores" do
@@ -168,4 +167,44 @@ RSpec.describe ExisRay::JsonFormatter do
       expect(result).to eq({ msg: "hello world" })
     end
   end
+
+  describe "#filter_sensitive_hash (privado)" do
+    it "filtra claves sensibles en el nivel raíz" do
+      result = formatter.send(:filter_sensitive_hash, { user: "gabriel", password: "secret" })
+
+      expect(result[:user]).to eq("gabriel")
+      expect(result[:password]).to eq("[FILTERED]")
+    end
+
+    it "filtra claves sensibles en hashes anidados" do
+      result = formatter.send(:filter_sensitive_hash, {
+        db: { host: "localhost", token: "abc123" }
+      })
+
+      expect(result[:db][:host]).to eq("localhost")
+      expect(result[:db][:token]).to eq("[FILTERED]")
+    end
+
+    it "filtra claves sensibles dentro de arrays de hashes" do
+      result = formatter.send(:filter_sensitive_hash, {
+        users: [{ name: "gabriel", password: "secret" }, { name: "ana", password: "other" }]
+      })
+
+      expect(result[:users][0][:name]).to eq("gabriel")
+      expect(result[:users][0][:password]).to eq("[FILTERED]")
+      expect(result[:users][1][:password]).to eq("[FILTERED]")
+    end
+
+    it "filtra claves sensibles en arrays primitivos cuando la clave padre es sensible" do
+      result = formatter.send(:filter_sensitive_hash, { tokens: ["abc", "def"] })
+
+      expect(result[:tokens]).to eq(["[FILTERED]", "[FILTERED]"])
+    end
+
+    it "no altera valores no sensibles en arrays" do
+      result = formatter.send(:filter_sensitive_hash, { tags: ["admin", "active"] })
+
+      expect(result[:tags]).to eq(["admin", "active"])
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.6
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -45,6 +45,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gemini/docs/TELEMETRY_GUIDELINES.md"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
@@ -53,6 +54,8 @@ files:
 - Rakefile
 - lib/exis_ray.rb
 - lib/exis_ray/active_resource_instrumentation.rb
+- lib/exis_ray/bug_bunny/consumer_tracing.rb
+- lib/exis_ray/bug_bunny/publisher_tracing.rb
 - lib/exis_ray/configuration.rb
 - lib/exis_ray/current.rb
 - lib/exis_ray/faraday_middleware.rb