exis_ray 0.5.3 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8bf4b504bfe6112b50328a358879a63b5ff19832e4724711a4650a110c94aaf
-  data.tar.gz: fd3332690b0ff0b3ca95ccf4dddbddcb99322fd01481f9da4e11a12d3f0bf801
+  metadata.gz: a79e0a93c6efad500f943dad46daa5d429f133d8144db2fd1ce1e32e2b07ac68
+  data.tar.gz: 243915edbd6405a89656457b1371b34971efa5f377def03093d4a024ca73b661
 SHA512:
-  metadata.gz: 639eb1ab36f013dbf034dd7be88e5c13ab77779ed6a130d0f28cb75ace6baf36b0bb7b387f7ec77cb9a37236cb5ac703daa9bfa7116160aeee59ccc18e43b9be
-  data.tar.gz: '0882e98c833ebc8774e47f2ddca1d33ce73fd9b7d8a5427b9851eafcab4323c41b0253d512e2ec9b0fd2391120f6390eeb1be2995d924a3674e155cda7c36dcb'
+  metadata.gz: 6877511e716b0fb3ec6fe55a4542b7129163da596344ec1b98f8042d9bdedd9b514c2fe80ec78af474a4d18d5fd9b70bacd84669d3c467ecd2c69904555a6d94
+  data.tar.gz: cc0356850bfd66654bd241e3aa2654c5114ea2e3a6fbac91eab248e5b4cb5f10affd2ccfdf62065b5f70cbe6f6d362018572299cb307d365db20cd7d2e7c03b7

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.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
+- **Human-readable durations:** `duration_human` now uses a smarter format: sub-second values show as `"7.2ms"`, values under 60s show as `"1.25s"`, and longer durations use `ActiveSupport::Duration` prose (e.g., `"2 minutes 5 seconds"`).
+- **Shared duration helper:** Extracted `ExisRay::Tracer.format_duration` to consolidate duration formatting used by both `LogSubscriber` and `TaskMonitor`.
+
 ## [0.5.3] - 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

@@ -286,6 +286,25 @@ If you don't need extra fields, skip this step — `ExisRay::LogSubscriber` is u
 * **`ExisRay::LogSubscriber`**: Replaces Lograge for HTTP request logging. Subscribes to `process_action.action_controller` and suppresses Rails' default multi-line log subscribers. Compatible with Rails 6, 7, and 8. Subclass it and override `self.extra_fields(event)` to inject custom fields.
 * **`ExisRay::TaskMonitor`**: The entry point for non-HTTP processes.
 
+## Known Behaviors
+
+### Third-party gem warnings in `body`
+
+ExisRay captures all log output — including warnings emitted by third-party gems — and routes free-text lines to the `body` field. Some gems may include user-identifying data in their warnings.
+
+**Example:** The [Bullet](https://github.com/flyerhzm/bullet) N+1 query detector emits warnings like:
+
+```
+user: gabriel
+GET /clients?page=1
+USE eager loading detected
+  Client => [:gps_point]
+```
+
+This text lands verbatim in `body`. ExisRay does not filter or redact `body` content, as it cannot know what third-party gems will include.
+
+**Recommendation:** If you use Bullet or similar gems in production, configure them to use a separate notification channel (e.g., Slack, Honeybadger) instead of `Rails.logger`, to avoid leaking usernames or other PII into your structured logs.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

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/log_subscriber.rb

@@ -84,7 +84,7 @@ module ExisRay
         action:         payload[:action],
         status:         status,
         duration_s:     duration_s,
-        duration_human: ActiveSupport::Duration.build(duration_s).inspect,
+        duration_human: ExisRay::Tracer.format_duration(duration_s),
         view_runtime_s: view_s,
         db_runtime_s:   db_s
       }

data/lib/exis_ray/task_monitor.rb

@@ -35,12 +35,12 @@ module ExisRay
       execute_with_optional_tags { yield }
 
       duration_s = ExisRay::Tracer.current_duration_s
-      human_time = ActiveSupport::Duration.build(duration_s).inspect
+      human_time = ExisRay::Tracer.format_duration(duration_s)
 
       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
       duration_s = ExisRay::Tracer.current_duration_s
-      human_time = ActiveSupport::Duration.build(duration_s).inspect
+      human_time = ExisRay::Tracer.format_duration(duration_s)
 
       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

data/lib/exis_ray/tracer.rb

@@ -70,6 +70,23 @@ module ExisRay
       (Process.clock_gettime(Process::CLOCK_MONOTONIC) - created_at).round(4)
     end
 
+    # Formatea una duración en segundos a un string legible por humanos.
+    # - Menos de 1s  → "7.2ms"
+    # - Entre 1-60s  → "1.25s"
+    # - 60s o más    → "2 minutes 5 seconds" (via ActiveSupport::Duration)
+    #
+    # @param seconds [Float] Duración en segundos.
+    # @return [String]
+    def self.format_duration(seconds)
+      if seconds < 1.0
+        "#{(seconds * 1000).round(1)}ms"
+      elsif seconds < 60.0
+        "#{seconds.round(3)}s"
+      else
+        ActiveSupport::Duration.build(seconds.round).inspect
+      end
+    end
+
     # Construye el header de trazabilidad para enviar al siguiente servicio.
     #
     # @return [String] Header formateado: "Root=...;Self=...;CalledFrom=...;TotalTimeSoFar=...ms"

data/lib/exis_ray/version.rb

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

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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.5
 platform: ruby
 authors:
 - Gabriel Edera
@@ -45,6 +45,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gemini/docs/TELEMETRY_GUIDELINES.md"
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt