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