exis_ray 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad3239a79f3c1393bc7138ed81a149afbc8564817687906e1dd06931a231a03f
-  data.tar.gz: 5ff151e3ca3035d9d962622ea9a5b3231078fe913be160d1acb1e8f1c892f05e
+  metadata.gz: c916d765b57e909cd3320e1670623536907d648c360039cbb5cada88b88a86fd
+  data.tar.gz: cab31ec104f79b58ecbd2ad8a8758f55f767e217f09c2880a3b911972a743112
 SHA512:
-  metadata.gz: 333e04eb54ce9df129976069e99bd349d4c56902e0f1c2e39baa56fc15bcdfacea9b977bb4e03f35bad36d0cf3ad149aa232c8de90385f267d035b24af666fc4
-  data.tar.gz: 1cb26ee1550c63524352ecce48ce2fcc761076cf9f6957757ce0e14b9ab6ced7aadc09e45ac0a954f8c2dc1018555f446ed1aa0fc9f2d3e44d6e7722c8d5e3a9
+  metadata.gz: b428640a4df2e1b64aa798568769c0d9902e503aa59fb14f7d2f34948115883f35e436097504de34a879eeb63890bbb031dc68e9f2adb672fa24c04c6064a47c
+  data.tar.gz: aa9c8bb741789384b66d1a98b9e5d5008d9e5eeea3802ecde39264c08c8ed95be8114285005c03dfb11d3506c2d4efb65c59336bc582d8b9cc8ccb1cf3bdb577

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [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/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.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.2
+  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