exis_ray 0.5.11 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38ac0186226043d69ad60406f9aa32045a8d1192e223322735c76773a1fd41dd
-  data.tar.gz: 5a37831fc8b34237723ca0ab929c79d469fe316241d97b859272f25b8349e6b6
+  metadata.gz: 2b8dea5e0b236f90177ce536cf1226b37b21c778ee6891dc0276756f9b972fc8
+  data.tar.gz: a8409a1e92f2494535f9e0512f1b47e8cc0bd841335e9b98d6b19ce20ebab08d
 SHA512:
-  metadata.gz: a7f0c1f2e1629f593fd3af2608678568fae5890cd2eb6ed19450364e2a353725dd730baa4cc665498695d0062147728b68d45f3f0485acce93a2e370a956442d
-  data.tar.gz: 84dc5252d489b2e28f5b9909d3928b49b8dfdc176019f4e2dcb066a7e25c1da460752625aca61b2be5c404c2eb7187da813de3fc34f02ba447a8e29902800129
+  metadata.gz: 3ad2bcc7d459c05efefd0e30b0701be99cf82477e843f233b4f62c36e56c4ba183a53d6097e6f461dd253bf07a8776da093c59396cbe0fc16948a0b0db813cc1
+  data.tar.gz: 297abed5f6adf6a799dd1b6a329833bd1433e1c7383aa364081677025f64b63a05d5b23fc6ae96bb2db0fa6a72d0544622a2820580568429f6433702d8aed0a6

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.6.1] - 2026-04-05
+
+### Added
+- **`exception.type` / `exception.message` / `exception.stacktrace`** emitidos junto a los legacy `error_class` / `error_message` en `TaskMonitor` y `LogSubscriber`. Inicia la transición a la convención OTel — los legacy se removerán en v1.0. El stacktrace se toma de `payload[:exception_object]` y se limita a las primeras 20 líneas para respetar el formato one-line KV del estándar Wispro.
+- **`http_route`** en `LogSubscriber` con resolución en capas: (1) `payload[:request].route_uri_pattern` para Rails 7.1+, (2) fallback iterando `Rails.application.routes.routes` y matcheando por `defaults[:controller]`, `defaults[:action]` y verb HTTP. Normaliza el controller name CamelCase (incluyendo namespaces `Api::V1::Users`) al formato snake_case que Rails usa en `route.defaults`.
+
+### Fixed
+- **`TaskMonitor.format_stacktrace`**: maneja `e.backtrace == nil` de forma segura y está envuelto en rescue para que un logger roto nunca afecte el flujo principal.
+- **`private_class_method` restaurado** en `TaskMonitor`: `pod_identifier`, `setup_tracer`, `execute_with_optional_tags`, `log_event` y el nuevo `format_stacktrace` vuelven a ser privados (regresión de 0.6.0).
+- **`extract_exception_data`**: las keys ahora son symbols (`:error_class`, `:"exception.type"`, etc) para ser consistentes con el resto del payload. Antes mezclaba strings y symbols, lo que causaba inconsistencias al serializar.
+- **`extract_http_route`**: la implementación anterior matcheaba contra `route.requirements[:controller]`, pero Rails guarda controller/action en `route.defaults`. El método antes siempre retornaba `nil` en producción, aunque sus tests pasaban por stubear un contrato inventado. Tests reescritos para stubear la API real (`route.defaults`, `route.path.spec`, `route.verb`).
+
 ## [0.5.11] - 2026-04-04
 
 ### Documentación

data/CLAUDE.md

@@ -4,9 +4,14 @@
 
 ExisRay es la capa de observabilidad y trazabilidad distribuida del ecosistema Wispro. Se integra con Rails para emitir logs estructurados en JSON, propagar trace context entre servicios (HTTP, Sidekiq, RabbitMQ), y mantener identidad de negocio (user_id, isp_id, correlation_id) en cada línea de log.
 
-El estándar de logging que implementa está definido en `MANIFEST.md`. Ese documento es la fuente de verdad — cualquier duda sobre formato, campos, o semántica de niveles se resuelve ahí.
+El estándar de logging que implementa está definido en `skill/SKILL.md` (API, arquitectura, reglas generales) y `skill/references/standard.md` (Data First, mapeo OpenTelemetry, ciclo de vida). Son la fuente de verdad — cualquier duda sobre formato, campos, o semántica de niveles se resuelve ahí.
+
+## Documentación
+
+- **Para humanos**: `docs/` (5 archivos) + `README.md`. Ver README para índice.
+- **Para agentes AI**: `skill/SKILL.md` + `skill/references/`. Es la skill empaquetada que otros proyectos consumen via `skill-manager sync`.
+- **Nunca referenciar `skill/` desde `docs/` o `README.md`** — son audiencias distintas.
 
----
 ## Knowledge Base
 - Las skills en `.agents/skills/` incluyen conocimiento de dependencias.
 - Leer la skill de una dependencia ANTES de responder sobre ella.
@@ -34,8 +39,8 @@ El estándar de logging que implementa está definido en `MANIFEST.md`. Ese docu
 - Todo código nuevo debe tener tests.
 
 ### Releases o Nuevas versiones
-- Gemas: `/gem-release`
-- Servicios: `/service-release build` o `/service-release deploy`
+- Usar `/gem-release` para publicar nuevas versiones.
+- El GitHub Action publica a RubyGems automáticamente al pushear un tag `v*`.
 
 ---
 
@@ -96,7 +101,10 @@ ExisRay.configuration.json_logs?                # => true/false
 |:------|:----------|
 | `time` | Siempre |
 | `level` | Siempre |
+| `severity_number` | Siempre (OTel: DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21) |
 | `service` | Siempre |
+| `service_version` | Siempre (de `config.version` o `config.x.version`) |
+| `deployment_environment` | Siempre (de `Rails.env`) |
 | `root_id` | Cuando hay trace context activo |
 | `trace_id` | Cuando hay trace context activo |
 | `source` | Cuando hay trace context activo |

data/README.md

@@ -242,14 +242,14 @@ task generate_invoices: :environment do
 end
 ```
 
-`TaskMonitor` genera un `root_id` nuevo, configura Reporter y Current, loguea `task_started`/`task_finished` con `duration_s` y `status`, y limpia el contexto al finalizar. Si el bloque lanza una excepción, la registra como `status=failed` y la re-lanza.
+`TaskMonitor` genera un `root_id` nuevo, configura Reporter y Current, loguea `task_started`/`task_finished` con `duration_s` y `outcome`, y limpia el contexto al finalizar. Si el bloque lanza una excepción, la registra como `outcome=failed` con `exception.type`, `exception.message` y `exception.stacktrace` (OTel) y la re-lanza.
 
 ## JSON Logging
 
 Con `log_format: :json`, `ExisRay::JsonFormatter` reemplaza el formatter de Rails y emite cada línea como JSON single-line con contexto inyectado automáticamente:
 
 ```json
-{"time":"2026-04-01T14:30:00Z","level":"INFO","service":"wispro_agent","root_id":"1-65f...abc","trace_id":"Root=1-65f...;Self=...","source":"http","user_id":42,"isp_id":10,"component":"exis_ray","event":"http_request","method":"GET","path":"/api/v1/users","status":200,"duration_s":0.0452}
+{"time":"2026-04-01T14:30:00Z","level":"INFO","severity_number":9,"service":"wispro_agent","service_version":"1.2.3","deployment_environment":"production","root_id":"1-65f...abc","trace_id":"Root=1-65f...;Self=...","source":"http","user_id":42,"isp_id":10,"component":"exis_ray","event":"http_request","method":"GET","path":"/api/v1/users","http_route":"/api/v1/users","http_status":200,"duration_s":0.0452,"user_agent_original":"Mozilla/5.0","server_address":"api.example.com"}
 ```
 
 Los mensajes con formato `key=value` se parsean y elevan al root del JSON. Los valores numéricos se castean automáticamente:
@@ -276,7 +276,10 @@ En modo `:text`, ExisRay inyecta el `trace_id` o `root_id` como tag de Rails (`c
 |:------|:----------|
 | `time` | Siempre (UTC ISO 8601) |
 | `level` | Siempre |
+| `severity_number` | Siempre (OTel SeverityNumber: DEBUG=5, INFO=9, WARN=13, ERROR=17, FATAL=21) |
 | `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`) |
@@ -287,6 +290,18 @@ En modo `:text`, ExisRay inyecta el `trace_id` o `root_id` como tag de Rails (`c
 | `task` | Solo en procesos TaskMonitor |
 | `tags` | Solo si hay Rails tagged logging activo |
 
+`LogSubscriber` inyecta además estos campos en los logs de requests HTTP:
+
+| Campo | Descripción |
+|:------|:------------|
+| `http_status` | Código HTTP (Integer). Antes `status`, renombrado en v0.6.0 |
+| `http_route` | Template de ruta (ej: `/users/:id`). Resolución via `route.defaults` |
+| `user_agent_original` | Header `User-Agent` del request |
+| `server_address` | Hostname sin puerto del header `Host` |
+| `exception.type` | Clase de la excepción (cuando el request falla) |
+| `exception.message` | Mensaje de la excepción |
+| `exception.stacktrace` | Primeras 20 líneas del backtrace |
+
 ### 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

@@ -40,6 +40,18 @@ module ExisRay
     #   @example 'MyLogSubscriber'
     attr_accessor :log_subscriber_class
 
+    # @!attribute [rw] service_version
+    #   @return [String, nil] Versión del servicio. Equivale a `service.version` de OTel.
+    #   Por defecto intenta leer `Rails.application.config.x.version` si Rails está disponible.
+    #   @example '1.2.3'
+    attr_accessor :service_version
+
+    # @!attribute [rw] deployment_environment
+    #   @return [String, nil] Entorno de despliegue. Equivale a `deployment.environment` de OTel.
+    #   Por defecto lee `Rails.env` si Rails está disponible.
+    #   @example 'production'
+    attr_accessor :deployment_environment
+
     # Inicializa la configuración con valores por defecto compatibles con AWS X-Ray.
     def initialize
       @trace_header = "HTTP_X_AMZN_TRACE_ID"
@@ -48,6 +60,39 @@ module ExisRay
       @current_class = "Current"
       @log_format = :text
       @log_subscriber_class = nil
+      @service_version = default_service_version
+      @deployment_environment = default_deployment_environment
+    end
+
+    # Lee la versión del servicio desde la configuración de Rails.
+    # Busca primero en `config.version` (atributo directo) y luego en `config.x.version`
+    # (custom config namespace). Retorna nil si ninguno está definido.
+    #
+    # @return [String, nil]
+    def default_service_version
+      return unless defined?(Rails) && Rails.application&.config
+
+      config = Rails.application.config
+
+      # Primero: config.version (atributo directo definido en Application)
+      version = config.version if config.respond_to?(:version)
+      return version.to_s if version.present?
+
+      # Fallback: config.x.version (custom config namespace)
+      if config.respond_to?(:x) && config.x.respond_to?(:version)
+        x_version = config.x.version
+        return x_version.to_s if x_version.present?
+      end
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def default_deployment_environment
+      return unless defined?(Rails) && Rails.respond_to?(:env)
+
+      Rails.env.to_s
     end
 
     # Indica si la aplicación está configurada para emitir logs en formato estructurado (JSON).

data/lib/exis_ray/json_formatter.rb

@@ -28,6 +28,16 @@ module ExisRay
     # Claves sensibles que deben filtrarse automáticamente según el estándar de Gabriel.
     SENSITIVE_KEYS = /password|pass|passwd|secret|token|api_key|auth/i
 
+    # Mapeo de severity_text OTel a SeverityNumber del Log Data Model.
+    # https://opentelemetry.io/docs/specs/otel/log/data-model/#field-severitynumber
+    SEVERITY_NUMBER = {
+      "DEBUG" => 5,
+      "INFO" => 9,
+      "WARN" => 13,
+      "ERROR" => 17,
+      "FATAL" => 21
+    }.freeze
+
     # Procesa un mensaje de log y lo formatea como una cadena estructurada en JSON.
     #
     # @param severity [String] El nivel de severidad del log (ej. "INFO", "ERROR", "DEBUG").
@@ -39,7 +49,10 @@ module ExisRay
       payload = {
         time: timestamp&.utc&.iso8601 || Time.now.utc.iso8601,
         level: severity,
-        service: ExisRay::Tracer.service_name
+        severity_number: SEVERITY_NUMBER[severity],
+        service: ExisRay::Tracer.service_name,
+        service_version: service_version,
+        deployment_environment: deployment_environment
       }
 
       inject_tracer_context(payload)
@@ -54,6 +67,16 @@ module ExisRay
 
     private
 
+    # @return [String, nil]
+    def service_version
+      ExisRay.configuration.service_version
+    end
+
+    # @return [String, nil]
+    def deployment_environment
+      ExisRay.configuration.deployment_environment
+    end
+
     # Genera un JSON de fallback cuando el formateo principal falla.
     # Nunca debe lanzar una excepción.
     #

data/lib/exis_ray/log_subscriber.rb

@@ -32,7 +32,7 @@ module ExisRay
     # @return [void]
     def process_action(event)
       payload = build_payload(event)
-      if payload[:status] && payload[:status] >= 500
+      if payload[:http_status] && payload[:http_status] >= 500
         logger.error(payload)
       else
         logger.info(payload)
@@ -90,25 +90,183 @@ module ExisRay
       view_s     = payload[:view_runtime] ? (payload[:view_runtime] / 1000.0).round(4) : nil
       db_s       = payload[:db_runtime] ? (payload[:db_runtime] / 1000.0).round(4) : nil
 
+      headers = payload[:headers] || {}
+
+      exception_data = extract_exception_data(payload)
+
       data = {
         component: "exis_ray",
         event: "http_request",
         method: payload[:method],
         path: payload[:path],
+        http_route: extract_http_route(payload),
         format: payload[:format],
         controller: payload[:controller],
         action: payload[:action],
-        status: status,
+        http_status: status,
         duration_s: duration_s,
         duration_human: ExisRay::Tracer.format_duration(duration_s),
         view_runtime_s: view_s,
-        db_runtime_s: db_s
+        db_runtime_s: db_s,
+        user_agent_original: headers["HTTP_USER_AGENT"],
+        server_address: extract_server_address(headers["HTTP_HOST"])
       }
 
+      data.merge!(exception_data)
       data.merge!(self.class.extra_fields(event))
       data.compact
     end
 
+    # Extrae el hostname del valor de HTTP_HOST, descartando el puerto si está presente.
+    # OTel `server.address` espera solo hostname; el puerto va en `server.port` por separado.
+    #
+    # @param http_host [String, nil] Valor del header HTTP_HOST (ej: "api.example.com:3000").
+    # @return [String, nil] Hostname sin puerto, o nil si http_host es nil.
+    def extract_server_address(http_host)
+      return nil unless http_host
+
+      http_host.split(":").first
+    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".
+    #
+    # 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.
+    def extract_exception_data(payload)
+      exception_info = payload[:exception]
+      return {} unless exception_info
+
+      exception_class = exception_info.first
+      exception_message = exception_info.last
+
+      data = {
+        error_class: exception_class,
+        error_message: exception_message,
+        "exception.type": exception_class,
+        "exception.message": exception_message
+      }
+
+      exception_object = payload[:exception_object]
+      if exception_object.respond_to?(:backtrace) && exception_object.backtrace
+        data[:"exception.stacktrace"] = exception_object.backtrace.take(20).join("\n")
+      end
+
+      data
+    rescue StandardError
+      {}
+    end
+
+    # Extrae la plantilla de ruta (http.route) de una URL concreta.
+    # OTel espera la ruta templated (ej: `/users/:id`) en lugar de la URL concreta
+    # (ej: `/users/42`), para bajar cardinalidad en dashboards.
+    #
+    # Estrategia en capas:
+    # 1. Rails 7.1+: `payload[:request].route_uri_pattern` si está presente.
+    # 2. Fallback: iterar `Rails.application.routes.routes` buscando el match por
+    #    `defaults[:controller]` + `defaults[:action]` + verb HTTP, y devolver el
+    #    pattern limpio de la primera ruta que matchee.
+    #
+    # @param payload [Hash] Payload del evento de Rails.
+    # @return [String, nil] Ruta plantilla o nil si no se puede resolver.
+    def extract_http_route(payload)
+      return nil unless defined?(Rails) && Rails.application&.routes
+
+      from_request = extract_from_route_uri_pattern(payload)
+      return from_request if from_request
+
+      controller = payload[:controller]
+      action = payload[:action]
+      method = payload[:method]
+      return nil unless controller && action && method
+
+      find_route_template(controller, action, method)
+    rescue StandardError
+      nil
+    end
+
+    # Rails 7.1+ expone `route_uri_pattern` en el request. Algunas versiones de
+    # `ActionController::Instrumentation` incluyen el request en el payload; si no,
+    # esta rama simplemente retorna nil y el caller cae al fallback.
+    #
+    # @param payload [Hash]
+    # @return [String, nil]
+    def extract_from_route_uri_pattern(payload)
+      request = payload[:request]
+      return nil unless request.respond_to?(:route_uri_pattern)
+
+      pattern = request.route_uri_pattern
+      clean_route_pattern(pattern.to_s) if pattern
+    rescue StandardError
+      nil
+    end
+
+    # Busca en la RouteSet de Rails la ruta que matchea controller + action + verb
+    # y devuelve su pattern template (ej: `/users/:id`).
+    #
+    # Rails guarda controller/action en `route.defaults`, no en `route.requirements`.
+    # El formato típico es `defaults[:controller] == "users"` (snake_case sin el sufijo
+    # `Controller`), mientras que `payload[:controller]` viene como `"UsersController"`.
+    #
+    # @param controller [String] Class name del controller (ej: "UsersController").
+    # @param action [String] Nombre del action (ej: "show").
+    # @param method [String] Método HTTP (ej: "GET").
+    # @return [String, nil] Pattern template o nil.
+    def find_route_template(controller, action, method)
+      normalized = controller.to_s.sub(/Controller$/, "").gsub("::", "/")
+      normalized = normalized.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                             .downcase
+      action_s = action.to_s
+      method_s = method.to_s.upcase
+
+      Rails.application.routes.routes.each do |route|
+        defaults = route.defaults
+        next unless defaults[:controller] == normalized
+        next unless defaults[:action].to_s == action_s
+        next unless route_matches_verb?(route, method_s)
+
+        return clean_route_pattern(route.path.spec.to_s)
+      end
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Verifica que el verb HTTP de la ruta matchee con el método del request.
+    # `route.verb` en Rails 5+ es un String (ej: "GET"); en versiones antes era un
+    # Regexp. Manejamos ambos y además el caso de rutas multi-verb (empty verb).
+    #
+    # @param route [ActionDispatch::Journey::Route]
+    # @param method [String] Método HTTP en mayúsculas.
+    # @return [Boolean]
+    def route_matches_verb?(route, method)
+      verb = route.verb
+      return true if verb.nil? || verb.to_s.empty?
+
+      if verb.is_a?(Regexp)
+        verb.match?(method)
+      else
+        verb.to_s.upcase == method
+      end
+    rescue StandardError
+      true
+    end
+
+    # Limpia el sufijo `(.:format)` típico de las rutas de Rails, que no es parte
+    # del template semántico que queremos emitir en el log.
+    #
+    # @param pattern [String] Pattern crudo de `route.path.spec.to_s`.
+    # @return [String]
+    def clean_route_pattern(pattern)
+      pattern.to_s.sub(/\(\.:format\)\z/, "")
+    end
+
     # Infiere el status HTTP desde el nombre de la excepción cuando el request
     # terminó con una excepción no rescatada (payload[:status] es nil).
     #

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} status=started")
+      log_event(:info, "component=exis_ray event=task_started task=#{task_name} outcome=started")
 
       # Bloque de ejecución con o sin tags dependiendo de la configuración
       execute_with_optional_tags(&block)
@@ -39,15 +39,17 @@ module ExisRay
 
       log_event(:info,
                 "component=exis_ray event=task_finished task=#{task_name} " \
-                "status=success duration_s=#{duration_s} duration_human=\"#{human_time}\"")
+                "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} " \
-                "status=failed duration_s=#{duration_s} duration_human=\"#{human_time}\" " \
-                "error_class=#{e.class} error_message=#{e.message.inspect}")
+                "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)}")
       raise e
     ensure
       # Limpieza centralizada obligatoria para evitar filtraciones de memoria o contexto
@@ -107,6 +109,22 @@ module ExisRay
     rescue StandardError
     end
 
-    private_class_method :pod_identifier, :setup_tracer, :execute_with_optional_tags, :log_event
+    # Formatea el backtrace para logging:
+    # - Limita a las primeras 20 líneas (evita líneas de MB)
+    # - Maneja nil backtrace (excepciones sin stacktrace)
+    #
+    # @param backtrace [Array<String>, nil]
+    # @return [String]
+    def self.format_stacktrace(backtrace)
+      return '""' unless backtrace
+
+      lines = backtrace.take(20).join("\n")
+      lines.inspect
+    rescue StandardError
+      '""'
+    end
+
+    private_class_method :pod_identifier, :setup_tracer, :execute_with_optional_tags,
+                         :log_event, :format_stacktrace
   end
 end

data/lib/exis_ray/version.rb

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

data/skill/SKILL.md

@@ -7,6 +7,8 @@ description: Skill de conocimiento completo sobre ExisRay, la capa de observabil
 
 Observabilidad y trazabilidad distribuida para microservicios Rails (AWS X-Ray compatible).
 
+Para el complemento del estándar de logging Wispro (regla Data First, mapeo OpenTelemetry, ciclo de vida de jobs/requests), ver `references/standard.md`.
+
 ---
 
 ## Glosario
@@ -69,8 +71,8 @@ ExisRay unifica trazabilidad distribuida, logging estructurado JSON, contexto de
 2. `Tracer.parse_trace_id` extrae `root_id`, `self_id`, `called_from`, `total_time_so_far`
 3. `ExisRay.sync_correlation_id` asigna `Tracer.correlation_id` a `Current.correlation_id`
 4. Controller ejecuta `before_action` para setear `Current.user_id`, `Current.isp_id`
-5. `JsonFormatter` intercepta cada `Rails.logger.*` e inyecta automaticamente: `time`, `level`, `service`, `root_id`, `trace_id`, `source`, `user_id`, `isp_id`, `correlation_id`
-6. `LogSubscriber` emite un unico Hash al finalizar el request (method, path, status, duration_s, etc.)
+5. `JsonFormatter` intercepta cada `Rails.logger.*` e inyecta automaticamente: `time`, `level`, `severity_number`, `service`, `service_version`, `deployment_environment`, `root_id`, `trace_id`, `source`, `user_id`, `isp_id`, `correlation_id`
+6. `LogSubscriber` emite un unico Hash al finalizar el request (method, path, http_status, http_route, duration_s, user_agent_original, server_address, etc.)
 7. En llamadas salientes, `FaradayMiddleware`/`ActiveResourceInstrumentation` inyectan `propagation_trace_header` con `Tracer.generate_trace_header`
 8. Al finalizar, `ActiveSupport::CurrentAttributes` hace reset automatico
 
@@ -88,6 +90,8 @@ ExisRay.configure do |config|
   config.reporter_class          = "Reporter"               # String, default "Reporter"
   config.log_format              = :json                    # Symbol, :text (default) | :json
   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
 end
 
 ExisRay.configuration.json_logs?  # => true si log_format == :json
@@ -199,7 +203,9 @@ Soporta Sentry moderno (`Sentry.capture_exception`) y legacy (`Session`/`Raven`)
 ExisRay::TaskMonitor.run("billing:generate_invoices") do
   InvoiceService.process_all
 end
-# Genera root_id propio, loguea task_started/task_finished con duration_s.
+# 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).
 # Re-lanza excepciones despues de loguearlas.
 # Hace reset de Tracer, Current y Reporter en ensure.
 ```