exis_ray 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c87f049dd7216e8ac33a9844b77cd1c863f9248130b329994002aa654c0c47ca
-  data.tar.gz: 1752d432a8437178121b36a0b28293f52f96b99d13a5c40589f312fb8f9b6236
+  metadata.gz: e474f1122d88cba11551996f1fe73b01da92f28dcea658e6eb473e51277e838e
+  data.tar.gz: 708af8ed6b2ece0cf5e78f74543135ceb4e83d8e2e51788e980847c7675d586e
 SHA512:
-  metadata.gz: 72f092befb65f8eb03fe851a302ec49ac47fb155a288ed1103923766f0322da6e5704e760d8c6fa7e4865d78666ddc29b7f7c5e486f22120de1c0ff4a072777e
-  data.tar.gz: 57e552a85bc42d9cb659d49a429c85131175350542856378d432063b9558f264a636c93d4a25ee57b51717718c5bcb03a2f86fbff3676ce85fedfde4562f5509
+  metadata.gz: 2e314e520ab390a510953c78c8774c816e30a9fd814e9bbd36eb2e874e5ed81abbaeb91a7f0abea350c46f4783f8f93c176209a08a15a4691de2c13551534135
+  data.tar.gz: 478cfe36c1b7f5e60c37de8c6db1e86c239a13a2ec2c8a3bd6797b455cc27dd0ed7f3960c02e29049e0979c648a7ab7857982d84664ae43647dfb2af5cb99f16

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.11.0] - 2026-05-26
+
+### Nuevas funcionalidades
+- **`config.emit_legacy_exception_keys`** (#15): nuevo flag de `Configuration` (default `true`) que controla la emisión de las keys legacy `error_class`/`error_message` junto a `exception.type`/`exception.message`. Bajado a `false`, `ExisRay::LogSubscriber` (logs HTTP) y `ExisRay::TaskMonitor` (logs de tasks) emiten solo las keys OTel v1.0 (`exception.*`), reduciendo bytes y ruido downstream cuando los consumers (dashboards, alertas, queries) ya migraron. Mantiene `true` como default durante la ventana de transición — se flipea a `false` en v0.12.0 y se remueve el flag en v1.0 cuando los legacy se eliminen definitivamente.
+- **`url.path` (OTel v1.0) + `config.emit_legacy_path_key`** (#15): `ExisRay::LogSubscriber` empieza a emitir `url.path` (nombre canónico OTel) en todos los logs HTTP. El alias legacy `path` se sigue emitiendo durante la ventana de transición y queda gateado por `config.emit_legacy_path_key` (default `true`). Cuando los consumers (queries, dashboards, alertas) hayan migrado a `url.path`, bajar el flag a `false` para suprimir el alias. Se flipea a `false` en v0.12.0 y se remueve el flag en v1.0.
+- **Doc: `url.path` vs `http_route` no se deduplican** (#15): el caso reportado de "valores idénticos en endpoints estáticos" no es un bug — `url.path` es la URL **concreta** (alta cardinalidad), `http_route` es el **template** (baja cardinalidad). Cumplen roles distintos en dashboards/queries downstream; siguen emitiéndose siempre los dos. Documentado en `README.md` y `skill/SKILL.md` (subsección "Migración OTel — `path` → `url.path`" + nota explicativa de la coexistencia semántica).
+
+## [0.10.0] - 2026-05-25
+
+### Documentación
+- **`SKILL.md`/`README` describían la auto-inyección como incondicional** (#11): la prosa de "Flujo runtime" en `SKILL.md` y "Flujo de propagación" en `README.md` listaba los campos auto-inyectados (`root_id`, `trace_id`, `source`, `request_id`, ...) sin desglosar los guards. `JsonFormatter#inject_tracer_context` corta su bloque con `return unless Tracer.root_id`, y `request_id` se emite **fuera** de ese guard (distinto ciclo de vida — fix de #9). Sin esa precisión, un implementador en `box_radius_manager` concluyó (apoyándose en la doc) que "`root_id` ya cubre la trazabilidad, `request_id` es redundante" y removió un workaround necesario; en su entrypoint sin trace header `root_id` era nil → logs sin `request_id`/`source`/`root_id`. Agregada subsección "Condiciones de emisión por campo" en `SKILL.md` con tabla "campo → condición → entrypoint que la garantiza", callout en el README arriba de "Campos auto-inyectados", y enlace cruzado a `docs/behavior/behavior.md` + `docs/glossary/glossary.md` (que ya tenían el detalle).
+
+### Correcciones
+- **Clave `task` duplicada en JSON cuando `TaskMonitor.run` loguea lifecycle** (#12): `TaskMonitor` emitía `task=#{task_name}` en los KV strings de `task_started`/`task_finished` (3 sites: `task_monitor.rb:32,41,48`); `JsonFormatter#inject_tracer_context` ya inyecta la misma clave desde `Tracer.task` con Symbol — al colapsar Symbol/String en `JSON.generate`, `json` emitía `warning: detected duplicate key "task"` y la línea entera va a romper en `json` 3.0. **Fix B** (origen): los KV de lifecycle ya no emiten `task=...`; la clave viene exclusivamente del formatter vía `Tracer.task`. **Fix A** (defensa en profundidad): `JsonFormatter` normaliza todas las claves del payload a String antes de `JSON.generate`, deduplicando con precedencia "última inserción gana" (developer payload pisa contexto canónico inyectado por Tracer, igual que `log_fields`). Cubre futuros casos análogos Tracer ↔ developer KV sobre la misma clave.
+
 ## [0.9.0] - 2026-05-19
 
 ### Correcciones

data/CLAUDE.md

@@ -178,6 +178,7 @@ ExisRay.configure do |config|
   config.propagation_trace_header = 'X-Amzn-Trace-Id'
   config.current_class           = 'Current'
   config.reporter_class          = 'Reporter'
+  config.emit_legacy_exception_keys = true            # default true; pasar a false cuando consumers usen exception.*
 end
 
 # BugBunny publisher — debe agregarse manualmente al cliente

data/README.md

@@ -52,7 +52,7 @@ 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. **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.
+2. `JsonFormatter` inyecta `root_id`, `trace_id`, `source`, `request_id` y el contexto de negocio (`user_id`, `isp_id`, `correlation_id`) en cada línea de log. **Cada campo tiene un guard:** `root_id`/`trace_id`/`source`/`task`/`sidekiq_job` salen solo si `Tracer.root_id` está presente; `request_id` se emite fuera de ese guard (distinto ciclo de vida). Como todo entrypoint asegura `root_id` (genera uno fresco si no llega header), `source` (mandatorio) nunca falta. Detalle por campo: tabla [Campos auto-inyectados](#campos-auto-inyectados) más abajo.
 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.
 
@@ -339,7 +339,9 @@ config.logger.formatter = ExisRay::JsonFormatter
 
 ### Campos auto-inyectados
 
-`JsonFormatter` inyecta estos campos automáticamente en cada línea. **Nunca** los incluyas manualmente en tus logs:
+`JsonFormatter` inyecta estos campos automáticamente en cada línea. **Nunca** los incluyas manualmente en tus logs.
+
+> **No es incondicional.** `root_id`/`trace_id`/`source`/`task`/`sidekiq_job` están gateados por `inject_tracer_context`'s `return unless Tracer.root_id`. Los 4 entrypoints (HTTP, Sidekiq server, BugBunny consumer, TaskMonitor) garantizan el `root_id` (fresco si no llega header), por eso `source` (mandatorio) nunca falta — pero si el código loguea fuera de un entrypoint (boot, código inicializador, hilos sueltos), esos campos pueden faltar. `request_id` se emite fuera de ese guard y tiene distinto ciclo de vida.
 
 | Campo | Condición |
 |:------|:----------|
@@ -368,8 +370,9 @@ config.logger.formatter = ExisRay::JsonFormatter
 | `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 |
+| `url.path` | String | URL concreta del request (OTel v1.0). Siempre presente |
+| `path` | String | Alias legacy de `url.path`. Solo si `config.emit_legacy_path_key` (default `true`, deprecado) |
+| `http_route` | String | Template (ej: `/users/:id`). Baja cardinalidad para dashboards. En endpoints sin params coincide en valor con `url.path` — la dupe es semánticamente esperada (concrete vs template) |
 | `format` | Symbol/String | `html`, `json`, etc. |
 | `controller` | String | Class name del controller |
 | `action` | String | Nombre del action |
@@ -380,11 +383,37 @@ config.logger.formatter = ExisRay::JsonFormatter
 | `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) |
+| `error_class`, `error_message` | String | Solo en fallo y si `config.emit_legacy_exception_keys` (default `true`, deprecadas) |
 | `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`.
 
+### Migración OTel — `error_class`/`error_message` → `exception.*`
+
+Durante la ventana de transición OTel v1.0, `LogSubscriber` y `TaskMonitor` emiten ambos sets de keys en cada log de error. Cuando todos los consumers (dashboards, queries, alertas) hayan migrado a `exception.type`/`exception.message`/`exception.stacktrace`, desactivar los legacy:
+
+```ruby
+ExisRay.configure do |c|
+  c.emit_legacy_exception_keys = false # default: true
+end
+```
+
+Roadmap: default `false` en v0.12.0; flag y legacy keys removidos en v1.0.
+
+### Migración OTel — `path` → `url.path`
+
+`LogSubscriber` emite `url.path` (nombre OTel v1.0) en todos los logs HTTP. Durante la ventana de transición emite también `path` (alias legacy Wispro). Cuando las queries/dashboards/alertas migren a `url.path`, desactivar el legacy:
+
+```ruby
+ExisRay.configure do |c|
+  c.emit_legacy_path_key = false # default: true
+end
+```
+
+Roadmap: default `false` en v0.12.0; flag y key `path` removidos en v1.0.
+
+> **Sobre `url.path` vs `http_route`:** son semánticamente distintos — `url.path` es la URL **concreta** (alta cardinalidad, ej. `/users/42`), `http_route` es el **template** matcheado (baja cardinalidad, ej. `/users/:id`). En endpoints sin params coinciden en valor (ej. `/up`), pero ambos se siguen emitiendo porque cumplen roles distintos en dashboards/queries downstream. La dupe en valor es esperada, no es un bug.
+
 ### Filtrado de claves sensibles
 
 Las claves que matcheen `/password|pass|passwd|secret|token|api_key|auth/i` se reemplazan automáticamente por `[FILTERED]`, tanto en strings KV como en Hashes (incluyendo anidados).

data/lib/exis_ray/configuration.rb

@@ -52,6 +52,25 @@ module ExisRay
     #   @example 'production'
     attr_accessor :deployment_environment
 
+    # @!attribute [rw] emit_legacy_exception_keys
+    #   @return [Boolean] Si true, emite `error_class`/`error_message` junto a `exception.type`/`exception.message`.
+    #   Default `true` durante la ventana de transición OTel v1.0. Setear a `false` cuando todos los
+    #   consumers (dashboards, alertas, queries) hayan migrado a `exception.*` para reducir bytes
+    #   y ruido en logs.
+    #   Aplica a `ExisRay::LogSubscriber` (logs HTTP) y `ExisRay::TaskMonitor` (logs de tasks).
+    #   @example false
+    attr_accessor :emit_legacy_exception_keys
+
+    # @!attribute [rw] emit_legacy_path_key
+    #   @return [Boolean] Si true, `ExisRay::LogSubscriber` emite `path` (nombre legacy Wispro)
+    #   junto a `url.path` (OTel v1.0). Default `true` durante la ventana de transición.
+    #   Setear a `false` cuando los consumers (queries, dashboards, alertas) hayan migrado a
+    #   `url.path` para reducir bytes y ruido en logs.
+    #   Nota: `url.path` y `http_route` son semánticamente distintos (URL concreta vs template);
+    #   coinciden como string solo en endpoints sin params — la dupe es esperada y no se elimina.
+    #   @example false
+    attr_accessor :emit_legacy_path_key
+
     # Inicializa la configuración con valores por defecto compatibles con AWS X-Ray.
     def initialize
       @trace_header = "HTTP_X_AMZN_TRACE_ID"
@@ -62,6 +81,8 @@ module ExisRay
       @log_subscriber_class = nil
       @service_version = default_service_version
       @deployment_environment = default_deployment_environment
+      @emit_legacy_exception_keys = true
+      @emit_legacy_path_key = true
     end
 
     # Lee la versión del servicio desde la configuración de Rails.

data/lib/exis_ray/json_formatter.rb

@@ -61,13 +61,29 @@ module ExisRay
       inject_current_tags(payload)
       process_message(payload, msg)
 
-      "#{JSON.generate(payload.compact, { ascii_only: false })}\n"
+      "#{JSON.generate(normalize_keys(payload), { ascii_only: false })}\n"
     rescue StandardError
       fallback_message(severity, timestamp, msg)
     end
 
     private
 
+    # Normaliza todas las claves del payload a strings y deduplica con precedencia
+    # "última inserción gana" (developer payload pisa contexto canónico inyectado
+    # antes, igual que `log_fields`). Previene el warning `duplicate key` que `json`
+    # emite cuando coexisten `:task` (Symbol, vía Tracer) y `"task"` (String, vía
+    # KV string developer) — `json` 3.0 lo va a transformar en error.
+    #
+    # @param payload [Hash]
+    # @return [Hash{String => Object}]
+    def normalize_keys(payload)
+      payload.each_with_object({}) do |(key, value), result|
+        next if value.nil?
+
+        result[key.to_s] = value
+      end
+    end
+
     # @return [String, nil]
     def service_version
       ExisRay.configuration.service_version

data/lib/exis_ray/log_subscriber.rb

@@ -98,7 +98,7 @@ module ExisRay
         component: "exis_ray",
         event: "http_request",
         method: payload[:method],
-        path: payload[:path],
+        "url.path": payload[:path],
         http_route: extract_http_route(payload),
         format: payload[:format],
         controller: payload[:controller],
@@ -112,6 +112,8 @@ module ExisRay
         server_address: extract_server_address(headers["HTTP_HOST"])
       }
 
+      data[:path] = payload[:path] if ExisRay.configuration.emit_legacy_path_key
+
       data.merge!(exception_data)
       data.merge!(self.class.extra_fields(event))
       data.compact
@@ -129,15 +131,16 @@ module ExisRay
     end
 
     # Extrae los datos de excepción para logs OTel.
-    # Emite tanto los campos legacy (`error_class`/`error_message`) como los OTel
-    # (`exception.type`/`exception.message`/`exception.stacktrace`) durante la ventana
-    # de transición definida en el plan "Breaking changes OTel v1.0".
+    # Siempre emite `exception.type`/`exception.message`/`exception.stacktrace` (OTel v1.0).
+    # Emite además los campos legacy (`error_class`/`error_message`) cuando
+    # `ExisRay.configuration.emit_legacy_exception_keys` es `true` (default durante la
+    # ventana de transición). Setear a `false` cuando los consumers hayan migrado.
     #
     # El stacktrace se toma de `payload[:exception_object]` (expuesto por Rails), no
     # de `payload[:exception]` que es solo `[class_name, message]`.
     #
     # @param payload [Hash] Payload completo del notification de Rails.
-    # @return [Hash] Campos exception.* y error_class/error_message con keys symbol.
+    # @return [Hash] Campos exception.* (y error_class/error_message si el flag está activo).
     def extract_exception_data(payload)
       exception_info = payload[:exception]
       return {} unless exception_info
@@ -146,12 +149,15 @@ module ExisRay
       exception_message = exception_info.last
 
       data = {
-        error_class: exception_class,
-        error_message: exception_message,
         "exception.type": exception_class,
         "exception.message": exception_message
       }
 
+      if ExisRay.configuration.emit_legacy_exception_keys
+        data[:error_class] = exception_class
+        data[:error_message] = exception_message
+      end
+
       exception_object = payload[:exception_object]
       if exception_object.respond_to?(:backtrace) && exception_object.backtrace
         data[:"exception.stacktrace"] = exception_object.backtrace.take(20).join("\n")

data/lib/exis_ray/task_monitor.rb

@@ -29,7 +29,7 @@ module ExisRay
         curr.correlation_id = ExisRay::Tracer.correlation_id
       end
 
-      log_event(:info, "component=exis_ray event=task_started task=#{task_name} outcome=started")
+      log_event(:info, "component=exis_ray event=task_started outcome=started")
 
       # Bloque de ejecución con o sin tags dependiendo de la configuración
       execute_with_optional_tags(&block)
@@ -38,18 +38,16 @@ module ExisRay
       human_time = ExisRay::Tracer.format_duration(duration_s)
 
       log_event(:info,
-                "component=exis_ray event=task_finished task=#{task_name} " \
+                "component=exis_ray event=task_finished " \
                 "outcome=success duration_s=#{duration_s} duration_human=\"#{human_time}\"")
     rescue StandardError => e
       duration_s = ExisRay::Tracer.current_duration_s
       human_time = ExisRay::Tracer.format_duration(duration_s)
 
       log_event(:error,
-                "component=exis_ray event=task_finished task=#{task_name} " \
+                "component=exis_ray event=task_finished " \
                 "outcome=failed duration_s=#{duration_s} duration_human=\"#{human_time}\" " \
-                "error_class=#{e.class} error_message=#{e.message.inspect} " \
-                "exception.type=#{e.class} exception.message=#{e.message.inspect} " \
-                "exception.stacktrace=#{format_stacktrace(e.backtrace)}")
+                "#{format_exception_fields(e)}")
       raise e
     ensure
       # Limpieza centralizada obligatoria para evitar filtraciones de memoria o contexto
@@ -124,7 +122,26 @@ module ExisRay
       '""'
     end
 
+    # Construye los campos KV de excepción para el log de `task_finished` failed.
+    # Siempre incluye `exception.type` / `exception.message` / `exception.stacktrace` (OTel v1.0).
+    # Incluye además `error_class` / `error_message` cuando
+    # `ExisRay.configuration.emit_legacy_exception_keys` es `true` (default durante la ventana
+    # de transición).
+    #
+    # @param error [Exception]
+    # @return [String]
+    def self.format_exception_fields(error)
+      message_quoted = error.message.inspect
+      stack = format_stacktrace(error.backtrace)
+
+      parts = []
+      parts << "error_class=#{error.class} error_message=#{message_quoted}" if ExisRay.configuration.emit_legacy_exception_keys
+      parts << "exception.type=#{error.class} exception.message=#{message_quoted} " \
+               "exception.stacktrace=#{stack}"
+      parts.join(" ")
+    end
+
     private_class_method :pod_identifier, :setup_tracer, :execute_with_optional_tags,
-                         :log_event, :format_stacktrace
+                         :log_event, :format_stacktrace, :format_exception_fields
   end
 end

data/lib/exis_ray/version.rb

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

data/skill/SKILL.md

@@ -11,7 +11,7 @@ Para el complemento del estándar de logging Wispro (regla Data First, mapeo Ope
 
 ### 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`):
+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.10.0** (post fix issues #9, #11, #12):
 
 - [`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`, ...).
@@ -79,8 +79,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`, `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.*`).
+5. `JsonFormatter` intercepta cada `Rails.logger.*` e inyecta el contexto de ejecucion en cada linea. **No es incondicional:** cada campo tiene un guard especifico (ver tabla "Condiciones de emision" mas abajo). En particular `inject_tracer_context` corta el bloque `root_id`/`trace_id`/`source`/`task`/`sidekiq_job` con `return unless Tracer.root_id` — la invariante "todo entrypoint garantiza `root_id`" es lo que hace que `source` (mandatorio) nunca falte. `request_id` se emite **fuera** de ese guard (distinto ciclo de vida que `root_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`, `url.path` siempre + `path` si `config.emit_legacy_path_key`, `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 `exception.type`/`exception.message`/`exception.stacktrace` siempre + `error_class`/`error_message` si `config.emit_legacy_exception_keys`).
 7. En llamadas salientes, `FaradayMiddleware`/`ActiveResourceInstrumentation` inyectan `propagation_trace_header` con `Tracer.generate_trace_header`
 8. Al finalizar, `ActiveSupport::CurrentAttributes` hace reset automatico
 
@@ -100,6 +100,8 @@ ExisRay.configure do |config|
   config.log_subscriber_class    = "MyLogSubscriber"        # String|nil, default nil
   config.service_version         = "1.2.3"                  # String|nil, default: Rails config.version o config.x.version
   config.deployment_environment  = "production"             # String|nil, default: Rails.env
+  config.emit_legacy_exception_keys = true                  # Boolean, default true (ventana transicion OTel v1.0)
+  config.emit_legacy_path_key       = true                  # Boolean, default true (ventana transicion `path` -> `url.path` OTel v1.0)
 end
 
 ExisRay.configuration.json_logs?  # => true si log_format == :json
@@ -233,8 +235,9 @@ ExisRay::TaskMonitor.run("billing:generate_invoices") do
   InvoiceService.process_all
 end
 # Genera root_id propio, loguea task_started/task_finished con outcome y duration_s.
-# En caso de error emite: error_class, error_message (legacy) + exception.type,
-# exception.message, exception.stacktrace (OTel, limitado a 20 lineas).
+# En caso de error emite: exception.type, exception.message, exception.stacktrace
+# (OTel, limitado a 20 lineas) + error_class/error_message si
+# config.emit_legacy_exception_keys es true (default durante ventana de transicion).
 # Re-lanza excepciones despues de loguearlas.
 # Hace reset de Tracer, Current y Reporter en ensure.
 ```
@@ -250,8 +253,9 @@ Reemplaza Lograge. Se suscribe a `process_action.action_controller` y emite un H
 | `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 |
+| `url.path` | String | URL concreta del request (OTel v1.0). Siempre presente |
+| `path` | String | Alias legacy de `url.path`. Solo si `config.emit_legacy_path_key` (default `true`, deprecado) |
+| `http_route` | String | Template (ej: `/users/:id`). Baja cardinalidad para dashboards. En endpoints sin params coincide en valor con `url.path` — dupe semanticamente esperada (concrete vs template) |
 | `format` | Symbol/String | `html`, `json`, etc. |
 | `controller` | String | Class name del controller |
 | `action` | String | Nombre del action |
@@ -262,7 +266,7 @@ Reemplaza Lograge. Se suscribe a `process_action.action_controller` y emite un H
 | `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) |
+| `error_class`, `error_message` | String | Solo en fallo y si `config.emit_legacy_exception_keys` (default `true`, deprecadas) |
 | `exception.type`, `exception.message`, `exception.stacktrace` | String | Solo en fallo (OTel; stack limitado a 20 lineas) |
 
 Para inyectar campos extra, sobreescribir `extra_fields`:
@@ -295,6 +299,26 @@ Casteo automatico: integers, floats, objetos JSON (`{...}`, `[...]`). Filtra cla
 
 Por eso `component` y `event` jamas se auto-inyectan, aunque el estandar Wispro los exija.
 
+#### Condiciones de emision por campo
+
+La auto-inyeccion **no es incondicional**: cada campo tiene un guard. `inject_tracer_context` corta su bloque con `return unless Tracer.root_id`, asi que `root_id`/`trace_id`/`source`/`task`/`sidekiq_job` solo se emiten cuando hay trace context activo. Los 4 entrypoints (HTTP, Sidekiq server, BugBunny consumer, TaskMonitor) garantizan ese `root_id` (fresco si no llega header), por eso `source` (mandatorio) nunca falta en una linea originada por un entrypoint. `request_id` se emite **fuera** del guard de `root_id` — distinto ciclo de vida.
+
+| Campo | Condicion de emision | Entrypoint que la garantiza |
+|:------|:---------------------|:----------------------------|
+| `time`, `level`, `severity_number`, `service`, `service_version`, `deployment_environment` | Siempre (no depende de Tracer/Current) | — |
+| `request_id` | `Tracer.request_id` presente. **Fuera del guard de `root_id`** (issue #9 Gap C): distinto ciclo de vida (UUID v4 de Rails vs formato X-Ray). | HTTP (via `ActionDispatch::RequestId`). Otros entrypoints solo si la app lo setea explicitamente. |
+| `root_id` | `Tracer.root_id` presente. **Gatea todo el bloque de tracer context.** | Los 4 entrypoints garantizan `root_id` fresco si no llega trace header (issue #9 Gap A). |
+| `source` | `Tracer.source` presente **y** `root_id` presente (esta dentro del bloque gateado). | Idem `root_id`. Como `source` es mandatorio del estandar Wispro, la invariante "todo entrypoint garantiza `root_id`" es lo que evita que falte. |
+| `trace_id` | `Tracer.trace_id` presente **y** `root_id` presente. Solo cuando el servicio es **eslabon intermedio** (recibio trace header upstream). | — (entrypoint que no recibe header tiene `root_id` fresco pero `trace_id` nil). |
+| `sidekiq_job` | `Tracer.sidekiq_job` presente **y** `root_id` presente. | Sidekiq `ServerMiddleware`. |
+| `task` | `Tracer.task` presente **y** `root_id` presente. | `TaskMonitor.run`. |
+| `correlation_id` | `Current.correlation_id` presente. | `ExisRay.sync_correlation_id` (HTTP middleware lo llama; otros entrypoints solo si la app lo invoca). |
+| `user_id`, `isp_id` | `Current.<attr>` no nil. | Lo setea la app (login, before_actions, etc.). |
+| `Current.log_fields` (cualquier key) | La subclass de `Current` overrideo el hook y retorno un Hash no vacio. | — |
+| `tags` | Rails tagged logging activo. **Antipatron con JSON** (rompe el formato) — ver FAQ. | — |
+
+Para el detalle por entrypoint (que setea que y cuando), ver [`docs/behavior/behavior.md`](../docs/behavior/behavior.md). Para el significado de cada campo, [`docs/glossary/glossary.md`](../docs/glossary/glossary.md).
+
 #### Ejemplos: KV vs Hash producen output equivalente
 
 ```ruby

data/skills.yml

@@ -2,48 +2,34 @@ mcps:
   - github
   - clickup
 skills:
-  skill-manager:
-    repo: sequre/ai_knowledge
-    scope: local
   yard:
     repo: sequre/ai_knowledge
-    scope: local
   quality-code:
     repo: sequre/ai_knowledge
-    scope: local
   gem-release:
     repo: sequre/ai_knowledge
-    scope: local
-  skill-builder:
+  dev-structure:
     repo: sequre/ai_knowledge
-    scope: local
-  ai-reports:
+  dev-compose:
     repo: sequre/ai_knowledge
-    scope: local
-    environment:
-      space_id: "${AI_REPORTS_SPACE_ID}"
-      bug_reports_list_id: "${AI_REPORTS_BUG_REPORTS_LIST_ID}"
-      improvements_list_id: "${AI_REPORTS_IMPROVEMENTS_LIST_ID}"
-  agent-review:
+  dev-enrich:
     repo: sequre/ai_knowledge
-    scope: local
-    environment:
-      space_id: "${AGENT_REVIEW_SAPCE_ID}"
-      list_id: "${AGENT_LIST_ID}"
-  action-plan:
+  skill-feedback:
+    repo: sequre/ai_knowledge
+  agent-issue:
+    repo: sequre/ai_knowledge
+  dev-flow:
+    repo: sequre/ai_knowledge
+  matrix-element:
     repo: sequre/ai_knowledge
     environment:
-      space_id: "${AGENT_REVIEW_SAPCE_ID}"
-      list_id: "${AGENT_ACTION_PLAN_LIST_ID}"
+      homeserver: "https://matrix.cloud.wispro.co"
+      auth_token: "${MATRIX_AUTH_TOKEN}"
+      rooms:
+        agents: "!VCHwQXgmXdyhhhPhoz:matrix.cloud.wispro.co"
   documentation-writer:
     repo: github/awesome-copilot
     path: skills/documentation-writer
-    scope: local
-  find-skills:
-    repo: vercel-labs/skills
-    path: skills/find-skills
-    scope: local
   opentelemetry:
     repo: bobmatnyc/claude-mpm-skills
     path: universal/observability/opentelemetry
-    scope: local

data/spec/exis_ray/configuration_spec.rb

@@ -37,6 +37,14 @@ RSpec.describe ExisRay::Configuration do
     it "deployment_environment por defecto es nil fuera de Rails" do
       expect(config.deployment_environment).to be_nil
     end
+
+    it "emit_legacy_exception_keys por defecto es true (ventana de transición OTel)" do
+      expect(config.emit_legacy_exception_keys).to be true
+    end
+
+    it "emit_legacy_path_key por defecto es true (ventana de transición OTel url.path)" do
+      expect(config.emit_legacy_path_key).to be true
+    end
   end
 
   describe "resource attributes OTel" do
@@ -158,5 +166,19 @@ RSpec.describe ExisRay::Configuration do
 
       expect(config.log_subscriber_class).to eq("MyLogSubscriber")
     end
+
+    it "permite cambiar emit_legacy_exception_keys" do
+      config = described_class.new
+      config.emit_legacy_exception_keys = false
+
+      expect(config.emit_legacy_exception_keys).to be false
+    end
+
+    it "permite cambiar emit_legacy_path_key" do
+      config = described_class.new
+      config.emit_legacy_path_key = false
+
+      expect(config.emit_legacy_path_key).to be false
+    end
   end
 end

data/spec/exis_ray/json_formatter_spec.rb

@@ -463,6 +463,72 @@ RSpec.describe ExisRay::JsonFormatter do
     end
   end
 
+  describe "dedup de claves Symbol/String (issue #12)" do
+    def stub_tracer_with_task(task_value)
+      stub_const("ExisRay::Tracer", Module.new do
+        define_singleton_method(:service_name) { "test-service" }
+        define_singleton_method(:root_id) { "1-abc-def" }
+        define_singleton_method(:trace_id) { nil }
+        define_singleton_method(:request_id) { nil }
+        define_singleton_method(:source) { "task" }
+        define_singleton_method(:sidekiq_job) { nil }
+        define_singleton_method(:task) { task_value }
+      end)
+    end
+
+    it "no emite warning de `duplicate key` cuando KV string y Tracer setean la misma key" do
+      stub_tracer_with_task("billing:invoices")
+
+      warning = nil
+      original_warn = Warning.method(:warn)
+      Warning.singleton_class.define_method(:warn) { |msg, **| warning = msg }
+
+      begin
+        call("event=task_started task=billing:invoices outcome=started")
+      ensure
+        Warning.singleton_class.define_method(:warn, original_warn)
+      end
+
+      expect(warning).to be_nil
+    end
+
+    it "developer payload (KV string) pisa al contexto canónico inyectado por Tracer" do
+      stub_tracer_with_task("billing:invoices")
+
+      result = call("event=foo task=override outcome=success")
+
+      expect(result["task"]).to eq("override")
+    end
+
+    it "emite la key como String aunque internamente fuese Symbol" do
+      stub_tracer_with_task("billing:invoices")
+
+      json_str = formatter.call(severity, timestamp, progname, "event=task_started outcome=started")
+
+      # Si quedaran ambas (`:task` y `"task"`) el JSON tendría dos veces la key.
+      expect(json_str.scan(/"task"\s*:/).size).to eq(1)
+      expect(JSON.parse(json_str)["task"]).to eq("billing:invoices")
+    end
+
+    it "no incluye keys con valor nil en el output" do
+      stub_const("ExisRay::Tracer", Module.new do
+        define_singleton_method(:service_name) { "test-service" }
+        define_singleton_method(:root_id) { nil }
+        define_singleton_method(:trace_id) { nil }
+        define_singleton_method(:request_id) { nil }
+        define_singleton_method(:source) { nil }
+        define_singleton_method(:sidekiq_job) { nil }
+        define_singleton_method(:task) { nil }
+      end)
+
+      result = call("event=foo")
+
+      expect(result).not_to have_key("root_id")
+      expect(result).not_to have_key("task")
+      expect(result).not_to have_key("source")
+    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" })

data/spec/exis_ray/log_subscriber_spec.rb

@@ -151,6 +151,33 @@ RSpec.describe ExisRay::LogSubscriber do
       expect(data[:server_address]).to eq("api.example.com")
     end
 
+    it "emite url.path (OTel v1.0) siempre con la URL concreta" do
+      event = build_event(payload: base_payload)
+
+      data = subscriber.send(:build_payload, event)
+
+      expect(data[:"url.path"]).to eq("/users/42")
+    end
+
+    it "emite path (legacy Wispro) junto a url.path cuando emit_legacy_path_key=true (default)" do
+      event = build_event(payload: base_payload)
+
+      data = subscriber.send(:build_payload, event)
+
+      expect(data[:path]).to eq("/users/42")
+      expect(data[:"url.path"]).to eq("/users/42")
+    end
+
+    it "omite path cuando emit_legacy_path_key=false (solo url.path)" do
+      allow(ExisRay.configuration).to receive(:emit_legacy_path_key).and_return(false)
+      event = build_event(payload: base_payload)
+
+      data = subscriber.send(:build_payload, event)
+
+      expect(data).not_to have_key(:path)
+      expect(data[:"url.path"]).to eq("/users/42")
+    end
+
     # Helper: construye un mock de ActionDispatch::Journey::Route con la API REAL
     # que usa el código de producción (route.defaults, route.path.spec, route.verb).
     # Esto evita el anti-patrón anterior de stubear una API inventada.
@@ -268,6 +295,22 @@ RSpec.describe ExisRay::LogSubscriber do
       expect(data[:error_message]).to eq("something went wrong")
     end
 
+    it "omite error_class/error_message cuando emit_legacy_exception_keys=false" do
+      allow(ExisRay.configuration).to receive(:emit_legacy_exception_keys).and_return(false)
+
+      event = build_event(payload: base_payload.merge(
+        status: nil,
+        exception: ["RuntimeError", "something went wrong"]
+      ))
+
+      data = subscriber.send(:build_payload, event)
+
+      expect(data[:"exception.type"]).to eq("RuntimeError")
+      expect(data[:"exception.message"]).to eq("something went wrong")
+      expect(data).not_to have_key(:error_class)
+      expect(data).not_to have_key(:error_message)
+    end
+
     it "inyecta exception.stacktrace desde payload[:exception_object]" do
       exception_object = RuntimeError.new("boom")
       exception_object.set_backtrace(["a.rb:1", "b.rb:2", "c.rb:3"])

data/spec/exis_ray/task_monitor_spec.rb

@@ -49,7 +49,22 @@ RSpec.describe ExisRay::TaskMonitor do
         expect(start_log[0]).to eq(:info)
         expect(start_log[1]).to include("outcome=started")
         expect(start_log[1]).to include("event=task_started")
-        expect(start_log[1]).to include("task=billing:invoices")
+      end
+
+      it "no emite `task=` en el KV (la clave viene del formatter vía Tracer.task)" do
+        captured_task = nil
+        described_class.run("billing:invoices") { captured_task = ExisRay::Tracer.task }
+
+        # task_name vive en el Tracer durante la ejecución del bloque
+        expect(captured_task).to eq("billing:invoices")
+
+        # Los KV de lifecycle NO incluyen `task=...` — evita la duplicación con
+        # `JsonFormatter#inject_tracer_context` (issue #12).
+        lifecycle = captured_logs.map { |_, msg| msg }.select { |m| m.include?("event=task_") }
+        expect(lifecycle).not_to be_empty
+        lifecycle.each do |msg|
+          expect(msg).not_to match(/\btask=/)
+        end
       end
 
       it "loguea task_finished con outcome=success (breaking rename v0.6.0)" do
@@ -94,6 +109,21 @@ RSpec.describe ExisRay::TaskMonitor do
         expect(finish_log[1]).to include("exception.stacktrace=")
       end
 
+      it "omite error_class/error_message cuando emit_legacy_exception_keys=false" do
+        allow(ExisRay.configuration).to receive(:emit_legacy_exception_keys).and_return(false)
+
+        expect do
+          described_class.run("task:boom") { raise "kaboom" }
+        end.to raise_error(RuntimeError, "kaboom")
+
+        finish_log = captured_logs.find { |lvl, msg| lvl == :error && msg.include?("task_finished") }
+        expect(finish_log[1]).not_to include("error_class=")
+        expect(finish_log[1]).not_to include("error_message=")
+        expect(finish_log[1]).to include("exception.type=RuntimeError")
+        expect(finish_log[1]).to include("exception.message=")
+        expect(finish_log[1]).to include("exception.stacktrace=")
+      end
+
       it "resetea el Tracer incluso en caso de error" do
         begin
           described_class.run("task:boom") { raise "kaboom" }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exis_ray
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Gabriel Edera
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -90,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.9.0/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.9.0/skill
+  changelog_uri: https://github.com/gedera/exis_ray/blob/v0.11.0/CHANGELOG.md
+  documentation_uri: https://github.com/gedera/exis_ray/blob/v0.11.0/skill
 post_install_message:
 rdoc_options: []
 require_paths: