exis_ray 0.5.11 → 0.7.0

data/skill/references/standard.md

@@ -0,0 +1,155 @@
+# Estándar de Logging Wispro — Complemento
+
+> Este documento recoge las reglas del estándar de logging del ecosistema Wispro que **no** están ya cubiertas en `SKILL.md`. Para formato general (`component=x event=y`), niveles, `source`, DEBUG block form, reloj monotónico, filtrado de claves sensibles y campos auto-inyectados, ver `SKILL.md`.
+
+---
+
+## Data First — Unidad en la key, número en el valor
+
+Regla de oro para métricas operables: **separar la unidad del dato numérico**. Nunca incluir unidades dentro de los valores.
+
+```
+# Incorrecto
+duration="0.5s"   memory="128MB"
+
+# Correcto
+duration_s=0.5    memory_mb=128
+```
+
+Sufijos de unidad estándar:
+
+| Sufijo   | Tipo    | Uso |
+|:---------|:--------|:----|
+| `_s`     | Float   | Segundos. Estándar para duraciones y latencias. |
+| `_ms`    | Integer | Milisegundos. Precisión técnica interna de alta frecuencia. |
+| `_count` | Integer | Cantidades o volúmenes. Ej: `record_count`, `retry_count`. |
+| `_bytes` / `_kb` / `_mb` | Integer | Almacenamiento o memoria. |
+| `_human` | String  | (Opcional) Texto legible. Ej: `duration_human="2 minutes 5 seconds"`. |
+
+Los valores numéricos se emiten como números reales (sin comillas) para que el motor de logs haga casting automático.
+
+---
+
+## Alineación con OpenTelemetry
+
+`ExisRay` sigue el **OpenTelemetry Log Data Model**. Los campos del estándar Wispro se mapean a las convenciones semánticas oficiales de OTel:
+
+| Campo Wispro  | OTel Semantic Convention       | Descripción |
+|:--------------|:--------------------------------|:------------|
+| `body`        | `body`                         | Contenido principal del log (texto libre). |
+| `level`       | `severity_text`                | Nivel de importancia. |
+| `http_status` | `http.response.status_code`    | Código de respuesta HTTP (Integer). |
+| `outcome`     | `otel.status_code` (enum)      | Resultado semántico de tasks/jobs (`success`/`failed`). |
+| `method`      | `http.request.method`          | Método HTTP. |
+| `path`        | `url.path`                     | Ruta del request. |
+| `user_id`     | `user.id`                      | Identificador del usuario. |
+
+> **Nota sobre `duration_s`**: OTel no define un atributo genérico `duration`. Las duraciones se expresan implícitamente en spans (diferencia entre `start_time` y `end_time`), o en métricas específicas como `http.server.request.duration` (histograma en segundos, según la convención de métricas). En logs Wispro, `duration_s` es una **extensión propia** que permite queries directas sin contexto de span.
+
+Para campos nuevos, seguir las OpenTelemetry Semantic Conventions siempre que exista una equivalencia oficial.
+
+### Naming de campos OTel en formato flat
+
+ExisRay emite JSON flat (ver divergencia D2 más abajo). Al mapear campos OTel al formato flat, aplicar estas reglas:
+
+1. **Dots → underscores**: `messaging.system` → `messaging_system`, `exception.type` → `exception.type` (excepción: los campos `exception.*` mantienen el dot por estar en transición OTel).
+2. **Preservar el prefijo semántico**: nunca abreviar el namespace OTel. `messaging.system` se convierte en `messaging_system`, **no** en `system`. El prefijo evita colisiones con otros campos del log (ej: `source: "system"` ya existe en ExisRay).
+3. **Sufijo de unidad donde aplique**: si el campo OTel tiene unidad implícita, agregar el sufijo Wispro (`_s`, `_ms`, `_bytes`). Ej: `http.server.request.duration` → `duration_s`.
+
+Ejemplos de mapeo existente:
+
+| OTel Semantic Convention | Campo flat ExisRay |
+|:-------------------------|:-------------------|
+| `http.response.status_code` | `http_status` |
+| `user_agent.original` | `user_agent_original` |
+| `server.address` | `server_address` |
+| `service.version` | `service_version` |
+| `deployment.environment` | `deployment_environment` |
+| `exception.type` | `exception.type` (en transición) |
+| `messaging.system` | `messaging_system` |
+| `messaging.operation` | `messaging_operation` |
+| `messaging.destination.name` | `messaging_destination_name` |
+| `messaging.message.id` | `messaging_message_id` |
+| `messaging.rabbitmq.destination.routing_key` | `messaging_routing_key` |
+
+**Regla de oro**: si al leer el campo aislado de su contexto no queda claro a qué dominio pertenece (ej: `system`, `operation`, `id`, `name`), le falta el prefijo.
+
+---
+
+## Divergencias deliberadas con OpenTelemetry
+
+ExisRay no pretende ser una implementación OTel. Las siguientes divergencias son decisiones conscientes con razones de peso:
+
+### Wire format AWS X-Ray, no W3C Trace Context
+
+OTel usa `traceparent: 00-<trace-id>-<parent-id>-<flags>`. ExisRay usa `X-Amzn-Trace-Id: Root=1-...;Self=...`.
+
+**Razón**: toda la infraestructura Wispro vive en AWS con X-Ray como backend de trazas. Si en el futuro se migra a un backend OTel-native, la traducción ocurrirá solo en el edge (HTTP middleware), sin tocar el core.
+
+### Flat JSON, no resource/attributes anidado
+
+OTel Log Data Model anida: `{"Resource": {...}, "Attributes": {...}, "Body": "..."}`. ExisRay emite flat: `{"service": "...", "component": "...", ...}`.
+
+**Razón**: los agregadores comunes (CloudWatch, Loki, Datadog) indexan mejor JSON flat. Queries como `component:auth AND event:login_failed` son triviales en flat. Un exporter OTel futuro haría el unflatten al emitir.
+
+### Sufijos de unidad en keys (`_s`, `_ms`, `_bytes`)
+
+OTel usa unit metadata UCUM o nombres sin sufijo. ExisRay usa sufijos explícitos.
+
+**Razón**: en JSON flat, un campo llamado `duration` sin unidad es ambiguo. El sufijo hace que el consumidor humano y el parser automático sepan la unidad sin metadata externa (regla "Data First" Wispro).
+
+### Campo `source` (http/sidekiq/task/system)
+
+No tiene equivalente OTel directo. Lo más parecido es `span.kind`, pero mide otra cosa.
+
+**Razón**: es el campo más útil para filtrado operacional — saber si un error viene de una request HTTP, un job o un consumer es la primera pregunta al mirar logs. Es una **extensión Wispro**.
+
+### Campo `component`
+
+OTel lo más parecido es `instrumentation.scope.name`. ExisRay lo usa para identificar el módulo de negocio (`component=billing`, `component=auth`).
+
+**Razón**: `component` es dominio-específico y útil para filtrado operacional. Convive sin conflicto con `instrumentation.scope.name` si en el futuro se agrega el emisor técnico.
+
+---
+
+## Ciclo de Vida del Evento
+
+### Procesos, Jobs y Tasks
+
+Todo proceso aislado debe reportar inicio y finalización con estructura consistente:
+
+- `event`: identificador de estado (`task_started`, `task_finished`, `job_started`, `job_finished`).
+- `outcome`: resultado final como **string semántico**, nunca un código numérico: `success`, `failed`, `aborted`.
+- `duration_s`: tiempo total de ejecución (reloj monotónico).
+- `error_class` y `error_message`: **obligatorios solo en caso de fallo**.
+
+```ruby
+start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+begin
+  InvoiceService.process_all
+  duration_s = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+  Rails.logger.info("component=billing event=task_finished outcome=success duration_s=#{duration_s} record_count=500")
+rescue => e
+  duration_s = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+  Rails.logger.error("component=billing event=task_finished outcome=failed duration_s=#{duration_s} error_class=#{e.class} error_message=\"#{e.message}\"")
+  raise
+end
+```
+
+`ExisRay::TaskMonitor` implementa exactamente este contrato para Rake/Cron.
+
+### Peticiones HTTP
+
+Los logs de cierre de request estandarizan el reporte de rendimiento:
+
+- `http_status`: **código HTTP como Integer** (ej: `200`, `404`, `500`).
+- `duration_s`: tiempo total de respuesta del servidor.
+- `[subsystem]_runtime_s`: desglose opcional por capa (`db_runtime_s`, `view_runtime_s`).
+
+`ExisRay::LogSubscriber` emite este shape automáticamente — no hace falta loguearlo manualmente.
+
+---
+
+## Regla de Oro
+
+> Tu log manual solo debe contener datos de **tu lógica de negocio**. La infraestructura (ExisRay) ya sabe quién sos, de dónde venís y cuál es tu ID de traza — no dupliques esos campos en los logs manuales.

data/skills.lock

@@ -1,6 +1,9 @@
 ---
-synced_at: '2026-04-04 19:02:47'
+synced_at: '2026-04-05 18:20:39'
 skills:
+- name: action-plan
+  scope: local
+  path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/action-plan"
 - name: agent-review
   scope: local
   path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/agent-review"
@@ -10,9 +13,15 @@ skills:
 - name: documentation-writer
   scope: local
   path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/documentation-writer"
+- name: find-skills
+  scope: local
+  path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/find-skills"
 - name: gem-release
   scope: local
   path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/gem-release"
+- name: opentelemetry
+  scope: local
+  path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/opentelemetry"
 - name: quality-code
   scope: local
   path: "/Users/gabriel/src/gems/exis_ray/.agents/skills/quality-code"

data/skills.yml

@@ -2,23 +2,48 @@ mcps:
   - github
   - clickup
 skills:
-  - name: skill-manager
+  skill-manager:
     repo: sequre/ai_knowledge
-  - name: yard
+    scope: local
+  yard:
     repo: sequre/ai_knowledge
-  - name: quality-code
+    scope: local
+  quality-code:
     repo: sequre/ai_knowledge
-  - name: gem-release
+    scope: local
+  gem-release:
     repo: sequre/ai_knowledge
-  - name: skill-builder
+    scope: local
+  skill-builder:
     repo: sequre/ai_knowledge
-  - name: ai-reports
+    scope: local
+  ai-reports:
     repo: sequre/ai_knowledge
-  - name: agent-review
+    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:
     repo: sequre/ai_knowledge
-  - name: documentation-writer
+    scope: local
+    environment:
+      space_id: "${AGENT_REVIEW_SAPCE_ID}"
+      list_id: "${AGENT_LIST_ID}"
+  action-plan:
+    repo: sequre/ai_knowledge
+    environment:
+      space_id: "${AGENT_REVIEW_SAPCE_ID}"
+      list_id: "${AGENT_ACTION_PLAN_LIST_ID}"
+  documentation-writer:
     repo: github/awesome-copilot
     path: skills/documentation-writer
-  - name: find-skills
+    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

@@ -14,12 +14,12 @@ RSpec.describe ExisRay::Configuration do
       expect(config.propagation_trace_header).to eq("X-Amzn-Trace-Id")
     end
 
-    it "reporter_class por defecto es Reporter" do
-      expect(config.reporter_class).to eq("Reporter")
+    it "reporter_class por defecto es nil" do
+      expect(config.reporter_class).to be_nil
     end
 
-    it "current_class por defecto es Current" do
-      expect(config.current_class).to eq("Current")
+    it "current_class por defecto es nil" do
+      expect(config.current_class).to be_nil
     end
 
     it "log_format por defecto es :text" do
@@ -29,6 +29,75 @@ RSpec.describe ExisRay::Configuration do
     it "log_subscriber_class por defecto es nil" do
       expect(config.log_subscriber_class).to be_nil
     end
+
+    it "service_version por defecto es nil fuera de Rails" do
+      expect(config.service_version).to be_nil
+    end
+
+    it "deployment_environment por defecto es nil fuera de Rails" do
+      expect(config.deployment_environment).to be_nil
+    end
+  end
+
+  describe "resource attributes OTel" do
+    it "permite setear service_version" do
+      config = described_class.new
+      config.service_version = "2.0.0"
+
+      expect(config.service_version).to eq("2.0.0")
+    end
+
+    it "permite setear deployment_environment" do
+      config = described_class.new
+      config.deployment_environment = "staging"
+
+      expect(config.deployment_environment).to eq("staging")
+    end
+
+    describe "#default_service_version" do
+      it "retorna nil cuando Rails no está definido" do
+        expect(described_class.new.default_service_version).to be_nil
+      end
+
+      it "lee config.version (atributo directo) con prioridad sobre config.x.version" do
+        rails_config = Struct.new(:version).new("1.2.3")
+        allow(rails_config).to receive(:respond_to?).and_call_original
+        app = Struct.new(:config).new(rails_config)
+        stub_const("Rails", Class.new do
+          define_singleton_method(:application) { app }
+        end)
+
+        expect(described_class.new.default_service_version).to eq("1.2.3")
+      end
+
+      it "cae a config.x.version si config.version no está definido" do
+        x_config = Struct.new(:version).new("3.0.0")
+        rails_config = Struct.new(:x).new(x_config)
+        app = Struct.new(:config).new(rails_config)
+        stub_const("Rails", Class.new do
+          define_singleton_method(:application) { app }
+        end)
+
+        expect(described_class.new.default_service_version).to eq("3.0.0")
+      end
+
+      it "retorna nil si config.x.version es un OrderedOptions vacío (no un string)" do
+        x_config = ActiveSupport::OrderedOptions.new
+        rails_config = Struct.new(:x).new(x_config)
+        app = Struct.new(:config).new(rails_config)
+        stub_const("Rails", Class.new do
+          define_singleton_method(:application) { app }
+        end)
+
+        expect(described_class.new.default_service_version).to be_nil
+      end
+    end
+
+    describe "#default_deployment_environment" do
+      it "retorna nil cuando Rails no está definido" do
+        expect(described_class.new.default_deployment_environment).to be_nil
+      end
+    end
   end
 
   describe "#json_logs?" do

data/spec/exis_ray/json_formatter_spec.rb

@@ -141,6 +141,78 @@ RSpec.describe ExisRay::JsonFormatter do
       end
     end
 
+    describe "severity_number (OTel Log Data Model)" do
+      it "inyecta severity_number=9 para INFO" do
+        result = JSON.parse(formatter.call("INFO", timestamp, progname, "event=x"))
+
+        expect(result["severity_number"]).to eq(9)
+      end
+
+      it "inyecta severity_number=13 para WARN" do
+        result = JSON.parse(formatter.call("WARN", timestamp, progname, "event=x"))
+
+        expect(result["severity_number"]).to eq(13)
+      end
+
+      it "inyecta severity_number=17 para ERROR" do
+        result = JSON.parse(formatter.call("ERROR", timestamp, progname, "event=x"))
+
+        expect(result["severity_number"]).to eq(17)
+      end
+
+      it "inyecta severity_number=5 para DEBUG" do
+        result = JSON.parse(formatter.call("DEBUG", timestamp, progname, "event=x"))
+
+        expect(result["severity_number"]).to eq(5)
+      end
+
+      it "inyecta severity_number=21 para FATAL" do
+        result = JSON.parse(formatter.call("FATAL", timestamp, progname, "event=x"))
+
+        expect(result["severity_number"]).to eq(21)
+      end
+
+      it "omite severity_number para niveles no estándar" do
+        result = JSON.parse(formatter.call("CUSTOM", timestamp, progname, "event=x"))
+
+        expect(result).not_to have_key("severity_number")
+      end
+    end
+
+    describe "resource attributes OTel (service_version, deployment_environment)" do
+      it "inyecta service_version cuando Configuration lo provee" do
+        allow(ExisRay.configuration).to receive_messages(service_version: "1.2.3", deployment_environment: nil)
+
+        result = call("event=boot")
+
+        expect(result["service_version"]).to eq("1.2.3")
+      end
+
+      it "inyecta deployment_environment cuando Configuration lo provee" do
+        allow(ExisRay.configuration).to receive_messages(service_version: nil, deployment_environment: "production")
+
+        result = call("event=boot")
+
+        expect(result["deployment_environment"]).to eq("production")
+      end
+
+      it "omite service_version cuando es nil" do
+        allow(ExisRay.configuration).to receive_messages(service_version: nil, deployment_environment: "test")
+
+        result = call("event=boot")
+
+        expect(result).not_to have_key("service_version")
+      end
+
+      it "omite deployment_environment cuando es nil" do
+        allow(ExisRay.configuration).to receive_messages(service_version: "1.0", deployment_environment: nil)
+
+        result = call("event=boot")
+
+        expect(result).not_to have_key("deployment_environment")
+      end
+    end
+
     describe "inyeccion de contexto de negocio" do
       let(:current_mock) do
         Class.new do