exis_ray 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad3239a79f3c1393bc7138ed81a149afbc8564817687906e1dd06931a231a03f
-  data.tar.gz: 5ff151e3ca3035d9d962622ea9a5b3231078fe913be160d1acb1e8f1c892f05e
+  metadata.gz: de4cf609747379030a7d49bf06aea93efbe9d60490eb3d9bfe4af3fec0fe1bd4
+  data.tar.gz: 0f3cbba6bf49ffec549c1cc7a306b9c018c12196f4a60afd62769268c5f964bf
 SHA512:
-  metadata.gz: 333e04eb54ce9df129976069e99bd349d4c56902e0f1c2e39baa56fc15bcdfacea9b977bb4e03f35bad36d0cf3ad149aa232c8de90385f267d035b24af666fc4
-  data.tar.gz: 1cb26ee1550c63524352ecce48ce2fcc761076cf9f6957757ce0e14b9ab6ced7aadc09e45ac0a954f8c2dc1018555f446ed1aa0fc9f2d3e44d6e7722c8d5e3a9
+  metadata.gz: 5e9532985f27d6ccb4efe76be22b3ff580eb60169e7f7c4a6a9db4ae19ac05a41489d43635f754deb6effd7732c97203ab0e28c19ae845f41f1a284ed79231ec
+  data.tar.gz: 40796e0043612a9636e212ae4ced8e096a984144e35f4d1e4baa9a1216514f8916ad9f3b2c054852861157015b4d37e9987da5e6b335a34254d0e5b5b8327468

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.5.1] - 2026-03-24
+
+### Fixed
+- **Type-Aware KV Parser:** The `JsonFormatter` now automatically casts numeric strings to `Integer` or `Float` when parsing KV messages. This ensures compliance with the Wispro standard where `duration_s` and `count` must be numeric types in the final JSON, not strings.
+
+## [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

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

@@ -127,6 +127,7 @@ module ExisRay
 
     # Parsea un string con formato key=value y retorna un Hash.
     # Soporta valores con espacios si están entre comillas dobles (ej: message="algo salió mal").
+    # Intenta convertir valores numéricos a Float o Integer automáticamente.
     #
     # @param str [String]
     # @return [Hash]
@@ -134,18 +135,25 @@ module ExisRay
       result = {}
       str.scan(KV_PARSE_RE) do |key, value|
         val = value.start_with?('"') ? (value[1..-2] || "").gsub('\\"', '"') : value
-        result[key.to_sym] = filter_sensitive_value(key, val)
+        result[key.to_sym] = cast_value(key, val)
       end
       result
     end
 
     # Filtra un valor si la clave se considera sensible.
+    # Si no es sensible, intenta castear el valor a número si corresponde.
     #
     # @param key [String, Symbol]
     # @param value [Object]
     # @return [Object]
-    def filter_sensitive_value(key, value)
-      key.to_s.match?(SENSITIVE_KEYS) ? "[FILTERED]" : value
+    def cast_value(key, value)
+      return "[FILTERED]" if key.to_s.match?(SENSITIVE_KEYS)
+
+      case value
+      when /\A\d+\z/ then value.to_i
+      when /\A\d+\.\d+\z/ then value.to_f
+      else value
+      end
     end
 
     # Filtra recursivamente un Hash que contenga claves sensibles.

data/lib/exis_ray/log_subscriber.rb

@@ -69,18 +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 = {
-        component:  "exis_ray",
-        event:      "http_request",
-        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/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.2"
+  VERSION = "0.5.1"
 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.2
+  version: 0.5.1
 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