iugu_logger 0.10.0

data/lib/iugu_logger/schema.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module IuguLogger
+  # event.action registry validator.
+  #
+  # Loads a compiled event.action registry (`dist/registry.json`) and validates
+  # each `event.action` emitted against it.
+  #
+  # Three modes:
+  #   :strict — raise IuguLogger::UnknownEventAction / SchemaViolation
+  #   :warn   — annotate the emitted log with `labels.schema_warning` and proceed
+  #   :off    — disable validation (default — backward compatible)
+  #
+  # When validation passes and the registry definition declares an
+  # `event_kind` (e.g. `pix.out.executed` is audit-class), the validator
+  # surfaces it so the Logger can override the caller's default.
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §4
+  module Schema
+    STRICT = :strict
+    WARN   = :warn
+    OFF    = :off
+
+    DEFAULT_MODE = OFF
+    VALID_MODES  = [STRICT, WARN, OFF].freeze
+
+    SUGGESTION_LIMIT      = 3
+    SUGGESTION_MAX_DISTANCE = 6 # cap, otherwise unrelated names show up
+
+    # Loads a registry.json from a path on disk. Errors fail loud — registry
+    # loading is dev-time configuration, not runtime.
+    def self.load_from_file(path)
+      JSON.parse(File.read(path))
+    end
+
+    # Frozen result of a single validate call.
+    # Plain class (not Struct keyword_init: which only landed in Ruby 2.5).
+    class Result
+      attr_reader :status, :event_kind, :missing_fields, :suggestions
+
+      def initialize(status:, event_kind: nil, missing_fields: [], suggestions: [])
+        @status         = status
+        @event_kind     = event_kind
+        @missing_fields = missing_fields
+        @suggestions    = suggestions
+        freeze
+      end
+
+      def ok?;               status == :ok;                end
+      def off?;              status == :off;               end
+      def unknown_action?;   status == :unknown_action;    end
+      def missing_required?; status == :missing_required; end
+    end
+
+    class Validator
+      attr_reader :mode
+
+      def initialize(registry: nil, mode: DEFAULT_MODE)
+        unless VALID_MODES.include?(mode)
+          raise ConfigurationError,
+                "unknown event_action_validator mode: #{mode.inspect} (expected :strict, :warn, :off)"
+        end
+
+        @mode     = mode
+        @registry = normalize_registry(registry)
+      end
+
+      def known?(action)
+        return false if @registry.nil?
+
+        @registry['events'].key?(action.to_s)
+      end
+
+      def event_definition(action)
+        return nil if @registry.nil?
+
+        @registry['events'][action.to_s]
+      end
+
+      def validate(action, payload)
+        return Result.new(status: :off) if @mode == OFF || @registry.nil?
+
+        defn = event_definition(action)
+        return Result.new(status: :unknown_action, suggestions: suggestions_for(action)) if defn.nil?
+
+        missing = (defn['required_fields'] || []).reject { |path| field_present?(payload, path) }
+        return Result.new(status: :missing_required, missing_fields: missing) unless missing.empty?
+
+        Result.new(status: :ok, event_kind: defn['event_kind'])
+      end
+
+      # Levenshtein-based typo suggestions for unknown actions.
+      def suggestions_for(action)
+        return [] if @registry.nil?
+
+        target = action.to_s
+        @registry['events'].keys
+                           .map { |a| [a, levenshtein(target, a)] }
+                           .reject { |(_, dist)| dist > SUGGESTION_MAX_DISTANCE }
+                           .sort_by(&:last)
+                           .first(SUGGESTION_LIMIT)
+                           .map(&:first)
+      end
+
+      private
+
+      def normalize_registry(registry)
+        return nil if registry.nil?
+        return registry if registry.is_a?(Hash) && registry['events'].is_a?(Hash)
+
+        raise ConfigurationError, 'event_action_registry must be a Hash with an "events" key'
+      end
+
+      # Walks a dot-namespaced path inside a payload Hash. Returns true if the
+      # leaf is present and non-empty. Both string and symbol keys accepted.
+      def field_present?(payload, dotted_path)
+        parts = dotted_path.to_s.split('.')
+        current = payload
+
+        parts.each do |part|
+          return false unless current.is_a?(Hash)
+
+          if current.key?(part)
+            current = current[part]
+          elsif current.key?(part.to_sym)
+            current = current[part.to_sym]
+          else
+            return false
+          end
+        end
+
+        return false if current.nil?
+        return false if current.respond_to?(:empty?) && current.empty?
+
+        true
+      end
+
+      # Standard iterative Levenshtein, stdlib only — fine for registries with
+      # ≤500 events (linear scan per validate call is acceptable; this only
+      # runs on the slow path of unknown actions).
+      def levenshtein(a, b)
+        return b.length if a.empty?
+        return a.length if b.empty?
+
+        m = a.length
+        n = b.length
+        prev = (0..n).to_a
+
+        (1..m).each do |i|
+          curr = [i] + Array.new(n, 0)
+          (1..n).each do |j|
+            cost = a[i - 1] == b[j - 1] ? 0 : 1
+            curr[j] = [
+              curr[j - 1] + 1,    # insertion
+              prev[j] + 1,        # deletion
+              prev[j - 1] + cost  # substitution
+            ].min
+          end
+          prev = curr
+        end
+
+        prev[n]
+      end
+    end
+  end
+end

data/lib/iugu_logger/severity.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  # Custom severity levels — includes :note (between :info and :warn) for
+  # business-critical events that should NOT be filtered as framework noise.
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §2.1 (custom :note severity pattern)
+  module Severity
+    TRACE = 0
+    DEBUG = 1
+    INFO  = 2
+    NOTE  = 3
+    WARN  = 4
+    ERROR = 5
+    FATAL = 6
+
+    NAMES = {
+      TRACE => 'trace',
+      DEBUG => 'debug',
+      INFO  => 'info',
+      NOTE  => 'note',
+      WARN  => 'warn',
+      ERROR => 'error',
+      FATAL => 'fatal'
+    }.freeze
+
+    BY_NAME = NAMES.each_with_object({}) { |(num, name), h| h[name.to_sym] = num }.freeze
+
+    module_function
+
+    # Integer severity for the given name (string or symbol). nil if unknown.
+    def from_name(name)
+      BY_NAME[name.to_sym]
+    end
+
+    def name_for(level)
+      NAMES[level]
+    end
+
+    def valid?(name)
+      BY_NAME.key?(name.to_sym)
+    end
+  end
+end

data/lib/iugu_logger/smoke_test.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'stringio'
+
+module IuguLogger
+  # Self-contained smoke test for the SDK. Verifies the consuming app's
+  # configuration is valid AND that emit / PII redaction / canonical
+  # schema work end-to-end. Used by:
+  #
+  #   bundle exec rake iugu_logger:smoke
+  #
+  # Output is human-readable and the run returns true on success / false on
+  # any failure. Exit code is set by the rake task wrapper.
+  module SmokeTest
+    CHECKS = %i[
+      sdk_loaded
+      configuration_present
+      basic_emit
+      pii_detection
+      account_id_safe_pattern
+      single_line_json
+    ].freeze
+
+    module_function
+
+    def run(io: $stdout)
+      io.puts "iugu_logger #{IuguLogger::VERSION} — smoke test"
+      io.puts '-' * 56
+
+      failures = []
+
+      CHECKS.each do |name|
+        result = send("check_#{name}")
+        if result == :ok
+          io.puts "  ✓ #{name}"
+        else
+          io.puts "  ✗ #{name}: #{result}"
+          failures << name
+        end
+      end
+
+      io.puts '-' * 56
+
+      if failures.empty?
+        io.puts 'OK — all checks passed.'
+        true
+      else
+        io.puts "FAIL — #{failures.size} check(s) failed: #{failures.join(', ')}"
+        false
+      end
+    end
+
+    # ─── checks ────────────────────────────────────────────────────────────
+
+    def check_sdk_loaded
+      missing = %i[Logger Pii Configuration Severity Buffer].reject do |const|
+        IuguLogger.const_defined?(const)
+      end
+      return :ok if missing.empty?
+
+      "missing IuguLogger::#{missing.join(', IuguLogger::')}"
+    end
+
+    def check_configuration_present
+      cfg = IuguLogger.configuration
+      return 'service_name is blank' if blank?(cfg.service_name)
+      return 'service_version is blank' if blank?(cfg.service_version)
+      return 'service_environment is blank' if blank?(cfg.service_environment)
+
+      :ok
+    end
+
+    def check_basic_emit
+      payload = capture_emit do |logger|
+        logger.event('iugu_logger.smoke.ok', message: 'smoke')
+      end
+      return 'no payload emitted' if payload.nil?
+      return "missing @timestamp" if payload['@timestamp'].to_s.empty?
+      return "wrong event.action: #{payload['event.action'].inspect}" if payload['event.action'] != 'iugu_logger.smoke.ok'
+      return 'pii.scanned should be true' unless payload.dig('pii', 'scanned') == true
+
+      :ok
+    end
+
+    # v0.7+ default strategies are :detect_only for personal data. This
+    # check validates that CPF is DETECTED (so audit + tagging work) but
+    # the content is preserved (operators / fraud analysts / support need
+    # the raw value to do their jobs). For apps that need stricter
+    # redaction, override `c.pii_redaction = ...` in the initializer.
+    def check_pii_detection
+      payload = capture_emit do |logger|
+        logger.event('iugu_logger.smoke.pii', message: 'smoke for CPF 123.456.789-09')
+      end
+
+      detected = payload.dig('pii', 'detected') || []
+      return "pii.detected missing 'cpf' (#{detected.inspect})" unless detected.include?('cpf')
+      unless payload['message'].to_s.include?('123.456.789-09')
+        return 'CPF was modified in message (expected :detect_only default)'
+      end
+
+      :ok
+    end
+
+    def check_account_id_safe_pattern
+      account_id = 'EB450085C67C482BA652988813DAB1A5'
+      payload = capture_emit do |logger|
+        logger.event('iugu_logger.smoke.account_id',
+                     iugu:    { account_id: account_id },
+                     message: "smoke for account #{account_id}")
+      end
+
+      unless payload.dig('iugu', 'account_id') == account_id
+        return 'iugu.account_id 32-hex was modified (should be SAFE_PATTERN, ILS-002)'
+      end
+      unless payload['message'].to_s.include?(account_id)
+        return 'account_id was redacted from message (should be SAFE_PATTERN, ILS-002)'
+      end
+
+      :ok
+    end
+
+    def check_single_line_json
+      io = StringIO.new
+      with_isolated_logger(io: io, format: :json) do |logger|
+        logger.event('iugu_logger.smoke.json_line', message: 'one-liner test')
+      end
+      raw = io.string
+      lines = raw.lines
+      return "expected 1 line, got #{lines.size}" if lines.size != 1
+      return 'output should end with newline' unless raw.end_with?("\n")
+
+      JSON.parse(raw.strip)
+      :ok
+    rescue JSON::ParserError => e
+      "JSON parse failed: #{e.message}"
+    end
+
+    # ─── helpers ───────────────────────────────────────────────────────────
+
+    def capture_emit(&block)
+      io = StringIO.new
+      with_isolated_logger(io: io, format: :json, &block)
+      raw = io.string.strip
+      return nil if raw.empty?
+
+      JSON.parse(raw)
+    end
+
+    # Builds an isolated Logger that mirrors the host app's configuration
+    # but writes to `io` and forces JSON format. The host app's logger and
+    # configuration are left untouched.
+    def with_isolated_logger(io:, format: :json)
+      base = IuguLogger.configuration
+
+      cfg = IuguLogger::Configuration.new
+      cfg.service_name        = base.service_name        || 'iugu-logger-smoke'
+      cfg.service_version     = base.service_version     || IuguLogger::VERSION
+      cfg.service_environment = base.service_environment || 'test'
+      cfg.format              = format
+      cfg.output              = io
+      cfg.pii_redaction       = base.pii_redaction
+      cfg.pii_param_blocklist = base.pii_param_blocklist
+
+      yield IuguLogger::Logger.new(cfg)
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/iugu_logger/tasks/iugu_logger.rake

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Rake tasks loaded by the Railtie when iugu_logger boots inside Rails.
+# Standalone Ruby apps can `require 'iugu_logger/tasks/iugu_logger.rake'`
+# from their own Rakefile to expose the same tasks.
+
+namespace :iugu_logger do
+  desc 'Smoke-test the local iugu_logger setup (config + emit + PII + canonical schema).'
+  task smoke: :environment do
+    require 'iugu_logger/smoke_test'
+    abort('iugu_logger smoke test failed') unless IuguLogger::SmokeTest.run
+  end
+end

data/lib/iugu_logger/tenant_context.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  # Tenant (iugu domain) context extractor.
+  #
+  # Reads tenant identifiers from a Rack env hash and builds a Hash compatible
+  # with the canonical `iugu.*` block of the schema. Convention is for
+  # platform/core to populate the env in middleware (e.g. after authentication)
+  # under the `iugu.current_*` namespace.
+  #
+  # Default key mapping per IUGU_LOGGING_STANDARD.md §6.3:
+  #
+  #   env['iugu.current_account_id']      → iugu.account_id
+  #   env['iugu.current_subaccount_id']   → iugu.subaccount_id
+  #   env['iugu.current_organization_id'] → iugu.organization_id
+  #   env['iugu.current_user_id']         → iugu.user_id
+  #   env['iugu.current_tier']            → iugu.tier
+  #   env['iugu.current_feature']         → iugu.feature
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §6.3
+  module TenantContext
+    DEFAULT_RACK_KEYS = {
+      'iugu.current_account_id'      => 'account_id',
+      'iugu.current_subaccount_id'   => 'subaccount_id',
+      'iugu.current_organization_id' => 'organization_id',
+      'iugu.current_user_id'         => 'user_id',
+      'iugu.current_tier'            => 'tier',
+      'iugu.current_feature'         => 'feature'
+    }.freeze
+
+    module_function
+
+    # Extract tenant context from a Rack env. Returns an empty hash when
+    # nothing matched — Logger then emits without `iugu` block.
+    #
+    # @param rack_env [Hash, nil] env hash; nil returns {}
+    # @param key_mapping [Hash] override the default rack-key → iugu-field map
+    # @return [Hash] string-keyed iugu context (suitable to pass as `iugu:` kwarg)
+    def from_rack(rack_env, key_mapping: DEFAULT_RACK_KEYS)
+      return {} if rack_env.nil?
+
+      result = {}
+      key_mapping.each do |rack_key, iugu_key|
+        value = rack_env[rack_key]
+        next if value.nil?
+        next if value.respond_to?(:empty?) && value.empty?
+
+        result[iugu_key] = value
+      end
+      result
+    end
+  end
+end

data/lib/iugu_logger/trace_context.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  # Trace context extractor — W3C / OpenTelemetry / Datadog / legacy header chain.
+  #
+  # Builds a {'id' => trace_id_32hex, 'span_id' => span_id_16hex,
+  # 'parent_id' => parent_span_id_16hex, 'source' => <origin>,
+  # 'sampled' => bool} Hash compatible with the canonical `trace.*` ECS+OTEL
+  # fields. Values (`id`/`span_id`) come straight from OpenTelemetry when the
+  # SDK is active, so the ECS names already carry the OTEL identifiers.
+  #
+  # `source` records WHERE the context came from (opentelemetry / datadog /
+  # w3c / request_id) and `sampled` mirrors the trace-flags sampling decision
+  # when the source exposes it.
+  #
+  # `parent_id` is backfilled from an inbound W3C `traceparent` when a live
+  # tracer continued an upstream trace — present means the trace was continued
+  # from another service, nil means it was rooted in this call.
+  #
+  # `otel` is a diagnostic added by {.extract}: when the OpenTelemetry SDK is
+  # bundled but never configured (so trace context silently fell back to a
+  # header/request-id source), it is set to "not_configured" so the
+  # misconfiguration is queryable in the log stream.
+  #
+  # Source priority (first non-nil wins):
+  #   1. OpenTelemetry::Trace.current_span — when otel-api is loaded
+  #      (Ruby >= 2.6 in practice; the gem itself enforces this)
+  #   2. Datadog::Tracing.active_trace    — when ddtrace gem is loaded
+  #      (works on Ruby 2.4 with ddtrace ~> 0.45)
+  #   3. W3C `traceparent` header         — manual parse, version-agnostic
+  #   4. Legacy iugu `X-Request-Id`       — padded to 32 hex (correlation only,
+  #      not a real trace ID; better than nothing for platform Ruby 2.4)
+  #
+  # Returns nil when no source has trace context — Logger emits without trace.*
+  # block (it is optional in the schema).
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §6.2.2
+  module TraceContext
+    TRACEPARENT_REGEX = /\A(\d{2})-([a-f0-9]{32})-([a-f0-9]{16})-([a-f0-9]{2})\z/.freeze
+
+    EMPTY_SPAN_ID = '0000000000000000'
+
+    module_function
+
+    # Main entry point — tries each source in priority order.
+    #
+    # @param rack_env [Hash, nil] Rack env hash (for header sources). Pass
+    #   `request.env` from a controller, or nil if not in a request.
+    # @return [Hash, nil] {'id' =>, 'span_id' =>, 'parent_id' =>} or nil
+    def extract(rack_env: nil)
+      result = from_opentelemetry ||
+               from_datadog ||
+               from_w3c_header(rack_env) ||
+               from_legacy_header(rack_env)
+
+      result = backfill_parent_id(result, rack_env)
+      annotate_otel_health(result)
+    end
+
+    # A live tracer (OTEL/Datadog) creates the local span, but its SpanContext
+    # doesn't expose the parent — only `trace_id`/`span_id`. When the request
+    # arrived with a W3C `traceparent` whose trace_id matches the active trace,
+    # that header's span_id IS the upstream caller's span (our parent), so we
+    # backfill `parent_id` with it. The net effect:
+    #   - parent_id present → trace was CONTINUED from another service;
+    #   - parent_id nil     → trace was ROOTED in this call.
+    # Skipped for the `w3c` fallback source (there the header span_id is
+    # already reported as `span_id`, so it has no distinct local parent) and
+    # for `request_id` (no real trace).
+    def backfill_parent_id(result, rack_env)
+      return result if result.nil? || rack_env.nil?
+      return result unless %w[opentelemetry datadog].include?(result['source'])
+      return result unless result['parent_id'].nil?
+
+      header = rack_env['HTTP_TRACEPARENT'] || rack_env['traceparent']
+      return result if header.nil? || header.to_s.empty?
+
+      match = TRACEPARENT_REGEX.match(header.to_s.strip)
+      return result if match.nil?
+
+      _, header_trace_id, header_span_id, _flags = match.captures
+      return result unless header_trace_id == result['id']
+
+      result['parent_id'] = header_span_id
+      result
+    end
+
+    # Adds `otel: "not_configured"` when the OpenTelemetry SDK is bundled but
+    # no SDK tracer provider is active (i.e. `OpenTelemetry::SDK.configure`
+    # never ran). That state means the trace context above came from a
+    # fallback source, not from a live span — almost always a boot
+    # misconfiguration worth surfacing. Stays silent (no field) when:
+    #   - OTEL SDK isn't bundled at all (Datadog / platform Ruby 2.4 apps), or
+    #   - the SDK is active (`status == 'active'`).
+    # When OTEL is misconfigured but there was no trace context whatsoever,
+    # still returns a hash carrying only the diagnostic so it isn't lost.
+    def annotate_otel_health(result)
+      status = otel_status
+      return result if status.nil? || status == 'active'
+
+      result ||= {}
+      result['otel'] = status
+      result
+    end
+
+    # @return [String, nil] 'active' / 'not_configured' when the OTEL SDK is
+    #   bundled, nil when it isn't (we don't opine on apps that never shipped
+    #   OpenTelemetry).
+    def otel_status
+      return nil unless defined?(::OpenTelemetry::SDK)
+
+      provider_class = ::OpenTelemetry.tracer_provider.class.name.to_s
+      provider_class.start_with?('OpenTelemetry::SDK') ? 'active' : 'not_configured'
+    rescue StandardError
+      nil
+    end
+
+    def from_opentelemetry
+      return nil unless defined?(::OpenTelemetry::Trace)
+
+      span = ::OpenTelemetry::Trace.current_span
+      return nil if span.nil?
+
+      ctx = span.context
+      return nil if ctx.nil?
+      return nil unless ctx.respond_to?(:valid?) && ctx.valid?
+
+      flags   = ctx.respond_to?(:trace_flags) ? ctx.trace_flags : nil
+      sampled = flags.respond_to?(:sampled?) ? flags.sampled? : nil
+
+      trace = {
+        'id'        => ctx.hex_trace_id,
+        'span_id'   => ctx.hex_span_id,
+        'parent_id' => nil,
+        'source'    => 'opentelemetry'
+      }
+      trace['sampled'] = sampled unless sampled.nil?
+      trace
+    rescue StandardError
+      # Defensive: never let a tracing-lib oddity break logging
+      nil
+    end
+
+    def from_datadog
+      return nil unless defined?(::Datadog::Tracing)
+
+      trace = ::Datadog::Tracing.active_trace
+      return nil if trace.nil?
+
+      span = ::Datadog::Tracing.active_span
+      span_id = span.respond_to?(:id) ? span.id : nil
+
+      {
+        'id'        => format('%032x', trace.id),
+        'span_id'   => span_id ? format('%016x', span_id) : EMPTY_SPAN_ID,
+        'parent_id' => nil,
+        'source'    => 'datadog'
+      }
+    rescue StandardError
+      nil
+    end
+
+    def from_w3c_header(rack_env)
+      return nil if rack_env.nil?
+
+      header = rack_env['HTTP_TRACEPARENT'] || rack_env['traceparent']
+      return nil if header.nil? || header.empty?
+
+      match = TRACEPARENT_REGEX.match(header.to_s.strip)
+      return nil if match.nil?
+
+      _, trace_id, span_id, flags = match.captures
+      trace = {
+        'id'        => trace_id,
+        'span_id'   => span_id,
+        'parent_id' => nil,
+        'source'    => 'w3c'
+      }
+      # traceparent flags: bit 0 (0x01) is the sampled flag (W3C §3.3.1).
+      trace['sampled'] = (flags.to_i(16) & 0x01) == 1 if flags
+      trace
+    end
+
+    # Last-resort fallback: derive a deterministic 32-hex trace_id from the
+    # iugu legacy X-Request-Id (or Rails action_dispatch.request_id). NOT a
+    # real W3C trace ID — only good for correlating logs within a single
+    # service. Used by platform/Ruby 2.4 where OTEL is unavailable.
+    def from_legacy_header(rack_env)
+      return nil if rack_env.nil?
+
+      raw = rack_env['HTTP_X_REQUEST_ID'] ||
+            rack_env['action_dispatch.request_id'] ||
+            rack_env['HTTP_REQUEST_ID']
+      return nil if raw.nil? || raw.to_s.empty?
+
+      hex = raw.to_s.gsub(/[^a-f0-9]/i, '').downcase[0, 32].to_s
+      return nil if hex.empty?
+
+      hex = hex.ljust(32, '0')
+      return nil if hex == ('0' * 32)
+
+      {
+        'id'        => hex,
+        'span_id'   => EMPTY_SPAN_ID,
+        'parent_id' => nil,
+        'source'    => 'request_id'
+      }
+    end
+  end
+end

data/lib/iugu_logger/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  VERSION = '0.10.0'
+end