exis_ray 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb94b36fd16b408d5359621e78a03c722c89dab7c087322b67c975db743ad24e
-  data.tar.gz: ef093be07091568e6bad52d26de306dd82f91fc8e8f554d4eb04a7ca8c3b1581
+  metadata.gz: c916d765b57e909cd3320e1670623536907d648c360039cbb5cada88b88a86fd
+  data.tar.gz: cab31ec104f79b58ecbd2ad8a8758f55f767e217f09c2880a3b911972a743112
 SHA512:
-  metadata.gz: ce25522741b66f66318fa6d5223c0db754f1fe8f7eb1067a867f219988a1bc4ae78ef55c61e0895d553df955f129165af211a52dd41c86d6e3f6fe7066f7d7b2
-  data.tar.gz: 7ab403c8790dae80419260834d18787faa060bb2528d10974a4ef255bd6a0ea79c9aa837040015360db531b6114c8d99b4412c592d6749a0cba298ce24d072bc
+  metadata.gz: b428640a4df2e1b64aa798568769c0d9902e503aa59fb14f7d2f34948115883f35e436097504de34a879eeb63890bbb031dc68e9f2adb672fa24c04c6064a47c
+  data.tar.gz: aa9c8bb741789384b66d1a98b9e5d5008d9e5eeea3802ecde39264c08c8ed95be8114285005c03dfb11d3506c2d4efb65c59336bc582d8b9cc8ccb1cf3bdb577

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.5.0] - 2026-03-23
+
+### Changed
+- **Wispro-Observability-Spec (v1) Compliance:** Refactored telemetry across all execution layers (`TaskMonitor` and HTTP `LogSubscriber`).
+- **Unit Standard:** Duration metrics now use `_s` suffix (Float) as the source of truth (e.g., `duration_s`, `view_runtime_s`, `db_runtime_s`).
+- **Human Readability:** Added `duration_human` to both HTTP requests and Background Tasks.
+- **Task Lifecycle:** The closing log now always uses `event=task_finished` with `status`, `duration_s`, and `duration_human` fields.
+- **Error Consistency:** Failed tasks now include `error_class` and `error_message` fields in the JSON log.
+- **Tracer Accuracy:** Improved `Tracer` with `current_duration_s` using monotonic clock precision.
+
+## [0.4.2] - 2026-03-23
+
+### Added
+- **Full compliance with "Gabriel's Global Standards" for Logging:**
+  - **Sensitive Data Filtering:** The KV parser and Hash merger now automatically filter sensitive keys (`password`, `token`, `api_key`, `auth`, etc.) replacing values with `[FILTERED]`.
+  - **Standardized HTTP Logs:** Added `component=exis_ray` and `event=http_request` to all automatic Rails request logs.
+  - **Dynamic Log Levels:** `LogSubscriber` now uses `ERROR` level for 5xx status codes and `INFO` for the rest.
+  - **Performance:** Switched to block form for internal `DEBUG` logs in `Railtie` to avoid unnecessary string interpolation.
+
 ## [0.4.1] - 2026-03-23
 
 ### Changed

data/CLAUDE.md

@@ -0,0 +1,27 @@
+# ExisRay Project Memory
+
+## Architecture & Components
+- `ExisRay::Tracer`: Distributed tracing (AWS X-Ray). Uses `CurrentAttributes` for thread-safety.
+- `ExisRay::Current`: Business context (User, ISP). Abstract base class for host app subclassing.
+- `ExisRay::Reporter`: Sentry wrapper. Abstract base class for host app subclassing.
+- `ExisRay::JsonFormatter`: Core engine. Handles Hash, KV strings, and free-text with automatic masking.
+- `ExisRay::LogSubscriber`: Native HTTP logger since v0.4.0. Replaces Lograge.
+
+## Technical Knowledge & Compatibility
+
+### Rails Compatibility (6, 7, 8)
+- **Reloading:** Use `cache_classes?` helper (checks `respond_to?(:enable_reloading)`) to avoid deprecation warnings in Rails 7.1+.
+- **Notifications:** Rails 7.1+ uses `all_listeners_for`, while 6/7.0 uses `listeners_for`. Always use `respond_to?` guards when manipulating subscribers.
+
+### Distributed Tracing (AWS X-Ray)
+- **Propagation:** Use `propagation_trace_header` (standard HTTP format) for outgoing requests.
+- **Parsing:** `trace_header` (Rack format) is ONLY for incoming request parsing.
+
+### Security & Privacy
+- **Sentry Context:** Default `sentry_user_context` and `sentry_isp_context` to `{ id: }` only. Never send full objects to avoid leaking sensitive fields (PII/Tokens).
+- **Masking:** `JsonFormatter` automatically filters `password`, `token`, `api_key`, `auth`, `secret`.
+
+## Execution Rules
+- **No Lograge:** Do not suggest or re-add the Lograge dependency.
+- **Pure Data Logging:** Gem internal logs must use KV strings (`component=exis_ray event=...`).
+- **Resilience:** All logging operations must be wrapped in `rescue StandardError` to ensure the host application never crashes due to a telemetry failure.

data/lib/exis_ray/json_formatter.rb

@@ -25,6 +25,9 @@ module ExisRay
     # Extrae pares key=value de un string. Soporta valores sin espacios o entre comillas dobles.
     KV_PARSE_RE  = /(\w+)=("(?:[^"\\]|\\.)*"|\S+)/
 
+    # Claves sensibles que deben filtrarse automáticamente según el estándar de Gabriel.
+    SENSITIVE_KEYS = /password|pass|passwd|secret|token|api_key|auth/i
+
     # Procesa un mensaje de log y lo formatea como una cadena estructurada en JSON.
     #
     # @param severity [String] El nivel de severidad del log (ej. "INFO", "ERROR", "DEBUG").
@@ -103,7 +106,8 @@ module ExisRay
     # @return [void]
     def process_message(payload, msg)
       if msg.is_a?(Hash)
-        payload.merge!(msg)
+        # Filtramos las claves del Hash antes del merge
+        payload.merge!(filter_sensitive_hash(msg))
       elsif msg.is_a?(String) && kv_string?(msg)
         parsed = parse_kv_string(msg)
         parsed.empty? ? payload[:message] = msg : payload.merge!(parsed)
@@ -129,9 +133,33 @@ module ExisRay
     def parse_kv_string(str)
       result = {}
       str.scan(KV_PARSE_RE) do |key, value|
-        result[key.to_sym] = value.start_with?('"') ? (value[1..-2] || "").gsub('\\"', '"') : value
+        val = value.start_with?('"') ? (value[1..-2] || "").gsub('\\"', '"') : value
+        result[key.to_sym] = filter_sensitive_value(key, val)
       end
       result
     end
+
+    # Filtra un valor si la clave se considera sensible.
+    #
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [Object]
+    def filter_sensitive_value(key, value)
+      key.to_s.match?(SENSITIVE_KEYS) ? "[FILTERED]" : value
+    end
+
+    # Filtra recursivamente un Hash que contenga claves sensibles.
+    #
+    # @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
+                      filter_sensitive_value(k, v)
+                    end
+      end
+    end
   end
 end

data/lib/exis_ray/log_subscriber.rb

@@ -32,7 +32,12 @@ module ExisRay
     # @return [void]
     def process_action(event)
       payload = build_payload(event)
-      logger.info(payload)
+      # Usamos el nivel ERROR si el status es 5xx, cumpliendo el estándar de Gabriel.
+      if payload[:status] && payload[:status] >= 500
+        logger.error(payload)
+      else
+        logger.info(payload)
+      end
     rescue StandardError
       # El logger nunca debe interrumpir el flujo del request.
     end
@@ -64,16 +69,24 @@ module ExisRay
       payload = event.payload
       status  = payload[:status] || exception_status(payload[:exception])
 
+      # Convertimos milisegundos (Rails default) a segundos (Estandar Wispro)
+      duration_s = (event.duration / 1000.0).round(4)
+      view_s     = payload[:view_runtime] ? (payload[:view_runtime] / 1000.0).round(4) : nil
+      db_s       = payload[:db_runtime] ? (payload[:db_runtime] / 1000.0).round(4) : nil
+
       data = {
-        method:     payload[:method],
-        path:       payload[:path],
-        format:     payload[:format],
-        controller: payload[:controller],
-        action:     payload[:action],
-        status:     status,
-        duration:   event.duration.round(2),
-        view:       payload[:view_runtime]&.round(2),
-        db:         payload[:db_runtime]&.round(2)
+        component:      "exis_ray",
+        event:          "http_request",
+        method:         payload[:method],
+        path:           payload[:path],
+        format:         payload[:format],
+        controller:     payload[:controller],
+        action:         payload[:action],
+        status:         status,
+        duration_s:     duration_s,
+        duration_human: ActiveSupport::Duration.build(duration_s).inspect,
+        view_runtime_s: view_s,
+        db_runtime_s:   db_s
       }
 
       data.merge!(self.class.extra_fields(event))

data/lib/exis_ray/railtie.rb

@@ -85,7 +85,7 @@ module ExisRay
     # @param message [String] String en formato key=value.
     # @return [void]
     def self.log_boot(message)
-      Rails.logger.debug(message)
+      Rails.logger.debug { message }
     end
   end
 end

data/lib/exis_ray/task_monitor.rb

@@ -34,9 +34,15 @@ module ExisRay
       # Bloque de ejecución con o sin tags dependiendo de la configuración
       execute_with_optional_tags { yield }
 
-      log_event(:info, "component=exis_ray event=task_finished task=#{task_name} status=success")
+      duration_s = ExisRay::Tracer.current_duration_s
+      human_time = ActiveSupport::Duration.build(duration_s).inspect
+
+      log_event(:info, "component=exis_ray event=task_finished task=#{task_name} status=success duration_s=#{duration_s} duration_human=\"#{human_time}\"")
     rescue StandardError => e
-      log_event(:error, "component=exis_ray event=task_failed task=#{task_name} status=failed error=#{e.message.inspect}")
+      duration_s = ExisRay::Tracer.current_duration_s
+      human_time = ActiveSupport::Duration.build(duration_s).inspect
+
+      log_event(:error, "component=exis_ray event=task_finished task=#{task_name} status=failed duration_s=#{duration_s} duration_human=\"#{human_time}\" error_class=#{e.class} error_message=#{e.message.inspect}")
       raise e
     ensure
       # Limpieza centralizada obligatoria para evitar filtraciones de memoria o contexto

data/lib/exis_ray/tracer.rb

@@ -58,8 +58,16 @@ module ExisRay
     #
     # @return [Integer] Duración en ms.
     def self.current_duration_ms
-      return 0 unless created_at
-      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - created_at) * 1000).round
+      (current_duration_s * 1000).round
+    end
+
+    # Calcula el tiempo transcurrido en segundos desde el inicio de la request.
+    # Cumple con el estándar Wispro-Observability-Spec (v1).
+    #
+    # @return [Float] Duración en segundos.
+    def self.current_duration_s
+      return 0.0 unless created_at
+      (Process.clock_gettime(Process::CLOCK_MONOTONIC) - created_at).round(4)
     end
 
     # Construye el header de trazabilidad para enviar al siguiente servicio.

data/lib/exis_ray/version.rb

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

data/lib/exis_ray.rb

@@ -1,10 +1,12 @@
 require "exis_ray/version"
 
 # Dependencias externas
-# Necesario para 'safe_constantize', 'present?', y 'CurrentAttributes'
+# Necesario para 'safe_constantize', 'present?', 'CurrentAttributes' y 'Duration'
 require "active_support"
 require "active_support/core_ext/string/inflections" # Para safe_constantize
 require "active_support/current_attributes"
+require "active_support/duration"
+require "active_support/core_ext/numeric/time" # Para .seconds, .minutes, etc.
 
 # Componentes internos del Core
 require "exis_ray/configuration"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile