Configuring Logging with Registry Parameters

Log files are collected in the folder that is defined during installation as Log File Directory of the Virtual Unit installation variable. The default value is $VU_HOME$\logs, and the level warning is used in all modules. In IA, the default logging level is warning as well, but in HAC it is info.

To his section introduces the logging configuration.

As of SP07 version, set logging settings for all modules centrally in IA using the Logging Configuration wizard, see Logging Configuration Wizard.
In versions prior SP07, define a registry key in Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Wicom\.
Instead of configuring logging, consider using Tracing.

Legacy BCM Parameters

For the legacy reasons, the most common parameters are written together as such, for example LogLevel, LogPath and LogKeepLogDays.

Defining Log Path

To define path and name pattern for the generated log files, enter LogPath=[path] with appropriate value.

Defining Log File Saving Time

To define how many days the log files are saved, enter LogKeepLogDays=[number of days], for example LogKeepLogDays=1. Use DWORD (32-bit) value. The parameter value is inherited from virtual unit level to modules and components.

Defining Log Level

Define the global log level with the entry LogLevel=[value]. Global level is by default inherited to all object types (such as module and components), but each log file, console, or other log target may have their own log level as well.

For example,

To define the global log level, enter LogLevel=error.
To use error level for LibIpc object, enter LogModule.LibIpc.Level=error. The parameter is inherited from virtual unit level to modules.

Note: Do not use very high global log level, such as trace and debug, otherwise huge amount of logs are collected and it is hard to find the error.

For more information, see Log Levels in Advanced Logging Configurations below.

Advanced Logging Configurations

More generally, logging function can be configured with the registry parameter starting with Log followed by attributes delimited with periods, such as LogObjectType.ObjectIdentifier.Attribute. See the following attributes.

Logging Categories and Locations

Using logging categories enable that, for example, database administrators only receive database related log files, and network administrators follow the network logs.

Table 1. Categories
Configuration Name	Description
Network	Network related events
Database	Database access related events
Security	Security related events
Object	Events modifying business level objects

Common libraries in BCM software define the following logging locations.

Table 2. Locations
Configuration Name	Description
LibIpc	BCM Inter Process Communications library
BcmApi	BCM API library
CommonLib	Common library code

Log Targets

Object type defines if the log is collected to a file, console, module or thread. Object types may have different attributes defined.

Table 3. Log Object Types and Related Attributes
Object Type	Attribute	Description
Console	Level	Filters the entries printed to this console log target.
File Note: Do not write the word file in the registry entry, but just Log + attribute, for example `LogWriteMethod=fast`.	Level	Filters the entries printed to this file log target.
	MaxFileSize	Limits size of each log file.
	Hourly	Sets on hourly or daily log files.
	WriteMethod	Writes to file in fast or reliable mode. In the fast mode, the log files are buffered to memory before they are written on the disk.
	FlushDelay	Defines how often a flush to file is forced (useful in fast write mode only).
	MaxBytes	Maximum size of log buffer. If this size limit is reached, log entries are discarded. Effective in fast mode only.
	MaxDebugRows	If the number of buffered rows is greater than this number, debug log entries are discarded. Effective in fast mode only.
	MaxTraceRows	If the number of buffered rows is greater than this limit, trace log entries are discarded. Effective in fast mode only.
	MaxRows	If the number of buffered rows is greater than this limit, log entries other than error and warning are discarded. Effective in Fast mode only.
Module	Level	Filters the entries printed from this module, for example. LibIpc.
Thread	Level	Filters the entries printed from this thread, for example main.

Log Levels

Log level is a general attribute for all object types, and it can have the following values.

Table 4. Log Level Values
Value	Log Writing Includes
always	Messages that should always be printed, such as process startup notifications.
error	Unrecoverable error has occurred. Some or all functions of the module are inoperable or perform incorrectly. Often indicates malfunctioning hardware, major misconfiguration, or a bug in the product.
warning	Warning messages indicate of problems that are somehow recoverable or are in less important functions. For example, minor misconfigurations, performance warnings, temporary inavailability of a service.
info	Informative messages about business level or service level objects.
trace	Messages to trace the execution of the code in more detail. Mostly contains useful information for developers only while providing information about how execution of the code occurred.
debug	Most detailed messages about internal execution logic of the code. Mostly contains useful information for developers only. Often used for tracing rare issues or bugs in the product.

Log level filters may also be given additional values to achieve more complex filtering.


Level	Description
never	Filters out all entries. All exclusive.
inherited	Use the level setting from the parent filter.

The global log level is the root level and cannot be assigned to be inherited. Log targets (log files, console, and so on) and logging modules (locations and categories) are by default set to inherit the global log level, but they can also be assigned to their own level setting. Some logging modules may be a child module to another logging module; the above parent filter is then the level filter of the parent logging module. Threads are set by default, to inherited to follow other effective level filters, but they may also be given their own thread-local log level filter setting. Combining the above level filters and settings, one may control specific parts of the code, threads or types of events that produce log entries.

Defining Log Entry Formats

The default formatter for all log targets is the BCM-style log format. Its technical name in configuration is bcm. Other implemented formatters are SAP’s List Log (list) and Generic Log file Format (glf).

Most settings are Boolean attributes (true/false or 1/0); the default value is true unless otherwise stated. Other value types are separately mentioned. The tables below list all formatter settings, starting from the common settings and ending with the formatter-specific sections.

Table 5. Log Entry Attributes
Attribute	Description
IncludeDate	Prints date to each log entry (YYYY-MM-DD) (default: false).
IncludeTime	Prints time to each log entry (HH:mm:ss.mmm).
IncludeThreadName	Prints the thread name to each log entry.
IncludeThreadId	Prints the thread ID number to each log entry.
IncludeThreadPrefix	Prints the prefix text specified for the thread to each log entry.
IncludeLevel	Prints the severity to each log entry.
IncludeModule	Prints the related logging module to each log entry (default: false).
IncludeCategory	Prints the related logging category to each log entry (default: false)
IncludeObject	Prints the logging object name to each log entry.
IncludeExtra	Prints the optional extra text to each log entry, for example resource name (deprecated).
IncludeFileFormatHeader	Prints log format specific header to beginning of each file (default: false)

Table 6. BCM Log Formatter Specific Settings
Setting	Description
Pretty	Prints easier to read, but possibly more spacious log.
MaxThreadPadding	Defines how long padding may be added to thread name/ID-field when printing in pretty mode (default: 15).

Table 7. GLF and List Log Formatter -Specific Settings
Setting	Description
FieldDelimiter	ASCII code number of character used to delimit fields (default: 35, #).
RecordDelimiter	ASCII code number of character used to delimit log record (default: 10,LineFeed).

GLF and List Log formats define to print category and module name by default. GLF format also defines to print the file format header by default.

Log formatters also define the log file extension. Default for BCM and List Logs is .log while for GLF logs it is .glf. The default one is applied if the log file name pattern does not include any extension.

example:

A server module that prints debug-level log to file and error-level log to console. Also, entries from LibIpc code location are narrowed down to error-level. The registry of the module (module’s own registry key) would have the following registry value names and value data (shown as ValueName=ValueData):

LogLevel=debug

LogConsoleLevel=error

LogModule.LibIpc.Level=error