data_drain 0.1.15 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5a97927218d94763cdead9362a4a0a0a40fe4a1b8b327f0f074117a66a10a46
-  data.tar.gz: a5f28048457a43d86942472b36946955e0aa88c9d75cb85158d27f44c986aec2
+  metadata.gz: c3b2ce171059217fbb96cf1d1f93e9bce121b31e0afdf73eaa3889d5dca38d5c
+  data.tar.gz: 14600532ba59fd8daf0ec7e1890175211402172d643481539980da8f54799f9b
 SHA512:
-  metadata.gz: 5f538227b8eda210214fa448ede9f3247fa73bf997a2cfb04ca0a1b37c81b096198ad250b4e3dcf2f902a4f54eee16cb69233e68e03d65aca68c6bf497de72e4
-  data.tar.gz: 93f7b591e556713614c0310415301787605cf3cefc26718e94b74ee1ab60cec17ffaeaaec3d7b8ce5bb31deb40a51b1007d60bd9cdcba1211e4a8e06f1079293
+  metadata.gz: d08d3a7391a2b1ec4ab4b5e9c6f3d894bd5a8d1f46cc1d93f4324559f7a92e9a4150e689f3ca990afecdf33817cbfd3259f9c6bd7162040742ad2fdda3ae3661
+  data.tar.gz: 863f1be6a3e391fe32c63b88a2d944443159d984fbf74f598dba58cbc44ffd8c4a5dc14cafcede6182c620d8b8580f9bec2225d298e75c50215766a87b56cb4a

data/CHANGELOG.md

@@ -1,6 +1,32 @@
 ## [Unreleased]
 
-## [0.1.15] - 2026-03-23
+## [0.1.19] - 2026-03-30
+
+- Fix: `Record.build_query_path` ahora usa `partition_keys` como fuente de verdad del orden, ignorando el orden de los kwargs del caller. Antes, pasar `where(year: 2026, isp_id: 42)` en distinto orden generaba un path que no coincidía con la estructura Hive en disco.
+- Fix: `GlueRunner` reemplaza `.truncate(200)` de ActiveSupport por `[0, 200]` de Ruby puro, eliminando la dependencia implícita.
+- Convention: orden canónico de `partition_keys` es `[dimension_principal, year, month]` (ej. `isp_id` primero). Documentado en CLAUDE.md y actualizado en README, specs y ejemplos de PySpark.
+- Docs: README actualizado con ejemplos de producción correctos para Glue + Engine + Record.
+
+## [0.1.18] - 2026-03-23
+
+- Feature: Módulo `Observability` centraliza el logging estructurado en toda la gema.
+- Feature: Heartbeat de progreso para purgas masivas (`engine.purge_heartbeat`).
+- Telemetry: Separación de contexto de error (`error_class`, `error_message`) en todos los eventos de falla.
+- Resilience: Los fallos en el sistema de logs nunca interrumpen el flujo principal de datos.
+
+## [0.1.17] - 2026-03-17
+
+- Feature: Telemetría granular por fases (Ingeniería de Performance).
+- Telemetry: Inclusión de métricas específicas como \`db_query_duration_s\`, \`export_duration_s\`, \`integrity_duration_s\` y \`purge_duration_s\` en el evento \`engine.complete\`.
+- Telemetry: Inclusión de \`source_query_duration_s\` y \`export_duration_s\` en \`file_ingestor.complete\`.
+
+## [0.1.16] - 2026-03-17
+
+- Refactor: Cumplimiento con el estándar **Wispro-Observability-Spec (v1)**.
+- Telemetry: Renombrado de métricas de tiempo a \`duration_s\` y \`next_check_in_s\` eliminando sufijos de unidad en los valores.
+- Observability: Garantía de valores numéricos puros para contadores y tiempos, facilitando el procesamiento por \`exis_ray\`.
+
+## [0.1.15] - 2026-03-17
 
 - Performance: Medición de duraciones con reloj monotónico (`Process.clock_gettime`) en eventos terminales de `Engine`, `FileIngestor` y `GlueRunner`.
 - Fix: `idle_in_transaction_session_timeout` ahora se aplica correctamente cuando el valor es `0` (desactiva el timeout). Antes `0.present?` evaluaba a `false` y se ignoraba.

data/CLAUDE.md

@@ -19,22 +19,43 @@ created_at >= 'START' AND created_at < 'END_BOUNDARY'
 ```
 Donde `END_BOUNDARY` es el inicio del periodo siguiente (ej. `next_day.beginning_of_day`). Nunca usar `<= end_of_day` — los microsegundos en el límite pueden quedar fuera.
 
+### Partition Keys — Orden y Contrato
+
+El array `partition_keys` es **completamente dinámico** — cada tabla/modelo define el suyo. No existe un orden estándar en la librería.
+
+**Regla crítica:** el orden de `partition_keys` al **escribir** (Engine/FileIngestor) debe ser idéntico al declarado en el modelo **Record** que lee esos archivos. Un mismatch genera paths que no coinciden y DuckDB retorna vacío sin error.
+
+```ruby
+# Escritura
+Engine.new(partition_keys: %w[isp_id year month], ...)
+
+# Lectura — debe coincidir
+class ArchivedVersion < DataDrain::Record
+  self.partition_keys = [:isp_id, :year, :month]
+end
+```
+
+**Criterio de diseño del orden:** el primer key debe ser la dimensión de mayor cardinalidad o la que más se usa como filtro (ej. `isp_id` si las consultas son siempre por ISP). Esto determina la jerarquía de carpetas Hive y el rendimiento del prefix scan en S3.
+
 ### Idempotencia
 Las exportaciones usan `OVERWRITE_OR_IGNORE 1` de DuckDB. Los procesos son seguros de reintentar.
 
 ### `idle_in_transaction_session_timeout`
 El valor `0` **desactiva** el timeout (sin límite). Para purgas de gran volumen esto es mandatorio. Internamente, se debe validar con `!nil?` ya que `0.present?` es falso.
 
-## Logging
+## Logging (Wispro-Observability-Spec v1)
 
-Seguir los estándares globales definidos en `~/.claude/CLAUDE.md`. Reglas específicas de este proyecto:
+La telemetría debe ser estructurada (KV) para ser procesada por `exis_ray`.
 
-- Formato obligatorio: `component=data_drain event=<clase>.<suceso> [campos]`
-- El campo `source` lo inyecta automáticamente `exis_ray` vía `ExisRay::Tracer` — DataDrain no debe incluirlo ni recibirlo como parámetro
-- Nunca logs puramente descriptivos, con emojis ni con prefijos entre corchetes
-- DEBUG siempre en forma de bloque: `logger.debug { "k=#{v}" }`
-- Duraciones con reloj monotónico: `Process.clock_gettime(Process::CLOCK_MONOTONIC)`
-- Filtrar datos sensibles (`password`, `token`, `secret`, `api_key`, `auth`) → `[FILTERED]`
+- **Formato:** `component=data_drain event=<clase>.<suceso> [campos]`
+- **Unidades:** Prohibido incluir unidades en los valores (ej: NO usar "0.5s").
+- **Tiempos:** Usar el sufijo `_s` en la key y valor `Float`. Ej: `duration_s=0.57`.
+- **Contadores:** Usar la palabra `count` en la key y valor `Integer`. Ej: `pg_count=100`.
+- **Naming:** Todas las llaves deben ser `snake_case`.
+- **Automatización:** El campo `source` lo inyecta automáticamente `exis_ray` — no incluirlo manualmente.
+- **DEBUG:** Siempre en forma de bloque: `logger.debug { "k=#{v}" }`.
+- **Duraciones:** Usar siempre `Process.clock_gettime(Process::CLOCK_MONOTONIC)`.
+- **Sensibilidad:** Filtrar datos sensibles (`password`, `token`, `secret`) → `[FILTERED]`.
 
 ## Código Ruby
 

data/README.md

@@ -1,4 +1,4 @@
-# DataDrain 🚰
+# DataDrain
 
 DataDrain es un micro-framework de nivel empresarial diseñado para extraer, archivar y purgar datos históricos desde bases de datos PostgreSQL transaccionales, así como para **ingerir archivos crudos (CSV, JSON, Parquet)**, hacia un Data Lake analítico.
 
@@ -12,13 +12,14 @@ Utiliza **DuckDB** en memoria para lograr velocidades de procesamiento y compres
 * **Storage Adapters:** Soporte nativo y transparente para almacenamiento en Disco Local y AWS S3.
 * **Integridad Garantizada:** Verifica matemáticamente que los datos exportados coincidan exactamente con el origen antes de ejecutar sentencias `DELETE`.
 * **ORM Analítico Integrado:** Incluye una clase base (`DataDrain::Record`) compatible con `ActiveModel` para consultar y destruir particiones históricas de forma idiomática.
+* **Observabilidad Estructurada:** Todos los eventos emiten logs en formato `key=value` compatibles con Datadog, CloudWatch y `exis_ray`. Los fallos de logging nunca interrumpen el flujo principal.
 
 ## Instalación
 
 Agrega esta línea al `Gemfile` de tu aplicación o microservicio:
 
 ```ruby
-gem 'data_drain', git: '[https://github.com/tu-organizacion/data_drain.git](https://github.com/tu-organizacion/data_drain.git)', branch: 'main'
+gem 'data_drain', git: 'https://github.com/gedera/data_drain.git', branch: 'main'
 ```
 
 Y ejecuta:
@@ -50,47 +51,42 @@ DataDrain.configure do |config|
   # Rendimiento y Tuning de Postgres
   config.batch_size     = 5000 # Registros a borrar por transacción
   config.throttle_delay = 0.5  # Segundos de pausa entre borrados
-  
+
   # Timeout de inactividad de transacciones en PostgreSQL (en milisegundos).
-  # Útil establecerlo en 0 para evitar que la conexión se cierre prematuramente 
-  # durante el borrado de grandes volúmenes de datos.
+  # El valor 0 DESACTIVA el timeout (sin límite de tiempo).
+  # Mandatorio para purgas de gran volumen donde cada lote puede tardar segundos.
   config.idle_in_transaction_session_timeout = 0
-  
-  config.logger         = Rails.logger
+
+  config.logger = Rails.logger
 
   # Tuning de DuckDB
   # Límite máximo de RAM para las consultas en memoria de DuckDB (ej. '2GB', '512MB').
-  # Evita que el proceso OOM (Out Of Memory) si el contenedor o servidor tiene memoria limitada.
-  config.limit_ram      = '2GB'
-  
+  # Evita que el proceso muera por OOM en contenedores con memoria limitada.
+  config.limit_ram = '2GB'
+
   # Directorio temporal de DuckDB para desbordar memoria (spill to disk) durante
   # transformaciones pesadas o creación de archivos Parquet masivos.
-  # Es muy recomendable que este directorio resida en un disco SSD/NVMe rápido.
-  config.tmp_directory  = '/tmp/duckdb_work'
+  # Se recomienda que este directorio resida en un disco SSD/NVMe rápido.
+  config.tmp_directory = '/tmp/duckdb_work'
 end
 ```
 
 ## Uso
 
-El framework provee tres herramientas principales: **Ingestor de Archivos**, **Drenaje de Base de Datos**, y el **ORM Analítico**.
+El framework provee cuatro herramientas principales: **Ingestor de Archivos**, **Drenaje de Base de Datos**, **ORM Analítico** y **Orquestación con AWS Glue**.
 
 ### 1. Ingestión de Archivos Crudos (FileIngestor)
 
 Ideal para servicios que generan grandes volúmenes de datos (ej. métricas de Netflow). Toma un archivo local, lo transforma, lo comprime a Parquet y lo sube particionado a S3.
 
 ```ruby
-# Un archivo generado temporalmente por tu servicio
-archivo_temporal = "/tmp/netflow_metrics_1600.csv"
-
 ingestor = DataDrain::FileIngestor.new(
-  bucket: 'my-bucket-store',
-  source_path: archivo_temporal,
-  folder_name: 'netflow',
-  # Particionamos dinámicamente según columnas extraídas al vuelo
-  partition_keys: %w[year month isp_id],
-  # Transformación SQL ejecutada por DuckDB durante la lectura
-  select_sql: "*, EXTRACT(YEAR FROM timestamp) AS year, EXTRACT(MONTH FROM timestamp) AS month",
-  delete_after_upload: true # Limpia el archivo temporal al terminar
+  bucket:              'my-bucket-store',
+  source_path:         '/tmp/netflow_metrics_1600.csv',
+  folder_name:         'netflow',
+  partition_keys:      %w[isp_id year month],
+  select_sql:          "*, EXTRACT(YEAR FROM timestamp) AS year, EXTRACT(MONTH FROM timestamp) AS month",
+  delete_after_upload: true
 )
 
 ingestor.call
@@ -98,25 +94,37 @@ ingestor.call
 
 ### 2. Extracción y Purga de BD (Engine)
 
-Ideal para crear Ventanas Rodantes de retención (ej. mantener solo 6 meses de datos vivos en Postgres y archivar el resto). 
+Ideal para crear ventanas rodantes de retención (ej. mantener solo 6 meses de datos vivos en Postgres y archivar el resto).
 
-**Modo Purga con Exportación Externa (AWS Glue):** 
-Si tu arquitectura ya utiliza **AWS Glue** o **AWS EMR** para mover datos pesados, puedes configurar DataDrain para que actúe únicamente como **Garante de Integridad**. En este modo, el motor omitirá el paso de exportación, pero verificará matemáticamente que los datos existan en el Data Lake antes de proceder a eliminarlos de PostgreSQL.
+**Flujo completo (Export + Verify + Purge):**
 
 ```ruby
-# lib/tasks/archive_with_glue.rake
-task purge_only: :environment do
-  engine = DataDrain::Engine.new(
-    bucket:         'my-bucket-store',
-    start_date:     6.months.ago.beginning_of_month,
-    end_date:       6.months.ago.end_of_month,
-    table_name:     'versions',
-    partition_keys: %w[year month],
-    skip_export:    true # ⚡️ No exporta nada, solo valida S3 y purga Postgres
-  )
-
-  engine.call
-end
+engine = DataDrain::Engine.new(
+  bucket:         'my-bucket-store',
+  start_date:     6.months.ago.beginning_of_month,
+  end_date:       6.months.ago.end_of_month,
+  table_name:     'versions',
+  partition_keys: %w[year month]
+)
+
+engine.call
+```
+
+**Modo Purga con Exportación Externa (skip_export):**
+
+Si tu arquitectura ya utiliza **AWS Glue** o **AWS EMR** para mover datos pesados, puedes configurar DataDrain para que actúe únicamente como garante de integridad. En este modo omite la exportación pero verifica matemáticamente que los datos existan en el Data Lake antes de eliminarlos de PostgreSQL.
+
+```ruby
+engine = DataDrain::Engine.new(
+  bucket:         'my-bucket-store',
+  start_date:     6.months.ago.beginning_of_month,
+  end_date:       6.months.ago.end_of_month,
+  table_name:     'versions',
+  partition_keys: %w[year month],
+  skip_export:    true
+)
+
+engine.call
 ```
 
 ### 3. Orquestación con AWS Glue (Big Data)
@@ -124,23 +132,23 @@ end
 Para tablas de gran volumen (**ej. > 500GB o 1TB**), se recomienda delegar el movimiento de datos a **AWS Glue** (basado en Apache Spark) para evitar saturar el servidor de Ruby. `DataDrain` actúa como el orquestador que dispara el Job, espera a que termine y luego realiza la validación y purga.
 
 ```ruby
-# 1. Disparar el Job de Glue y esperar su finalización exitosa
 config = DataDrain.configuration
 bucket = "my-bucket"
 table  = "versions"
 
+# 1. Disparar el Job de Glue y esperar su finalización exitosa
 DataDrain::GlueRunner.run_and_wait(
   "my-glue-export-job",
   {
-    "--start_date"    => start_date.to_fs(:db),
-    "--end_date"      => end_date.to_fs(:db),
-    "--s3_bucket"     => bucket,
-    "--s3_folder"     => table,
-    "--db_url"        => "jdbc:postgresql://#{config.db_host}:#{config.db_port}/#{config.db_name}",
-    "--db_user"       => config.db_user,
-    "--db_password"   => config.db_pass,
-    "--db_table"      => table,
-    "--partition_by"  => "year,month,isp_id" # <--- Columnas dinámicas
+    "--start_date"   => start_date.to_fs(:db),
+    "--end_date"     => end_date.to_fs(:db),
+    "--s3_bucket"    => bucket,
+    "--s3_folder"    => table,
+    "--db_url"       => "jdbc:postgresql://#{config.db_host}:#{config.db_port}/#{config.db_name}",
+    "--db_user"      => config.db_user,
+    "--db_password"  => config.db_pass,
+    "--db_table"     => table,
+    "--partition_by" => "isp_id,year,month"
   }
 )
 
@@ -151,14 +159,14 @@ DataDrain::Engine.new(
   start_date:     start_date,
   end_date:       end_date,
   table_name:     table,
-  partition_keys: %w[year month isp_id],
-  skip_export:    true # <--- Modo Validación + Purga
+  partition_keys: %w[isp_id year month],
+  skip_export:    true
 ).call
 ```
 
 #### Script de AWS Glue (PySpark) compatible con DataDrain
 
-Crea un Job en la consola de AWS Glue (Spark 4.0+) y utiliza este script como base. Está diseñado para extraer datos de PostgreSQL de forma dinámica:
+Crea un Job en la consola de AWS Glue (Spark 4.0+) y utiliza este script como base:
 
 ```python
 import sys
@@ -168,7 +176,6 @@ from awsglue.context import GlueContext
 from awsglue.job import Job
 from pyspark.sql.functions import col, year, month
 
-# Parámetros recibidos desde DataDrain::GlueRunner
 args = getResolvedOptions(sys.argv, [
     'JOB_NAME', 'start_date', 'end_date', 's3_bucket', 's3_folder',
     'db_url', 'db_user', 'db_password', 'db_table', 'partition_by'
@@ -180,7 +187,6 @@ spark = glueContext.spark_session
 job = Job(glueContext)
 job.init(args['JOB_NAME'], args)
 
-# 1. Leer de PostgreSQL (vía JDBC dinámico)
 options = {
     "url": args['db_url'],
     "dbtable": args['db_table'],
@@ -191,12 +197,12 @@ options = {
 
 df = spark.read.format("jdbc").options(**options).load()
 
-# 2. Agregar columnas de partición temporales (Hive Partitioning)
+# Agregar columnas derivadas necesarias para las particiones.
+# isp_id ya existe en la tabla fuente — solo agregar las que se calculan.
+# Personalizar esta sección según las partition_keys de cada tabla.
 df_final = df.withColumn("year", year(col("created_at"))) \
              .withColumn("month", month(col("created_at")))
 
-# 3. Escribir a S3 en Parquet con compresión ZSTD
-# Construimos el path dinámicamente: s3://bucket/folder/
 output_path = f"s3://{args['s3_bucket']}/{args['s3_folder']}/"
 partitions = args['partition_by'].split(",")
 
@@ -216,40 +222,38 @@ Para consultar los datos archivados sin salir de Ruby, crea un modelo que herede
 ```ruby
 # app/models/archived_version.rb
 class ArchivedVersion < DataDrain::Record
-  self.bucket = 'my-bucket-storage'
-  self.folder_name = 'versions'
-  self.partition_keys = [:year, :month, :isp_id]
-
-  attribute :id, :string
-  attribute :item_type, :string
-  attribute :item_id, :string
-  attribute :event, :string
-  attribute :whodunnit, :string
-  attribute :created_at, :datetime
-
-  # Utiliza el tipo :json provisto por la gema para hidratar Hashes
-  attribute :object, :json
+  self.bucket       = 'my-bucket-storage'
+  self.folder_name  = 'versions'
+  self.partition_keys = [:isp_id, :year, :month]
+
+  attribute :id,             :string
+  attribute :item_type,      :string
+  attribute :item_id,        :string
+  attribute :event,          :string
+  attribute :whodunnit,      :string
+  attribute :created_at,     :datetime
+  attribute :object,         :json
   attribute :object_changes, :json
 end
 ```
 
-Consultas altamente optimizadas mediante Hive Partitioning:
+Consultas optimizadas mediante Hive Partitioning:
 
 ```ruby
-# Búsqueda puntual hiper-rápida aislando las particiones
-version = ArchivedVersion.find("un-uuid", year: 2026, month: 3, isp_id: 42)
+# Búsqueda puntual aislando la partición exacta
+version = ArchivedVersion.find("un-uuid", isp_id: 42, year: 2026, month: 3)
 puts version.object_changes # => {"status" => ["active", "suspended"]}
 
 # Colecciones
-history = ArchivedVersion.where(limit: 10, year: 2026, month: 3, isp_id: 42)
+history = ArchivedVersion.where(limit: 10, isp_id: 42, year: 2026, month: 3)
 ```
 
-### 4. Destrucción de Datos (Retención y Cumplimiento)
+### 5. Destrucción de Datos (Retención y Cumplimiento)
 
 El framework permite eliminar físicamente carpetas completas en S3 o Local utilizando comodines.
 
 ```ruby
-# Elimina todo el historial de un cliente en específico a través de todos los años
+# Elimina todo el historial de un cliente a través de todos los años
 ArchivedVersion.destroy_all(isp_id: 42)
 
 # Elimina todos los datos de marzo de 2024 globalmente
@@ -258,9 +262,25 @@ ArchivedVersion.destroy_all(year: 2024, month: 3)
 
 ## Arquitectura
 
-DataDrain implementa el patrón **Storage Adapter**, lo que permite aislar completamente la lógica del sistema de archivos de los motores de procesamiento. 
-* DuckDB mantiene una conexión persistente (`Thread-Safe`) para maximizar el rendimiento de las consultas web.
-* El ORM Analítico incluye sanitización de parámetros para prevenir Inyección SQL al consultar archivos Parquet.
+DataDrain implementa el patrón **Storage Adapter**, lo que permite aislar completamente la lógica del sistema de archivos de los motores de procesamiento.
+
+* **Conexión DuckDB thread-local:** `DataDrain::Record` mantiene una conexión DuckDB por thread (`Thread.current[:data_drain_duckdb]`). Cada thread inicializa su propia conexión una sola vez, incluyendo la carga de extensiones como `httpfs`. Tener esto en cuenta en entornos Puma o Sidekiq.
+* **Storage Adapter cacheado:** `DataDrain::Storage.adapter` cachea la instancia del adaptador. Si `storage_mode` cambia en runtime, llamar `DataDrain::Storage.reset_adapter!` para invalidar el cache.
+* **ORM Analítico con sanitización:** `DataDrain::Record` incluye sanitización de parámetros para prevenir inyección SQL al consultar archivos Parquet.
+
+## Observabilidad
+
+Todos los eventos emiten logs estructurados en formato `key=value` procesables por herramientas como Datadog, CloudWatch Logs Insights o `exis_ray`:
+
+```
+component=data_drain event=engine.complete table=versions duration_s=12.4 export_duration_s=8.1 purge_duration_s=3.9 count=150000
+component=data_drain event=engine.integrity_error table=versions duration_s=5.2 count=150000
+component=data_drain event=engine.purge_heartbeat table=versions batches_processed_count=100 rows_deleted_count=500000
+component=data_drain event=file_ingestor.complete source_path=/tmp/data.csv duration_s=2.1 count=85000
+component=data_drain event=glue_runner.failed job=my-export-job run_id=jr_abc123 status=FAILED duration_s=301.0
+```
+
+Los fallos internos del sistema de logging nunca interrumpen el flujo principal de datos.
 
 ## Licencia
 

data/lib/data_drain/engine.rb

@@ -9,6 +9,7 @@ module DataDrain
   # Orquesta el flujo ETL desde PostgreSQL hacia un Data Lake analítico
   # delegando la interacción del almacenamiento al adaptador configurado.
   class Engine
+    include Observability
     # Inicializa una nueva instancia del motor de extracción.
     #
     # @param options [Hash] Diccionario de configuración para la extracción.
@@ -50,33 +51,57 @@ module DataDrain
     # @return [Boolean] `true` si el proceso finalizó con éxito, `false` si falló la integridad.
     def call
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      @logger.info "component=data_drain event=engine.start table=#{@table_name} start_date=#{@start_date.to_date} end_date=#{@end_date.to_date}"
+      safe_log(:info, "engine.start", { table: @table_name, start_date: @start_date.to_date, end_date: @end_date.to_date })
 
       setup_duckdb
 
+      # 1. Conteo inicial en Postgres
+      step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @pg_count = get_postgres_count
+      db_query_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
 
       if @pg_count.zero?
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        @logger.info "component=data_drain event=engine.skip_empty table=#{@table_name} duration=#{duration.round(2)}s"
+        safe_log(:info, "engine.skip_empty", { table: @table_name, duration_s: duration.round(2), db_query_duration_s: db_query_duration.round(2) })
         return true
       end
 
+      # 2. Exportación
+      export_duration = 0.0
       if @skip_export
-        @logger.info "component=data_drain event=engine.skip_export table=#{@table_name}"
+        safe_log(:info, "engine.skip_export", { table: @table_name })
       else
-        @logger.info "component=data_drain event=engine.export_start table=#{@table_name} count=#{@pg_count}"
+        safe_log(:info, "engine.export_start", { table: @table_name, count: @pg_count })
+        step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         export_to_parquet
+        export_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
       end
 
-      if verify_integrity
+      # 3. Verificación de Integridad
+      step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      integrity_ok = verify_integrity
+      integrity_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
+
+      if integrity_ok
+        # 4. Purga en Postgres
+        step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         purge_from_postgres
+        purge_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
+
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        @logger.info "component=data_drain event=engine.complete table=#{@table_name} duration=#{duration.round(2)}s"
+        safe_log(:info, "engine.complete", {
+          table: @table_name,
+          duration_s: duration.round(2),
+          db_query_duration_s: db_query_duration.round(2),
+          export_duration_s: export_duration.round(2),
+          integrity_duration_s: integrity_duration.round(2),
+          purge_duration_s: purge_duration.round(2),
+          count: @pg_count
+        })
         true
       else
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        @logger.error "component=data_drain event=engine.integrity_error table=#{@table_name} duration=#{duration.round(2)}s"
+        safe_log(:error, "engine.integrity_error", { table: @table_name, duration_s: duration.round(2), count: @pg_count })
         false
       end
     end
@@ -151,17 +176,17 @@ module DataDrain
         SQL
         parquet_result = @duckdb.query(query).first.first
       rescue DuckDB::Error => e
-        @logger.error "component=data_drain event=engine.parquet_read_error table=#{@table_name} error=#{e.message}"
+        safe_log(:error, "engine.parquet_read_error", { table: @table_name }.merge(exception_metadata(e)))
         return false
       end
 
-      @logger.info "component=data_drain event=engine.integrity_check table=#{@table_name} pg_count=#{@pg_count} parquet_count=#{parquet_result}"
+      safe_log(:info, "engine.integrity_check", { table: @table_name, pg_count: @pg_count, parquet_count: parquet_result })
       @pg_count == parquet_result
     end
 
     # @api private
     def purge_from_postgres
-      @logger.info "component=data_drain event=engine.purge_start table=#{@table_name} batch_size=#{@config.batch_size}"
+      safe_log(:info, "engine.purge_start", { table: @table_name, batch_size: @config.batch_size })
 
       conn = PG.connect(
         host:     @config.db_host,
@@ -175,6 +200,9 @@ module DataDrain
         conn.exec("SET idle_in_transaction_session_timeout = #{@config.idle_in_transaction_session_timeout};")
       end
 
+      batches_processed = 0
+      total_deleted = 0
+
       loop do
         sql = <<~SQL
           DELETE FROM #{@table_name}
@@ -186,7 +214,20 @@ module DataDrain
         SQL
 
         result = conn.exec(sql)
-        break if result.cmd_tuples.zero?
+        count = result.cmd_tuples
+        break if count.zero?
+
+        batches_processed += 1
+        total_deleted += count
+
+        # Heartbeat cada 100 lotes para monitorear procesos largos de 1TB
+        if (batches_processed % 100).zero?
+          safe_log(:info, "engine.purge_heartbeat", {
+            table: @table_name,
+            batches_processed_count: batches_processed,
+            rows_deleted_count: total_deleted
+          })
+        end
 
         sleep(@config.throttle_delay) if @config.throttle_delay.positive?
       end

data/lib/data_drain/file_ingestor.rb

@@ -5,6 +5,8 @@ module DataDrain
   # generados por otros servicios (ej. Netflow) y subirlos al Data Lake
   # aplicando compresión ZSTD y particionamiento Hive.
   class FileIngestor
+    include Observability
+
     # @param options [Hash] Opciones de ingestión.
     # @option options [String] :source_path Ruta absoluta al archivo local.
     # @option options [String] :folder_name Nombre de la carpeta destino en el Data Lake.
@@ -31,10 +33,10 @@ module DataDrain
     # @return [Boolean] true si el proceso fue exitoso.
     def call
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      @logger.info "component=data_drain event=file_ingestor.start source_path=#{@source_path}"
+      safe_log(:info, "file_ingestor.start", { source_path: @source_path })
 
       unless File.exist?(@source_path)
-        @logger.error "component=data_drain event=file_ingestor.file_not_found source_path=#{@source_path}"
+        safe_log(:error, "file_ingestor.file_not_found", { source_path: @source_path })
         return false
       end
 
@@ -47,13 +49,15 @@ module DataDrain
       reader_function = determine_reader
 
       # 1. Conteo de seguridad
+      step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       source_count = @duckdb.query("SELECT COUNT(*) FROM #{reader_function}").first.first
-      @logger.info "component=data_drain event=file_ingestor.count source_path=#{@source_path} count=#{source_count}"
+      source_query_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
+      safe_log(:info, "file_ingestor.count", { source_path: @source_path, count: source_count, source_query_duration_s: source_query_duration.round(2) })
 
       if source_count.zero?
         cleanup_local_file
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        @logger.info "component=data_drain event=file_ingestor.skip_empty source_path=#{@source_path} duration=#{duration.round(2)}s"
+        safe_log(:info, "file_ingestor.skip_empty", { source_path: @source_path, duration_s: duration.round(2) })
         return true
       end
 
@@ -76,17 +80,25 @@ module DataDrain
         );
       SQL
 
-      @logger.info "component=data_drain event=file_ingestor.export_start dest_path=#{dest_path}"
+      safe_log(:info, "file_ingestor.export_start", { dest_path: dest_path })
+      step_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @duckdb.query(query)
+      export_duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - step_start
 
       duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-      @logger.info "component=data_drain event=file_ingestor.complete source_path=#{@source_path} duration=#{duration.round(2)}s"
+      safe_log(:info, "file_ingestor.complete", {
+        source_path: @source_path,
+        duration_s: duration.round(2),
+        source_query_duration_s: source_query_duration.round(2),
+        export_duration_s: export_duration.round(2),
+        count: source_count
+      })
 
       cleanup_local_file
       true
     rescue DuckDB::Error => e
       duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-      @logger.error "component=data_drain event=file_ingestor.duckdb_error source_path=#{@source_path} error=#{e.message} duration=#{duration.round(2)}s"
+      safe_log(:error, "file_ingestor.duckdb_error", { source_path: @source_path }.merge(exception_metadata(e)).merge(duration_s: duration.round(2)))
       false
     ensure
       @duckdb&.close
@@ -112,7 +124,7 @@ module DataDrain
     def cleanup_local_file
       if @delete_after_upload && File.exist?(@source_path)
         File.delete(@source_path)
-        @logger.info "component=data_drain event=file_ingestor.cleanup source_path=#{@source_path}"
+        safe_log(:info, "file_ingestor.cleanup", { source_path: @source_path })
       end
     end
   end

data/lib/data_drain/glue_runner.rb

@@ -6,6 +6,9 @@ module DataDrain
   # Orquestador para AWS Glue. Permite disparar y monitorear Jobs en AWS
   # para delegar el movimiento masivo de datos (ej. tablas de 1TB).
   class GlueRunner
+    extend Observability
+    private_class_method :safe_log, :exception_metadata, :observability_name
+
     # Dispara un Job de Glue y espera a que termine exitosamente.
     #
     # @param job_name [String] Nombre del Job en la consola de AWS.
@@ -18,7 +21,11 @@ module DataDrain
       client = Aws::Glue::Client.new(region: config.aws_region)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-      config.logger.info "component=data_drain event=glue_runner.start job=#{job_name}"
+      # Usamos el logger de la configuración directamente para el primer log antes de instanciar safe_log si fuera necesario
+      # Pero como extendemos Observability, usamos safe_log directamente.
+      @logger = config.logger 
+
+      safe_log(:info, "glue_runner.start", { job: job_name })
       resp = client.start_job_run(job_name: job_name, arguments: arguments)
       run_id = resp.job_run_id
 
@@ -29,15 +36,20 @@ module DataDrain
         case status
         when "SUCCEEDED"
           duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-          config.logger.info "component=data_drain event=glue_runner.complete job=#{job_name} run_id=#{run_id} duration=#{duration.round(2)}s"
+          safe_log(:info, "glue_runner.complete", { job: job_name, run_id: run_id, duration_s: duration.round(2) })
           return true
         when "FAILED", "STOPPED", "TIMEOUT"
-          error_msg = run_info.error_message || "Sin mensaje de error disponible."
           duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-          config.logger.error "component=data_drain event=glue_runner.failed job=#{job_name} run_id=#{run_id} status=#{status} error=#{error_msg} duration=#{duration.round(2)}s"
+          error_metadata = { job: job_name, run_id: run_id, status: status, duration_s: duration.round(2) }
+          
+          if run_info.error_message
+            error_metadata[:error_message] = run_info.error_message.gsub("\"", "'")[0, 200]
+          end
+
+          safe_log(:error, "glue_runner.failed", error_metadata)
           raise "Glue Job #{job_name} (Run ID: #{run_id}) falló con estado #{status}."
         else
-          config.logger.info "component=data_drain event=glue_runner.polling job=#{job_name} run_id=#{run_id} status=#{status} next_check_in=#{polling_interval}s"
+          safe_log(:info, "glue_runner.polling", { job: job_name, run_id: run_id, status: status, next_check_in_s: polling_interval })
           sleep polling_interval
         end
       end

data/lib/data_drain/observability.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DataDrain
+  # Módulo interno para garantizar que la telemetría cumpla con los 
+  # Global-Observability-Standards: resiliencia, KV-structured y precisión.
+  #
+  # Este módulo es genérico y puede ser utilizado en otras gemas.
+  # @api private
+  module Observability
+    private
+
+    # Emite un log estructurado de forma segura.
+    # Garantiza que el logging nunca interrumpa el proceso principal (Resilience).
+    def safe_log(level, event, metadata = {})
+      return unless @logger
+
+      # component y event siempre primeros, luego el contexto
+      fields = { component: observability_name, event: event }.merge(metadata)
+
+      # Enmascaramiento preventivo de secretos (Security)
+      log_line = fields.map do |k, v|
+        val = %i[password token secret api_key auth].include?(k.to_sym) ? "[FILTERED]" : v
+        "#{k}=#{val}"
+      end.join(" ")
+
+      @logger.send(level) { log_line }
+    rescue StandardError
+      # Silencio absoluto en fallos de log para no detener procesos críticos
+    end
+
+    # Formatea excepciones siguiendo el Standard Error Context.
+    def exception_metadata(error)
+      {
+        error_class: error.class.name,
+        error_message: error.message.gsub("\"", "'")[0, 200]
+      }
+    end
+
+    # Nombre del componente para los logs.
+    # Funciona tanto en métodos de instancia (self = objeto) como de clase (self = Class).
+    def observability_name
+      klass = is_a?(Class) ? self : self.class
+      klass.name.split("::").first.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    rescue StandardError
+      "unknown"
+    end
+  end
+end

data/lib/data_drain/record.rb

@@ -11,12 +11,14 @@ module DataDrain
   # @example
   #   class ArchivedVersion < DataDrain::Record
   #     self.folder_name = 'versions'
-  #     self.partition_keys = [:year, :month, :isp_id]
+  #     self.partition_keys = [:isp_id, :year, :month]
   #     attribute :event, :string
   #   end
   class Record
     include ActiveModel::Model
     include ActiveModel::Attributes
+    extend Observability
+    private_class_method :safe_log, :exception_metadata, :observability_name
 
     class_attribute :bucket
     class_attribute :folder_name
@@ -86,7 +88,8 @@ module DataDrain
     # @return [Integer] Cantidad de particiones físicas eliminadas.
     def self.destroy_all(**partitions)
       adapter = DataDrain::Storage.adapter
-      DataDrain.configuration.logger.info "component=data_drain event=record.destroy_all folder=#{folder_name} partitions=#{partitions.inspect}"
+      @logger = DataDrain.configuration.logger
+      safe_log(:info, "record.destroy_all", { folder: folder_name, partitions: partitions.inspect })
 
       adapter.destroy_partitions(bucket, folder_name, partition_keys, partitions)
     end
@@ -107,7 +110,7 @@ module DataDrain
       # @param partitions [Hash]
       # @return [String]
       def build_query_path(partitions)
-        partition_path = partitions.map { |k, v| "#{k}=#{v}" }.join("/")
+        partition_path = partition_keys.map { |k| "#{k}=#{partitions[k.to_sym] || partitions[k.to_s]}" }.join("/")
         DataDrain::Storage.adapter.build_path(bucket, folder_name, partition_path)
       end
 
@@ -116,10 +119,11 @@ module DataDrain
       # @param columns [Array<String>]
       # @return [Array<DataDrain::Record>]
       def execute_and_instantiate(sql, columns)
+        @logger = DataDrain.configuration.logger
         begin
           result = connection.query(sql)
         rescue DuckDB::Error => e
-          DataDrain.configuration.logger.warn "component=data_drain event=record.parquet_not_found error=#{e.message}"
+          safe_log(:warn, "record.parquet_not_found", exception_metadata(e))
           return []
         end
 

data/lib/data_drain/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataDrain
-  VERSION = "0.1.15"
+  VERSION = "0.1.19"
 end

data/lib/data_drain.rb

@@ -5,6 +5,7 @@ require_relative "data_drain/version"
 require_relative "data_drain/errors"
 require_relative "data_drain/configuration"
 require_relative "data_drain/storage"
+require_relative "data_drain/observability"
 require_relative "data_drain/engine"
 require_relative "data_drain/record"
 require_relative "data_drain/file_ingestor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.15
+  version: 0.1.19
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -103,6 +103,7 @@ files:
 - lib/data_drain/errors.rb
 - lib/data_drain/file_ingestor.rb
 - lib/data_drain/glue_runner.rb
+- lib/data_drain/observability.rb
 - lib/data_drain/record.rb
 - lib/data_drain/storage.rb
 - lib/data_drain/storage/base.rb