Class: SemanticLogger::Appender::File

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

Instance Attribute Summary collapse

Attributes inherited from Subscriber

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

Instance Method Summary collapse

Methods inherited from Subscriber

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

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, permissions: nil, **args) ⇒ 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

:permissions [Integer]
Octal file permissions to apply to the log file.
Log files frequently contain sensitive information, so restrict access
by supplying for example `0o640` (owner read/write, group read).
Applied both when the file is created and to an existing log file.
Default: nil (use the process umask, the standard Ruby behavior)

: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"


132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/semantic_logger/appender/file.rb', line 132

def initialize(file_name, retry_count: 1, append: true, reopen_period: nil, reopen_count: 0, reopen_size: 0,
               encoding: Encoding::BINARY, exclusive_lock: false, permissions: nil, **args, &)
  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
  @permissions    = permissions
  @log_count      = 0
  @log_size       = 0
  @reopen_at      = nil

  super(**args, &)
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

#permissions ⇒ Object

Returns the value of attribute permissions.



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

def permissions
  @permissions
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



222
223
224
 
# File 'lib/semantic_logger/appender/file.rb', line 222

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.



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/semantic_logger/appender/file.rb', line 200

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.



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/semantic_logger/appender/file.rb', line 157

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 =
    if permissions
      ::File.open(current_file_name, options, permissions)
    else
      ::File.open(current_file_name, options)
    end
  # File.open only applies the permissions when creating the file, so also
  # enforce them on an already existing log file.
  @file.chmod(permissions) if permissions
  # 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