exis_ray 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddc4b5882506b1b65b8b6c6feedfed798b1f810b234f8894165bec04992390c1
-  data.tar.gz: d45294e9c7eb72f3e936f93f73240eb6b88526524c9fadea1e599f8561d08413
+  metadata.gz: 13877001eee2022a6c6de0d2709ef5080b0cc2e43459d5e81ea99d9f28f9b216
+  data.tar.gz: c6b551a316813a3671ae980a0fc8061b32fc1b585bc39b49a5c761a73c3af145
 SHA512:
-  metadata.gz: b6e9a927b39630af22182153eeaa0130c76d971abf3e57b3d0271ff5b827f2170e49df978ff745daedcaae529b896d555e6f65651ffd758061f471ac087b4a32
-  data.tar.gz: d050fb07c85131b1fac04bd588f3b24a43c2f345a9499178004b6458754836dd6ee8bec489b2c403fbdfd2366ddb5480984b4c656fe72e813892cedf2a52dc86
+  metadata.gz: e41a2bc99ab67896aac64e6eb8becca74fd03217807fa16e24ed434477109b053f9d9580b206a2c4f4123fefa6beca5f580b934e22c468175d20fa808179a7eb
+  data.tar.gz: 80bc6a49ea2b9ed2e4b45aa3f4e501752edb2d5873a8871cce6ba3b4e1bf4f925fb793a3ba5ab1a0f9c717d4ee63c9411bc1d738ab7d9a742ed48585071664fd

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [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
+- **OpenTelemetry Alignment:** Free-text log lines now emit their content under the `body` key instead of `message`, following the OpenTelemetry Log Data Model specification.
+
+### Fixed
+- **Robust KV Parsing:** Added support for single-quoted values (`' '`) in the KV parser. This fixes cases where human-readable durations or other strings used single quotes.
+- **Quote Sanitization:** Values extracted from the KV parser now have surrounding quotes (single or double) removed before JSON emission.
+
 ## [0.5.2] - 2026-03-24
 
 ### Added

data/CLAUDE.md

@@ -33,4 +33,5 @@
 - **No Lograge:** Do not suggest or re-add the Lograge dependency.
 - **Pure Data Logging:** Internal logs use KV strings (`component=exis_ray event=...`).
 - **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

@@ -30,26 +30,28 @@ Cada línea de log debe llevar los metadatos necesarios para identificar su orig
 - **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.
 
----
-
-## Infraestructura de Datos (Automática)
+## 🏗 Infraestructura de Datos (Automática)
 
-La gema `exis_ray` inyecta automáticamente los siguientes metadatos en cada línea de log JSON, por lo que **no deben incluirse manualmente** en los mensajes:
+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:
 
-| Llave | Descripción | Origen |
+| Llave | Descripción | Por qué no incluirla |
 | :--- | :--- | :--- |
-| `time` | Marca de tiempo en formato ISO8601 UTC. | Logger |
-| `level` | Nivel de severidad (INFO, ERROR, DEBUG, etc.). | Logger |
-| `service` | Nombre de la aplicación en `snake_case`. | Tracer |
-| `source` | Entrypoint: `http`, `sidekiq`, `task` o `system`. | Tracer |
-| `root_id` | Identificador único de la traza distribuida (AWS X-Ray). | Tracer |
-| `correlation_id` | ID compuesto para rastreo cruzado. | Tracer |
-| `user_id` / `isp_id` | Identidad del sujeto de negocio (si está presente). | Current |
-| `sidekiq_job` | Nombre de la clase del Worker (solo en Sidekiq). | Tracer |
-| `task` | Nombre de la tarea Rake o Cron (solo en TaskMonitor). | Tracer |
+| `time` | Timestamp ISO8601 | Lo añade el Logger base. |
+| `level` | INFO, ERROR, etc. | Lo añade el Logger base. |
+| `service` | Nombre de la App | Se obtiene de la configuración global. |
+| `source` | Entrypoint (http, task) | Lo inyecta el middleware/monitor correspondiente. |
+| `root_id` | Trace ID (AWS X-Ray) | Se gestiona a nivel de hilo/petición. |
+| `correlation_id`| ID de rastreo cruzado | Se genera automáticamente al inicio de la ejecución. |
+| `user_id` / `isp_id`| Contexto de negocio | Se extrae del estado global de la petición. |
+| `sidekiq_job` | Clase del Worker | Inyectado automáticamente en procesos Sidekiq. |
+| `task` | Nombre de la tarea | Inyectado automáticamente por el TaskMonitor. |
+
+> **Regla de Oro:** Tu log manual solo debe contener datos de **tu lógica de negocio**. La infraestructura ya sabe quién eres, de dónde vienes y cuál es tu ID de traza.
 
 ---
 
+## 🛰 Ciclo de Vida del Evento
+
 ## Ciclo de Vida del Evento
 
 ### Procesos, Trabajos y Tareas (Jobs/Tasks)

data/README.md

@@ -148,14 +148,14 @@ end
 
 When `config.log_format = :json` is enabled, ExisRay transforms all your application outputs into single-line, context-rich JSON objects.
 
-**HTTP Requests (via Lograge):**
+**HTTP Requests:**
 ```json
 {"time":"2026-03-12T14:30:00Z","level":"INFO","service":"App-HTTP","root_id":"Root=1-65a...bc","trace_id":"Root=1-65a...bc;Self=...","request_id":"9876-abcd-...","user_id":42,"isp_id":10,"method":"GET","path":"/api/v1/users","format":"html","controller":"UsersController","action":"index","status":200,"duration":45.2,"view":20.1,"db":15.0}
 ```
 
 **Sidekiq Jobs & Rake Tasks:**
 ```json
-{"time":"2026-03-12T14:31:00Z","level":"INFO","service":"Sidekiq-HardWorker","root_id":"Root=1-65a...bc","user_id":42,"message":"[ExisRay] Processing payment..."}
+{"time":"2026-03-12T14:31:00Z","level":"INFO","service":"Sidekiq-HardWorker","root_id":"Root=1-65a...bc","user_id":42,"body":"[ExisRay] Processing payment..."}
 ```
 
 ### B. Automatic Sidekiq Integration
@@ -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

@@ -22,8 +22,8 @@ module ExisRay
     # Detecta si un string comienza con al menos un par key=value.
     KV_DETECT_RE = /\A\w+=/
 
-    # Extrae pares key=value de un string. Soporta valores sin espacios o entre comillas dobles.
-    KV_PARSE_RE  = /(\w+)=("(?:[^"\\]|\\.)*"|\S+)/
+    # Extrae pares key=value de un string. Soporta valores sin espacios o entre comillas dobles/simples.
+    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
@@ -99,7 +99,7 @@ module ExisRay
     # se hace un merge directo. Si es un String con formato key=value (ej: "event=foo bar=baz"),
     # se parsea y los campos se elevan al nivel raíz del JSON. Valores con espacios deben estar
     # entre comillas (ej: message="algo salió mal"). Si el String no sigue ese formato, se asigna
-    # a la clave `:message`.
+    # a la clave `:body` (OpenTelemetry log body).
     #
     # @param payload [Hash] El diccionario base del log.
     # @param msg [String, Hash, Object] El mensaje original recibido por el logger.
@@ -110,9 +110,9 @@ module ExisRay
         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)
+        parsed.empty? ? payload[:body] = msg : payload.merge!(parsed)
       else
-        payload[:message] = msg.to_s
+        payload[:body] = msg.to_s
       end
     end
 
@@ -126,7 +126,7 @@ module ExisRay
     end
 
     # 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").
+    # Soporta valores con espacios si están entre comillas dobles o simples.
     # Intenta convertir valores numéricos a Float o Integer automáticamente.
     #
     # @param str [String]
@@ -134,7 +134,13 @@ module ExisRay
     def parse_kv_string(str)
       result = {}
       str.scan(KV_PARSE_RE) do |key, value|
-        val = value.start_with?('"') ? (value[1..-2] || "").gsub('\\"', '"') : value
+        # Eliminamos comillas envolventes si existen (dobles o simples)
+        val = if value.start_with?('"', "'")
+                value[1..-2].to_s.gsub("\\#{value[0]}", value[0])
+              else
+                value
+              end
+
         result[key.to_sym] = cast_value(key, val)
       end
       result

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.2"
+  VERSION = "0.5.4"
 end

data/spec/exis_ray/json_formatter_spec.rb

@@ -98,32 +98,32 @@ RSpec.describe ExisRay::JsonFormatter do
       end
     end
 
-      it "cae a message si el string parece kv pero no produce ningún par" do
+      it "cae a body si el string parece kv pero no produce ningún par" do
         result = call("key=")
 
-        expect(result["message"]).to eq("key=")
+        expect(result["body"]).to eq("key=")
         expect(result).not_to have_key("key")
       end
     end
 
     context "cuando el mensaje es un String libre (sin formato key=value)" do
-      it "asigna el string completo al campo message" do
+      it "asigna el string completo al campo body" do
         result = call("algo salió mal")
 
-        expect(result["message"]).to eq("algo salió mal")
+        expect(result["body"]).to eq("algo salió mal")
         expect(result).to include("level" => "INFO", "service" => "test-service")
       end
 
-      it "asigna un string vacío al campo message" do
+      it "asigna un string vacío al campo body" do
         result = call("")
 
-        expect(result["message"]).to eq("")
+        expect(result["body"]).to eq("")
       end
 
       it "convierte objetos arbitrarios a string via to_s" do
         result = call(42)
 
-        expect(result["message"]).to eq("42")
+        expect(result["body"]).to eq("42")
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.4
 platform: ruby
 authors:
 - Gabriel Edera