Class: SemanticLogger::Appender::File

Inherits:
Subscriber show all
Defined in:
lib/semantic_logger/appender/file.rb

Instance Attribute Summary collapse

Attributes inherited from Subscriber

#application, #environment, #formatter, #host, #logger, #metrics

Attributes inherited from Base

#filter, #name

Instance Method Summary collapse

Methods inherited from Subscriber

#close, #console_output?, #default_formatter, #level, #should_log?

Methods inherited from Base

#backtrace, #fast_tag, #level, #level=, #measure, #named_tags, #pop_tags, #push_tags, #should_log?, #silence, #tagged, #tags

Constructor Details

#initialize(file_name, retry_count: 1, append: true, reopen_period: nil, reopen_count: 0, reopen_size: 0, encoding: Encoding::BINARY, exclusive_lock: false, **args, &block) ⇒ File

Create an appender to log to a named file.

Parameters

file_name [String]
  Name of the file to write to.

  File name format directives:
    %p - Process Id
    %n - Short hostname (SemanticLogger.host). Everything before the first period in the hostname.
    %N - Full hostname (SemanticLogger.host)
    %a - Application name (SemanticLogger.application)
    %e - Environment name (SemanticLogger.environment)
    %D - Current Date. Equivalent to "%Y%m%d"
    %T - Current Time. Equivalent to "%H%M%S"
    %% - Literal `%` character

  Date:
    %Y - Year with century
    %C - year / 100 (round down.  20 in 2009)
    %y - year % 100 (00..99)
    %m - Month of the year, zero-padded (01..12)
    %d - Day of the month, zero-padded (01..31)
    %j - Day of the year (001..366)
    %U - Week number of the year.  The week starts with Sunday.  (00..53)
    %W - Week number of the year.  The week starts with Monday.  (00..53)

  Time:
    %H - 24 Hour of the day, zero-padded (00..23)
    %M - Minute of the hour (00..59)
    %S - Second of the minute (00..60)

  Examples:
    Create a log file name consisting of the short host name, process id, date, and time.
      "log/production-%n-%p-%D-%T.log"

:level [:trace | :debug | :info | :warn | :error | :fatal]
  Override the log level for this appender.
  Default: SemanticLogger.default_level

:formatter: [Object|Proc]
  An instance of a class that implements #call, or a Proc to be used to format
  the output from this appender
  Default: Use the built-in formatter (See: #call)

:filter [Regexp|Proc]
  RegExp: Only include log messages where the class name matches the supplied
  regular expression. All other messages will be ignored.
  Proc: Only include log messages where the supplied Proc returns true
        The Proc must return true or false.

:append [true|false]
  Append to the log file if already present?
  Default: true

:exclusive_lock [true|false]
  Obtain an exclusive lock on the file, for operating systems that support it.
  Prevents multiple processes from trying to write to the same log file.
  Default: false

:encoding ["UTF-8", "UTF-16", etc.]
  Encoding to use when writing to the file.
  Default: Encoding::BINARY

:retry_count [Integer]
  Number of times to attempt to re-open the file name when an error occurs trying to
  write to the file.
  Note: Set to 0 to disable retries.
  Default: 1

:reopen_period [String]
  Specify a period after which to re-open the log file, specified in minutes, hours, or days.
  The format of the duration must start with an Integer or Float number,
  followed by the duration specified as:
    "m" : minutes
    "h" : hours
    "d" : days
  The time is rounded down to the specified time interval, so that:
  - "1h" will re-open every hour at the beginning of the hour.
  - "30m" will re-open every 30 minutes at the beginning of the 30th minute.
  - "1d" will re-open every day at midnight.
  Examples:
    "60m" : Every 60 minutes at the beginning of the minute: 10:24:00, 11:24:00, 12:24:00, ...
    "1h"  : Every hour at the beginning of the hour: 10:00:00, 11:00:00, 12:00:00, ...
    "1d"  : Every day at the beginning of the day: "20211008 00:00:00", "20211009 00:00:00", ...
  Default: nil (Disabled)

:reopen_count [Integer]
  Close and re-open the log file after every `reopen_count` number of logged entries.
  Default: 0 (Disabled)

:reopen_size [Integer]
  Approximate number of bytes to write to a log file by this process before closing and re-opening it.
  Notes:
  - When `append: true` and the file already exists, it reads the size of the current log file
    and starts with that size.
    - If the current log file size already exceeds the `reopen_size`, its current size is ignored.
  - The `reopen_size` is only the amount of bytes written by this process, it excludes data
    written by other processes. Use a unique filename to prevent multiple processes from writing to
    the same log file at the same time.
  Default: 0 (Disabled)

Example

require "semantic_logger"

# Enable trace level logging
SemanticLogger.default_level = :info

# Log to a file
SemanticLogger.add_appender(file_name: "application.log", formatter: :color)

logger = SemanticLogger["test"]
logger.info "Hello World"



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/semantic_logger/appender/file.rb', line 125

def initialize(file_name, retry_count: 1, append: true, reopen_period: nil, reopen_count: 0, reopen_size: 0, encoding: Encoding::BINARY, exclusive_lock: false, **args, &block)
  if !file_name.is_a?(String) || file_name.empty?
    raise(ArgumentError, "SemanticLogging::Appender::File file_name must be a non-empty string")
  end

  @file_name      = file_name
  @retry_count    = retry_count
  @file           = nil
  @append         = append
  @reopen_period  = reopen_period
  @reopen_count   = reopen_count
  @reopen_size    = reopen_size
  @encoding       = encoding
  @exclusive_lock = exclusive_lock
  @log_count      = 0
  @log_size       = 0
  @reopen_at      = nil

  super(**args, &block)
end

Instance Attribute Details

#append ⇒ Object

Returns the value of attribute append.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def append
  @append
end

#current_file_name ⇒ Object

Returns the value of attribute current_file_name.



11
12
13
 
# File 'lib/semantic_logger/appender/file.rb', line 11

def current_file_name
  @current_file_name
end

#encoding ⇒ Object

Returns the value of attribute encoding.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def encoding
  @encoding
end

#exclusive_lock ⇒ Object

Returns the value of attribute exclusive_lock.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def exclusive_lock
  @exclusive_lock
end

#file_name ⇒ Object

Returns the value of attribute file_name.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def file_name
  @file_name
end

#log_count ⇒ Object

Returns the value of attribute log_count.



11
12
13
 
# File 'lib/semantic_logger/appender/file.rb', line 11

def log_count
  @log_count
end

#log_size ⇒ Object

Returns the value of attribute log_size.



11
12
13
 
# File 'lib/semantic_logger/appender/file.rb', line 11

def log_size
  @log_size
end

#reopen_at ⇒ Object

Returns the value of attribute reopen_at.



11
12
13
 
# File 'lib/semantic_logger/appender/file.rb', line 11

def reopen_at
  @reopen_at
end

#reopen_count ⇒ Object

Returns the value of attribute reopen_count.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def reopen_count
  @reopen_count
end

#reopen_period ⇒ Object

Returns the value of attribute reopen_period.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def reopen_period
  @reopen_period
end

#reopen_size ⇒ Object

Returns the value of attribute reopen_size.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def reopen_size
  @reopen_size
end

#retry_count ⇒ Object

Returns the value of attribute retry_count.



9
10
11
 
# File 'lib/semantic_logger/appender/file.rb', line 9

def retry_count
  @retry_count
end

Instance Method Details

#flush ⇒ Object

Flush all pending logs to disk.

Waits for all sent documents to be written to disk



205
206
207
 
# File 'lib/semantic_logger/appender/file.rb', line 205

def flush
  @file&.flush
end

#log(log) ⇒ Object

Since only one appender thread will be writing to the file at a time it is not necessary to protect access to the file with a semaphore.



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/semantic_logger/appender/file.rb', line 183

def log(log)
  reopen if time_to_reopen?

  count = 0
  begin
    message = formatter.call(log, self) << "\n"
    @file.write(message)
    @log_count += 1
    @log_size  += message.size
  rescue StandardError => e
    if count < retry_count
      count += 1
      reopen
      retry
    end
    raise(e)
  end
  true
end

#reopen ⇒ Object

After forking an active process call #reopen to re-open open the file handles etc to resources.



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/semantic_logger/appender/file.rb', line 148

def reopen
  begin
    @file&.close
  rescue StandardError
    nil
  end

  self.current_file_name = apply_format_directives(file_name)
  if ::File.directory?(file_name)
    raise(ArgumentError, "The supplied log file_name: #{current_file_name} is already a directory.")
  end

  self.log_count = 0
  if append && reopen_size && ::File.exist?(current_file_name)
    self.log_size = ::File.size(current_file_name)
    self.log_size = 0 if log_size >= reopen_size
  else
    self.log_size = 0
  end

  self.reopen_at = reopen_period ? next_reopen_period(reopen_period) : nil

  options = ::File::WRONLY | ::File::CREAT
  options |= ::File::APPEND if append
  @file = ::File.open(current_file_name, options)
  # Force all log entries to write immediately without buffering
  # Allows multiple processes to write to the same log file simultaneously
  @file.sync = true
  @file.set_encoding(encoding) if @file.respond_to?(:set_encoding)
  @file.flock(::File::LOCK_EX) if exclusive_lock
  @file
end