exis_ray 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd52ddf30f1d4eaaaad95ed4acde4bd94c8dd4a01b20853f42ddd71887c0876
-  data.tar.gz: 329163a0bbbd0473e8da70971822c645de763f6a2c99eb4ccf1c973603cd700e
+  metadata.gz: 95101aa6f502c3c839070a556ab984244493d9f8bbabaad2b3b4e2e83b19cc67
+  data.tar.gz: af2097e279144370005dd457effbeaf961a11938f191a9aa30053efe717f9b12
 SHA512:
-  metadata.gz: 9eb8bb340dae5b7f423e206ed1fa708caf0b599be0bfc3dd9f1d71209485cf6f2a17a06c9805167cd4988cae20b751f684fda2253d5983efa3c3d9e456e51849
-  data.tar.gz: e18cf7eaa0962d39591072eb9241df8c950c0d1d1c1786aaff4d84ebc4acd1b6ff993b280f5bedc6175bbabd56a0a75f0e8f92a50b899051a1942d21e91888fc
+  metadata.gz: 62e1bf2fe943f02976ba69b73ba9d76e698f93f6b9d1284a02354c01c4ab4d5b18411212da27ffe0ea315616184dfce0d3b66dc9a871c6cebbb50320656f5342
+  data.tar.gz: 10cf92356274c0da04446c96a109f298eb2c94a8eacb3787762e9785cf42915b877304161f70aeb6ac8478598b29c6aca127057a0db8d7f089f29b046a9bd954

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.8.0] - 2026-05-14
+
+### Nuevas funcionalidades
+- **`Current.log_fields` hook** (#6, #8): class method overridable en `ExisRay::Current` para inyectar campos custom en cada log line. Cubre con un solo mecanismo tanto constantes de proceso (frozen constants en la subclass) como valores dinámicos per-request (atributos de Current). `JsonFormatter` filtra claves sensibles del hash retornado y rescata silenciosamente si el override revienta. Útil para servicios multi-tenant donde se necesita inyectar `tenant_id`, `region`, `stack_id`, etc.
+
+### Mejoras internas
+- **`.rubocop.yml` relajado para destrabar CI**: los thresholds default venían bloqueando todos los PRs recientes. Excluido `Metrics/BlockLength` en specs y railtie, deshabilitado `Lint/SuppressedException` (el estándar Wispro requiere `rescue StandardError` vacíos en logging), thresholds más realistas para Metrics en lib/.
+
 ## [0.7.2] - 2026-05-11
 
 ### Documentación

data/CLAUDE.md

@@ -111,6 +111,7 @@ ExisRay.configuration.json_logs?                # => true/false
 | `correlation_id` | Cuando `Current.correlation_id` está presente |
 | `user_id` | Cuando `Current.user_id` está presente |
 | `isp_id` | Cuando `Current.isp_id` está presente |
+| `Current.log_fields` (cualquier key) | Si la subclass overrideó el hook (default `{}`) |
 | `sidekiq_job` | Solo en procesos Sidekiq |
 | `task` | Solo en procesos TaskMonitor |
 | `tags` | Solo si hay Rails tagged logging activo |

data/README.md

@@ -151,6 +151,38 @@ end
 | `Current.user?` / `Current.isp?` | Predicate: true si el ID no es nil |
 | `Current.correlation_id?` | Predicate: true si está presente (no vacío) |
 
+#### Hook `log_fields` — inyectar campos custom en cada log
+
+`Current.log_fields` es un class method overridable que retorna un Hash de campos
+extra a inyectar en cada log line, junto a `user_id`/`isp_id`/`correlation_id`.
+Cubre tanto **constantes de proceso** (declaradas como frozen constants en la
+subclass) como **valores dinámicos per-request** (leídos de atributos de
+`Current`) — todo en un solo lugar.
+
+```ruby
+class Current < ExisRay::Current
+  TENANT_ID = ENV.fetch("TENANT_ID").freeze   # static, frozen al boot
+  attribute :region                             # dynamic, per-request
+
+  def self.log_fields
+    { tenant_id: TENANT_ID, region: region }.compact
+  end
+end
+
+# En un before_action / middleware:
+Current.region = request.headers["X-Region"]
+
+# Los logs salen automáticamente con tenant_id y region:
+# {"...":"...", "tenant_id":"42", "region":"us-east-1", "event":"..."}
+```
+
+**Reglas:**
+
+- Default `{}` — cero overhead si no se override.
+- `JsonFormatter` filtra claves sensibles del hash retornado (`api_key`, `token`, etc.).
+- Si el override revienta, el formatter lo rescata silenciosamente (logging nunca debe afectar el flujo principal).
+- **Precedencia**: los campos canónicos del Tracer (`trace_id`, `root_id`, etc.) y las keys del propio mensaje del developer (ej. `Rails.logger.info "tenant_id=99"`) pisan `log_fields`. No sirve para overrideear campos canónicos, solo para agregar nuevos.
+
 ### Reporter (reporte de errores)
 
 `ExisRay::Reporter` es un wrapper de Sentry que enriquece automáticamente cada evento con el trace context del `Tracer` y el contexto de negocio del `Current`. Soporta Sentry SDK moderno y legacy (Raven/Session).
@@ -310,6 +342,7 @@ config.logger.formatter = ExisRay::JsonFormatter
 | `correlation_id` | Cuando `Current.correlation_id` está presente |
 | `user_id` | Cuando `Current.user_id` no es nil |
 | `isp_id` | Cuando `Current.isp_id` no es nil |
+| `Current.log_fields` (cualquier key) | Si la subclass overrideó el hook y retornó un Hash no vacío |
 | `sidekiq_job` | Solo en procesos Sidekiq |
 | `task` | Solo en procesos TaskMonitor |
 | `tags` | Solo si hay Rails tagged logging activo |

data/lib/exis_ray/current.rb

@@ -8,6 +8,30 @@ module ExisRay
   class Current < ActiveSupport::CurrentAttributes
     attribute :user_id, :isp_id, :correlation_id
 
+    # Hook overridable por la subclass de la app host. Retorna un Hash de campos
+    # extra a inyectar en cada log line, junto a `user_id`/`isp_id`/`correlation_id`.
+    #
+    # Pensado para cubrir tanto constantes de proceso (declaradas como `freeze`-d
+    # constants en la subclass) como valores dinámicos per-request (leídos de
+    # atributos de Current). El JsonFormatter invoca este método en cada log y
+    # mergea el resultado al payload — luego de los campos canónicos pero antes
+    # de las keys del propio mensaje del developer (que ganan por override).
+    #
+    # @example Constantes de proceso + valores per-request combinados
+    #   class Current < ExisRay::Current
+    #     TENANT_ID = ENV.fetch("TENANT_ID").freeze
+    #     attribute :region
+    #
+    #     def self.log_fields
+    #       { tenant_id: TENANT_ID, region: region }.compact
+    #     end
+    #   end
+    #
+    # @return [Hash] Pares clave/valor a inyectar. Default `{}`.
+    def self.log_fields
+      {}
+    end
+
     # Callback nativo de Rails: Se ejecuta automáticamente al llamar a Current.reset
     resets do
       @user_object = nil

data/lib/exis_ray/json_formatter.rb

@@ -122,9 +122,28 @@ module ExisRay
       payload[:user_id] = curr.user_id if curr.respond_to?(:user_id) && !curr.user_id.nil?
       payload[:isp_id]  = curr.isp_id  if curr.respond_to?(:isp_id)  && !curr.isp_id.nil?
 
-      return unless curr.respond_to?(:correlation_id) && curr.correlation_id
+      payload[:correlation_id] = curr.correlation_id if curr.respond_to?(:correlation_id) && curr.correlation_id
 
-      payload[:correlation_id] = curr.correlation_id
+      inject_log_fields(payload, curr)
+    end
+
+    # Mergea el resultado de `Current.log_fields` al payload, aplicando el mismo
+    # filtrado de claves sensibles que el resto del formatter. Si la subclass del
+    # host overrideó el hook y revienta, el error se traga: logging nunca debe
+    # afectar el flujo principal.
+    #
+    # @param payload [Hash]
+    # @param curr [Class] La clase Current configurada por la app host.
+    # @return [void]
+    def inject_log_fields(payload, curr)
+      return unless curr.respond_to?(:log_fields)
+
+      fields = curr.log_fields
+      return if fields.nil? || fields.empty?
+
+      payload.merge!(filter_sensitive_hash(fields))
+    rescue StandardError
+      nil
     end
 
     # Inyecta cualquier etiqueta nativa (tags) de Rails que esté presente en el hilo actual.

data/lib/exis_ray/railtie.rb

@@ -44,16 +44,12 @@ module ExisRay
       # y safe_constantize puede fallar aún con eager_load=true.
       if (name = ExisRay.configuration.current_class).present?
         klass = name.safe_constantize
-        if klass && !klass.<=(ExisRay::Current)
-          raise "ExisRay: current_class '#{name}' does not inherit from ExisRay::Current"
-        end
+        raise "ExisRay: current_class '#{name}' does not inherit from ExisRay::Current" if klass && !klass.<=(ExisRay::Current)
       end
 
       if (name = ExisRay.configuration.reporter_class).present?
         klass = name.safe_constantize
-        if klass && !klass.<=(ExisRay::Reporter)
-          raise "ExisRay: reporter_class '#{name}' does not inherit from ExisRay::Reporter"
-        end
+        raise "ExisRay: reporter_class '#{name}' does not inherit from ExisRay::Reporter" if klass && !klass.<=(ExisRay::Reporter)
       end
 
       # Aplicamos el formateador JSON globalmente al logger ya instanciado de Rails

data/lib/exis_ray/version.rb

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

data/skill/SKILL.md

@@ -163,6 +163,27 @@ Current.correlation_id? # => true si correlation_id es present?
 
 Los setters auto-sincronizan con `ActiveResource::Base.headers` y `PaperTrail.request` cuando estan definidos.
 
+#### Hook `log_fields` — inyectar campos custom en cada log
+
+Class method overridable que retorna un Hash de campos extra para JsonFormatter. Cubre tanto **constantes de proceso** (frozen constants en la subclass) como **valores dinámicos per-request** (atributos de Current) en un solo lugar. Default `{}`.
+
+```ruby
+class Current < ExisRay::Current
+  TENANT_ID = ENV.fetch("TENANT_ID").freeze   # static, frozen al boot
+  attribute :region                             # dynamic, per-request
+
+  def self.log_fields
+    { tenant_id: TENANT_ID, region: region }.compact
+  end
+end
+```
+
+Reglas:
+
+- `JsonFormatter` filtra claves sensibles del hash retornado (mismo regex que el resto del formatter).
+- Si el override revienta, el formatter rescata silenciosamente (logging no afecta flujo principal).
+- Precedencia: campos canónicos del Tracer y keys del mensaje del developer pisan `log_fields` en colisión. Solo sirve para agregar fields nuevos, no para overrideear los canónicos.
+
 ### ExisRay::Reporter (clase base abstracta)
 
 ```ruby

data/spec/exis_ray/current_spec.rb

@@ -112,4 +112,38 @@ RSpec.describe ExisRay::Current do
       TestCurrent.correlation_id = "corr-1"
     end
   end
+
+  describe ".log_fields hook" do
+    it "retorna un Hash vacío por defecto" do
+      expect(TestCurrent.log_fields).to eq({})
+    end
+
+    it "permite que la subclass overridee el método para inyectar campos custom" do
+      stub_const("TenantCurrent", Class.new(ExisRay::Current) do
+        def self.log_fields
+          { tenant_id: "42", region: "us-east-1" }
+        end
+      end)
+
+      expect(TenantCurrent.log_fields).to eq(tenant_id: "42", region: "us-east-1")
+    end
+
+    it "soporta combinar constantes de proceso con atributos per-request" do
+      stub_const("MixedCurrent", Class.new(ExisRay::Current) do
+        attribute :region
+
+        STATIC_TENANT = "tenant-42"
+
+        def self.log_fields
+          { tenant_id: STATIC_TENANT, region: region }.compact
+        end
+      end)
+      MixedCurrent.region = "us-east-1"
+
+      expect(MixedCurrent.log_fields).to eq(tenant_id: "tenant-42", region: "us-east-1")
+
+      MixedCurrent.reset
+      expect(MixedCurrent.log_fields).to eq(tenant_id: "tenant-42")
+    end
+  end
 end

data/spec/exis_ray/json_formatter_spec.rb

@@ -261,6 +261,91 @@ RSpec.describe ExisRay::JsonFormatter do
         expect(result).not_to have_key("user_id")
       end
     end
+
+    describe "inyeccion de Current.log_fields" do
+      # Mock estilo ActiveSupport::CurrentAttributes que combina los atributos canónicos
+      # con un hook log_fields. Por defecto retorna {}, los tests lo redefinen vía stub.
+      let(:current_class_double) do
+        Class.new do
+          class << self
+            attr_accessor :user_id, :isp_id, :correlation_id, :_log_fields
+
+            def respond_to_missing?(method, *)
+              %i[user_id isp_id correlation_id log_fields].include?(method) || super
+            end
+          end
+
+          def self.log_fields
+            _log_fields || {}
+          end
+        end
+      end
+
+      before do
+        allow(ExisRay).to receive(:current_class).and_return(current_class_double)
+      end
+
+      it "inyecta los campos retornados por log_fields en el payload" do
+        current_class_double._log_fields = { tenant_id: "42", region: "us-east-1" }
+
+        result = call("event=boot")
+
+        # tenant_id="42" se castea a Integer por filter_sensitive_hash (igual que cualquier otro KV)
+        expect(result).to include("tenant_id" => 42, "region" => "us-east-1", "event" => "boot")
+      end
+
+      it "no agrega keys cuando log_fields retorna hash vacío" do
+        current_class_double._log_fields = {}
+
+        result = call("event=boot")
+
+        expect(result).not_to have_key("tenant_id")
+      end
+
+      it "no agrega keys cuando log_fields retorna nil" do
+        current_class_double._log_fields = nil
+
+        result = call("event=boot")
+
+        expect(result.keys).to contain_exactly("time", "level", "severity_number", "service", "event")
+      end
+
+      it "el mensaje del developer pisa log_fields (override por call site)" do
+        current_class_double._log_fields = { tenant_id: "from-current" }
+
+        result = call("event=override tenant_id=from-message")
+
+        expect(result["tenant_id"]).to eq("from-message")
+      end
+
+      it "filtra claves sensibles" do
+        current_class_double._log_fields = { api_key: "leaked", tenant_id: "42" }
+
+        result = call("event=boot")
+
+        expect(result["api_key"]).to eq("[FILTERED]")
+        expect(result["tenant_id"]).to eq(42)
+      end
+
+      it "no rompe el formatter si la subclass overrideó log_fields con un método que revienta" do
+        allow(current_class_double).to receive(:log_fields).and_raise(StandardError, "boom")
+
+        expect { call("event=boot") }.not_to raise_error
+        result = call("event=boot")
+        expect(result["event"]).to eq("boot")
+      end
+
+      it "no falla si Current configurado no implementa log_fields (backwards compat)" do
+        legacy_current = Class.new do
+          class << self
+            attr_accessor :user_id, :isp_id, :correlation_id
+          end
+        end
+        allow(ExisRay).to receive(:current_class).and_return(legacy_current)
+
+        expect { call("event=boot") }.not_to raise_error
+      end
+    end
   end
 
   describe "#kv_string? (privado)" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -87,8 +87,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/gedera/exis_ray
   source_code_uri: https://github.com/gedera/exis_ray
-  changelog_uri: https://github.com/gedera/exis_ray/blob/v0.7.2/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.7.2/skill
+  changelog_uri: https://github.com/gedera/exis_ray/blob/v0.8.0/CHANGELOG.md
+  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.8.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: