Kea: isc::legal_log::RotatingFile Class Reference

| Kea 3.2.0-git

isc::legal_log::RotatingFile Class Reference

RotatingFile implements an appending text file which rotates to a new file on a daily basis. More...

`#include <rotating_file.h>`

Inheritance diagram for isc::legal_log::RotatingFile:
[legend]

## Public Types
enum class | TimeUnit { Second , Day , Month , Year }
| Time unit type used to rotate file. More...

## Public Member Functions
| RotatingFile (const isc::db::DatabaseConnection::ParameterMap &parameters)
| Constructor.
virtual | ~RotatingFile ()
| Destructor.
void | apply (const isc::db::DatabaseConnection::ParameterMap &parameters)
| Parse file specification and create forensic log backend.
virtual void | close ()
| Closes the underlying file.
std::string | getBaseName () const
| Returns the file base name.
std::string | getFileName () const
| Returns the current file name.
std::string | getPath () const
| Returns the file path.
virtual std::string | getType () const
| Return backend type.
virtual void | open ()
| Opens the current file for writing.
void | updateFileNameAndTimestamp (struct tm &time_info, bool use_existing)
| Function which updates the file name and internal timestamp from previously created file name (if it can still be used).
virtual void | writeln (const std::string &text, const std::string &addr)
| Appends a string to the current file.
Public Member Functions inherited from isc::dhcp::LegalLogMgr
| LegalLogMgr (const isc::db::DatabaseConnection::ParameterMap parameters)
| Constructor.
virtual | ~LegalLogMgr ()=default
| Destructor.
virtual struct tm | currentTimeInfo () const
| Returns the current local date and time.
virtual std::string | getNowString () const
| Returns the current date and time as string.
virtual std::string | getNowString (const std::string &format) const
| Returns the current date and time as a string using a specific strftime format string.
virtual isc::db::DatabaseConnection::ParameterMap | getParameters () const
| Return backend parameters.
isc::dhcp::ExpressionPtr | getRequestFormatExpression ()
| Gets request extended format expression for custom logging.
isc::dhcp::ExpressionPtr | getResponseFormatExpression ()
| Gets response extended format expression for custom logging.
std::string | getTimestampFormat ()
| Gets the timestamp format used for logging.
virtual bool | isUnusable ()
| Flag which indicates if the forensic log backend has at least one unusable connection.
virtual struct timespec | now () const
| Returns the current system time.
virtual void | setParameters (isc::db::DatabaseConnection::ParameterMap parameters)
| Sets backend parameters.
void | setRequestFormatExpression (const std::string &extended_format)
| Sets request extended format expression for custom logging.
void | setResponseFormatExpression (const std::string &extended_format)
| Sets response extended format expression for custom logging.
void | setTimestampFormat (const std::string &timestamp_format)
| Sets the timestamp format used for logging.

## Static Public Member Functions
static isc::dhcp::LegalLogMgrPtr | factory (const isc::db::DatabaseConnection::ParameterMap &parameters)
| Factory class method.
static std::string | getYearMonthDay (const struct tm &time_info)
| Build the year-month-day string from a date.
Static Public Member Functions inherited from isc::dhcp::LegalLogMgr
static std::string | genDurationString (const uint32_t secs)
| Translates seconds into a text string of days, hours, minutes and seconds.
static std::string | getLogPath (bool reset=false, const std::string explicit_path="")
| Fetches the supported legal log file path.
static std::string | getTimeString (const struct timespec &time, const std::string &format)
| Returns a time as string.
static void | parseConfig (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
| Parse database specification.
static void | parseDatabase (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
| Parse database specification.
static void | parseExtraParameters (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
| Parse extra parameters which are not related to backend connection.
static void | parseFile (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
| Parse file specification.
static void | parseSyslog (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
| Parse syslog specification.
static std::string | validatePath (const std::string logpath)
| Validates a log path against the supported path for legal log files.
static std::string | vectorDump (const std::vector< uint8_t > &bytes)
| Creates a string from a vector of printable bytes.
static std::string | vectorHexDump (const std::vector< uint8_t > &bytes, const std::string &delimiter=":")
| Creates a string of hex digit pairs from a vector of bytes.

## Protected Member Functions
virtual bool | isOpen () const
| Returns true if the file is open.
virtual void | openInternal (struct tm &time_info, bool use_existing)
| Open file using specified timestamp.
virtual void | rotate ()
| Rotates the file if necessary.
void | useExistingFiles (struct tm &time_info)
| Update file name with previously created file.

## Detailed Description

RotatingFile implements an appending text file which rotates to a new file on a daily basis.

The physical file name(s) are determined as follows:

Forms the current file name from:

"<path>/<base_name>.<date>.txt"

where:

- path - is the pathname supplied via the constructor. The path must exist and be writable by the process
- base_name - an arbitrary text label supplied via the constructor
- date - is the system date, at the time the file is opened, in local time. The format of the value is CCYYMMDD (century,year,month,day) or TXXXXXXXXXXXXXXXXXXXX (XXXXXXXXXXXXXXXXXXXX is the time in seconds since epoch)

Prior to each write, the system date is compared to the current file date to determine if rotation is necessary (i.e. day boundary has been crossed since the last write). If so, the current file is closed, and the new file is created.

Content is added to the file by passing the desired line text into the method, writeln(). This method prepends the content with the current date and time and appends an EOL.

The class implements virtual methods in facilitate unit testing and derives from `LegalLogMgr` abstract class.

Definition at line 50 of file rotating_file.h.

## Member Enumeration Documentation

## ◆ TimeUnit

enum class isc::legal_log::RotatingFile::TimeUnit
| strong

Time unit type used to rotate file.

Enumerator
Second |
Day |
Month |
Year |

Definition at line 54 of file rotating_file.h.

## Constructor & Destructor Documentation

## ◆ RotatingFile()

isc::legal_log::RotatingFile::RotatingFile | ( | const isc::db::DatabaseConnection::ParameterMap & | parameters | ) |

Constructor.

Create a RotatingFile for the given file name without opening the file. The file will be rotated after a specific time interval has passed since the log file was created or opened. If the time unit used is day, month or year, the file will be rotated at the beginning of the respective 'count' number of days, months or years (when the write function call detects that the day, month or year has changed).

Note
  The supported parameters are:
  - logfile parameters:
    - path
    - base-name
    - time-unit - one of: second, day, month, year
    - prerotate
    - postrotate
    - count

Parameters

  parameters | A data structure relating keywords and values concerned with the manager configuration.

Exceptions

  LegalLogMgrError | if given file name is empty.

Definition at line 35 of file rotating_file.cc.

References isc::dhcp::LegalLogMgr::LegalLogMgr(), and apply().

Referenced by factory().

Here is the call graph for this function:

## ◆ ~RotatingFile()

isc::legal_log::RotatingFile::~RotatingFile | ( |  | ) |
| virtual

Destructor.

The destructor does call the close method.

Definition at line 126 of file rotating_file.cc.

References close().

Here is the call graph for this function:

## Member Function Documentation

## ◆ apply()

void isc::legal_log::RotatingFile::apply | ( | const isc::db::DatabaseConnection::ParameterMap & | parameters | ) |

Parse file specification and create forensic log backend.

It supports the following parameters via the Hook Library Parameter mechanism:

path - Directory in which the legal file(s) will be written. The default value is "<prefix>/var/log/kea". The directory must exist.

base-name - An arbitrary value which is used in conjunction with current system date to form the current legal file name. It defaults to "kea-legal".

Legal file names will have the form:

    <path>/<base-name>.<CCYYMMDD>.txt
    <path>/<base-name>.<TXXXXXXXXXXXXXXXXXXXX>.txt

time-unit - The time unit used to rotate the log file. Valid values are: "second", "day", "month", or "year". It defaults to "day".

count - The number of time units that need to pass until the log file is rotated. It can be any positive number, or 0, which disables log rotation. It defaults to 1.

prerotate - An external executable or script called with the name of the file that will be closed. Kea does not wait for the process to finish.

postrotate - An external executable or script called with the name of the file that was opened. Kea does not wait for the process to finish.

Parameters

  parameters | The library parameters.

Definition at line 41 of file rotating_file.cc.

References isc::asiolink::ProcessSpawn::ASYNC, Day, isc::dhcp::LegalLogMgr::getLogPath(), isc_throw, Month, Second, isc::hooks::HookLibraryScriptsChecker::validatePath(), isc::Exception::what(), and Year.

Referenced by RotatingFile().

Here is the call graph for this function:

## ◆ close()

void isc::legal_log::RotatingFile::close | ( |  | ) |
| virtual

Closes the underlying file.

Method is exception safe.

Implements isc::dhcp::LegalLogMgr.

Definition at line 410 of file rotating_file.cc.

References isc::legal_log::legal_log_logger, LEGAL_LOG_STORE_CLOSE_ERROR, LEGAL_LOG_STORE_CLOSED, LOG_ERROR, and LOG_INFO.

Referenced by ~RotatingFile(), and rotate().

## ◆ factory()

LegalLogMgrPtr isc::legal_log::RotatingFile::factory | ( | const isc::db::DatabaseConnection::ParameterMap & | parameters | ) |
| static

Factory class method.

Parameters

  parameters | A data structure relating keywords and values concerned with the database.

Returns
  The Rotating File Store Backend.

Definition at line 427 of file rotating_file.cc.

References RotatingFile(), isc::legal_log::legal_log_logger, LEGAL_LOG_STORE_OPEN, LOG_INFO, and isc::db::DatabaseConnection::redactedAccessString().

Referenced by isc::legal_log::RotatingFileInit::RotatingFileInit(), and load().

Here is the call graph for this function:

## ◆ getBaseName()

std::string isc::legal_log::RotatingFile::getBaseName | ( |  | ) | const
| inline

Returns the file base name.

Returns
  The file base name.

Definition at line 189 of file rotating_file.h.

## ◆ getFileName()

std::string isc::legal_log::RotatingFile::getFileName | ( |  | ) | const
| inline

Returns the current file name.

Returns
  The file name.

Definition at line 182 of file rotating_file.h.

Referenced by rotate().

## ◆ getPath()

std::string isc::legal_log::RotatingFile::getPath | ( |  | ) | const
| inline

Returns the file path.

Returns
  The file path.

Definition at line 196 of file rotating_file.h.

## ◆ getType()

virtual std::string isc::legal_log::RotatingFile::getType | ( |  | ) | const
| inlinevirtual

Return backend type.

Returns the type of the backend (e.g. "mysql", "logfile" etc.).

Returns
  Type of the backend.

Implements isc::dhcp::LegalLogMgr.

Definition at line 175 of file rotating_file.h.

## ◆ getYearMonthDay()

string isc::legal_log::RotatingFile::getYearMonthDay | ( | const struct tm & | time_info | ) |
| static

Build the year-month-day string from a date.

Parameters

  time_info | The time info to be converted to string.

Returns
  the YYYYMMDD string.

Definition at line 131 of file rotating_file.cc.

Referenced by updateFileNameAndTimestamp().

## ◆ isOpen()

bool isc::legal_log::RotatingFile::isOpen | ( |  | ) | const
| protectedvirtual

Returns true if the file is open.

Returns
  True if the physical file is open, false otherwise.

Definition at line 405 of file rotating_file.cc.

Referenced by open(), and rotate().

## ◆ open()

void isc::legal_log::RotatingFile::open | ( |  | ) |
| virtual

Opens the current file for writing.

Forms the current file name if using seconds as time units:

"<path_>/<base_name_>.<TXXXXXXXXXXXXXXXXXXXX>.txt"

where XXXXXXXXXXXXXXXXXXXX is the time in seconds since epoch,

or if using days, months, years as time units:

"<path_>/<base_name_>.<CCYYMMDD>.txt"

where CCYYMMDD is the current date in local time,

and opens the file for appending. If the file does not exist it is created. If the file is already open, the method simply returns.

Exceptions

  LegalLogMgrError | if the file cannot be opened.

Implements isc::dhcp::LegalLogMgr.

Definition at line 278 of file rotating_file.cc.

References isc::dhcp::LegalLogMgr::currentTimeInfo(), isc::util::MultiThreadingMgr::instance(), isOpen(), and openInternal().

Here is the call graph for this function:

## ◆ openInternal()

void isc::legal_log::RotatingFile::openInternal | ( | struct tm & | time_info,
|  | bool | use_existing )
| protectedvirtual

Open file using specified timestamp.

Parameters

  time_info | The current time info used to open log rotate file.
  use_existing | Flag which indicates if the name should be updated with previously created file name if the file can still be used.

Definition at line 288 of file rotating_file.cc.

References isc_throw, isc::legal_log::legal_log_logger, LEGAL_LOG_STORE_OPENED, LOG_INFO, and updateFileNameAndTimestamp().

Referenced by open(), and rotate().

Here is the call graph for this function:

## ◆ rotate()

void isc::legal_log::RotatingFile::rotate | ( |  | ) |
| protectedvirtual

Rotates the file if necessary.

The system date (no time component) is latter than the current file date (i.e. day boundary has been crossed), then the current physical file is closed and replaced with a newly created and open file.

Definition at line 306 of file rotating_file.cc.

References isc::asiolink::ProcessSpawn::ASYNC, close(), isc::dhcp::LegalLogMgr::currentTimeInfo(), Day, getFileName(), isOpen(), Month, openInternal(), Second, and Year.

Here is the call graph for this function:

## ◆ updateFileNameAndTimestamp()

void isc::legal_log::RotatingFile::updateFileNameAndTimestamp | ( | struct tm & | time_info,
|  | bool | use_existing )

Function which updates the file name and internal timestamp from previously created file name (if it can still be used).

Parameters

  time_info | The current time info that should be used for the new name if previous files can not be reused.
  use_existing | Flag which indicates if the name should be updated with previously created file name if the file can still be used.

Definition at line 138 of file rotating_file.cc.

References getYearMonthDay(), Second, and useExistingFiles().

Referenced by openInternal().

Here is the call graph for this function:

## ◆ useExistingFiles()

void isc::legal_log::RotatingFile::useExistingFiles | ( | struct tm & | time_info | ) |
| protected

Update file name with previously created file.

Parameters

  time_info | The current time info used to open log rotate file.

Definition at line 165 of file rotating_file.cc.

References Day, Month, Second, and Year.

Referenced by updateFileNameAndTimestamp().

## ◆ writeln()

void isc::legal_log::RotatingFile::writeln | ( | const std::string & | text,
|  | const std::string & | addr )
| virtual

Appends a string to the current file.

Invokes rotate() and then attempts to add the new line followed by EOL to the end of the file. The content of new line will be:

    "<timestamp>SP<text><EOL>"

where:

- timestamp - current local date and time as given by the strftime format "%Y-%m-%d %H:%M:%S %Z"
- text - text supplied by the parameter
- EOL - the character(s) generated std::endl

Parameters

  addr | Address or prefix (ignored).
  text | String to append.

Exceptions

  LegalLogMgrError | if the write fails.

Implements isc::dhcp::LegalLogMgr.

Definition at line 374 of file rotating_file.cc.

References isc::util::MultiThreadingMgr::instance().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

- rotating_file.h
- rotating_file.cc