Class: Snails::Logger::Record

Inherits:

Object

• Object
• Snails::Logger::Record

Defined in:

runtime/snails/logger/record.rbs,
runtime/snails/logger/record.rb

Constant Summary

SEVERITIES =

Severities in increasing order — the same vocabulary the logger's level gate accepts.

[ :debug, :info, :warn, :error, :fatal ].freeze

SCHEMA_VERSION =

The field contract version — bump when a field is renamed or removed.

1

RESERVED_FIELDS =

Names the record owns, plus the context fields the logger sets. A caller field with one of these names is refused rather than silently overwriting the record's identity or correlation data.

[
  "event.name",
  "body",
  "severity",
  "severityNumber",
  "severityText",
  "timeUnixNano",
  "snails.request_id",
  "snails.controller",
  "snails.action",
  "snails.job.name",
  "snails.job.id",
  "snails.job.attempt",
  "snails.batch_id",
  "snails.seq",
  "exception.type",
  "exception.message",
  "exception.stacktrace",
  "service.name",
  "service.version",
  "host.name",
  "process.pid",
  "deployment.environment.name",
  "snails.version",
  "snails.rev",
  "snails.log.schema_version"
].freeze

FIELD_PATTERN =

A field name is one or more dot-separated identifiers; the underscore and hyphen cover OTel and snails names without allowing whitespace or punctuation that would make a key ambiguous.

/\A[A-Za-z][A-Za-z0-9_.-]*\z/

EVENT_PATTERN =

An event name is lowercase dot-separated segments: request.completed, job.failed, worker.loop_stopped, app.log.

/\A[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+\z/

Instance Method Summary

• #body ⇒ String

  the human-readable message.

• #event ⇒ String

  the stable event name.

• #exception ⇒ Exception^?

  the failure this record reports, when any.

• #exception_message ⇒ String^?

  the exception message as a field value.

• #exception_stacktrace ⇒ String^?

  the backtrace joined into one string.

• #exception_type ⇒ String^?

  the exception class name as a field value.

• #fields ⇒ Hash{String => Object}

  the caller fields merged with logger context.

• #initialize(severity, event, body, fields: {}, exception: nil, time: nil, context: {}, resource: {}) ⇒ Record constructor

  build one record.

• #resource ⇒ Hash{String => Object}

  the service/process attributes for the transport.

• #severity ⇒ Symbol

  the record's severity.

• #time ⇒ Time

  the event time.

Constructor Details

#initialize(severity, event, body, fields: {}, exception: nil, time: nil, context: {}, resource: {}) ⇒ Record

build one record. fields are caller-owned and checked against RESERVED_FIELDS; context carries the request/job correlation the logger already validated, so those names are allowed there; resource carries the service/process attributes the transport sends per batch.

Parameters:

• severity (Symbol) —

  one of SEVERITIES

• event (String) —

  the stable event name

• body (String) —

  the human-readable message

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

  caller fields

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

  the failure this record reports

• time (Time, nil) (defaults to: nil) —

  the event time; defaults to the current UTC time

• context (Hash{String => Object}) (defaults to: {}) —

  logger-owned correlation fields

• resource (Hash{String => Object}) (defaults to: {}) —

  service/process attributes

Raises:

• (ArgumentError) —

  a severity, event, field, value, exception, or time outside the contract

# File 'runtime/snails/logger/record.rb', line 79

def initialize: (

Instance Method Details

#body ⇒ String

the human-readable message.

Returns:

• (String)

# File 'runtime/snails/logger/record.rb', line 122

def body: () -> String

#event ⇒ String

the stable event name.

Returns:

• (String) —

  e.g. request.completed

# File 'runtime/snails/logger/record.rb', line 115

def event: () -> String

#exception ⇒ Exception^?

the failure this record reports, when any.

Returns:

• (Exception, nil)

# File 'runtime/snails/logger/record.rb', line 145

def exception: () -> Exception?

#exception_message ⇒ String^?

the exception message as a field value.

Returns:

• (String, nil)

# File 'runtime/snails/logger/record.rb', line 166

def exception_message: () -> String?

#exception_stacktrace ⇒ String^?

the backtrace joined into one string.

Returns:

• (String, nil) —

  nil when there is no exception or no backtrace

# File 'runtime/snails/logger/record.rb', line 173

def exception_stacktrace: () -> String?

#exception_type ⇒ String^?

the exception class name as a field value.

Returns:

• (String, nil)

# File 'runtime/snails/logger/record.rb', line 159

def exception_type: () -> String?

#fields ⇒ Hash{String => Object}

the caller fields merged with logger context.

Returns:

• (Hash{String => Object}) —

  the record's field bag

# File 'runtime/snails/logger/record.rb', line 129

def fields: () -> Hash[String, untyped]

#resource ⇒ Hash{String => Object}

the service/process attributes for the transport. The local formatter does not render them; an OTLP transport sends them once per batch rather than on every record.

Returns:

• (Hash{String => Object}) —

  the resource attribute bag

# File 'runtime/snails/logger/record.rb', line 138

def resource: () -> Hash[String, untyped]

#severity ⇒ Symbol

the record's severity.

Returns:

• (Symbol) —

  one of SEVERITIES

# File 'runtime/snails/logger/record.rb', line 108

def severity: () -> Symbol

#time ⇒ Time

the event time.

Returns:

• (Time)

# File 'runtime/snails/logger/record.rb', line 152

def time: () -> Time