Class: Snails::Logger

Inherits:

Object

• Object
• Snails::Logger

Defined in:

runtime/snails/logger.rb,
runtime/snails/logger.rbs,
runtime/snails/logger/context.rbs,
runtime/snails/logger/delivery.rbs,
runtime/snails/logger/formatter.rbs,
runtime/snails/logger/otlp_transport.rbs,
runtime/snails/logger/record.rbs,
runtime/snails/logger/record_formatter.rbs,
runtime/snails/logger/context.rb,
runtime/snails/logger/delivery.rb,
runtime/snails/logger/formatter.rb,
runtime/snails/logger/otlp_transport.rb,
runtime/snails/logger/record.rb,
runtime/snails/logger/record_formatter.rb

Overview

the runtime's one logger. Apps call the five level methods — with event: when the call is a structured event — and configure the slots above.

Defined Under Namespace

Modules: Context Classes: Delivery, Formatter, OTLPTransport, Record, RecordFormatter

Instance Method Summary

• #after_fork ⇒ void

  make this process's logger its own: a forked child may have inherited a write lock another thread held, and the parent's buffered records would otherwise be sent by every child.

• #debug(message, event: nil, fields: {}, exception: nil) ⇒ void

  write at DEBUG when the level allows it.

• #debug? ⇒ Boolean

  whether a line at this severity would be written now.

• #error(message, event: nil, fields: {}, exception: nil) ⇒ void

  write at ERROR when the level allows it.

• #error? ⇒ Boolean

  whether an error line would be written now.

• #fatal(message, event: nil, fields: {}, exception: nil) ⇒ void

  write at FATAL when the level allows it.

• #fatal? ⇒ Boolean

  whether a fatal line would be written now.

• #flush ⇒ void

  hand every buffered record to the transport now.

• #formatter ⇒ untyped

  the object that renders the five string calls.

• #formatter=(value) ⇒ untyped

  replace the rendering for string calls.

• #host_name ⇒ String

  the host that names the process in resource attributes.

• #host_name=(name) ⇒ String

  set the host that every record's resource carries.

• #info(message, event: nil, fields: {}, exception: nil) ⇒ void

  write at INFO when the level allows it.

• #info? ⇒ Boolean

  whether an info line would be written now.

• #initialize ⇒ Logger constructor

  A new instance of Logger.

• #level ⇒ Symbol

  the minimum severity written, as a Symbol.

• #level=(name) ⇒ Symbol

  pin the level, overriding the mode's default.

• #output ⇒ IO

  the IO log lines are written to.

• #output=(io) ⇒ IO^?

  send log lines somewhere else.

• #progname ⇒ String

  the service name between -- and : in the default line.

• #progname=(name) ⇒ String

  set the service name rendered by the default formatter.

• #record_formatter ⇒ untyped

  the object that renders level calls carrying an event: name.

• #record_formatter=(value) ⇒ untyped

  replace the rendering for structured records.

• #register_flush ⇒ void

  put the periodic buffer flush on the scheduler this process is about to run.

• #report_local(severity, message) ⇒ void

  write one line locally without creating a record or calling the transport.

• #transport ⇒ untyped

  the object that receives structured records, or nil when the logger only writes locally.

• #transport=(value) ⇒ untyped

  replace the record destination.

• #warn(message, event: nil, fields: {}, exception: nil) ⇒ void

  write at WARN when the level allows it.

• #warn? ⇒ Boolean

  whether a warning line would be written now.

Constructor Details

#initialize ⇒ Logger

Returns a new instance of Logger.

# File 'runtime/snails/logger.rbs', line 14

def initialize: () -> void

Instance Method Details

#after_fork ⇒ void

make this process's logger its own: a forked child may have inherited a write lock another thread held, and the parent's buffered records would otherwise be sent by every child. The prefork servers call it as the child's first statement, before the first record; a process that never forked has nothing to reset.

# File 'runtime/snails/logger.rb', line 263

def after_fork: () -> void

#debug(message, event: nil, fields: {}, exception: nil) ⇒ void

write at DEBUG when the level allows it. Without event: the call is a plain line; with event: it is a named record.

Parameters:

• message (untyped) —

  rendered with to_s

• event (String, nil) (defaults to: nil) —

  the stable event name, e.g. request.completed

• fields (Hash{String, Symbol => Object}) (defaults to: {}) —

  simple field values

• exception (Exception, nil) (defaults to: nil) —

  the failure this event reports

Raises:

• (ArgumentError) —

  fields or an exception without an event name

# File 'runtime/snails/logger.rb', line 312

def debug: (untyped message, ?event: String?, ?fields: Hash[untyped, untyped], ?exception: Exception?) -> void

#debug? ⇒ Boolean

whether a line at this severity would be written now.

Returns:

• (Boolean)

# File 'runtime/snails/logger.rb', line 85

def debug?: () -> bool

#error(message, event: nil, fields: {}, exception: nil) ⇒ void

write at ERROR when the level allows it. Without event: the call is a plain line; with event: it is a named record.

Parameters:

• message (untyped) —

  rendered with to_s

• event (String, nil) (defaults to: nil) —

  the stable event name, e.g. job.failed

• fields (Hash{String, Symbol => Object}) (defaults to: {}) —

  simple field values

• exception (Exception, nil) (defaults to: nil) —

  the failure this event reports

Raises:

• (ArgumentError) —

  fields or an exception without an event name

# File 'runtime/snails/logger.rb', line 351

def error: (untyped message, ?event: String?, ?fields: Hash[untyped, untyped], ?exception: Exception?) -> void

#error? ⇒ Boolean

whether an error line would be written now.

Returns:

• (Boolean) —

  see debug?

# File 'runtime/snails/logger.rb', line 106

def error?: () -> bool

#fatal(message, event: nil, fields: {}, exception: nil) ⇒ void

write at FATAL when the level allows it. Without event: the call is a plain line; with event: it is a named record.

Parameters:

• message (untyped) —

  rendered with to_s

• event (String, nil) (defaults to: nil) —

  the stable event name, e.g. job.failed

• fields (Hash{String, Symbol => Object}) (defaults to: {}) —

  simple field values

• exception (Exception, nil) (defaults to: nil) —

  the failure this event reports

Raises:

• (ArgumentError) —

  fields or an exception without an event name

# File 'runtime/snails/logger.rb', line 364

def fatal: (untyped message, ?event: String?, ?fields: Hash[untyped, untyped], ?exception: Exception?) -> void

#fatal? ⇒ Boolean

whether a fatal line would be written now.

Returns:

• (Boolean) —

  see debug?

# File 'runtime/snails/logger.rb', line 113

def fatal?: () -> bool

#flush ⇒ void

hand every buffered record to the transport now. The periodic scheduler calls it; a process shutting down can call it too. A non-fatal delivery outcome is written locally; the caller cannot act on it. Callers here hold no write lock, so the line goes through report_local, which takes it.

# File 'runtime/snails/logger.rb', line 284

def flush: () -> void

#formatter ⇒ untyped

the object that renders the five string calls.

Returns:

• (untyped) —

  the current formatter

# File 'runtime/snails/logger.rb', line 143

def formatter: () -> untyped

#formatter=(value) ⇒ untyped

replace the rendering for string calls. The contract is call(severity, time, progname, message) -> String; the returned string is written as-is, so it must end with a newline. Structured records use record_formatter instead.

Parameters:

• value (untyped) —

  an object answering call

Returns:

• (untyped) —

  the assigned formatter

Raises:

• (ArgumentError) —

  value does not answer call

# File 'runtime/snails/logger.rb', line 155

def formatter=: (untyped value) -> untyped

#host_name ⇒ String

the host that names the process in resource attributes. An unset slot answers ENV["HOSTNAME"] at read time, so a deployment can set the environment variable without touching the app config.

Returns:

• (String) —

  the configured host name, possibly empty

# File 'runtime/snails/logger.rb', line 236

def host_name: () -> String

#host_name=(name) ⇒ String

set the host that every record's resource carries. An empty string omits the attribute rather than sending an empty host.

Parameters:

• name (String) —

  the host name

Returns:

• (String) —

  the assigned name

Raises:

• (ArgumentError) —

  name is not a String

# File 'runtime/snails/logger.rb', line 248

def host_name=: (String name) -> String

#info(message, event: nil, fields: {}, exception: nil) ⇒ void

write at INFO when the level allows it. Without event: the call is a plain line; with event: it is a named record.

Parameters:

• message (untyped) —

  rendered with to_s

• event (String, nil) (defaults to: nil) —

  the stable event name, e.g. request.completed

• fields (Hash{String, Symbol => Object}) (defaults to: {}) —

  simple field values

• exception (Exception, nil) (defaults to: nil) —

  the failure this event reports

Raises:

• (ArgumentError) —

  fields or an exception without an event name

# File 'runtime/snails/logger.rb', line 325

def info: (untyped message, ?event: String?, ?fields: Hash[untyped, untyped], ?exception: Exception?) -> void

#info? ⇒ Boolean

whether an info line would be written now.

Returns:

• (Boolean) —

  see debug?

# File 'runtime/snails/logger.rb', line 92

def info?: () -> bool

#level ⇒ Symbol

the minimum severity written, as a Symbol. Without an explicit level it follows the mode (development :debug, every other mode :info), so an in-process Snails.env= still moves it.

Returns:

• (Symbol) —

  one of :debug, :info, :warn, :error, :fatal

# File 'runtime/snails/logger.rb', line 65

def level: () -> Symbol

#level=(name) ⇒ Symbol

pin the level, overriding the mode's default.

Parameters:

• name (Symbol) —

  one of :debug, :info, :warn, :error, :fatal

Returns:

• (Symbol) —

  the assigned level

Raises:

• (ArgumentError) —

  name is not a known severity

# File 'runtime/snails/logger.rb', line 76

def level=: (Symbol name) -> Symbol

#output ⇒ IO

the IO log lines are written to. An unset output answers $stderr at write time, so an in-process redirection still applies.

Returns:

• (IO) —

  the current destination

# File 'runtime/snails/logger.rb', line 121

def output: () -> untyped

#output=(io) ⇒ IO^?

send log lines somewhere else. A String path is rejected: open the file first and pass the IO, or the typo would silently log nowhere.

Parameters:

• io (IO, nil) —

  an object answering write; nil restores stderr

Returns:

• (IO, nil) —

  the assigned output

Raises:

• (ArgumentError) —

  io is neither nil nor IO-like

# File 'runtime/snails/logger.rb', line 131

def output=: (untyped io) -> untyped

#progname ⇒ String

the service name between -- and : in the default line. Empty by default; an app sharing a log stream with other processes sets its own.

Returns:

• (String) —

  the current progname

# File 'runtime/snails/logger.rb', line 214

def progname: () -> String

#progname=(name) ⇒ String

set the service name rendered by the default formatter.

Parameters:

• name (String) —

  the service name

Returns:

• (String) —

  the assigned name

Raises:

• (ArgumentError) —

  name is not a String

# File 'runtime/snails/logger.rb', line 223

def progname=: (String name) -> String

#record_formatter ⇒ untyped

the object that renders level calls carrying an event: name.

Returns:

• (untyped) —

  the current record formatter

# File 'runtime/snails/logger.rb', line 167

def record_formatter: () -> untyped

#record_formatter=(value) ⇒ untyped

replace the rendering for structured records. The contract is call(record, progname) -> String; the returned string is written as-is, so it must end with a newline. Level calls without an event: name still use formatter.

Parameters:

• value (untyped) —

  an object answering call

Returns:

• (untyped) —

  the assigned record formatter

Raises:

• (ArgumentError) —

  value does not answer call

# File 'runtime/snails/logger.rb', line 179

def record_formatter=: (untyped value) -> untyped

#register_flush ⇒ void

put the periodic buffer flush on the scheduler this process is about to run. ActiveJob::Launcher.start calls it once per server process before it spawns the loops; a second call in the same process does nothing.

# File 'runtime/snails/logger.rb', line 274

def register_flush: () -> void

#report_local(severity, message) ⇒ void

write one line locally without creating a record or calling the transport. The transport and its delivery job use it for their own failures, so a broken destination cannot make logging recurse into itself.

Parameters:

• severity (Symbol) —

  one of :debug, :info, :warn, :error, :fatal

• message (untyped) —

  rendered with to_s

Raises:

• (ArgumentError) —

  severity is not a known severity

# File 'runtime/snails/logger.rb', line 296

def report_local: (Symbol severity, untyped message) -> void

#transport ⇒ untyped

the object that receives structured records, or nil when the logger only writes locally. The slot is owned by Snails::Logger::Delivery, which also isolates a unit delivery failure.

Returns:

• (untyped) —

  the current transport

# File 'runtime/snails/logger.rb', line 193

def transport: () -> untyped

#transport=(value) ⇒ untyped

replace the record destination. The contract is deliver(records) with an Array of Record; nil disables remote delivery. A unit delivery failure is reported locally and does not stop the app; control and fatal exceptions still propagate. Validation and the hand-off live in Delivery.

Parameters:

• value (untyped) —

  an object answering deliver, or nil

Returns:

• (untyped) —

  the assigned transport

Raises:

• (ArgumentError) —

  value is neither nil nor transport-like

# File 'runtime/snails/logger.rb', line 206

def transport=: (untyped value) -> untyped

#warn(message, event: nil, fields: {}, exception: nil) ⇒ void

write at WARN when the level allows it. Without event: the call is a plain line; with event: it is a named record.

Parameters:

• message (untyped) —

  rendered with to_s

• event (String, nil) (defaults to: nil) —

  the stable event name, e.g. request.completed

• fields (Hash{String, Symbol => Object}) (defaults to: {}) —

  simple field values

• exception (Exception, nil) (defaults to: nil) —

  the failure this event reports

Raises:

• (ArgumentError) —

  fields or an exception without an event name

# File 'runtime/snails/logger.rb', line 338

def warn: (untyped message, ?event: String?, ?fields: Hash[untyped, untyped], ?exception: Exception?) -> void

#warn? ⇒ Boolean

whether a warning line would be written now.

Returns:

• (Boolean) —

  see debug?

# File 'runtime/snails/logger.rb', line 99

def warn?: () -> bool