Class: IuguLogger::Logger

Inherits:
Object
  • Object
show all
Defined in:
lib/iugu_logger/logger.rb

Overview

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

Constant Summary collapse

EVENT_KIND_DEFAULT = 
'event'
DEFAULT_SEVERITY = 
:info

Instance Method Summary collapse

Constructor Details

#initialize(configuration) ⇒ Logger

Returns a new instance of Logger.



19
20
21
22
 
# File 'lib/iugu_logger/logger.rb', line 19

def initialize(configuration)
  @configuration = configuration
  @configuration.validate!
end

Instance Method Details

#event(action, severity: nil, kind: nil, message: nil, **fields) ⇒ Object

Emits a structured event log.

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:`.

Examples:

logger.event('pix.out.requested',
             pix:  { end_to_end_id: e2e, amount_brl: 100 },
             iugu: { account_id: .id })

with explicit severity and kind

logger.event('pix.out.timeout', severity: :error, message: 'jdpi timeout')

Raises:

  • (ArgumentError) 


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/iugu_logger/logger.rb', line 42

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