exis_ray 0.7.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd52ddf30f1d4eaaaad95ed4acde4bd94c8dd4a01b20853f42ddd71887c0876
-  data.tar.gz: 329163a0bbbd0473e8da70971822c645de763f6a2c99eb4ccf1c973603cd700e
+  metadata.gz: c87f049dd7216e8ac33a9844b77cd1c863f9248130b329994002aa654c0c47ca
+  data.tar.gz: 1752d432a8437178121b36a0b28293f52f96b99d13a5c40589f312fb8f9b6236
 SHA512:
-  metadata.gz: 9eb8bb340dae5b7f423e206ed1fa708caf0b599be0bfc3dd9f1d71209485cf6f2a17a06c9805167cd4988cae20b751f684fda2253d5983efa3c3d9e456e51849
-  data.tar.gz: e18cf7eaa0962d39591072eb9241df8c950c0d1d1c1786aaff4d84ebc4acd1b6ff993b280f5bedc6175bbabd56a0a75f0e8f92a50b899051a1942d21e91888fc
+  metadata.gz: 72f092befb65f8eb03fe851a302ec49ac47fb155a288ed1103923766f0322da6e5704e760d8c6fa7e4865d78666ddc29b7f7c5e486f22120de1c0ff4a072777e
+  data.tar.gz: 57e552a85bc42d9cb659d49a429c85131175350542856378d432063b9558f264a636c93d4a25ee57b51717718c5bcb03a2f86fbff3676ce85fedfde4562f5509

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.9.0] - 2026-05-19
+
+### Correcciones
+- **HTTP entrypoint sin trace header no emitía `root_id`/`source`/`request_id`** (#9): `HttpMiddleware` era el único entrypoint sin fallback de `root_id`. Un servicio que es punto de entrada (no eslabón intermedio de un trace distribuido) emitía log lines sin `root_id` y, por efecto cascada en `JsonFormatter#inject_tracer_context` (`return unless root_id`), sin `source` —campo mandatorio del estándar Wispro—. Ahora `HttpMiddleware` genera un `root_id` fresco cuando no llega trace header, igual que `Sidekiq::ServerMiddleware`/`BugBunny::ConsumerTracingMiddleware`/`TaskMonitor`. Además `JsonFormatter` emite `request_id` fuera del guard de `root_id` (distinto ciclo de vida: UUID v4 de Rails vs formato X-Ray), así un servicio puede correlacionar por request aunque no haya trace context activo.
+
+### Documentación
+- **Artefactos dev-\* (RFC-008/010)**: nuevos `docs/behavior/behavior.md` (RFC-007 — secuencia de hidratación de trace por entrypoint y emisión en logs, cobertura declarada) y `docs/glossary/glossary.md` (RFC-009 — lenguaje ubicuo del bounded context: `root_id`, `trace_id`, `source`, `request_id`, `entrypoint`, ...). `README.md` y `skill/SKILL.md` recompuestos indexando el detalle (indexa, no duplica): índice de artefactos, nota de coexistencia transitoria para capas F2, version-lock declarado y `description` endurecida como contrato de discoverability.
+
+## [0.8.0] - 2026-05-14
+
+### Nuevas funcionalidades
+- **`Current.log_fields` hook** (#6, #8): class method overridable en `ExisRay::Current` para inyectar campos custom en cada log line. Cubre con un solo mecanismo tanto constantes de proceso (frozen constants en la subclass) como valores dinámicos per-request (atributos de Current). `JsonFormatter` filtra claves sensibles del hash retornado y rescata silenciosamente si el override revienta. Útil para servicios multi-tenant donde se necesita inyectar `tenant_id`, `region`, `stack_id`, etc.
+
+### Mejoras internas
+- **`.rubocop.yml` relajado para destrabar CI**: los thresholds default venían bloqueando todos los PRs recientes. Excluido `Metrics/BlockLength` en specs y railtie, deshabilitado `Lint/SuppressedException` (el estándar Wispro requiere `rescue StandardError` vacíos en logging), thresholds más realistas para Metrics en lib/.
+
 ## [0.7.2] - 2026-05-11
 
 ### Documentación

data/CLAUDE.md

@@ -105,12 +105,14 @@ ExisRay.configuration.json_logs?                # => true/false
 | `service` | Siempre |
 | `service_version` | Siempre (de `config.version` o `config.x.version`) |
 | `deployment_environment` | Siempre (de `Rails.env`) |
+| `request_id` | Cuando `Tracer.request_id` está presente (independiente de root_id) |
 | `root_id` | Cuando hay trace context activo |
 | `trace_id` | Cuando hay trace context activo |
-| `source` | Cuando hay trace context activo |
+| `source` | Cuando hay trace context activo (HTTP siempre genera root fresco si no llega header) |
 | `correlation_id` | Cuando `Current.correlation_id` está presente |
 | `user_id` | Cuando `Current.user_id` está presente |
 | `isp_id` | Cuando `Current.isp_id` está presente |
+| `Current.log_fields` (cualquier key) | Si la subclass overrideó el hook (default `{}`) |
 | `sidekiq_job` | Solo en procesos Sidekiq |
 | `task` | Solo en procesos TaskMonitor |
 | `tags` | Solo si hay Rails tagged logging activo |

data/README.md

@@ -51,11 +51,24 @@ ExisRay opera en tres capas que se combinan automáticamente:
 
 **Flujo de propagación:**
 
-1. Un request/job/mensaje llega al servicio. El middleware correspondiente hidrata el `Tracer` con el header entrante (o genera un nuevo `root_id` si no trae uno).
-2. `JsonFormatter` inyecta automáticamente `root_id`, `trace_id`, `source` y el contexto de negocio (`user_id`, `isp_id`, `correlation_id`) en cada línea de log.
+1. Un request/job/mensaje llega al servicio. El middleware correspondiente hidrata el `Tracer` con el header entrante. **Todo entrypoint garantiza un `root_id`**: si no llega trace header (servicio que es punto de entrada, no eslabón intermedio), genera uno fresco. En HTTP además captura el `request_id` de Rails.
+2. `JsonFormatter` inyecta automáticamente `root_id`, `trace_id`, `source`, `request_id` y el contexto de negocio (`user_id`, `isp_id`, `correlation_id`) en cada línea de log. Como el entrypoint siempre asegura `root_id`, `source` (campo mandatorio) nunca falta.
 3. Cuando el servicio llama a otro servicio (HTTP, Sidekiq, RabbitMQ), el middleware de salida genera un nuevo header con `Tracer.generate_trace_header`, que incluye el `root_id` original, el `self_id` del servicio actual, el `CalledFrom` y el tiempo acumulado.
 4. El servicio destino repite desde el paso 1. El `root_id` se mantiene constante a lo largo de toda la cadena.
 
+## Documentación de detalle
+
+Artefactos de detalle (RFC-008 — el contrato y el significado viven acá; este README indexa y resume, no duplica):
+
+| Capa | Artefacto | Estado |
+|:-----|:----------|:-------|
+| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) — secuencias de hidratación de trace por entrypoint y emisión en logs | parcial, incremental por PR |
+| Glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) — lenguaje ubicuo (`root_id`, `trace_id`, `source`, `request_id`, `entrypoint`, ...) | sembrado inicial, acreta |
+| Datos | — | n/a (gema sin DB) |
+| Operaciones · Interfaz · Topología | — | F2 `dev-structure`, no implementado |
+
+> **Coexistencia transitoria (RFC-008 §2):** las secciones _Cómo funciona_, _Campos auto-inyectados_ y _Referencia del Tracer_ de este README contienen contrato/arquitectura cuyo destino estructural (`docs/interface`, `docs/topology`) es **F2 no implementado**. Permanecen embebidas hasta que esas capas existan; el significado y las secuencias ya migraron a `docs/glossary` y `docs/behavior` y se referencian desde acá.
+
 ## Instalación
 
 ```ruby
@@ -151,6 +164,38 @@ end
 | `Current.user?` / `Current.isp?` | Predicate: true si el ID no es nil |
 | `Current.correlation_id?` | Predicate: true si está presente (no vacío) |
 
+#### Hook `log_fields` — inyectar campos custom en cada log
+
+`Current.log_fields` es un class method overridable que retorna un Hash de campos
+extra a inyectar en cada log line, junto a `user_id`/`isp_id`/`correlation_id`.
+Cubre tanto **constantes de proceso** (declaradas como frozen constants en la
+subclass) como **valores dinámicos per-request** (leídos de atributos de
+`Current`) — todo en un solo lugar.
+
+```ruby
+class Current < ExisRay::Current
+  TENANT_ID = ENV.fetch("TENANT_ID").freeze   # static, frozen al boot
+  attribute :region                             # dynamic, per-request
+
+  def self.log_fields
+    { tenant_id: TENANT_ID, region: region }.compact
+  end
+end
+
+# En un before_action / middleware:
+Current.region = request.headers["X-Region"]
+
+# Los logs salen automáticamente con tenant_id y region:
+# {"...":"...", "tenant_id":"42", "region":"us-east-1", "event":"..."}
+```
+
+**Reglas:**
+
+- Default `{}` — cero overhead si no se override.
+- `JsonFormatter` filtra claves sensibles del hash retornado (`api_key`, `token`, etc.).
+- Si el override revienta, el formatter lo rescata silenciosamente (logging nunca debe afectar el flujo principal).
+- **Precedencia**: los campos canónicos del Tracer (`trace_id`, `root_id`, etc.) y las keys del propio mensaje del developer (ej. `Rails.logger.info "tenant_id=99"`) pisan `log_fields`. No sirve para overrideear campos canónicos, solo para agregar nuevos.
+
 ### Reporter (reporte de errores)
 
 `ExisRay::Reporter` es un wrapper de Sentry que enriquece automáticamente cada evento con el trace context del `Tracer` y el contexto de negocio del `Current`. Soporta Sentry SDK moderno y legacy (Raven/Session).
@@ -304,12 +349,14 @@ config.logger.formatter = ExisRay::JsonFormatter
 | `service` | Siempre (nombre de la app Rails en snake_case) |
 | `service_version` | Siempre (lee de `config.version` o `config.x.version`) |
 | `deployment_environment` | Siempre (lee de `Rails.env`) |
-| `root_id` | Cuando hay trace context activo |
-| `trace_id` | Cuando hay trace context activo |
-| `source` | Cuando hay trace context activo (`http`, `sidekiq`, `task`, `system`) |
+| `request_id` | Cuando `Tracer.request_id` está presente (independiente del trace context — ver [glosario](docs/glossary/glossary.md)) |
+| `root_id` | Siempre en cualquier entrypoint (genera uno fresco si no llega trace header) |
+| `trace_id` | Cuando hay trace header entrante parseado (eslabón intermedio) |
+| `source` | Siempre en cualquier entrypoint (`http`, `sidekiq`, `task`, `system`) |
 | `correlation_id` | Cuando `Current.correlation_id` está presente |
 | `user_id` | Cuando `Current.user_id` no es nil |
 | `isp_id` | Cuando `Current.isp_id` no es nil |
+| `Current.log_fields` (cualquier key) | Si la subclass overrideó el hook y retornó un Hash no vacío |
 | `sidekiq_job` | Solo en procesos Sidekiq |
 | `task` | Solo en procesos TaskMonitor |
 | `tags` | Solo si hay Rails tagged logging activo |

data/docs/behavior/behavior.md

@@ -0,0 +1,75 @@
+# Comportamiento — exis_ray
+
+> meta: artefacto · RFC-007 (UML 2.x sequence / BPMN 2.0, render Mermaid) · generado dev-enrich · anclado a commit `00cf803` (v0.8.0 + fix issue #9) · cobertura **parcial incremental**
+
+## 1. Resumen
+
+Comportamiento runtime de la trazabilidad distribuida: hidratación del `Tracer` en cada entrypoint y emisión del contexto en cada línea de log. Documentación **incremental** — este artefacto se inició con el PR del issue #9 (flujo de entrypoint HTTP); el resto de flujos se acreta cuando se tocan.
+
+## 2. Cuerpo
+
+### Cobertura (obligatoria — RFC-007 §2.a)
+
+| Flujo | Estado | Origen |
+|---|---|---|
+| Hidratación de trace en entrypoint HTTP + emisión en logs | **documentado** | PR issue #9 |
+| Hidratación en entrypoint Sidekiq (server middleware) | **referenciado** (no diagramado) | — |
+| Hidratación en entrypoint BugBunny consumer | **referenciado** (no diagramado) | — |
+| Hidratación en entrypoint TaskMonitor (Rake/Cron) | **referenciado** (no diagramado) | — |
+| Propagación saliente (Faraday / ActiveResource / BugBunny publisher) | **NO documentado** | — |
+| Ciclo de vida RPC reply (BugBunny) | **NO documentado** | — |
+
+Ausencia de un flujo en este artefacto ≠ inexistencia del flujo. Acreta por PR.
+
+### Flujo: Hidratación de trace en entrypoint HTTP + emisión en logs
+
+Invariante de paridad: los 4 entrypoints (`HttpMiddleware`, `Sidekiq::ServerMiddleware`, `BugBunny::ConsumerTracingMiddleware`, `TaskMonitor`) garantizan un `root_id` aunque no llegue trace header entrante. Antes del fix de issue #9, `HttpMiddleware` era el único sin ese fallback: un servicio que es **punto de entrada** (no eslabón intermedio) emitía logs sin `root_id`, y por efecto cascada sin `source` (campo mandatorio del estándar Wispro).
+
+```mermaid
+sequenceDiagram
+    participant Cliente
+    participant HM as HttpMiddleware
+    participant T as ExisRay::Tracer
+    participant App as Rack app / Controller
+    participant JF as JsonFormatter
+
+    Cliente->>HM: request (con o sin trace_header)
+    HM->>T: hydrate(trace_id: env[trace_header], source: "http")
+    T->>T: created_at, source="http", trace_id=...
+    T->>T: parse_trace_id
+    alt trace_header presente (eslabón intermedio)
+        T->>T: root_id = data["Root"] (parseado del header)
+    else sin trace_header (servicio entrypoint)
+        T-->>HM: root_id queda nil
+        HM->>T: root_id ||= generate_new_root  %% fix issue #9 Gap A
+        T->>T: root_id = "Root=1-<ts>-<rand>" (fresco)
+    end
+    HM->>T: request_id = env["action_dispatch.request_id"]
+    HM->>HM: ExisRay.sync_correlation_id
+    HM->>App: @app.call(env)
+    App->>JF: Rails.logger.info "event=..."
+    JF->>T: request_id?  %% issue #9 Gap C: fuera del guard de root_id
+    JF->>JF: payload[:request_id] = T.request_id (si presente)
+    JF->>T: root_id?
+    alt root_id presente (siempre en entrypoint, post-fix)
+        JF->>JF: payload += root_id, trace_id, source, ...
+    end
+    JF-->>App: línea JSON con source + correlación
+    Note over HM,App: rescue StandardError ⇒ @app.call(env) igual<br/>(logging nunca rompe el flujo principal)
+```
+
+Contexto: `JsonFormatter#inject_tracer_context` corta todo su bloque con `return unless root_id` (Gap B — efecto cascada de Gap A). El fix de Gap A (root fresco en `HttpMiddleware`) des-gatea ese bloque y `source` vuelve a emitirse. `request_id` se emite **fuera** de ese guard (Gap C): tiene distinto ciclo de vida que `root_id` (UUID v4 de Rails vs formato X-Ray) y un servicio puede querer correlación por request aunque no haya trace context.
+
+## 3. Inferencias
+
+| Afirmación | confidence | a verificar por humano |
+|---|---|---|
+| Los 4 entrypoints comparten la invariante "siempre hay root_id" | `declared` | código de los 4 middlewares lo confirma (issue #9 lo tabula) |
+| `request_id` no se emitía en ninguna línea pre-fix | `declared` | confirmado: `JsonFormatter` solo lo usaba interno vía `clean_request_id` |
+| Orden de emisión (request_id antes del guard de root_id) | `declared` | `json_formatter.rb#inject_tracer_context` post-fix |
+
+## 4. Cobertura y fronteras
+
+- **Incremental:** solo el flujo de entrypoint HTTP está diagramado. Sidekiq/BugBunny/TaskMonitor referenciados por paridad pero no diagramados (acretan cuando se toquen).
+- **Fuera de alcance:** estructura de datos (gema sin DB → no aplica), interfaz Ruby pública / topología (capas F2 de `dev-structure`, no implementadas).
+- **Significado de términos** (`root_id`, `source`, etc.) → `docs/glossary/glossary.md`.

data/docs/glossary/glossary.md

@@ -0,0 +1,76 @@
+# Glosario — exis_ray
+
+> meta: artefacto · RFC-009 (DDD ubiquitous language / bounded context + ISO 11179) · generado dev-enrich · anclado a commit `00cf803` · cobertura **parcial — sembrado inicial, acreta por PR**
+
+## 1. Resumen
+
+Lenguaje ubicuo del bounded context **exis_ray** (observabilidad/trazabilidad del ecosistema Wispro). Significado de cada término **en esta gema**. Gema sin capa de datos (`docs/data` = n/a): el `Binding` apunta al símbolo público estable que *es* el concepto (ISO 11179, materialización no-tabular), no a tablas.
+
+## 2. Cuerpo
+
+## entrypoint
+
+Punto donde la ejecución entra al servicio y nace (o se continúa) un contexto de trazabilidad. Hay exactamente 4: HTTP, Sidekiq, BugBunny consumer, TaskMonitor. **Invariante:** todo entrypoint garantiza un `root_id` — si no llega trace header entrante, genera uno fresco. Un servicio que es entrypoint sin trace upstream (ej. collector/ingest) igual emite logs correlacionables y con `source`.
+
+**Binding:** `ExisRay::HttpMiddleware`, `ExisRay::Sidekiq::ServerMiddleware`, `ExisRay::BugBunny::ConsumerTracingMiddleware`, `ExisRay::TaskMonitor`.
+
+## root_id
+
+Identificador raíz de un trace distribuido (formato AWS X-Ray: `1-<ts_hex>-<rand_hex>`, prefijado `Root=`). **Constante a lo largo de toda la cadena** de servicios: nace en el primer entrypoint y se propaga sin cambiar. Es el campo de correlación primario de logs.
+
+**Binding:** `ExisRay::Tracer.root_id`.
+
+## trace_id
+
+Header de traza entrante completo, sin parsear: `Root=...;Self=...;CalledFrom=...;TotalTimeSoFar=...ms`. Presente solo cuando el servicio es **eslabón intermedio** (recibió header upstream). Un entrypoint sin trace upstream tiene `root_id` (fresco) pero no `trace_id`.
+
+**Binding:** `ExisRay::Tracer.trace_id`.
+
+## self_id
+
+Identificador del span del servicio actual dentro del trace. Se genera por servicio y viaja en el header saliente como `Self=`.
+
+**Binding:** `ExisRay::Tracer.self_id`.
+
+## source
+
+Entrypoint de ejecución que originó la línea de log. Valores válidos: `http`, `sidekiq`, `task`, `system`. **Campo mandatorio** del estándar Wispro de logging — toda línea debe tenerlo. Se emite dentro del bloque de tracer context, que está gateado por `root_id`; por eso la invariante "todo entrypoint garantiza root_id" es lo que hace que `source` nunca falte.
+
+**Binding:** `ExisRay::Tracer.source`.
+
+## request_id
+
+UUID v4 del request HTTP, provisto por `ActionDispatch::RequestId` (`env["action_dispatch.request_id"]`). **Distinto ciclo de vida que `root_id`**: identificador por-request de Rails, no formato X-Ray, no constante a lo largo de la cadena. Se emite en logs fuera del guard de `root_id` — un servicio puede querer correlación por request aunque no haya trace context activo.
+
+**Binding:** `ExisRay::Tracer.request_id`.
+
+## correlation_id
+
+ID de correlación de negocio compuesto `ServiceName;RootID`, sincronizado al `Current` configurado por la app host. Liga logs de negocio con el trace.
+
+**Binding:** `ExisRay::Tracer.correlation_id`, `ExisRay::Current#correlation_id`.
+
+## trace context
+
+Conjunto thread-safe de atributos de trazabilidad activos en la request/job actual (`root_id`, `trace_id`, `self_id`, `source`, `request_id`, `created_at`, ...). Vive en `ActiveSupport::CurrentAttributes`; se hidrata en el entrypoint y se resetea al finalizar. "Hay trace context activo" ≡ `root_id` presente.
+
+**Binding:** `ExisRay::Tracer` (subclase de `ActiveSupport::CurrentAttributes`).
+
+## propagation header
+
+Header saliente que lleva el trace al siguiente servicio (`X-Amzn-Trace-Id` por default): `Root=...;Self=...;CalledFrom=<service>;TotalTimeSoFar=<acc>ms`. Lo genera `Tracer.generate_trace_header`. Distinto del header **entrante** (formato Rack `HTTP_X_AMZN_TRACE_ID`).
+
+**Binding:** `ExisRay::Tracer.generate_trace_header`, `ExisRay.configuration.propagation_trace_header`.
+
+## 3. Inferencias
+
+| Término | confidence | a verificar |
+|---|---|---|
+| Significado de negocio de cada término | `inferred` (LLM ancló al código; significado lo confirma humano) | revisar que la prosa refleje el uso real en servicios consumidores |
+| `trace context activo ≡ root_id presente` | `declared` | `JsonFormatter#inject_tracer_context` lo implementa literal |
+
+## 4. Cobertura y fronteras
+
+- **Sembrado inicial** disparado por PR issue #9; cubre los términos del núcleo trace/log. Acreta por PR (ausencia ≠ inexistencia).
+- **Términos no cubiertos aún:** `Reporter`/Sentry context, `total_time_so_far`, `called_from`, `log_fields`, `sidekiq_job`, `task`.
+- **Frontera:** comportamiento/secuencias → `docs/behavior/behavior.md`. Estructura de datos → n/a (gema sin DB).

data/lib/exis_ray/current.rb

@@ -8,6 +8,30 @@ module ExisRay
   class Current < ActiveSupport::CurrentAttributes
     attribute :user_id, :isp_id, :correlation_id
 
+    # Hook overridable por la subclass de la app host. Retorna un Hash de campos
+    # extra a inyectar en cada log line, junto a `user_id`/`isp_id`/`correlation_id`.
+    #
+    # Pensado para cubrir tanto constantes de proceso (declaradas como `freeze`-d
+    # constants en la subclass) como valores dinámicos per-request (leídos de
+    # atributos de Current). El JsonFormatter invoca este método en cada log y
+    # mergea el resultado al payload — luego de los campos canónicos pero antes
+    # de las keys del propio mensaje del developer (que ganan por override).
+    #
+    # @example Constantes de proceso + valores per-request combinados
+    #   class Current < ExisRay::Current
+    #     TENANT_ID = ENV.fetch("TENANT_ID").freeze
+    #     attribute :region
+    #
+    #     def self.log_fields
+    #       { tenant_id: TENANT_ID, region: region }.compact
+    #     end
+    #   end
+    #
+    # @return [Hash] Pares clave/valor a inyectar. Default `{}`.
+    def self.log_fields
+      {}
+    end
+
     # Callback nativo de Rails: Se ejecuta automáticamente al llamar a Current.reset
     resets do
       @user_object = nil

data/lib/exis_ray/http_middleware.rb

@@ -13,6 +13,13 @@ module ExisRay
         trace_id: env[ExisRay.configuration.trace_header],
         source: "http"
       )
+      # Si la request no trae trace header entrante (servicio que es punto de
+      # entrada, no eslabón intermedio de un trace distribuido), generamos un
+      # root_id fresco igual que el resto de entrypoints
+      # (Sidekiq::ServerMiddleware, BugBunny::ConsumerTracingMiddleware,
+      # TaskMonitor). Sin esto root_id queda nil y JsonFormatter dropea todo
+      # el bloque de tracer, incluido `source` (campo mandatorio). Ver issue #9.
+      ExisRay::Tracer.root_id ||= ExisRay::Tracer.send(:generate_new_root)
       ExisRay::Tracer.request_id = env["action_dispatch.request_id"]
       ExisRay.sync_correlation_id
 

data/lib/exis_ray/json_formatter.rb

@@ -102,6 +102,12 @@ module ExisRay
     # @param payload [Hash] El diccionario del log donde se insertarán los datos.
     # @return [void]
     def inject_tracer_context(payload)
+      # `request_id` (UUID v4 de Rails) tiene distinto ciclo de vida que
+      # `root_id` (formato X-Ray). Se emite fuera del guard de `root_id`:
+      # un servicio puede querer correlación por request_id aunque no haya
+      # trace context activo. Ver issue #9 (Gap C).
+      payload[:request_id] = ExisRay::Tracer.request_id if ExisRay::Tracer.request_id
+
       return unless ExisRay::Tracer.root_id
 
       payload[:root_id]  = ExisRay::Tracer.root_id
@@ -122,9 +128,28 @@ module ExisRay
       payload[:user_id] = curr.user_id if curr.respond_to?(:user_id) && !curr.user_id.nil?
       payload[:isp_id]  = curr.isp_id  if curr.respond_to?(:isp_id)  && !curr.isp_id.nil?
 
-      return unless curr.respond_to?(:correlation_id) && curr.correlation_id
+      payload[:correlation_id] = curr.correlation_id if curr.respond_to?(:correlation_id) && curr.correlation_id
+
+      inject_log_fields(payload, curr)
+    end
+
+    # Mergea el resultado de `Current.log_fields` al payload, aplicando el mismo
+    # filtrado de claves sensibles que el resto del formatter. Si la subclass del
+    # host overrideó el hook y revienta, el error se traga: logging nunca debe
+    # afectar el flujo principal.
+    #
+    # @param payload [Hash]
+    # @param curr [Class] La clase Current configurada por la app host.
+    # @return [void]
+    def inject_log_fields(payload, curr)
+      return unless curr.respond_to?(:log_fields)
 
-      payload[:correlation_id] = curr.correlation_id
+      fields = curr.log_fields
+      return if fields.nil? || fields.empty?
+
+      payload.merge!(filter_sensitive_hash(fields))
+    rescue StandardError
+      nil
     end
 
     # Inyecta cualquier etiqueta nativa (tags) de Rails que esté presente en el hilo actual.

data/lib/exis_ray/railtie.rb

@@ -44,16 +44,12 @@ module ExisRay
       # y safe_constantize puede fallar aún con eager_load=true.
       if (name = ExisRay.configuration.current_class).present?
         klass = name.safe_constantize
-        if klass && !klass.<=(ExisRay::Current)
-          raise "ExisRay: current_class '#{name}' does not inherit from ExisRay::Current"
-        end
+        raise "ExisRay: current_class '#{name}' does not inherit from ExisRay::Current" if klass && !klass.<=(ExisRay::Current)
       end
 
       if (name = ExisRay.configuration.reporter_class).present?
         klass = name.safe_constantize
-        if klass && !klass.<=(ExisRay::Reporter)
-          raise "ExisRay: reporter_class '#{name}' does not inherit from ExisRay::Reporter"
-        end
+        raise "ExisRay: reporter_class '#{name}' does not inherit from ExisRay::Reporter" if klass && !klass.<=(ExisRay::Reporter)
       end
 
       # Aplicamos el formateador JSON globalmente al logger ya instanciado de Rails

data/lib/exis_ray/version.rb

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

data/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exis-ray
-description: Skill de conocimiento completo sobre ExisRay, la capa de observabilidad y trazabilidad distribuida del ecosistema Wispro. Consultame para integración, arquitectura, API, errores y antipatrones.
+description: Conocimiento completo de ExisRay, la capa de observabilidad y trazabilidad distribuida del ecosistema Wispro (logging JSON estructurado, trace context AWS X-Ray, propagación entre servicios). ACTIVAR cuando un servicio o gema Rails integra/configura ExisRay, emite o debuggea logs JSON estructurados, propaga trace context (header X-Amzn-Trace-Id) entre HTTP/Sidekiq/BugBunny, usa ExisRay::Tracer/Current/Reporter/JsonFormatter/TaskMonitor, edita el initializer de ExisRay, o resuelve errores/antipatrones de logging-trazabilidad Wispro.
 ---
 
 # ExisRay Expert
@@ -9,6 +9,14 @@ Observabilidad y trazabilidad distribuida para microservicios Rails (AWS X-Ray c
 
 Para el complemento del estándar de logging Wispro (regla Data First, mapeo OpenTelemetry, ciclo de vida de jobs/requests), ver `references/standard.md`.
 
+### Artefactos de detalle (RFC-008)
+
+Este SKILL.md **resume e indexa**; el contrato y el significado de detalle viven en `docs/<capa>/`. **Version-lock por construcción:** `gemspec.files` empaqueta `docs/**` en el mismo tag que este `SKILL.md`; los links son rutas relativas dentro del paquete del release (nunca rama/`HEAD`/URL flotante). Contrato resumido anclado a **v0.8.0 + fix issue #9** (commit `00cf803`):
+
+- [`docs/behavior/behavior.md`](../docs/behavior/behavior.md) — secuencias de hidratación de trace por entrypoint + emisión en logs (parcial, incremental).
+- [`docs/glossary/glossary.md`](../docs/glossary/glossary.md) — lenguaje ubicuo del bounded context (`root_id`, `trace_id`, `source`, `request_id`, `entrypoint`, ...).
+- Datos = n/a (gema sin DB). Operaciones/Interfaz/Topología = F2 `dev-structure`, no implementado: contrato Ruby permanece embebido abajo (coexistencia transitoria RFC-008 §2).
+
 ---
 
 ## Glosario
@@ -67,11 +75,11 @@ ExisRay unifica trazabilidad distribuida, logging estructurado JSON, contexto de
 
 ### Flujo runtime (HTTP request)
 
-1. `HttpMiddleware` lee `trace_header` del env Rack, llama `Tracer.hydrate(trace_id:, source: "http")`
+1. `HttpMiddleware` lee `trace_header` del env Rack, llama `Tracer.hydrate(trace_id:, source: "http")`. **Si no llega header** (servicio entrypoint, no eslabón intermedio) genera un `root_id` fresco — paridad con `Sidekiq::ServerMiddleware`/`BugBunny::ConsumerTracingMiddleware`/`TaskMonitor`. Captura `request_id` de `action_dispatch.request_id`. Secuencia detallada: `docs/behavior/behavior.md`.
 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`. 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.
+5. `JsonFormatter` intercepta cada `Rails.logger.*` e inyecta automaticamente: `time`, `level`, `severity_number`, `service`, `service_version`, `deployment_environment`, `request_id` (fuera del guard de `root_id` — distinto ciclo de vida), `root_id`, `trace_id`, `source`, `user_id`, `isp_id`, `correlation_id`. Como el entrypoint siempre garantiza `root_id`, `source` (mandatorio) nunca falta. 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
@@ -163,6 +171,27 @@ Current.correlation_id? # => true si correlation_id es present?
 
 Los setters auto-sincronizan con `ActiveResource::Base.headers` y `PaperTrail.request` cuando estan definidos.
 
+#### Hook `log_fields` — inyectar campos custom en cada log
+
+Class method overridable que retorna un Hash de campos extra para JsonFormatter. Cubre tanto **constantes de proceso** (frozen constants en la subclass) como **valores dinámicos per-request** (atributos de Current) en un solo lugar. Default `{}`.
+
+```ruby
+class Current < ExisRay::Current
+  TENANT_ID = ENV.fetch("TENANT_ID").freeze   # static, frozen al boot
+  attribute :region                             # dynamic, per-request
+
+  def self.log_fields
+    { tenant_id: TENANT_ID, region: region }.compact
+  end
+end
+```
+
+Reglas:
+
+- `JsonFormatter` filtra claves sensibles del hash retornado (mismo regex que el resto del formatter).
+- Si el override revienta, el formatter rescata silenciosamente (logging no afecta flujo principal).
+- Precedencia: campos canónicos del Tracer y keys del mensaje del developer pisan `log_fields` en colisión. Solo sirve para agregar fields nuevos, no para overrideear los canónicos.
+
 ### ExisRay::Reporter (clase base abstracta)
 
 ```ruby

data/spec/exis_ray/current_spec.rb

@@ -112,4 +112,38 @@ RSpec.describe ExisRay::Current do
       TestCurrent.correlation_id = "corr-1"
     end
   end
+
+  describe ".log_fields hook" do
+    it "retorna un Hash vacío por defecto" do
+      expect(TestCurrent.log_fields).to eq({})
+    end
+
+    it "permite que la subclass overridee el método para inyectar campos custom" do
+      stub_const("TenantCurrent", Class.new(ExisRay::Current) do
+        def self.log_fields
+          { tenant_id: "42", region: "us-east-1" }
+        end
+      end)
+
+      expect(TenantCurrent.log_fields).to eq(tenant_id: "42", region: "us-east-1")
+    end
+
+    it "soporta combinar constantes de proceso con atributos per-request" do
+      stub_const("MixedCurrent", Class.new(ExisRay::Current) do
+        attribute :region
+
+        STATIC_TENANT = "tenant-42"
+
+        def self.log_fields
+          { tenant_id: STATIC_TENANT, region: region }.compact
+        end
+      end)
+      MixedCurrent.region = "us-east-1"
+
+      expect(MixedCurrent.log_fields).to eq(tenant_id: "tenant-42", region: "us-east-1")
+
+      MixedCurrent.reset
+      expect(MixedCurrent.log_fields).to eq(tenant_id: "tenant-42")
+    end
+  end
 end

data/spec/exis_ray/http_middleware_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe ExisRay::HttpMiddleware do
+  subject(:middleware) { described_class.new(app) }
+
+  let(:app) { ->(_env) { [200, {}, ["ok"]] } }
+  let(:trace_header) { ExisRay.configuration.trace_header }
+
+  after { ExisRay::Tracer.reset }
+
+  describe "#call" do
+    context "cuando la request NO trae trace header entrante (entrypoint, issue #9 Gap A)" do
+      let(:env) { { "action_dispatch.request_id" => "req-uuid-123" } }
+
+      it "genera un root_id fresco igual que los demás entrypoints" do
+        middleware.call(env)
+
+        expect(ExisRay::Tracer.root_id).to match(/\ARoot=1-/)
+      end
+
+      it "setea source=http (des-gatea el bloque de tracer en JsonFormatter, Gap B)" do
+        middleware.call(env)
+
+        expect(ExisRay::Tracer.source).to eq("http")
+      end
+
+      it "setea request_id desde el env de Rails" do
+        middleware.call(env)
+
+        expect(ExisRay::Tracer.request_id).to eq("req-uuid-123")
+      end
+    end
+
+    context "cuando la request trae trace header entrante (eslabón intermedio)" do
+      let(:env) do
+        {
+          trace_header => "Root=1-5759b146-abc123;Self=1-5759b146-def456;CalledFrom=upstream",
+          "action_dispatch.request_id" => "req-uuid-456"
+        }
+      end
+
+      it "respeta el root_id entrante y no genera uno nuevo" do
+        middleware.call(env)
+
+        expect(ExisRay::Tracer.root_id).to eq("1-5759b146-abc123")
+      end
+
+      it "setea source=http y request_id" do
+        middleware.call(env)
+
+        expect(ExisRay::Tracer.source).to eq("http")
+        expect(ExisRay::Tracer.request_id).to eq("req-uuid-456")
+      end
+    end
+
+    it "invoca la app y retorna su respuesta" do
+      expect(middleware.call({})).to eq([200, {}, ["ok"]])
+    end
+
+    it "no rompe el flujo principal si la hidratación falla" do
+      allow(ExisRay::Tracer).to receive(:hydrate).and_raise(StandardError)
+
+      expect(middleware.call({})).to eq([200, {}, ["ok"]])
+    end
+  end
+end

data/spec/exis_ray/json_formatter_spec.rb

@@ -15,6 +15,7 @@ RSpec.describe ExisRay::JsonFormatter do
       def self.service_name = "test-service"
       def self.root_id      = nil
       def self.trace_id     = nil
+      def self.request_id   = nil
     end)
 
     allow(ExisRay).to receive(:current_class).and_return(nil)
@@ -261,6 +262,91 @@ RSpec.describe ExisRay::JsonFormatter do
         expect(result).not_to have_key("user_id")
       end
     end
+
+    describe "inyeccion de Current.log_fields" do
+      # Mock estilo ActiveSupport::CurrentAttributes que combina los atributos canónicos
+      # con un hook log_fields. Por defecto retorna {}, los tests lo redefinen vía stub.
+      let(:current_class_double) do
+        Class.new do
+          class << self
+            attr_accessor :user_id, :isp_id, :correlation_id, :_log_fields
+
+            def respond_to_missing?(method, *)
+              %i[user_id isp_id correlation_id log_fields].include?(method) || super
+            end
+          end
+
+          def self.log_fields
+            _log_fields || {}
+          end
+        end
+      end
+
+      before do
+        allow(ExisRay).to receive(:current_class).and_return(current_class_double)
+      end
+
+      it "inyecta los campos retornados por log_fields en el payload" do
+        current_class_double._log_fields = { tenant_id: "42", region: "us-east-1" }
+
+        result = call("event=boot")
+
+        # tenant_id="42" se castea a Integer por filter_sensitive_hash (igual que cualquier otro KV)
+        expect(result).to include("tenant_id" => 42, "region" => "us-east-1", "event" => "boot")
+      end
+
+      it "no agrega keys cuando log_fields retorna hash vacío" do
+        current_class_double._log_fields = {}
+
+        result = call("event=boot")
+
+        expect(result).not_to have_key("tenant_id")
+      end
+
+      it "no agrega keys cuando log_fields retorna nil" do
+        current_class_double._log_fields = nil
+
+        result = call("event=boot")
+
+        expect(result.keys).to contain_exactly("time", "level", "severity_number", "service", "event")
+      end
+
+      it "el mensaje del developer pisa log_fields (override por call site)" do
+        current_class_double._log_fields = { tenant_id: "from-current" }
+
+        result = call("event=override tenant_id=from-message")
+
+        expect(result["tenant_id"]).to eq("from-message")
+      end
+
+      it "filtra claves sensibles" do
+        current_class_double._log_fields = { api_key: "leaked", tenant_id: "42" }
+
+        result = call("event=boot")
+
+        expect(result["api_key"]).to eq("[FILTERED]")
+        expect(result["tenant_id"]).to eq(42)
+      end
+
+      it "no rompe el formatter si la subclass overrideó log_fields con un método que revienta" do
+        allow(current_class_double).to receive(:log_fields).and_raise(StandardError, "boom")
+
+        expect { call("event=boot") }.not_to raise_error
+        result = call("event=boot")
+        expect(result["event"]).to eq("boot")
+      end
+
+      it "no falla si Current configurado no implementa log_fields (backwards compat)" do
+        legacy_current = Class.new do
+          class << self
+            attr_accessor :user_id, :isp_id, :correlation_id
+          end
+        end
+        allow(ExisRay).to receive(:current_class).and_return(legacy_current)
+
+        expect { call("event=boot") }.not_to raise_error
+      end
+    end
   end
 
   describe "#kv_string? (privado)" do
@@ -321,6 +407,62 @@ RSpec.describe ExisRay::JsonFormatter do
     end
   end
 
+  describe "inyección de contexto de tracer (issue #9)" do
+    def stub_tracer(root_id:, request_id:, source:, trace_id: nil)
+      stub_const("ExisRay::Tracer", Module.new do
+        define_singleton_method(:service_name) { "test-service" }
+        define_singleton_method(:root_id) { root_id }
+        define_singleton_method(:trace_id) { trace_id }
+        define_singleton_method(:request_id) { request_id }
+        define_singleton_method(:source) { source }
+        define_singleton_method(:sidekiq_job) { nil }
+        define_singleton_method(:task) { nil }
+      end)
+    end
+
+    context "cuando hay trace context activo (root_id presente)" do
+      before { stub_tracer(root_id: "1-abc-def", request_id: "uuid-1", source: "http", trace_id: "Root=1-abc-def") }
+
+      it "emite root_id, trace_id, source y request_id" do
+        result = call("event=acct.received")
+
+        expect(result).to include(
+          "root_id" => "1-abc-def",
+          "trace_id" => "Root=1-abc-def",
+          "source" => "http",
+          "request_id" => "uuid-1"
+        )
+      end
+    end
+
+    context "cuando NO hay trace context (root_id nil) pero sí request_id (Gap C)" do
+      before { stub_tracer(root_id: nil, request_id: "uuid-2", source: "http") }
+
+      it "emite request_id aunque root_id esté ausente" do
+        result = call("event=acct.received")
+
+        expect(result["request_id"]).to eq("uuid-2")
+      end
+
+      it "no emite root_id ni trace_id" do
+        result = call("event=acct.received")
+
+        expect(result).not_to have_key("root_id")
+        expect(result).not_to have_key("trace_id")
+      end
+    end
+
+    context "cuando no hay request_id" do
+      before { stub_tracer(root_id: "1-x-y", request_id: nil, source: "http") }
+
+      it "no incluye la clave request_id" do
+        result = call("event=acct.received")
+
+        expect(result).not_to have_key("request_id")
+      end
+    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" })

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -51,6 +51,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/behavior/behavior.md
+- docs/glossary/glossary.md
 - lib/exis_ray.rb
 - lib/exis_ray/active_resource_instrumentation.rb
 - lib/exis_ray/bug_bunny/consumer_tracing_middleware.rb
@@ -75,6 +77,7 @@ files:
 - skills.yml
 - spec/exis_ray/configuration_spec.rb
 - spec/exis_ray/current_spec.rb
+- spec/exis_ray/http_middleware_spec.rb
 - spec/exis_ray/json_formatter_spec.rb
 - spec/exis_ray/log_subscriber_spec.rb
 - spec/exis_ray/reporter_spec.rb
@@ -87,8 +90,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.2/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.7.2/skill
+  changelog_uri: https://github.com/gedera/exis_ray/blob/v0.9.0/CHANGELOG.md
+  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.9.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: