exis_ray 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de4cf609747379030a7d49bf06aea93efbe9d60490eb3d9bfe4af3fec0fe1bd4
-  data.tar.gz: 0f3cbba6bf49ffec549c1cc7a306b9c018c12196f4a60afd62769268c5f964bf
+  metadata.gz: ddc4b5882506b1b65b8b6c6feedfed798b1f810b234f8894165bec04992390c1
+  data.tar.gz: d45294e9c7eb72f3e936f93f73240eb6b88526524c9fadea1e599f8561d08413
 SHA512:
-  metadata.gz: 5e9532985f27d6ccb4efe76be22b3ff580eb60169e7f7c4a6a9db4ae19ac05a41489d43635f754deb6effd7732c97203ab0e28c19ae845f41f1a284ed79231ec
-  data.tar.gz: 40796e0043612a9636e212ae4ced8e096a984144e35f4d1e4baa9a1216514f8916ad9f3b2c054852861157015b4d37e9987da5e6b335a34254d0e5b5b8327468
+  metadata.gz: b6e9a927b39630af22182153eeaa0130c76d971abf3e57b3d0271ff5b827f2170e49df978ff745daedcaae529b896d555e6f65651ffd758061f471ac087b4a32
+  data.tar.gz: d050fb07c85131b1fac04bd588f3b24a43c2f345a9499178004b6458754836dd6ee8bec489b2c403fbdfd2366ddb5480984b4c656fe72e813892cedf2a52dc86

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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,13 @@
 - **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`.
+- **Source Values:** Valid values for `source` field: `http`, `sidekiq`, `task`, `system`.

data/MANIFEST.md

@@ -0,0 +1,96 @@
+# 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)
+
+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:
+
+| Llave | Descripción | Origen |
+| :--- | :--- | :--- |
+| `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 |
+
+---
+
+## 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/lib/exis_ray/json_formatter.rb

@@ -165,7 +165,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.2"
 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.2
 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