data_drain 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c484ac47a5f767491fa8d8e48dbdb53ccdd55d756a6a0eb90d7bbeb0d28f68a
-  data.tar.gz: 18526e071ac821f7c19127cb53dad875108ede9ab9b7bfe40a1d17bde877a6cc
+  metadata.gz: c5a97927218d94763cdead9362a4a0a0a40fe4a1b8b327f0f074117a66a10a46
+  data.tar.gz: a5f28048457a43d86942472b36946955e0aa88c9d75cb85158d27f44c986aec2
 SHA512:
-  metadata.gz: abf18e9f987f24cb2e58fb71be8a15f92f867f6e671b174e6414b7a44a5626a316235c091bd59708c1ddc93c755db87ec92af117573c68213d0f2238165728be
-  data.tar.gz: '00124804ef7f7c9dc2c67d47a1a2304d4dc996b0caff24548acbe913e85f5ae43d410eac6725f264f9b9648d49c7dc8bdc0baed77e5ea958bfa3fc8cea08ee9d'
+  metadata.gz: 5f538227b8eda210214fa448ede9f3247fa73bf997a2cfb04ca0a1b37c81b096198ad250b4e3dcf2f902a4f54eee16cb69233e68e03d65aca68c6bf497de72e4
+  data.tar.gz: 93f7b591e556713614c0310415301787605cf3cefc26718e94b74ee1ab60cec17ffaeaaec3d7b8ce5bb31deb40a51b1007d60bd9cdcba1211e4a8e06f1079293

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.1.15] - 2026-03-23
+
+- 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.
+- Fix: Objeto `DuckDB::Database` en `Record` ahora se ancla en el thread-local junto a la conexión, previniendo garbage collection prematura.
+- Fix: `Storage.adapter` cachea la instancia en vez de crearla en cada llamada.
+- Documentation: Agregado `CLAUDE.md` con guía de arquitectura y estándares del proyecto.
+
+## [0.1.14] - 2026-03-17
+
+- Feature: Implementación de **Logging Estructurado** en toda la gema (\`key=value\`) para mejor observabilidad en producción.
+- Optimization: Caching automático de adaptadores de almacenamiento para mejorar el rendimiento de consultas repetidas.
+- Testing: Mejora en la robustez de los tests de \`Engine\` desacoplándolos de cambios menores en el setup de DuckDB.
+
 ## [0.1.13] - 2026-03-17
 
 - Feature: Parametrización total en la orquestación con Glue. Se añadieron \`s3_bucket\`, \`s3_folder\` y \`partition_by\` como argumentos dinámicos, permitiendo que el mismo Job de Glue sirva para múltiples tablas y destinos.

data/CLAUDE.md

@@ -0,0 +1,56 @@
+# DataDrain - Contexto de Desarrollo
+
+## Arquitectura y Patrones Core
+
+- **Engine (`DataDrain::Engine`):** Orquesta el flujo ETL: Conteo → Export → Verify → Purge. El paso de export es omitible con `skip_export: true` (para delegar a AWS Glue).
+- **Storage Adapters (`DataDrain::Storage`):** Patrón Strategy. La instancia se cachea en `DataDrain::Storage.adapter`. Si `storage_mode` cambia en runtime, llamar `DataDrain::Storage.reset_adapter!` antes de la próxima operación.
+- **Analytical ORM (`DataDrain::Record`):** Interfaz tipo ActiveRecord de solo lectura sobre Parquet vía DuckDB. Usa una conexión DuckDB por thread (`Thread.current[:data_drain_duckdb_conn]`) que se inicializa una vez y se reutiliza — nunca se cierra explícitamente. Tener en cuenta en Puma/Sidekiq.
+- **Glue Orchestrator (`DataDrain::GlueRunner`):** Para tablas 1TB+. Patrón: `GlueRunner.run_and_wait(...)` seguido de `Engine.new(..., skip_export: true).call` para verificar + purgar.
+
+## Convenciones Críticas
+
+### Seguridad en Purga
+`purge_from_postgres` nunca debe ejecutarse si `verify_integrity` devuelve `false`. La verificación matemática de conteos (Postgres vs Parquet) es el único gate de seguridad antes de borrar datos.
+
+### Precisión de Fechas
+Las consultas SQL de rango siempre deben usar **límites semi-abiertos**:
+```sql
+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.
+
+### 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
+
+Seguir los estándares globales definidos en `~/.claude/CLAUDE.md`. Reglas específicas de este proyecto:
+
+- 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]`
+
+## Código Ruby
+
+- Todo código nuevo o modificado debe pasar `bundle exec rubocop` sin ofensas
+- Documentación pública con YARD (`@param`, `@return`, `@raise`, `@example`)
+- No modificar ni agregar YARD/comentarios a código existente no tocado
+
+## Comandos
+
+```bash
+bundle exec rspec       # tests
+bundle exec rubocop     # linting
+bin/console             # REPL de desarrollo
+```
+
+## Rendimiento
+
+- `limit_ram` y `tmp_directory` en la configuración evitan OOM en contenedores
+- DuckDB usa spill-to-disk automáticamente cuando `tmp_directory` está seteado

data/lib/data_drain/engine.rb

@@ -49,30 +49,34 @@ module DataDrain
     #
     # @return [Boolean] `true` si el proceso finalizó con éxito, `false` si falló la integridad.
     def call
-      @logger.info "[DataDrain Engine] 🚀 Preparando '#{@table_name}' (#{@start_date.to_date} a #{@end_date.to_date})..."
+      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}"
 
       setup_duckdb
 
       @pg_count = get_postgres_count
 
       if @pg_count.zero?
-        @logger.info "[DataDrain Engine] ⏭️ No hay registros que cumplan las condiciones."
+        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"
         return true
       end
 
       if @skip_export
-        @logger.info "[DataDrain Engine] ⏭️ Modo 'Skip Export' activo. Saltando paso de exportación..."
+        @logger.info "component=data_drain event=engine.skip_export table=#{@table_name}"
       else
-        @logger.info "[DataDrain Engine] 📦 Exportando #{@pg_count} registros a Parquet..."
+        @logger.info "component=data_drain event=engine.export_start table=#{@table_name} count=#{@pg_count}"
         export_to_parquet
       end
 
       if verify_integrity
         purge_from_postgres
-        @logger.info "[DataDrain Engine] ✅ Proceso completado exitosamente para '#{@table_name}'."
+        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"
         true
       else
-        @logger.error "[DataDrain Engine] ❌ ERROR de integridad en '#{@table_name}'. Abortando purga."
+        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"
         false
       end
     end
@@ -147,17 +151,17 @@ module DataDrain
         SQL
         parquet_result = @duckdb.query(query).first.first
       rescue DuckDB::Error => e
-        @logger.error "[DataDrain Engine] ❌ Error leyendo Parquet: #{e.message}"
+        @logger.error "component=data_drain event=engine.parquet_read_error table=#{@table_name} error=#{e.message}"
         return false
       end
 
-      @logger.info "[DataDrain Engine] 📊 Verificación -> Postgres: #{@pg_count} | Parquet: #{parquet_result}"
+      @logger.info "component=data_drain event=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 "[DataDrain Engine] 🗑️ Purgando en base de datos (Lotes de #{@config.batch_size})..."
+      @logger.info "component=data_drain event=engine.purge_start table=#{@table_name} batch_size=#{@config.batch_size}"
 
       conn = PG.connect(
         host:     @config.db_host,
@@ -167,7 +171,7 @@ module DataDrain
         dbname:   @config.db_name
       )
 
-      if @config.idle_in_transaction_session_timeout.present?
+      unless @config.idle_in_transaction_session_timeout.nil?
         conn.exec("SET idle_in_transaction_session_timeout = #{@config.idle_in_transaction_session_timeout};")
       end
 

data/lib/data_drain/file_ingestor.rb

@@ -30,10 +30,11 @@ module DataDrain
     # Ejecuta el flujo de ingestión.
     # @return [Boolean] true si el proceso fue exitoso.
     def call
-      @logger.info "[DataDrain FileIngestor] 🚀 Iniciando ingestión de '#{@source_path}'..."
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @logger.info "component=data_drain event=file_ingestor.start source_path=#{@source_path}"
 
       unless File.exist?(@source_path)
-        @logger.error "[DataDrain FileIngestor] ❌ El archivo origen no existe: #{@source_path}"
+        @logger.error "component=data_drain event=file_ingestor.file_not_found source_path=#{@source_path}"
         return false
       end
 
@@ -47,10 +48,12 @@ module DataDrain
 
       # 1. Conteo de seguridad
       source_count = @duckdb.query("SELECT COUNT(*) FROM #{reader_function}").first.first
-      @logger.info "[DataDrain FileIngestor] 📊 Encontrados #{source_count} registros para procesar."
+      @logger.info "component=data_drain event=file_ingestor.count source_path=#{@source_path} count=#{source_count}"
 
       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"
         return true
       end
 
@@ -73,15 +76,17 @@ module DataDrain
         );
       SQL
 
-      @logger.info "[DataDrain FileIngestor] ☁️ Escribiendo en el Data Lake..."
+      @logger.info "component=data_drain event=file_ingestor.export_start dest_path=#{dest_path}"
       @duckdb.query(query)
 
-      @logger.info "[DataDrain FileIngestor] ✅ Archivo ingerido y comprimido exitosamente."
+      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"
 
       cleanup_local_file
       true
     rescue DuckDB::Error => e
-      @logger.error "[DataDrain FileIngestor] ❌ Error de DuckDB durante la ingestión: #{e.message}"
+      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"
       false
     ensure
       @duckdb&.close
@@ -107,7 +112,7 @@ module DataDrain
     def cleanup_local_file
       if @delete_after_upload && File.exist?(@source_path)
         File.delete(@source_path)
-        @logger.info "[DataDrain FileIngestor] 🗑️ Archivo temporal local eliminado."
+        @logger.info "component=data_drain event=file_ingestor.cleanup source_path=#{@source_path}"
       end
     end
   end

data/lib/data_drain/glue_runner.rb

@@ -16,8 +16,9 @@ module DataDrain
     def self.run_and_wait(job_name, arguments = {}, polling_interval: 30)
       config = DataDrain.configuration
       client = Aws::Glue::Client.new(region: config.aws_region)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-      config.logger.info "[DataDrain GlueRunner] 🚀 Disparando Job: #{job_name}..."
+      config.logger.info "component=data_drain event=glue_runner.start job=#{job_name}"
       resp = client.start_job_run(job_name: job_name, arguments: arguments)
       run_id = resp.job_run_id
 
@@ -27,14 +28,16 @@ module DataDrain
 
         case status
         when "SUCCEEDED"
-          config.logger.info "[DataDrain GlueRunner] ✅ Job completado con éxito."
+          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"
           return true
         when "FAILED", "STOPPED", "TIMEOUT"
           error_msg = run_info.error_message || "Sin mensaje de error disponible."
-          config.logger.error "[DataDrain GlueRunner] ❌ ERROR: El Job terminó con estado #{status}: #{error_msg}"
+          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"
           raise "Glue Job #{job_name} (Run ID: #{run_id}) falló con estado #{status}."
         else
-          config.logger.info "[DataDrain GlueRunner] ⏳ Estado: #{status}. Esperando #{polling_interval}s..."
+          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"
           sleep polling_interval
         end
       end

data/lib/data_drain/record.rb

@@ -27,7 +27,7 @@ module DataDrain
     #
     # @return [DuckDB::Connection] Conexión activa a DuckDB.
     def self.connection
-      Thread.current[:data_drain_duckdb_conn] ||= begin
+      Thread.current[:data_drain_duckdb] ||= begin
         db = DuckDB::Database.open(":memory:")
         conn = db.connect
 
@@ -36,8 +36,9 @@ module DataDrain
         conn.query("SET temp_directory='#{config.tmp_directory}'") if config.tmp_directory.present?
 
         DataDrain::Storage.adapter.setup_duckdb(conn)
-        conn
+        { db: db, conn: conn }
       end
+      Thread.current[:data_drain_duckdb][:conn]
     end
 
     # Consulta registros en el Data Lake filtrando por claves de partición.
@@ -85,7 +86,7 @@ module DataDrain
     # @return [Integer] Cantidad de particiones físicas eliminadas.
     def self.destroy_all(**partitions)
       adapter = DataDrain::Storage.adapter
-      DataDrain.configuration.logger.info "[DataDrain] 🗑️ Ejecutando destroy_all en #{folder_name} con: #{partitions.inspect}"
+      DataDrain.configuration.logger.info "component=data_drain event=record.destroy_all folder=#{folder_name} partitions=#{partitions.inspect}"
 
       adapter.destroy_partitions(bucket, folder_name, partition_keys, partitions)
     end
@@ -118,7 +119,7 @@ module DataDrain
         begin
           result = connection.query(sql)
         rescue DuckDB::Error => e
-          DataDrain.configuration.logger.warn "[DataDrain] ⚠️ Ruta o archivo no encontrado: #{e.message}"
+          DataDrain.configuration.logger.warn "component=data_drain event=record.parquet_not_found error=#{e.message}"
           return []
         end
 

data/lib/data_drain/storage.rb

@@ -11,20 +11,28 @@ module DataDrain
     class InvalidAdapterError < DataDrain::Error; end
 
     # Resuelve e instancia el adaptador de almacenamiento correspondiente
-    # basándose en la configuración actual del framework.
+    # basándose en la configuración actual del framework. La instancia se
+    # cachea para evitar allocations innecesarias entre queries.
     #
     # @return [DataDrain::Storage::Base] Una instancia de Local o S3.
     # @raise [InvalidAdapterError] Si el storage_mode no es válido.
     def self.adapter
-      mode = DataDrain.configuration.storage_mode
-      case mode.to_sym
-      when :local
-        Local.new(DataDrain.configuration)
-      when :s3
-        S3.new(DataDrain.configuration)
-      else
-        raise InvalidAdapterError, "Storage mode '#{mode}' no está soportado."
+      @adapter ||= begin
+        mode = DataDrain.configuration.storage_mode
+        case mode.to_sym
+        when :local
+          Local.new(DataDrain.configuration)
+        when :s3
+          S3.new(DataDrain.configuration)
+        else
+          raise InvalidAdapterError, "Storage mode '#{mode}' no está soportado."
+        end
       end
     end
+
+    # Descarta el adaptador cacheado. Llamar cuando cambia storage_mode.
+    def self.reset_adapter!
+      @adapter = nil
+    end
   end
 end

data/lib/data_drain/version.rb

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

data/lib/data_drain.rb

@@ -29,6 +29,7 @@ module DataDrain
     # @api private
     def reset_configuration!
       @configuration = Configuration.new
+      DataDrain::Storage.reset_adapter!
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.13
+  version: 0.1.15
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-20 00:00:00.000000000 Z
+date: 2026-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -91,6 +91,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md