exis_ray 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de4cf609747379030a7d49bf06aea93efbe9d60490eb3d9bfe4af3fec0fe1bd4
-  data.tar.gz: 0f3cbba6bf49ffec549c1cc7a306b9c018c12196f4a60afd62769268c5f964bf
+  metadata.gz: d8bf4b504bfe6112b50328a358879a63b5ff19832e4724711a4650a110c94aaf
+  data.tar.gz: fd3332690b0ff0b3ca95ccf4dddbddcb99322fd01481f9da4e11a12d3f0bf801
 SHA512:
-  metadata.gz: 5e9532985f27d6ccb4efe76be22b3ff580eb60169e7f7c4a6a9db4ae19ac05a41489d43635f754deb6effd7732c97203ab0e28c19ae845f41f1a284ed79231ec
-  data.tar.gz: 40796e0043612a9636e212ae4ced8e096a984144e35f4d1e4baa9a1216514f8916ad9f3b2c054852861157015b4d37e9987da5e6b335a34254d0e5b5b8327468
+  metadata.gz: 639eb1ab36f013dbf034dd7be88e5c13ab77779ed6a130d0f28cb75ace6baf36b0bb7b387f7ec77cb9a37236cb5ac703daa9bfa7116160aeee59ccc18e43b9be
+  data.tar.gz: '0882e98c833ebc8774e47f2ddca1d33ce73fd9b7d8a5427b9851eafcab4323c41b0253d512e2ec9b0fd2391120f6390eeb1be2995d924a3674e155cda7c36dcb'

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [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
+- **Official Documentation:** Introduced `MANIFEST.md` as the source of truth for observability standards.
+- **Universal Type-Casting:** Improved `JsonFormatter` to apply automatic numeric casting (Integer/Float) to direct `Hash` inputs, not just KV strings.
+- **Security Hardening:** Documented explicit bans on PII in logs and established valid `source` entrypoint values.
+
 ## [0.5.1] - 2026-03-24
 
 ### Fixed

data/CLAUDE.md

@@ -4,11 +4,18 @@
 - `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::JsonFormatter`: Core engine. Handles Hash, KV strings, and free-text with automatic masking and **Type Casting**.
 - `ExisRay::LogSubscriber`: Native HTTP logger since v0.4.0. Replaces Lograge.
+- `ExisRay::TaskMonitor`: Lifecycle manager for non-HTTP processes.
 
 ## Technical Knowledge & Compatibility
 
+### Wispro Observability Spec (v1)
+- **Manifest:** All logging MUST follow the rules defined in `MANIFEST.md`.
+- **Metrics:** Always use `_s` suffix for durations (Float) and `count` for volumes (Integer). Never include units in values.
+- **Type-Awareness:** `JsonFormatter` automatically casts numeric KV values to Float/Integer. Emit raw numbers in KV strings.
+- **Automatic Fields:** Do not manually log `time`, `level`, `service`, `source`, `root_id`, `correlation_id`, `sidekiq_job` or `task`. These are handled by the library.
+
 ### 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.
@@ -17,11 +24,14 @@
 - **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`.
+## Security & Privacy
+- **Sensitive Key Filtering:** `JsonFormatter` auto-filters keys matching `password|pass|passwd|secret|token|api_key|auth` → replaced with `[FILTERED]`.
+- **Header Injection Prevention:** `ExisRay::Current` sanitizes values via `sanitize_header_value` before storing user/ISP identity.
+- **No PII in Logs:** Never log raw user data. Only IDs (`user_id`, `isp_id`) are permitted.
 
 ## 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.
+- **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

@@ -0,0 +1,98 @@
+# Observability & Telemetry Manifest
+
+Este documento define el estándar obligatorio de telemetría y logging estructurado para todo nuestro ecosistema de software. El objetivo es garantizar que cualquier sistema, independientemente de su propósito, emita datos que sean **analizables, consistentes y escalables**.
+
+## Objetivo
+Transformar el logging tradicional en un **flujo de eventos de datos**. Esto permite que herramientas de análisis puedan generar dashboards de rendimiento, alertas inteligentes y rastreo de errores sin necesidad de procesamiento manual de texto o transformaciones complejas.
+
+## Reglas Fundamentales
+
+### 1. Unidad en la Key, Número en el Valor (Data First)
+La regla de oro para que las métricas sean operables es separar la unidad del dato numérico. **Nunca** incluir unidades dentro de los valores de los logs.
+*   Incorrecto: `duration="0.5s"`, `memory="128MB"`.
+*   Correcto: `duration_s=0.5`, `memory_mb=128`.
+
+**Sufijos de unidad recomendados:**
+- `_s`: Segundos (Float). Estándar para duraciones y latencias visibles al negocio.
+- `_ms`: Milisegundos (Integer). Para precisión técnica interna de alta frecuencia.
+- `_count`: Cantidades o volúmenes (Integer). Ej: `record_count`, `retry_count`.
+- `_bytes` / `_kb` / `_mb`: Unidades de almacenamiento o memoria.
+- `_human`: (Opcional) Texto explicativo legible para humanos (ej: `duration_human="2 hours"`).
+
+### 2. Contexto de Identidad
+Cada línea de log debe llevar los metadatos necesarios para identificar su origen técnico de forma inmediata:
+*   `component`: Nombre de la gema, librería o módulo responsable (ej: `exis_ray`, `storage_engine`).
+*   `event`: Nombre de la acción puntual o hito alcanzado (ej: `http_request`, `engine.complete`).
+*   `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`.
+- **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)
+
+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 | Por qué no incluirla |
+| :--- | :--- | :--- |
+| `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)
+Todo proceso aislado debe reportar su inicio y su finalización con una estructura consistente:
+- `event`: Identificador de estado (ej: `task_started`, `task_finished`).
+- `status`: Resultado final de la operación (`success`, `failed`, `aborted`). En contexto de tareas/jobs, siempre es un string semántico, no un código HTTP.
+- `duration_s`: Tiempo total de ejecución (calculado con reloj monotónico).
+- `error_class` / `error_message`: Obligatorios solo en caso de fallo.
+
+### Peticiones de Interfaz (APIs/HTTP)
+Los logs de cierre de peticiones deben estandarizar el reporte de rendimiento para telemetría:
+- `status`: Código de respuesta HTTP (Integer). En contexto HTTP siempre es el código numérico (ej: `200`, `404`, `500`).
+- `duration_s`: Tiempo total de respuesta del servidor.
+- `[subsystem]_runtime_s`: Desglose opcional de tiempos por capa (ej: `db_runtime_s`, `view_runtime_s`).
+
+---
+
+## Ejemplo de Implementación Estándar
+
+**En el código fuente:**
+```ruby
+# Reporte de éxito con métricas integradas
+logger.info "component=data_processor event=sync_complete status=success duration_s=1.25 record_count=500"
+
+# Reporte de error con contexto técnico
+logger.error "component=data_processor event=sync_complete status=failed error_class=Timeout error_message=\"Server reset\""
+```
+
+**Resultado JSON unificado:**
+```json
+{
+  "time": "2026-03-24T14:00:00Z",
+  "level": "INFO",
+  "service": "my_application",
+  "component": "data_processor",
+  "event": "sync_complete",
+  "status": "success",
+  "duration_s": 1.25,
+  "record_count": 500,
+  "source": "task",
+  "root_id": "Root=1-...",
+  "correlation_id": "my_application;Root=..."
+}
+```

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

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
@@ -165,7 +171,7 @@ module ExisRay
         result[k] = if v.is_a?(Hash)
                       filter_sensitive_hash(v)
                     else
-                      filter_sensitive_value(k, v)
+                      cast_value(k, v)
                     end
       end
     end

data/lib/exis_ray/version.rb

@@ -2,5 +2,5 @@
 
 module ExisRay
   # Versión actual de la gema.
-  VERSION = "0.5.1"
+  VERSION = "0.5.3"
 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.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Gabriel Edera
@@ -48,6 +48,7 @@ files:
 - CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
+- MANIFEST.md
 - README.md
 - Rakefile
 - lib/exis_ray.rb