Class: Assistant::LogItem

Inherits:
Object
  • Object
show all
Defined in:
lib/assistant/log_item.rb

Overview

A single structured log entry produced by Service (directly via LogList#add_log or through one of the log_item_* shorthands). Construction is strict since 1.0 (M10): invalid attributes raise ArgumentError rather than producing an instance whose #valid? returns false. See docs/v1/06-migration-0x-to-1.md for the rationale.

Examples:

Build an error log entry

Assistant::LogItem.new(
  level: :error,
  source: :create_user,
  detail: :email,
  message: 'must not be blank'
)

Constant Summary collapse

VALID_LEVELS =

The exhaustive set of accepted level: values, in display order.

Returns:

  • (Array<Symbol>) 
%i[info warning error].freeze
ERRORS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Validation rules applied in #initialize. Each entry pairs a human message with the predicate that must hold. Internal.

[
  ["level must be one of [#{VALID_LEVELS.join(', ')}]", :valid_level?],
  ['source must be present and different from detail', :valid_source?],
  ['detail must be present and different from source', :valid_detail?],
  ['message must be present', :valid_message?]
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(level:, source:, detail:, message:, trace: nil) ⇒ LogItem

Returns a new instance of LogItem.

Parameters:

  • level (Symbol, #to_sym) —

    one of VALID_LEVELS

  • source (Symbol, #to_sym) —

    subsystem identifier; must differ from detail

  • detail (Symbol, #to_sym) —

    sub-identifier; must differ from source

  • message (#to_s) —

    human-readable message; must not be blank

  • trace (Array<String>, nil) (defaults to: nil) —

    optional backtrace

Raises:

  • (ArgumentError) —

    when any of the constructor checks in ERRORS fail



51
52
53
54
55
56
57
58
 
# File 'lib/assistant/log_item.rb', line 51

def initialize(level:, source:, detail:, message:, trace: nil)
  @level = normalize_symbol(level)
  @source = normalize_symbol(source)
  @detail = normalize_symbol(detail)
  @message = message.to_s
  @trace = trace
  validate!
end

Instance Attribute Details

#detail ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    severity (:info, :warning, or :error)

  • (Symbol) —

    high-level subsystem the entry came from (e.g. :initialize, :hook)

  • (Symbol) —

    finer-grained detail under source (often an attribute name)

  • (String) —

    human-readable message

  • (Array<String>, nil) —

    optional backtrace captured at construction



43
 
# File 'lib/assistant/log_item.rb', line 43

attr_reader :level, :source, :detail, :message, :trace

#level ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    severity (:info, :warning, or :error)

  • (Symbol) —

    high-level subsystem the entry came from (e.g. :initialize, :hook)

  • (Symbol) —

    finer-grained detail under source (often an attribute name)

  • (String) —

    human-readable message

  • (Array<String>, nil) —

    optional backtrace captured at construction



43
44
45
 
# File 'lib/assistant/log_item.rb', line 43

def level
  @level
end

#message ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    severity (:info, :warning, or :error)

  • (Symbol) —

    high-level subsystem the entry came from (e.g. :initialize, :hook)

  • (Symbol) —

    finer-grained detail under source (often an attribute name)

  • (String) —

    human-readable message

  • (Array<String>, nil) —

    optional backtrace captured at construction



43
 
# File 'lib/assistant/log_item.rb', line 43

attr_reader :level, :source, :detail, :message, :trace

#source ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    severity (:info, :warning, or :error)

  • (Symbol) —

    high-level subsystem the entry came from (e.g. :initialize, :hook)

  • (Symbol) —

    finer-grained detail under source (often an attribute name)

  • (String) —

    human-readable message

  • (Array<String>, nil) —

    optional backtrace captured at construction



43
 
# File 'lib/assistant/log_item.rb', line 43

attr_reader :level, :source, :detail, :message, :trace

#trace ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol) —

    severity (:info, :warning, or :error)

  • (Symbol) —

    high-level subsystem the entry came from (e.g. :initialize, :hook)

  • (Symbol) —

    finer-grained detail under source (often an attribute name)

  • (String) —

    human-readable message

  • (Array<String>, nil) —

    optional backtrace captured at construction



43
 
# File 'lib/assistant/log_item.rb', line 43

attr_reader :level, :source, :detail, :message, :trace

Instance Method Details

#item ⇒ Hash{Symbol => Object}

Returns hash view with keys :level, :source, :detail, :message, :trace.

Returns:

  • (Hash{Symbol => Object}) —

    hash view with keys :level, :source, :detail, :message, :trace



65
66
67
 
# File 'lib/assistant/log_item.rb', line 65

def item
  { level:, source:, detail:, message:, trace: }
end

#valid? ⇒ Boolean

Returns always true for instances constructed via #initialize (which raises on invalid input). Retained for introspection and downstream tooling.

Returns:

  • (Boolean) —

    always true for instances constructed via #initialize (which raises on invalid input). Retained for introspection and downstream tooling.



62
 
# File 'lib/assistant/log_item.rb', line 62

def valid? = [valid_level?, valid_source?, valid_detail?, valid_message?].all?

#valid_detail? ⇒ Boolean

Returns true when detail is non-empty and not equal to source.

Returns:

  • (Boolean) —

    true when detail is non-empty and not equal to source



83
 
# File 'lib/assistant/log_item.rb', line 83

def valid_detail? = present_log_attribute?(detail) && source != detail

#valid_level? ⇒ Boolean

Returns true when level is one of VALID_LEVELS.

Returns:



77
 
# File 'lib/assistant/log_item.rb', line 77

def valid_level? = VALID_LEVELS.include?(level)

#valid_message? ⇒ Boolean

Returns true when message contains at least one non-whitespace character.

Returns:

  • (Boolean) —

    true when message contains at least one non-whitespace character



86
 
# File 'lib/assistant/log_item.rb', line 86

def valid_message? = !message.strip.empty?

#valid_source? ⇒ Boolean

Returns true when source is non-empty and not equal to detail.

Returns:

  • (Boolean) —

    true when source is non-empty and not equal to detail



80
 
# File 'lib/assistant/log_item.rb', line 80

def valid_source? = present_log_attribute?(source) && detail != source