iugu_logger 0.10.0

data/lib/iugu_logger/buffer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module IuguLogger
+  # Thread-local buffer for in-app log entries collected during a single
+  # request or job execution.
+  #
+  # Pattern (per IUGU_LOGGING_STANDARD.md §2.1):
+  #   - Framework / app code calls IuguLogger::Buffer.current.push(...)
+  #     instead of emitting one log per call.
+  #   - Middleware (RequestLogger / JobLogger) drains the buffer at end of
+  #     execution and emits ONE consolidated event with `logs: [...]` array.
+  #   - Result: 1 log line per request, instead of N — aggregation is 10×
+  #     simpler downstream (Loki/Splunk).
+  #
+  # Also carries a `context` hash for request-scoped enrichment (trace,
+  # iugu, request) that downstream code can read or that middleware merges
+  # into the final emitted event.
+  #
+  # Thread safety: each thread has its own buffer instance via
+  # Concurrent::ThreadLocalVar. Reset between requests by the middleware.
+  #
+  # NOT used by IuguLogger.event(...) directly — that API still emits
+  # immediately. Buffer is the place where Rails.logger.X (post-Railtie,
+  # v0.5) accumulates entries.
+  class Buffer
+    THREAD_LOCAL = Concurrent::ThreadLocalVar.new
+
+    class << self
+      # Returns the buffer for the current thread, creating one lazily.
+      def current
+        THREAD_LOCAL.value ||= new
+      end
+
+      # Resets the current thread's buffer (used by middleware between
+      # requests). Safe to call when no buffer exists yet.
+      def reset!
+        THREAD_LOCAL.value = nil
+      end
+    end
+
+    MAX_ENTRIES = 100
+
+    attr_reader :context, :rails_runtime
+
+    def initialize
+      @entries       = []
+      @context       = {}
+      @rails_runtime = {} # view_ms / db_ms captured by Railtie subscriber
+    end
+
+    # Records the Rails view/db runtime captured at the end of action
+    # dispatch via ActiveSupport::Notifications. RequestLogger reads
+    # these when building the canonical `rails.*` block, since
+    # ActionController::API doesn't populate the corresponding env keys.
+    def set_rails_runtime(view_ms: nil, db_ms: nil)
+      @rails_runtime['view_ms'] = view_ms unless view_ms.nil?
+      @rails_runtime['db_ms']   = db_ms   unless db_ms.nil?
+    end
+
+    # Append a log entry. Severity is a symbol or string; message is the
+    # human-readable summary; extras become extra keys on the entry.
+    def push(severity:, message:, **extras)
+      return if @entries.length >= MAX_ENTRIES # cap to avoid unbounded growth
+
+      entry = {
+        'timestamp' => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%6NZ'),
+        'severity'  => severity.to_s,
+        'message'   => message
+      }
+      extras.each { |k, v| entry[k.to_s] = v unless v.nil? }
+      @entries << entry
+    end
+
+    # Returns the array of entries collected so far and clears the buffer.
+    def drain
+      collected = @entries
+      @entries = []
+      collected
+    end
+
+    # Number of entries currently buffered (without draining).
+    def size
+      @entries.length
+    end
+
+    # Merge fields into the request-scoped context. Existing keys overwritten.
+    def add_context(**fields)
+      fields.each { |k, v| @context[k] = v unless v.nil? }
+    end
+
+    def reset_context!
+      @context = {}
+    end
+  end
+end

data/lib/iugu_logger/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  # SDK configuration object. Set via `IuguLogger.configure`.
+  class Configuration
+    attr_accessor :service_name, :service_version, :service_environment,
+                  :output, :format,
+                  :pii_redaction, :pii_param_blocklist,
+                  :event_action_validator, :event_action_registry,
+                  :max_log_size_kb, :emit_service_instance
+
+    # Default cap for emitted log size, in KB. The middleware truncates
+    # `request.params` (typically the biggest field) when the encoded
+    # payload would exceed this, and sets `request.params_truncated: true`
+    # so downstream consumers know.
+    DEFAULT_MAX_LOG_SIZE_KB = 64
+
+    def initialize
+      @service_name        = nil
+      @service_version     = nil
+      @service_environment = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+      @output              = $stdout
+      @format              = :json # :json | :pretty
+
+      # PII v0.2 — strategies overridable per type:
+      #   :full_redact / :last4 / :detect_only / :preserve
+      @pii_redaction       = Pii::DEFAULT_STRATEGIES.dup
+      @pii_param_blocklist = Pii::DEFAULT_PARAM_BLOCKLIST.dup
+
+      # Schema v0.3 — event.action validation:
+      #   :strict — raise on unknown action / missing required field
+      #   :warn   — annotate emitted log with labels.schema_warning, proceed
+      #   :off    — disabled (default — backward compatible)
+      # event_action_registry: Hash from Schema.load_from_file or nil. When
+      # nil, validation is :off regardless of mode.
+      @event_action_validator = Schema::DEFAULT_MODE
+      @event_action_registry  = nil
+
+      # v0.9 — log size cap (KB). Set to nil to disable.
+      @max_log_size_kb = DEFAULT_MAX_LOG_SIZE_KB
+
+      # service.instance (= HOSTNAME/POD_NAME) is OFF by default: in the
+      # canonical K8s + Alloy pipeline it duplicates the `pod_name` label
+      # Alloy already attaches to every log line. Set to true for contexts
+      # where no collector enriches the log (local dev, non-K8s, alternate
+      # sinks) and you still want the instance identifier in the payload.
+      @emit_service_instance = false
+    end
+
+    # Validates required fields. Raises ConfigurationError if missing.
+    def validate!
+      missing = []
+      missing << 'service_name'        if blank?(service_name)
+      missing << 'service_version'     if blank?(service_version)
+      missing << 'service_environment' if blank?(service_environment)
+
+      unless missing.empty?
+        raise ConfigurationError,
+              "missing required configuration: #{missing.join(', ')}. " \
+              "Call IuguLogger.configure { |c| c.service_name = ... }."
+      end
+
+      unless %i[json pretty].include?(format)
+        raise ConfigurationError, "unknown format: #{format.inspect} (expected :json or :pretty)"
+      end
+
+      self
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/iugu_logger/job_logger.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module IuguLogger
+  # Background job middlewares — emit ONE consolidated event per job execution.
+  # Same pattern as RequestLogger, applied to Sidekiq and ActiveJob.
+  #
+  # Usage (Sidekiq, server side):
+  #
+  #   Sidekiq.configure_server do |config|
+  #     config.server_middleware do |chain|
+  #       chain.add IuguLogger::JobLogger::Sidekiq
+  #     end
+  #   end
+  #
+  # Usage (ActiveJob — typically via ApplicationJob):
+  #
+  #   class ApplicationJob < ActiveJob::Base
+  #     include IuguLogger::JobLogger::ActiveJob
+  #   end
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §6 (JobLogger middleware)
+  module JobLogger
+    SOURCE_SIDEKIQ   = 'sidekiq'
+    SOURCE_ACTIVEJOB = 'activejob'
+
+    # Common body for Sidekiq + ActiveJob — wraps a job execution with the
+    # 1-log-per-execution pattern. Both wrappers below delegate here.
+    class Adapter
+      def initialize(job_class:, job_id:, queue:, source:, attempt:)
+        @job_class = job_class.to_s
+        @job_id    = job_id.to_s
+        @queue     = queue.to_s
+        @source    = source.to_s
+        @attempt   = attempt.to_i
+      end
+
+      def call
+        Buffer.reset!
+        buffer = Buffer.current
+
+        request = build_request
+        labels  = build_labels
+
+        buffer.add_context(request: request, labels: labels)
+
+        start = monotonic_now
+        result = yield
+        emit_completed(request: request, labels: labels,
+                       duration_ms: elapsed_ms(start), logs: buffer.drain)
+        result
+      rescue StandardError => e
+        emit_failed(request: request, labels: labels, error: e,
+                    duration_ms: elapsed_ms(start), logs: buffer&.drain || [])
+        raise
+      ensure
+        Buffer.reset!
+      end
+
+      private
+
+      def build_request
+        {
+          'id'     => @job_id,
+          'source' => @source
+        }.reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+      end
+
+      def build_labels
+        # Loki cardinality: keep only stable, low-cardinality dimensions here
+        # (job_class, queue, attempt). Per-execution things (duration_ms,
+        # job_id) live elsewhere on the payload.
+        {
+          'job_class' => @job_class,
+          'queue'     => @queue,
+          'attempt'   => @attempt.to_s
+        }
+      end
+
+      def emit_completed(request:, labels:, duration_ms:, logs:)
+        IuguLogger.event(
+          "#{@source}.job.completed",
+          severity:    :info,
+          message:     format_completed_message(duration_ms),
+          request:     request,
+          labels:      labels,
+          duration_ms: duration_ms,
+          logs:        logs.empty? ? nil : logs
+        )
+      end
+
+      def emit_failed(request:, labels:, error:, duration_ms:, logs:)
+        IuguLogger.event(
+          "#{@source}.job.failed",
+          severity:    :error,
+          message:     format_failed_message(error, duration_ms),
+          request:     request,
+          labels:      labels,
+          duration_ms: duration_ms,
+          error: {
+            'type'        => error.class.name,
+            'message'     => error.message.to_s,
+            'fingerprint' => fingerprint(error)
+          },
+          logs: logs.empty? ? nil : logs
+        )
+      end
+
+      # Human-readable summary in the same family as the HTTP RequestLogger:
+      # `<JobClass>#perform [<queue>] <ok|failed> [<duration_ms>ms]`. Helps
+      # plantonista 3am scan Sidekiq logs without expanding each event.
+      def format_completed_message(duration_ms)
+        "#{@job_class}#perform [#{@queue}] ok [#{duration_ms}ms]"
+      end
+
+      def format_failed_message(error, duration_ms)
+        "#{@job_class}#perform [#{@queue}] failed [#{duration_ms}ms] #{error.class.name}"
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def elapsed_ms(start)
+        return 0 if start.nil?
+
+        ((monotonic_now - start) * 1000).round
+      end
+
+      def fingerprint(error)
+        Digest::SHA256.hexdigest("#{error.class.name}|#{normalized_message(error.message)}")
+      end
+
+      def normalized_message(msg)
+        msg.to_s.gsub(/\d+/, 'N').gsub(/[a-f0-9]{16,}/i, 'HEX')
+      end
+    end
+
+    # Sidekiq server middleware. Compatible with sidekiq, sidekiq-pro,
+    # sidekiq-ent (msg payload format identical).
+    class Sidekiq
+      def call(_worker_instance, msg, queue)
+        Adapter.new(
+          job_class: msg['class'],
+          job_id:    msg['jid'],
+          queue:     queue,
+          source:    SOURCE_SIDEKIQ,
+          attempt:   (msg['retry_count'] || 0) + 1
+        ).call { yield }
+      end
+    end
+
+    # ActiveJob mixin. `include` in ApplicationJob to capture all jobs.
+    # ActiveJob >= 5 has #executions; we fall back to 1 on Rails 4.2
+    # (platform).
+    module ActiveJob
+      def self.included(base)
+        base.around_perform do |job, block|
+          Adapter.new(
+            job_class: job.class.name,
+            job_id:    job.job_id,
+            queue:     job.queue_name,
+            source:    SOURCE_ACTIVEJOB,
+            attempt:   job.respond_to?(:executions) ? job.executions : 1
+          ).call { block.call }
+        end
+      end
+    end
+  end
+end

data/lib/iugu_logger/logger.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module IuguLogger
+  # Core logger — emits canonical iugu log events as JSON lines.
+  #
+  # v0.3 adds Schema::Validator integration. Subsequent releases add:
+  #   - Trace context extraction + Rack/Sidekiq middlewares (ILS-023)
+  #   - Thread-local buffer for in-app logs
+  #   - Railtie auto-config
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §6
+  class Logger
+    EVENT_KIND_DEFAULT = 'event'
+    DEFAULT_SEVERITY   = :info
+
+    def initialize(configuration)
+      @configuration = configuration
+      @configuration.validate!
+    end
+
+    # Emits a structured event log.
+    #
+    # @example
+    #   logger.event('pix.out.requested',
+    #                pix:  { end_to_end_id: e2e, amount_brl: 100 },
+    #                iugu: { account_id: account.id })
+    #
+    # @example with explicit severity and kind
+    #   logger.event('pix.out.timeout', severity: :error, message: 'jdpi timeout')
+    #
+    # When event_action_validator is :strict, an unknown action or a missing
+    # required field raises (UnknownEventAction / SchemaViolation).
+    # When :warn, the emitted log carries `labels.schema_warning` and proceeds.
+    # When :off (default), no validation runs.
+    #
+    # If the registry definition declares an `event_kind` for the action
+    # (e.g. audit-class events), it is used as default when the caller does
+    # not pass an explicit `kind:`.
+    def event(action, severity: nil, kind: nil, message: nil, **fields)
+      raise ArgumentError, 'event.action is required' if action.nil? || action.to_s.empty?
+
+      validation = schema_validator.validate(action.to_s, fields)
+      enforce_validation!(action, validation)
+
+      effective_kind     = kind || validation.event_kind || EVENT_KIND_DEFAULT
+      effective_severity = severity || DEFAULT_SEVERITY
+
+      raise ArgumentError, "unknown severity: #{effective_severity.inspect}" unless Severity.valid?(effective_severity)
+
+      fields = inject_trace_context(fields)
+
+      user_section_raw = build_user_section(message: message || action, fields: fields)
+      user_section_raw = annotate_warning(user_section_raw, validation) if warn_mode? && needs_warning?(validation)
+
+      scan_result = pii_scanner.scan(user_section_raw)
+
+      payload = build_metadata(action: action.to_s, severity: effective_severity.to_s, kind: effective_kind.to_s)
+                .merge(scan_result.payload)
+                .merge('pii' => scan_result.to_pii_block)
+
+      emit(payload)
+    end
+
+    private
+
+    # Raise on validation problems when in :strict mode. In :warn mode, no
+    # raise — the warning is annotated into the emitted payload.
+    def enforce_validation!(action, validation)
+      return if validation.ok? || validation.off?
+      return unless @configuration.event_action_validator == Schema::STRICT
+
+      case validation.status
+      when :unknown_action
+        suggestion_text = format_suggestions(validation.suggestions)
+        raise UnknownEventAction, "unknown event.action: #{action.inspect}#{suggestion_text}"
+      when :missing_required
+        raise SchemaViolation,
+              "event.action #{action.inspect} missing required field(s): #{validation.missing_fields.join(', ')}"
+      end
+    end
+
+    def format_suggestions(suggestions)
+      return '' if suggestions.nil? || suggestions.empty?
+
+      ". Did you mean: #{suggestions.join(', ')}?"
+    end
+
+    def warn_mode?
+      @configuration.event_action_validator == Schema::WARN
+    end
+
+    def needs_warning?(validation)
+      validation.unknown_action? || validation.missing_required?
+    end
+
+    def annotate_warning(section, validation)
+      warning =
+        if validation.unknown_action?
+          'unknown_event_action'
+        else
+          "missing_required:#{validation.missing_fields.join(',')}"
+        end
+
+      labels = (section['labels'] || {}).merge('schema_warning' => warning)
+      section.merge('labels' => labels)
+    end
+
+    # SDK-controlled fields. Not subjected to PII scan (no user content).
+    def build_metadata(action:, severity:, kind:)
+      {
+        '@timestamp'   => current_timestamp,
+        'log.level'    => severity,
+        'event.kind'   => kind,
+        'event.action' => action,
+        'service'      => service_payload
+      }
+    end
+
+    # Auto-correlates a standalone event with the active trace context, so a
+    # domain event (`IuguLogger.event`) emitted during a request/job carries
+    # the same `trace.*` as the consolidated request/job log — without the
+    # caller having to thread the trace through by hand.
+    #
+    # Skipped entirely when the caller passes `trace:` (including the
+    # RequestLogger middleware, which manages its own — `trace: nil` there
+    # means "no trace", and we respect it).
+    #
+    # Resolution order (first wins):
+    #   1. Buffer context — populated by RequestLogger via a full
+    #      rack_env-aware extraction (incl. the X-Request-Id fallback), so it
+    #      matches the request log exactly, even when OTEL is absent.
+    #   2. Ambient OpenTelemetry/Datadog span via TraceContext.extract —
+    #      covers jobs / scripts / console where no middleware filled the
+    #      buffer (no rack_env, so OTEL/Datadog only).
+    def inject_trace_context(fields)
+      return fields if fields.key?(:trace)
+
+      trace = buffered_trace || TraceContext.extract
+      return fields if trace.nil? || (trace.respond_to?(:empty?) && trace.empty?)
+
+      fields.merge(trace: trace)
+    end
+
+    def buffered_trace
+      context = Buffer.current.context
+      context && context[:trace]
+    end
+
+    # User-supplied content. Will be scanned by Pii::Scanner.
+    def build_user_section(message:, fields:)
+      result = { 'message' => message.to_s }
+      fields.each do |key, value|
+        next if value.nil?
+
+        result[key.to_s] = stringify_keys(value)
+      end
+      result
+    end
+
+    def schema_validator
+      @schema_validator ||= Schema::Validator.new(
+        registry: @configuration.event_action_registry,
+        mode:     @configuration.event_action_validator
+      )
+    end
+
+    def pii_scanner
+      Pii::Scanner.new(
+        strategies:      @configuration.pii_redaction,
+        param_blocklist: @configuration.pii_param_blocklist
+      )
+    end
+
+    def current_timestamp
+      Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%6NZ')
+    end
+
+    def service_payload
+      result = {
+        'name'        => @configuration.service_name.to_s,
+        'version'     => @configuration.service_version.to_s,
+        'environment' => @configuration.service_environment.to_s
+      }
+      # Opt-in (default off): in K8s + Alloy the `pod_name` label already
+      # carries this, so emitting it here would duplicate it on every line.
+      if @configuration.emit_service_instance
+        instance = ENV['HOSTNAME'] || ENV['POD_NAME']
+        result['instance'] = instance unless instance.nil? || instance.empty?
+      end
+      result
+    end
+
+    # Recursively stringifies hash keys for JSON output. Avoids ActiveSupport
+    # dependency for this hot-path operation.
+    def stringify_keys(value)
+      case value
+      when Hash
+        result = {}
+        value.each { |k, v| result[k.to_s] = stringify_keys(v) }
+        result
+      when Array
+        value.map { |item| stringify_keys(item) }
+      else
+        value
+      end
+    end
+
+    def emit(payload)
+      payload = truncate_oversized_params(payload)
+
+      line =
+        case @configuration.format
+        when :pretty then JSON.pretty_generate(payload)
+        else              JSON.generate(payload)
+        end
+      @configuration.output.puts(line)
+    end
+
+    # If the emitted payload exceeds `Configuration#max_log_size_kb`, drop the
+    # contents of `request.params` (typically the biggest field by a wide
+    # margin — full HTTP request body) and flag `request.params_truncated:
+    # true`. Other canonical fields (trace, iugu, rails, http, pii, etc.)
+    # stay intact so observability/audit still works on the truncated log.
+    #
+    # When `max_log_size_kb` is nil, this is a no-op.
+    def truncate_oversized_params(payload)
+      cap_kb = @configuration.max_log_size_kb
+      return payload if cap_kb.nil?
+      return payload unless payload.is_a?(Hash) && payload['request'].is_a?(Hash)
+      return payload unless payload['request']['params']
+
+      cap_bytes = cap_kb * 1024
+      return payload if JSON.generate(payload).bytesize <= cap_bytes
+
+      truncated_request = payload['request'].merge(
+        'params'           => '[TRUNCATED]',
+        'params_truncated' => true
+      )
+      payload.merge('request' => truncated_request)
+    rescue StandardError
+      payload
+    end
+  end
+end