exis_ray 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91d6964520e83c2088af45357edf601358d2ffefbff4861ef15e1abaf09a36bc
-  data.tar.gz: d276b0753bd7b956662a3f6e1d61cb51d707a9729496f17b8bd4a3ca1bc7fba4
+  metadata.gz: 5dd52ddf30f1d4eaaaad95ed4acde4bd94c8dd4a01b20853f42ddd71887c0876
+  data.tar.gz: 329163a0bbbd0473e8da70971822c645de763f6a2c99eb4ccf1c973603cd700e
 SHA512:
-  metadata.gz: 4b382e4fcd8171db8771f9f5f8d2238fdf2cd17b2ac4e953c54d06248eab390c321bf37579b954e3965bb7092c0959dcfae999782200ea8cbee487ca6c74b314
-  data.tar.gz: a6da50e40e16e4560d6c52e6443b36d2c7ffef5263940b73a3696d7411817ef5990cd26bf625141984694b7d2f824b22fdd88ba2e9072762b721b9e1718a3eaf
+  metadata.gz: 9eb8bb340dae5b7f423e206ed1fa708caf0b599be0bfc3dd9f1d71209485cf6f2a17a06c9805167cd4988cae20b751f684fda2253d5983efa3c3d9e456e51849
+  data.tar.gz: e18cf7eaa0962d39591072eb9241df8c950c0d1d1c1786aaff4d84ebc4acd1b6ff993b280f5bedc6175bbabd56a0a75f0e8f92a50b899051a1942d21e91888fc

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.7.2] - 2026-05-11
+
+### Documentación
+- **Warning sobre `ActiveSupport::TaggedLogging` con JSON logging:** `TaggedLogging` antepone tags como texto raw antes del formatter, rompiendo el JSON (`[req_id] {...}`). `JsonFormatter` ya inyecta `request_id`/`trace_id` como campos JSON — usar ambos genera salida inválida. Documentada la config correcta del logger en `production.rb` (README + SKILL FAQ).
+- **Skill improvements (issue #4):** (1) Clarificado el criterio auto-inyectado vs manual — el formatter solo conoce contexto de ejecución (Tracer/Current), por eso `component` y `event` deben aportarse manualmente. (2) Agregados ejemplos concretos de output JSON lado-a-lado con el input KV/Hash. (3) Completada la lista de campos default de `LogSubscriber` (17 campos con tipos y condiciones, antes truncado con "etc."). (4) Documentados los 3 modos de input del formatter (KV / Hash / string libre) con ejemplos de cada uno.
+
 ## [0.7.1] - 2026-04-06
 
 ### Fixed

data/README.md

@@ -252,22 +252,46 @@ Con `log_format: :json`, `ExisRay::JsonFormatter` reemplaza el formatter de Rail
 {"time":"2026-04-01T14:30:00Z","level":"INFO","severity_number":9,"service":"wispro_agent","service_version":"1.2.3","deployment_environment":"production","root_id":"1-65f...abc","trace_id":"Root=1-65f...;Self=...","source":"http","user_id":42,"isp_id":10,"component":"exis_ray","event":"http_request","method":"GET","path":"/api/v1/users","http_route":"/api/v1/users","http_status":200,"duration_s":0.0452,"user_agent_original":"Mozilla/5.0","server_address":"api.example.com"}
 ```
 
-Los mensajes con formato `key=value` se parsean y elevan al root del JSON. Los valores numéricos se castean automáticamente:
+El formatter acepta tres tipos de mensaje. Los tres producen output JSON equivalente; elegí el que sea más legible para tu caso:
 
 ```ruby
+# 1. String KV — one-liner rápido, valores numéricos se castean
 Rails.logger.info "component=billing event=invoice_created invoice_id=123 total=45.50"
-# => {"time":"...","level":"INFO","service":"...","root_id":"...","component":"billing","event":"invoice_created","invoice_id":123,"total":45.5}
-```
 
-Los mensajes tipo Hash (usados internamente por `LogSubscriber`) se mergean directamente. Los mensajes de texto libre se asignan a la clave `body`:
+# 2. Hash style — payloads complejos o con valores nested
+Rails.logger.info(component: "billing", event: "invoice_created",
+                  invoice: { id: 123, total: 45.50 })
 
-```ruby
+# 3. String libre — fallback, va a la clave `body`
 Rails.logger.info "Algo pasó sin formato KV"
 # => {"time":"...","level":"INFO","service":"...","body":"Algo pasó sin formato KV"}
 ```
 
+Los mensajes Hash también son la forma que usa internamente `LogSubscriber` para emitir el cierre de cada request HTTP.
+
+> **Nota:** `component` (módulo de negocio) y `event` (qué pasó) **no** son auto-inyectados — los aporta el call site. El formatter solo conoce el contexto de **ejecución** (quién, de dónde, con qué identidad), no el contexto del **lugar del código** que loguea.
+
 En modo `:text`, ExisRay inyecta el `trace_id` o `root_id` como tag de Rails (`config.log_tags`) y no modifica el formatter.
 
+### Configuración del logger en producción
+
+Para logs JSON limpios sin códigos ANSI ni texto extra, configurar el logger así:
+
+```ruby
+# config/environments/production.rb
+config.colorize_logging = false
+config.logger = ActiveSupport::Logger.new(STDOUT)
+config.logger.formatter = ExisRay::JsonFormatter
+```
+
+**No usar `ActiveSupport::TaggedLogging`** — agrega tags como texto al inicio de cada línea antes del formatter, lo cual rompe el JSON:
+
+```
+[request_id] {"time":"...","level":"INFO",...}   # ← texto antes del JSON (INVALIDO)
+```
+
+`ExisRay::JsonFormatter` ya inyecta los tags (`request_id`, `trace_id`, etc.) como campos JSON, así que `TaggedLogging` es redundante e incompatible.
+
 ### Campos auto-inyectados
 
 `JsonFormatter` inyecta estos campos automáticamente en cada línea. **Nunca** los incluyas manualmente en tus logs:
@@ -290,17 +314,29 @@ En modo `:text`, ExisRay inyecta el `trace_id` o `root_id` como tag de Rails (`c
 | `task` | Solo en procesos TaskMonitor |
 | `tags` | Solo si hay Rails tagged logging activo |
 
-`LogSubscriber` inyecta además estos campos en los logs de requests HTTP:
-
-| Campo | Descripción |
-|:------|:------------|
-| `http_status` | Código HTTP (Integer). Antes `status`, renombrado en v0.6.0 |
-| `http_route` | Template de ruta (ej: `/users/:id`). Resolución via `route.defaults` |
-| `user_agent_original` | Header `User-Agent` del request |
-| `server_address` | Hostname sin puerto del header `Host` |
-| `exception.type` | Clase de la excepción (cuando el request falla) |
-| `exception.message` | Mensaje de la excepción |
-| `exception.stacktrace` | Primeras 20 líneas del backtrace |
+`LogSubscriber` inyecta además estos campos en cada log de cierre de request HTTP. **Nunca duplicarlos** en logs manuales:
+
+| Campo | Tipo | Notas |
+|:------|:-----|:------|
+| `component` | String | Siempre `"exis_ray"` |
+| `event` | String | Siempre `"http_request"` |
+| `method` | String | Verbo HTTP |
+| `path` | String | URL concreta del request |
+| `http_route` | String | Template (ej: `/users/:id`). Baja cardinalidad para dashboards |
+| `format` | Symbol/String | `html`, `json`, etc. |
+| `controller` | String | Class name del controller |
+| `action` | String | Nombre del action |
+| `http_status` | Integer | Status HTTP final. Antes `status`, renombrado en v0.6.0 |
+| `duration_s` | Float | Segundos (Rails reporta ms, se convierte), redondeo 4 decimales |
+| `duration_human` | String | Legible: `"42.5ms"`, `"1.25s"`, `"2 minutes 5 seconds"` |
+| `view_runtime_s` | Float\|nil | Solo si Rails lo reporta |
+| `db_runtime_s` | Float\|nil | Solo si ActiveRecord lo reporta |
+| `user_agent_original` | String | Header `User-Agent` |
+| `server_address` | String | Hostname sin puerto del header `Host` |
+| `error_class`, `error_message` | String | Solo en fallo (legacy) |
+| `exception.type`, `exception.message`, `exception.stacktrace` | String | Solo en fallo (OTel; stack limitado a 20 líneas) |
+
+Severity del log: `ERROR` si `http_status >= 500`, sino `INFO`.
 
 ### Filtrado de claves sensibles
 

data/lib/exis_ray/version.rb

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

data/skill/SKILL.md

@@ -71,8 +71,8 @@ ExisRay unifica trazabilidad distribuida, logging estructurado JSON, contexto de
 2. `Tracer.parse_trace_id` extrae `root_id`, `self_id`, `called_from`, `total_time_so_far`
 3. `ExisRay.sync_correlation_id` asigna `Tracer.correlation_id` a `Current.correlation_id`
 4. Controller ejecuta `before_action` para setear `Current.user_id`, `Current.isp_id`
-5. `JsonFormatter` intercepta cada `Rails.logger.*` e inyecta automaticamente: `time`, `level`, `severity_number`, `service`, `service_version`, `deployment_environment`, `root_id`, `trace_id`, `source`, `user_id`, `isp_id`, `correlation_id`
-6. `LogSubscriber` emite un unico Hash al finalizar el request (method, path, http_status, http_route, duration_s, user_agent_original, server_address, etc.)
+5. `JsonFormatter` intercepta cada `Rails.logger.*` e inyecta automaticamente: `time`, `level`, `severity_number`, `service`, `service_version`, `deployment_environment`, `root_id`, `trace_id`, `source`, `user_id`, `isp_id`, `correlation_id`. El developer aporta `component` (modulo de negocio) y `event` (que paso); estos NO son auto-inyectados porque dependen del call site, no del contexto de ejecucion.
+6. `LogSubscriber` emite un unico Hash al finalizar el request con campos default (`component`, `event`, `method`, `path`, `http_route`, `format`, `controller`, `action`, `http_status`, `duration_s`, `duration_human`, `view_runtime_s`, `db_runtime_s`, `user_agent_original`, `server_address`, y en error `error_class`/`error_message`/`exception.*`).
 7. En llamadas salientes, `FaradayMiddleware`/`ActiveResourceInstrumentation` inyectan `propagation_trace_header` con `Tracer.generate_trace_header`
 8. Al finalizar, `ActiveSupport::CurrentAttributes` hace reset automatico
 
@@ -212,6 +212,32 @@ end
 
 ### ExisRay::LogSubscriber
 
+Reemplaza Lograge. Se suscribe a `process_action.action_controller` y emite un Hash por request HTTP. Severity es `ERROR` si `http_status >= 500`, sino `INFO`.
+
+**Campos default emitidos** (mergeados al payload JSON; nunca duplicarlos manualmente):
+
+| Campo | Tipo | Notas |
+|:------|:-----|:------|
+| `component` | String | Siempre `"exis_ray"` |
+| `event` | String | Siempre `"http_request"` |
+| `method` | String | Verbo HTTP |
+| `path` | String | URL concreta del request |
+| `http_route` | String | Template (ej: `/users/:id`). Baja cardinalidad para dashboards |
+| `format` | Symbol/String | `html`, `json`, etc. |
+| `controller` | String | Class name del controller |
+| `action` | String | Nombre del action |
+| `http_status` | Integer | Status HTTP final |
+| `duration_s` | Float | Segundos (Rails reporta ms, se convierte), redondeo 4 decimales |
+| `duration_human` | String | Legible: `"42.5ms"`, `"1.25s"`, `"2 minutes 5 seconds"` |
+| `view_runtime_s` | Float\|nil | Solo si Rails lo reporta |
+| `db_runtime_s` | Float\|nil | Solo si ActiveRecord lo reporta |
+| `user_agent_original` | String | Header `User-Agent` |
+| `server_address` | String | Hostname sin puerto (de `Host` header) |
+| `error_class`, `error_message` | String | Solo en fallo (legacy) |
+| `exception.type`, `exception.message`, `exception.stacktrace` | String | Solo en fallo (OTel; stack limitado a 20 lineas) |
+
+Para inyectar campos extra, sobreescribir `extra_fields`:
+
 ```ruby
 class MyLogSubscriber < ExisRay::LogSubscriber
   def self.extra_fields(event)
@@ -227,12 +253,41 @@ ExisRay.configure { |c| c.log_subscriber_class = "MyLogSubscriber" }
 
 Se asigna automaticamente a `Rails.logger.formatter` cuando `log_format: :json`. Acepta tres tipos de mensaje:
 
-- **Hash**: merge directo al payload JSON
-- **String KV** (`"event=foo bar=baz"`): parsea pares y los eleva al root del JSON
-- **String libre**: asigna al campo `body`
+- **Hash**: merge directo al payload JSON. Util para payloads complejos o con valores nested.
+- **String KV** (`"event=foo bar=baz"`): parsea pares y los eleva al root del JSON. Util para one-liners rapidos.
+- **String libre**: asigna al campo `body` (OTel log body).
 
 Casteo automatico: integers, floats, objetos JSON (`{...}`, `[...]`). Filtra claves sensibles (`password|secret|token|api_key|auth`) a `[FILTERED]`. Fallback a JSON minimo si el formateo falla.
 
+#### Criterio auto-inyectado vs manual
+
+- **Auto-inyectado** (formatter conoce desde `Tracer`/`Current`): contexto de **ejecucion** — quien hace el request, de donde viene, en que servicio, con que identidad.
+- **Manual** (lo aporta cada `Rails.logger.*`): contexto del **call site** — que modulo (`component`) y que paso (`event`). El formatter no puede saber esto sin recorrer el stack en cada log.
+
+Por eso `component` y `event` jamas se auto-inyectan, aunque el estandar Wispro los exija.
+
+#### Ejemplos: KV vs Hash producen output equivalente
+
+```ruby
+# KV string — one-liner rapido
+Rails.logger.info("component=billing event=invoice_paid invoice_id=42 total=199.99")
+
+# Hash style — payloads complejos / nested
+Rails.logger.info(component: "billing", event: "invoice_paid",
+                  invoice: { id: 42, total: 199.99 })
+
+# String libre — fallback, va a `body`
+Rails.logger.info("usuario hizo click")
+```
+
+#### Output JSON resultante (mismo para KV y Hash del ejemplo)
+
+```json
+{"time":"2026-05-11T09:15:00.123Z","level":"INFO","severity_number":9,"service":"box_radius_manager","service_version":"1.2.3","deployment_environment":"production","root_id":"1-abc","trace_id":"Root=1-abc;Self=...","source":"http","user_id":42,"isp_id":10,"correlation_id":"box_radius_manager;1-abc","component":"billing","event":"invoice_paid","invoice_id":42,"total":199.99}
+```
+
+Los campos hasta `correlation_id` los inyecta el formatter automaticamente. De `component` en adelante son los campos del mensaje del developer.
+
 ### Middlewares de propagacion
 
 ```ruby
@@ -290,6 +345,20 @@ Agrega `f.use ExisRay::FaradayMiddleware` al stack de Faraday. Solo inyecta head
 **P: Puedo usar ExisRay sin JSON logging?**
 Si. Con `log_format: :text` (default), ExisRay inyecta el `root_id` como tag de Rails via `config.log_tags`. El JsonFormatter y LogSubscriber no se activan.
 
+**P: Por que no usar `ActiveSupport::TaggedLogging` con JSON logging?**
+`TaggedLogging` agrega tags como texto plano al inicio de cada línea **antes** del formatter, lo cual rompe el JSON:
+```
+[request_id] {"time":"...","level":"INFO",...}   # ← texto antes del JSON
+```
+`ExisRay::JsonFormatter` ya inyecta los tags (`request_id`, `trace_id`, etc.) como campos JSON. Usar ambos genera JSON inválido.
+
+Configuración correcta en production.rb:
+```ruby
+config.colorize_logging = false
+config.logger = ActiveSupport::Logger.new(STDOUT)
+config.logger.formatter = ExisRay::JsonFormatter
+```
+
 **P: Que pasa con los logs de Sidekiq (el propio logger de Sidekiq)?**
 Si `json_logs?` es true, el Railtie asigna `Sidekiq.logger.formatter = ExisRay::JsonFormatter.new`, asi los logs internos de Sidekiq tambien salen en JSON.
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-07 00:00:00.000000000 Z
+date: 2026-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -87,8 +87,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/gedera/exis_ray
   source_code_uri: https://github.com/gedera/exis_ray
-  changelog_uri: https://github.com/gedera/exis_ray/blob/v0.7.1/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.7.1/skill
+  changelog_uri: https://github.com/gedera/exis_ray/blob/v0.7.2/CHANGELOG.md
+  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.7.2/skill
 post_install_message:
 rdoc_options: []
 require_paths: