exis_ray 0.10.0 → 0.11.1

data/docs/config/configuracion.md

@@ -0,0 +1,144 @@
+# Configuración — exis_ray
+
+> meta: artefacto · RFC-012 (12-Factor App §III, shape v2.2) · generado arch-structure + arch-enrich · anclado a commit `7db39ca` (v0.11.0) · cobertura **inventario base completa · §f enriquecido 11/11 · §j mapeado 2/2**
+
+## 1. Resumen
+
+Gema de tracing/observabilidad. Configuración pública vía `ExisRay.configure do |config| ... end` (clase `ExisRay::Configuration`, 10 opciones con defaults compatibles AWS X-Ray) + 1 env var de runtime (`HOSTNAME`). Sin scheduler propio; el `Railtie` inyecta middlewares, formatter de logs e instrumentación de Sidekiq/BugBunny/ActiveResource al host durante el boot.
+
+## 2. Cuerpo
+
+### §a Hecho verificable
+
+| métrica | conteo |
+|---|---|
+| total vars/opciones | 11 |
+| requeridas | 0 |
+| con default | 11 |
+| derivadas | 2 |
+| secretas | 0 |
+
+### §b Inventario base
+
+| nombre | tipo | requerida | default | origen | consumidor (file:line) | secret? |
+|---|---|---|---|---|---|---|
+| `trace_header` | String | no | `"HTTP_X_AMZN_TRACE_ID"` | code-default | `configuration.rb:76` | no |
+| `propagation_trace_header` | String | no | `"X-Amzn-Trace-Id"` | code-default | `configuration.rb:77` | no |
+| `reporter_class` | String/Class/nil | no | `nil` | code-default | `configuration.rb:78` | no |
+| `current_class` | String/Class/nil | no | `nil` | code-default | `configuration.rb:79` | no |
+| `log_format` | Symbol | no | `:text` | code-default | `configuration.rb:80` | no |
+| `log_subscriber_class` | String/nil | no | `nil` | code-default | `configuration.rb:81` | no |
+| `service_version` | String/nil | no | `derived(Rails config.version ∥ config.x.version)` | derived | `configuration.rb:82,93-111` | no |
+| `deployment_environment` | String/nil | no | `derived(Rails.env)` | derived | `configuration.rb:83,113-117` | no |
+| `emit_legacy_exception_keys` | Boolean | no | `true` | code-default | `configuration.rb:84` | no |
+| `emit_legacy_path_key` | Boolean | no | `true` | code-default | `configuration.rb:85` | no |
+| `HOSTNAME` | String | no | `"local"` (fallback) | env | `task_monitor.rb:81` | no |
+
+> Solo shape — sin valores reales (RFC-012 §3). `requerida=no` en las 10 opciones: el `initialize` siembra default a todas; `HOSTNAME` cae a `"local"` si ausente.
+
+### §c Meta-templates
+
+`n/a` — sin patrón de sufijo/prefijo repetido ≥3 (no hay service discovery estática `_HOST/_PORT/_PROTOCOL`).
+
+### §d Derivaciones simples
+
+| var derivada | fórmula | fuente |
+|---|---|---|
+| `service_version` | `Rails.application.config.version` → fallback `config.x.version` → `nil` | `configuration.rb:93-111` |
+| `deployment_environment` | `Rails.env.to_s` | `configuration.rb:113-117` |
+| `pod_id` (no-config) | `(ENV["HOSTNAME"] ∥ "local").split("-").last` | `task_monitor.rb:81` |
+
+### §e Scheduling
+
+`n/a` — la gema no define `sidekiq.yml`/`queue.yml`/`recurring.yml` ni queues/cron propios. **Instrumenta** el Sidekiq del host (middlewares) pero no agenda trabajo — ver §i.
+
+### §i Inyecciones al host (Railtie)
+
+| inyección | gatillo | efecto | file:line |
+|---|---|---|---|
+| `exis_ray.configure_middleware` | initializer | inserta `ExisRay::HttpMiddleware` after `ActionDispatch::RequestId` (fallback `use`) | `railtie.rb:14-23` |
+| `exis_ray.configure_logging` | initializer (after `:load_config_initializers`) | en modo texto: `app.config.log_tags << proc { trace_id ∥ root_id }` | `railtie.rb:28-36` |
+| validación de clases | `config.after_initialize` | `raise` si `current_class`/`reporter_class` no heredan de base | `railtie.rb:45-53` |
+| formatter JSON global | `config.after_initialize` (modo json) | `Rails.logger.formatter = ExisRay::JsonFormatter.new` | `railtie.rb:57` |
+| LogSubscriber HTTP | `config.after_initialize` (modo json) | `ExisRay::LogSubscriber.install!` (reemplaza Lograge/defaults Rails) | `railtie.rb:62` |
+| instrumentación BugBunny | `config.after_initialize` (si `defined?(::BugBunny)`) | consumer middleware + `rpc_reply_headers` + `on_rpc_reply` | `railtie.rb:68-90` |
+| instrumentación ActiveResource | `config.after_initialize` (si `defined?(ActiveResource::Base)`) | `prepend ExisRay::ActiveResourceInstrumentation` | `railtie.rb:93-99` |
+| instrumentación Sidekiq | `config.after_initialize` (si `defined?(::Sidekiq)`) | client/server middleware + `Sidekiq.logger.formatter` (modo json) | `railtie.rb:102-123` |
+
+### §j Inyección a gemas configuradas
+
+| gema configurada | superficie tocada | file:line | mapeo opción local → gema | ancla |
+|---|---|---|---|---|
+| `::BugBunny` | `consumer_middlewares.use ConsumerTracingMiddleware`; `configuration.rpc_reply_headers`; `configuration.on_rpc_reply` | `railtie.rb:71-88` | `propagation_trace_header` → key del header en `rpc_reply_headers` (`railtie.rb:75`) y lectura en `on_rpc_reply` (`railtie.rb:79`). El middleware/consumer no mapea opción de valor. | **integración opcional** (guard `defined?(::BugBunny)`), **no es dependencia declarada** (ausente de gemspec/Gemfile.lock) → sin ancla cross-repo, no aplica `skills.yml` |
+| `::Sidekiq` | `configure_client` / `configure_server` (middleware chains); `Sidekiq.logger.formatter` | `railtie.rb:106-121` | `log_format=:json` (vía `json_logs?`) → `Sidekiq.logger.formatter = ExisRay::JsonFormatter.new` (`railtie.rb:121`). Las chains de middleware no mapean opción de valor. | **integración opcional** (guard `defined?(::Sidekiq)`), no es dependencia declarada → sin `docs/config/` a linkear |
+
+## f. Enriquecimiento semántico
+
+> cobertura: 11/11 vars enriquecidas; ausencia ≠ "no aplica".
+
+### f.1 Propagación de trace context (`*trace_header`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `trace_header` | integration | silent-default (cae al header AWS X-Ray si no se setea) | per-request (leído por request) | boot-only | key del header **Rack entrante** que `HttpMiddleware` lee para hidratar el Tracer (`http_middleware.rb:13`); cambiarla solo si el edge/LB usa otro header de traza |
+| `propagation_trace_header` | integration | silent-default | per-request | boot-only | key del header **saliente** que inyectan Faraday/ActiveResource/BugBunny-publisher + RPC reply (`faraday_middleware.rb:20`, `active_resource_instrumentation.rb:31`, `bug_bunny/publisher_tracing.rb:33`, `railtie.rb:75,79`); debe coincidir con el `trace_header` (forma HTTP) del downstream o la cadena se corta |
+
+### f.2 Wiring de clases del host (`*_class`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `current_class` | orchestration | boot-crash @ after-initialize si la clase no hereda de `ExisRay::Current` (`railtie.rb:45-47`); silent-default (`nil` → contexto de negocio no-op) si no existe | restart (prod: memoizado `@current_class_cache`, `exis_ray.rb:78`) · per-request (dev: re-resuelto para Zeitwerk reload, `exis_ray.rb:80`) | boot-only en prod · mutable-singleton en dev | clase del host que provee `user_id`/`isp_id`/`correlation_id`; se pasa como String para evitar `uninitialized constant` en boot |
+| `reporter_class` | orchestration | boot-crash @ after-initialize si no hereda de `ExisRay::Reporter` (`railtie.rb:50-52`); silent-default (`nil` → no se reporta a Sentry) | restart · per-request (idem `current_class`, `exis_ray.rb:95-97`) | boot-only en prod · mutable-singleton en dev | clase del host que envía errores a Sentry con trace context; consumida por TaskMonitor/middlewares al rescatar |
+| `log_subscriber_class` | observability | silent-default (`nil` → `ExisRay::LogSubscriber` base sin `extra_fields`) | restart (`install!` en after_initialize, `log_subscriber.rb:295`) | boot-only | subclase para inyectar `extra_fields` en el log de cierre HTTP; **solo aplica si `json_logs?`** (ver §g) |
+
+### f.3 Estrategia de logging (`log_format`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `log_format` | observability | silent-default (`:text` → tags de Rails, sin JsonFormatter) | restart (decisión tomada en boot tras `load_config_initializers`, `railtie.rb:28-29`) | boot-only | conmuta **toda** la estrategia: `:json` instala JsonFormatter global + LogSubscriber + formatter de Sidekiq (`railtie.rb:56-65,121`); `:text` solo agrega `root_id` como `log_tag`. **Ramificador** (§g). |
+
+### f.4 Metadata de recurso OTel
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `service_version` | observability | silent-default (`nil` → campo `service_version` omitido del log) | per-request (emitido por línea, `json_formatter.rb:89`) | boot-only (computado una vez de Rails config) | equivale a `service.version` de OTel |
+| `deployment_environment` | observability | silent-default (`nil` → campo omitido) | per-request (`json_formatter.rb:94`) | boot-only (derivado de `Rails.env`) | equivale a `deployment.environment` de OTel |
+
+### f.5 Feature-flags de migración OTel (transitorios)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `emit_legacy_exception_keys` | feature-flag | silent-default (`true` → emite `error_class`/`error_message` además de `exception.*`) | per-request en error (`log_subscriber.rb:156`, `task_monitor.rb:138`) | boot-only | flag transitorio ventana OTel v1.0. **Ramp:** partial (default `true`). **Cleanup:** cuando dashboards/alertas/queries migren a `exception.*`. Roadmap: default `false` en v0.12.0, removido en v1.0 |
+| `emit_legacy_path_key` | feature-flag | silent-default (`true` → emite `path` además de `url.path`) | per-request (`log_subscriber.rb:115`) | boot-only | flag transitorio. **Ramp:** partial. **Cleanup:** cuando consumers migren a `url.path`. Roadmap: default `false` en v0.12.0, removido en v1.0 |
+
+### f.6 Identidad de pod (`HOSTNAME`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `HOSTNAME` | infra | silent-default (`"local"` si ausente) | per-task (leído al generar root en TaskMonitor, `task_monitor.rb:81`) | boot-only (env del contenedor) | sufijo del hostname (post último `-`) como `pod_id` en el `root_id` de tasks; en K8s/Docker lo inyecta el orquestador |
+
+**Threading (§h):** los callbacks RPC de BugBunny (`on_rpc_reply`, `railtie.rb:77-88`) corren en el **thread del publisher** y resuelven `reporter_class`/`current_class` vía los helpers memoizados. `ExisRay::Tracer`/`Current` heredan `ActiveSupport::CurrentAttributes` (thread/fiber-local). Constraint: el valor de config es un singleton global; las clases resueltas se comparten entre threads — safe porque son class objects inmutables tras boot.
+
+**Ramificadores intra-config (§g):**
+
+- `log_format=:json` (vía `json_logs?`) ramifica la aplicabilidad de **`log_subscriber_class`** (inerte en `:text` — `install!` solo corre en modo json) y dispara `JsonFormatter` global + `Sidekiq.logger.formatter` (`railtie.rb:56-65,121`).
+- `emit_legacy_exception_keys` / `emit_legacy_path_key` ramifican **qué keys se emiten** en el log, no la aplicabilidad de otras vars.
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| `HOSTNAME` clasificada `requerida=no` | declared | fallback `"local"` explícito en `task_monitor.rb:81` — confirmado |
+| `service_version`/`deployment_environment` como `derived` | declared | defaults computados en `initialize` vía `default_*` — confirmado |
+| sin secretos | declared | ninguna opción matchea `*_KEY|*_SECRET|*_PASS|*_TOKEN` ni literal sensible — confirmado |
+| `reporter_class`/`current_class` aceptan String o Class | declared | YARD `@return [String, Class, nil]`; el `safe_constantize` del Railtie asume String — verificar uso real |
+| `::BugBunny`/`::Sidekiq` sin ancla cross-repo (§j) | declared | son **integraciones opcionales** (guard `defined?`), no dependencias declaradas (ausentes de gemspec/Gemfile.lock) — la gema inyecta hooks si el host las tiene. Por eso NO van en `skills.yml`: no hay relación de consumo que anclar |
+| `scope-override` boot-only vs mutable-singleton de `*_class` (§f.2) | inferred | depende de `cache_classes?` (`exis_ray.rb:118-128`): prod memoiza (boot-only), dev re-resuelve por request (mutable). Verificar que el host no mute `configuration.*_class` post-boot |
+
+## 4. Cobertura y fronteras
+
+- **Inventario base completo** para v0.11.0 — las 11 vars/opciones del código están listadas.
+- **Enriquecimiento §f completo 11/11** — categoría · failure-mode · side-effect · scope-override · business-reason por opción, + threading (§h) y ramificadores (§g). Anclado al consumidor real (`file:line`); las inferencias quedan en §3 para verificación humana.
+- **Mapeo §j → gema completo 2/2** — `propagation_trace_header`→BugBunny RPC headers; `log_format`→Sidekiq formatter. Ancla cross-repo de BugBunny pendiente (no declarada en `skills.yml`, ver §3).
+- **Fuera de alcance:** `ENV["TENANT_ID"]` en `current.rb:22` es **ejemplo en comentario YARD** (no consumo real) → no se lista. Vars de Rails core (`SECRET_KEY_BASE`, `RAILS_ENV`, etc.) las aporta la app host, no esta gema.
+- **`config.x.version`** (lectura de `service_version`) depende del host — la gema solo lee, no define.

data/docs/interface/interface.md

@@ -0,0 +1,120 @@
+# Interfaz — exis_ray
+
+> meta: artefacto · RFC-004 (RBS firmas como modelo conceptual) · generado arch-structure · anclado a commit `b7b96c7` (v0.11.0) · cobertura **superficie pública consumer-facing completa**
+
+## 1. Resumen
+
+API Ruby pública de la gema: módulo `ExisRay` (config + resolución de clases host), 2 bases abstractas que el host subclasea (`Current`, `Reporter`), el contexto de trazabilidad (`Tracer`), el formatter/subscriber de logs, el monitor de tasks, y 7 middlewares de propagación (HTTP/Faraday/ActiveResource/Sidekiq×2/BugBunny×2). Las clases configurables (`Configuration`) se documentan en detalle en [`docs/config/configuracion.md`](../config/configuracion.md).
+
+## 2. Superficie pública (símbolo · tipo · firma · nota)
+
+### `ExisRay` (módulo raíz)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `ExisRay::VERSION` | const | `String` | `"0.11.0"` (`version.rb:5`) |
+| `ExisRay::Error` | class | `< StandardError` | error base de la gema (`exis_ray.rb:36`) |
+| `ExisRay.configure` | method | `() { (Configuration) -> void } -> void` | bloque de configuración (`exis_ray.rb:60`) |
+| `ExisRay.configuration` | method | `() -> Configuration` | instancia singleton (`exis_ray.rb:46`) |
+| `ExisRay.configuration=` | writer | `(Configuration) -> void` | reemplaza la config — uso en tests (`exis_ray.rb:40`) |
+| `ExisRay.current_class` | method | `() -> Class?` | resuelve `config.current_class`; memoizado en prod, re-resuelto en dev (`exis_ray.rb:71`) |
+| `ExisRay.reporter_class` | method | `() -> Class?` | resuelve `config.reporter_class` (`exis_ray.rb:88`) |
+| `ExisRay.sync_correlation_id` | method | `() -> void` | copia `Tracer.correlation_id` → `Current.correlation_id` (`exis_ray.rb:105`) |
+
+### `ExisRay::Configuration` (clase)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `Configuration#<attr>` | accessor (rw) | — | 10 opciones (`trace_header`, `log_format`, `current_class`, ...) — inventario y semántica en [`docs/config/`](../config/configuracion.md) |
+| `Configuration#json_logs?` | method | `() -> bool` | `true` si `log_format == :json` (`configuration.rb:122`) |
+
+### `ExisRay::Tracer` (`< ActiveSupport::CurrentAttributes`)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `Tracer.<attr>` | accessor (rw) | — | `trace_id · request_id · root_id · self_id · called_from · total_time_so_far · created_at · sidekiq_job · source · task` (`tracer.rb:15`) |
+| `Tracer.hydrate` | method | `(trace_id:, source:) -> void` | inicializa el contexto desde header entrante (`tracer.rb:78`) |
+| `Tracer.generate_trace_header` | method | `() -> String` | header para propagar al siguiente servicio (`tracer.rb:115`) |
+| `Tracer.parse_trace_id` | method | `() -> void` | extrae `root_id`/`self_id`/`called_from`/`total_time_so_far` del `trace_id` (`tracer.rb:40`) |
+| `Tracer.service_name` | method | `() -> String` | nombre del servicio (de `Rails.application`) (`tracer.rb:22`) |
+| `Tracer.correlation_id` | method | `() -> String` | compuesto `service_name;root_id` (`tracer.rb:32`) |
+| `Tracer.current_duration_s` | method | `() -> Float` | segundos desde `created_at` (monotónico) (`tracer.rb:89`) |
+| `Tracer.current_duration_ms` | method | `() -> Integer` | milisegundos desde `created_at` (`tracer.rb:67`) |
+| `Tracer.format_duration` | method | `(Float seconds) -> String` | formato humano (`"7.0ms"`, `"2 minutes 5 seconds"`) (`tracer.rb:102`) |
+
+### `ExisRay::Current` (`< ActiveSupport::CurrentAttributes`, base abstracta — el host subclasea)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `Current.<attr>` | accessor (rw) | — | `user_id · isp_id · correlation_id` (`current.rb:9`) |
+| `Current.user_id=` | setter | `(Integer?) -> void` | usa `!nil?` (acepta `0`) + sincroniza PaperTrail/ActiveResource (`current.rb:54`) |
+| `Current.isp_id=` | setter | `(Integer?) -> void` | ídem (`current.rb:63`) |
+| `Current.correlation_id=` | setter | `(String?) -> void` | propaga a Session/Reporter (`current.rb:71`) |
+| `Current.user=` / `Current.user` | accessor | `(obj) -> void` / `() -> User?` | asigna `user_id` de `obj.id` / lazy-load memoizado (`current.rb:84,88`) |
+| `Current.isp=` / `Current.isp` | accessor | `(obj) -> void` / `() -> Isp?` | ídem (`current.rb:95,99`) |
+| `Current.user?` / `Current.isp?` | predicate | `() -> bool` | true si el id `!nil?` (`current.rb:106,110`) |
+| `Current.correlation_id?` | predicate | `() -> bool` | true si `present?` (`current.rb:116`) |
+| `Current.log_fields` | hook | `() -> Hash` | **override** para inyectar campos custom en cada log; default `{}` (`current.rb:31`) |
+
+### `ExisRay::Reporter` (`< ActiveSupport::CurrentAttributes`, base abstracta — el host subclasea)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `Reporter.report` | method | `(String message, context: {}, tags: {}, fingerprint: [], transaction_name: nil) -> void` | reporta mensaje a Sentry (`reporter.rb:24`) |
+| `Reporter.exception` | method | `(Exception excep, context: {}, tags: {}, fingerprint: [], transaction_name: nil) -> void` | reporta excepción (`reporter.rb:33`) |
+| `Reporter.add_context` | method | `(Hash attrs) -> void` | acumula contexto (`reporter.rb:58`) |
+| `Reporter.add_tags` | method | `(Hash attrs) -> void` | acumula tags (`reporter.rb:64`) |
+| `Reporter.add_fingerprint` | method | `(value) -> void` | acumula fingerprint (`reporter.rb:52`) |
+| `Reporter.build_custom_context` | hook | `() -> void` | **override** para contexto específico del servicio (`reporter.rb:70`) |
+| `Reporter.sentry_user_context` | hook | `(current) -> Hash` | **override**; default `{ id: user_id }` (`reporter.rb:196`) |
+| `Reporter.sentry_isp_context` | hook | `(current) -> Hash` | **override** (`reporter.rb:205`) |
+
+### `ExisRay::JsonFormatter` (`< ::Logger::Formatter`)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `JsonFormatter#call` | method | `(severity, timestamp, progname, msg) -> String` | interfaz `Logger::Formatter`; emite JSON single-line con contexto inyectado (`json_formatter.rb:49`) |
+
+### `ExisRay::LogSubscriber` (`< ActiveSupport::LogSubscriber`)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `LogSubscriber.install!` | method | `() -> void` | suscribe y suprime los subscribers default de Rails (`log_subscriber.rb:68`) |
+| `LogSubscriber.attached?` | method | `() -> bool` | si ya está instalado (`log_subscriber.rb:76`) |
+| `LogSubscriber.extra_fields` | hook | `(event) -> Hash` | **override** para campos HTTP extra; default `{}` (`log_subscriber.rb:58`) |
+| `LogSubscriber#process_action` | method | `(event) -> void` | interfaz subscriber; emite el log de cierre de request (`log_subscriber.rb:33`) |
+
+### `ExisRay::TaskMonitor` (módulo)
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `TaskMonitor.run` | method | `(String task_name) { () -> void } -> void` | genera `root_id`, loguea `task_started`/`task_finished`, re-lanza excepciones, resetea contexto (`task_monitor.rb:16`) |
+
+### Middlewares de propagación
+
+| símbolo | tipo | firma | nota |
+|---|---|---|---|
+| `ExisRay::HttpMiddleware` | class (Rack) | `#initialize(app)` · `#call(env) -> Array` | auto-insertado tras `ActionDispatch::RequestId` (`http_middleware.rb`) |
+| `ExisRay::FaradayMiddleware` | class (`< Faraday::Middleware`) | `#call(env)` | **manual** en el stack Faraday (`faraday_middleware.rb`) |
+| `ExisRay::ActiveResourceInstrumentation` | module (prepend) | `#headers -> Hash` | auto-prepend a `ActiveResource::Base` (`active_resource_instrumentation.rb`) |
+| `ExisRay::Sidekiq::ClientMiddleware` | class | `#call(worker_class, job, queue, redis_pool = nil) { }` | auto-registrado (client) (`sidekiq/client_middleware.rb`) |
+| `ExisRay::Sidekiq::ServerMiddleware` | class | `#call(worker, job, queue) { }` | auto-registrado (server) (`sidekiq/server_middleware.rb`) |
+| `ExisRay::BugBunny::PublisherTracing` | class (`< ::BugBunny::Middleware::Base`) | `#on_request(env)` | **manual** en el cliente (`bug_bunny/publisher_tracing.rb`) |
+| `ExisRay::BugBunny::ConsumerTracingMiddleware` | class (`< ::BugBunny::ConsumerMiddleware::Base`) | `#call(delivery_info, properties, body)` | auto-registrado (consumer) (`bug_bunny/consumer_tracing_middleware.rb`) |
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| `Tracer`/`Reporter`/`TaskMonitor` no declaran `private` | declared | métodos helper (`generate_new_root`, `clean_request_id`, `build_from_*`, `*_to_old/new_sentry`, `setup_tracer`, ...) quedan **reachable** Ruby-wise pero NO son contrato — ver §4 (Hyrum's Law) |
+| accesores de `Current`/`Tracer`/`Reporter` como métodos de clase | declared | son `ActiveSupport::CurrentAttributes` → los `attribute :x` exponen `.x`/`.x=` a nivel de clase, thread/fiber-local |
+| middlewares "manual" vs "auto" | declared | Faraday y BugBunny-publisher requieren registro manual; el resto los inyecta el Railtie (ver `docs/config` §i) |
+
+## 4. Cobertura y fronteras
+
+- **Superficie consumer-facing completa** para v0.11.0 — lo que un host app usa o subclasea.
+- **Helpers públicos-Ruby pero NO contrato:** `Tracer.generate_new_root` / `.clean_request_id`; `Reporter.build_from_tracer` / `.build_from_current` / `.*_to_old_sentry` / `.*_to_new_sentry` / `.session_*`; `TaskMonitor.setup_tracer` / `.pod_identifier` / `.log_event` / `.format_*`; helpers privados de `Current` (`assign_session_request_id`, `sync_reporter_correlation_id`, `sanitize_header_value` — sí marcados `private`, `current.rb:120`). Reachable por falta de `private` (salvo Current), pero son detalle de implementación; cambiar su firma no es breaking de contrato.
+- **Internos del formatter/subscriber:** los `inject_*`/`extract_*`/`parse_*` de `JsonFormatter` y `LogSubscriber` son privados de implementación — el contrato es `#call` / `#process_action` + los hooks de override.
+- **Constantes:** `JsonFormatter::SENSITIVE_KEYS`, `::SEVERITY_NUMBER`, `::KV_DETECT_RE` son detalle interno, no contrato.
+- **Configuración:** el shape de `Configuration` (defaults, tipos, failure-modes) vive en [`docs/config/configuracion.md`](../config/configuracion.md) — acá solo se lista la clase y `json_logs?`.
+- **Comportamiento runtime** (secuencias de hidratación/emisión) → [`docs/behavior/behavior.md`](../behavior/behavior.md); **significado de términos** → [`docs/glossary/glossary.md`](../glossary/glossary.md).

data/docs/test/testing.md

@@ -0,0 +1,156 @@
+# Test — exis_ray
+
+> meta: artefacto test · RFC-013 (shape v2.1, `accepted`) · generado
+> manualmente (**piloto RFC-013** — suplemento de gema para validar §j/§k;
+> predata el soporte de `test` en `arch-structure`, futura regeneración vía
+> esa skill) · anclado a `spec/` · fecha 2026-06-01 · cobertura: completa para los
+> componentes aislados; gap real en inyección del Railtie (sin dummy app) y
+> matrix de versiones (CI mono-versión).
+
+## 1. Resumen
+
+Estrategia y cobertura de test de la gema (Railtie de observabilidad). Stack:
+**RSpec**, 8 suites / **176** examples, **sin SimpleCov**. Cada componente se
+testea **aislado con mocks de Rails** (`stub_const`), no contra una app real.
+Filosofía **test-last + FDD**. Este artefacto es el **suplemento gema** del
+piloto RFC-013: ejercita §j (inyección al host + matrix) y confirma que §k
+(concurrencia) es **n/a** acá.
+
+## 2. Cuerpo
+
+### a. Hecho verificable
+
+- **Suites:** 8 / **176** examples (todos unit aislados).
+- **Modo:** `railtie`/`library` (no http/worker — es gema).
+- **Factories:** 0 (Structs/doubles inline).
+- **Regresiones post-incidente:** 2 (#9, #12) — **con** comentario de origen
+  (§h, convención ya practicada).
+- **% coverage:** `n/a (sin tooling)`.
+- **Inyecciones al host testeadas:** 0 de ~7 (§j) — sin dummy app.
+- **Matrix:** declarado Ruby ≥2.6 / Rails ≥6; testeado CI **solo 3.4.4** (§j).
+- **Tests de concurrencia:** 0 (§k n/a).
+
+### b. Estrategia / pirámide
+
+Todo **unit aislado**: cada clase (`Tracer`, `HttpMiddleware`, `JsonFormatter`,
+`LogSubscriber`, `Configuration`, `Current`, `Reporter`, `TaskMonitor`) se
+testea sola, mockeando `Rails`/`Logger`/`ActionDispatch`. Sin nivel
+integration/system (no hay app real). Mapeo: la gema no mapea a capas de
+servicio — los componentes son su propia superficie (RFC-004 interfaz).
+Momento: **test-last**.
+
+### c. Inventario de suites
+
+| Suite | Nivel | Modo | Nº specs |
+|---|---|---|---|
+| `spec/exis_ray/json_formatter_spec.rb` | unit | library | 54 |
+| `spec/exis_ray/log_subscriber_spec.rb` | unit | railtie | 29 |
+| `spec/exis_ray/tracer_spec.rb` | unit | library | 27 |
+| `spec/exis_ray/configuration_spec.rb` | unit | library | 27 |
+| `spec/exis_ray/current_spec.rb` | unit | library | 16 |
+| `spec/exis_ray/reporter_spec.rb` | unit | library | 8 |
+| `spec/exis_ray/task_monitor_spec.rb` | unit | library | 8 |
+| `spec/exis_ray/http_middleware_spec.rb` | unit | railtie | 7 |
+
+Invocación: `bundle exec rake` (RSpec + RuboCop), ~1.2s.
+
+### d. Cobertura declarada
+
+| Flujo crítico | Cubierto? | Spec | Fuente del gap |
+|---|---|---|---|
+| Trace propagation (parse X-Ray headers, root_id) | sí | `spec/exis_ray/tracer_spec.rb`, `http_middleware_spec.rb` | — |
+| JSON log formatting + OTel + filtrado sensible | sí | `spec/exis_ray/json_formatter_spec.rb` | — |
+| LogSubscriber (HTTP status → log level) | sí | `spec/exis_ray/log_subscriber_spec.rb` | — |
+| **Inyección del Railtie en app real** | **no** | — (sin `spec/dummy/`) | inferido — componentes testeados aislados; la inyección (`lib/exis_ray/railtie.rb`) no se ejercita (§j) |
+
+`% coverage: n/a`. Gap nominal: la **inyección** (lo que distingue a una gema
+Railtie) no tiene test — solo la lógica de cada componente por separado.
+
+### e. Fixtures / factories / test data
+
+Sin FactoryBot, sin fixtures, sin PII. Datos sintéticos inline: Structs
+(`build_event`, `build_route` en `log_subscriber_spec.rb`), `stub_const` de
+`Rails`/`Tracer`/`Logger`. n/a la columna entidad (gema sin capa de datos).
+
+### f. Topología de integration/system tests
+
+**n/a** — no se levanta nada real (sin DB/broker/app). Todo mockeado:
+`Rails`, `Rails.application`, `Logger`, `ActionDispatch::*` vía `stub_const`/
+`instance_double`. Estado requerido para correr: **ninguno** (solo
+`activesupport`). No es el sub-caso "gema-envuelve-infra" (exis_ray no envuelve
+infra externa; instrumenta el host).
+
+### g. Contract tests (cross RFC-018)
+
+**n/a** — la gema no **consume** servicios (no tiene `docs/consumed/`). Nota: sí
+**inyecta** hooks a otras gemas (`BugBunny.consumer_middlewares`, Sidekiq
+client/server middleware, `ActiveResource::Base.prepend` —
+`lib/exis_ray/railtie.rb:71,96,116`), pero **ninguno tiene test** (cae en §j,
+no en §g — es inyección, no consumo).
+
+### h. Tests de no-regresión / nacidos de incidentes
+
+| Test | Incidente | Qué reproduce |
+|---|---|---|
+| `spec/exis_ray/json_formatter_spec.rb:410` `describe "...(issue #9)"` | issue #9 | inyección de contexto de tracer; root_id nil pero request_id presente (Gap C) |
+| `spec/exis_ray/json_formatter_spec.rb:466` `describe "...(issue #12)"` | issue #12 | dedup de claves Symbol/String (no duplicar en JSON) |
+
+- **Convención §h ya practicada** ✅ — exis_ray ancla el incidente en el
+  `describe`. Valida que la convención v2.1 es factible y de bajo costo. (Forma
+  observada: `(issue #N)` en el describe; la norma sugiere `# Regresión: #N` en
+  comentario — ambas cumplen el objetivo de link recuperable sin `git blame`.)
+
+### i. Ejecución, gates y flaky
+
+- **Ejecución:** `bundle exec rake` (RSpec + RuboCop), ~1.2s. Sin gates de
+  suite (no hay integration que excluir).
+- **Flaky:** 0 (176 pasan consistentes, sin `sleep`/`Thread`).
+- **CI:** `.github/workflows/main.yml` — corre la suite, pero ver §j (matrix).
+
+### j. Inyección al host + matrix de versiones
+
+**Sección de alto valor para esta gema** (motivó §j en v2.1).
+
+**Inyección al host** — `lib/exis_ray/railtie.rb` inyecta ~7 cosas; **ninguna
+testeada en app real** (no hay `spec/dummy/`):
+
+| Inyección | file:line | Testeada? |
+|---|---|---|
+| `HttpMiddleware` (`insert_after ActionDispatch::RequestId`) | `railtie.rb:17` | **sin-test** de inyección (lógica del middleware sí, aislada — `mock-rails`) |
+| `config.log_tags` (request_id proc) | `railtie.rb:31` | sin-test |
+| `Rails.logger.formatter = JsonFormatter.new` | `railtie.rb:57` | sin-test (formatter sí, aislado) |
+| `LogSubscriber` (subscribe a ActionController) | `railtie.rb:61` | sin-test (subscriber sí, aislado con `mock-rails`) |
+| `BugBunny.consumer_middlewares.use` | `railtie.rb:71` | **sin-test** |
+| `ActiveResource::Base.prepend` instrumentation | `railtie.rb:96` | **sin-test** |
+| Sidekiq client/server middleware | `railtie.rb:107,116` | **sin-test** |
+
+Gap: lo que **define** a la gema (inyectar al host) es lo único sin test.
+Cruza [`docs/config/configuracion.md`](../config/configuracion.md) §i (mismo
+inventario de inyecciones del Railtie, lado config). Un `spec/dummy/` cerraría
+el gap.
+
+**Matrix de versiones:**
+
+| | Valor |
+|---|---|
+| Declarado (gemspec) | Ruby `>= 2.6.0` · activesupport/railties `>= 6.0` (`exis_ray.gemspec:15,38`) |
+| Testeado (CI) | **solo Ruby 3.4.4** (`.github/workflows/main.yml:17`) — sin Appraisal, sin matrix de Rails |
+| Gap | rango Ruby 2.6–3.3 y Rails 6–7 **declarado pero no ejercitado** |
+
+### k. Tests de concurrencia / async
+
+**n/a** — exis_ray no tiene threads ni callbacks en reader-thread. Confirma que
+§k es **específica de gemas que gestionan concurrencia** (`bug_bunny`), no
+universal. (Input para §5 de la RFC: §k aplicó a 1 de 4 repos validados →
+evaluar si va como sección top-level o sub-bloque condicional.)
+
+## 3. Inferencias
+
+- "Inyección sin test" se infiere de la ausencia de `spec/dummy/` + presencia
+  de hooks en `railtie.rb`. No medido (sin coverage).
+
+## 4. Cobertura y fronteras
+
+- Cobertura completa de los **componentes aislados**; gap en la **integración
+  Railtie↔Rails real** y en la **matrix de versiones**. Ambos son los hallazgos
+  que §j hace visibles — el valor del artefacto para una gema.

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/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

@@ -47,9 +47,7 @@ module ExisRay
       log_event(:error,
                 "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.10.0"
+  VERSION = "0.11.1"
 end

data/skill/SKILL.md

@@ -11,11 +11,14 @@ 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.10.0** (post fix issues #9, #11, #12):
+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.11.1** (capas de doc config/interface + Mapa de conocimiento; sin cambios de código desde v0.11.0):
 
 - [`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).
+- [`docs/config/configuracion.md`](../docs/config/configuracion.md) — inventario de las 10 opciones de `ExisRay.configure` + `HOSTNAME` + inyecciones del Railtie al host (enriquecimiento semántico §f pendiente).
+- [`docs/test/testing.md`](../docs/test/testing.md) — mapa de suites RSpec + fixtures + coverage.
+- [`docs/interface/interface.md`](../docs/interface/interface.md) — superficie Ruby pública (símbolo · tipo · firma · nota); el detalle de uso de cada símbolo permanece abajo.
+- Datos · Operaciones · Eventos · Consumidas = `n/a` (gema sin DB, no expone superficie propia ni consume servicios). Topología/Release/Errores = **pendiente**. Ver mapa de cobertura completo en `AGENTS.md`.
 
 ---
 
@@ -80,7 +83,7 @@ ExisRay unifica trazabilidad distribuida, logging estructurado JSON, contexto de
 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 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`, `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.*`).
+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 +103,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 +238,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 +256,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 +269,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`: