Class: ConvertSdk::LogManager

Inherits:
Object
  • Object
show all
Defined in:
lib/convert_sdk/log_manager.rb

Overview

Multi-sink, level-gated logger with secret redaction wired in by construction.

LogManager is consumed by every manager from the HTTP client (Story 1.5) onward. It fans messages out to any number of stdlib-+Logger+-compatible sinks and guarantees, structurally, that no message reaches a sink without first passing through the Redactor: every public level method funnels through the single private #emit path, and that path applies the loggable conversion boundary and redaction before touching a sink. There is no public method that bypasses #emit.

Levels

Verbosity is gated by the JS-parity LogLevel values (TRACE=0 … SILENT=5). A call at level L emits only when L >= configured_level; SILENT suppresses everything. The stdlib Logger has no trace, so both #trace and #debug dispatch to the sink's #debug — the numeric level value (0 vs 1), not the sink method, decides whether they emit.

Level conventions (callers choose the level by intent):

  • trace / debug — decisioning internals (bucketing, rule evaluation).
  • info — lifecycle events (SDK ready, config refreshed).
  • warn — recoverable conditions (stale config, retry).
  • error — internal failures (parse error, exhausted retries).

Message format

Callers pass messages already formatted as {ClassName}#{method}: {message}. LogManager does not prepend the class name itself — the format is a usage convention, documented here and enforced at call sites.

Thread safety

The sink list is guarded by @sinks_mutex. Compound operations on the list happen inside the lock; the (potentially slow, potentially raising) sink I/O happens outside the lock by iterating a dup snapshot. A sink that raises is contained (rescue StandardError) so a broken sink never crashes the host or starves the other sinks.

Constant Summary collapse

REQUIRED_SINK_METHODS =

The methods every valid sink must respond to (stdlib Logger contract).

%i[debug info warn error].freeze

Instance Method Summary collapse

Constructor Details

#initialize(level: LogLevel::ERROR, sink: nil, secrets: []) ⇒ LogManager

Returns a new instance of LogManager.

Parameters:

  • level (Integer) (defaults to: LogLevel::ERROR) —

    a ConvertSdk::LogLevel threshold; messages below it are suppressed. Defaults to ERROR (quiet by default).

  • sink (Object, nil) (defaults to: nil) —

    an optional initial sink (anything responding to debug/info/warn/error). Invalid sinks are rejected, not raised.

  • secrets (Array<String>) (defaults to: []) —

    secret values to redact from every message. More can be added later via #register_secret.



50
51
52
53
54
55
56
57
 
# File 'lib/convert_sdk/log_manager.rb', line 50

def initialize(level: LogLevel::ERROR, sink: nil, secrets: [])
  @level = level
  @redactor = Redactor.new(secrets)
  @sinks = []
  # Thread safety: guarded by @sinks_mutex.
  @sinks_mutex = Thread::Mutex.new
  add_sink(sink) unless sink.nil?
end

Instance Method Details

#add_sink(sink) ⇒ self

Register a sink. Accepted iff it duck-types to the stdlib Logger contract (responds to debug/info/warn/error). An invalid sink is rejected with a logged error rather than raising — registration must never crash the host.

Parameters:

  • sink (Object) —

    the candidate sink.

Returns:

  • (self) —

    for chaining. A rejected sink is logged, not registered.



69
70
71
72
73
74
75
76
77
 
# File 'lib/convert_sdk/log_manager.rb', line 69

def add_sink(sink)
  if REQUIRED_SINK_METHODS.all? { |m| sink.respond_to?(m) }
    @sinks_mutex.synchronize { @sinks << sink }
  else
    emit(LogLevel::ERROR, "LogManager#add_sink: rejected sink #{sink.class} " \
                          "(must respond to #{REQUIRED_SINK_METHODS.join("/")})")
  end
  self
end

#debug(message) ⇒ Object

Log at DEBUG — decisioning internals. Dispatches to sink #debug.




# File 'lib/convert_sdk/log_manager.rb', line 88

#error(message) ⇒ Object

Log at ERROR — internal failures.




# File 'lib/convert_sdk/log_manager.rb', line 88

#info(message) ⇒ Object

Log at INFO — lifecycle events.




# File 'lib/convert_sdk/log_manager.rb', line 88

#register_secret(secret) ⇒ void

This method returns an undefined value.

Register an additional secret to redact (e.g. once the SDK key is known at ConvertSdk.create time). nil/blank is a no-op.

Parameters:

  • secret (String, nil) 


84
85
86
 
# File 'lib/convert_sdk/log_manager.rb', line 84

def register_secret(secret)
  @redactor.register_secret(secret)
end

#trace(message) ⇒ void

This method returns an undefined value.

Returns log at TRACE (finest-grained); dispatches to the sink's #debug.

Parameters:

  • message (String) —

    the already-formatted message.




# File 'lib/convert_sdk/log_manager.rb', line 88

#warn(message) ⇒ Object

Log at WARN — recoverable conditions.




# File 'lib/convert_sdk/log_manager.rb', line 88