Common Log Options

This page describes common options used to create, view, and otherwise use the Centralized Log facility in Genesys software.

[log] Section

This section must be called log.

Warning

For applications configured via a configuration file, changes to log options take effect after the application is restarted.

buffering

Default Value: true
Valid Values:

true	Enables buffering
false	Disables buffering

Changes Take Effect: Immediately

Turns on/off operating system file buffering. The option is applicable only to the stderr and stdout output (see page 21). Setting this option to true increases the output performance.

Important

When buffering is enabled, there might be a delay before log messages appear at the console.

check-point

Default Value: 1
Valid Values: 0–24
Changes Take Effect: Immediately

Specifies, in hours, how often the application generates a check point log event, to divide the log into sections of equal time. By default, the application generates this log event every hour. Setting the option to 0 prevents the generation of check-point events.

enable-thread

Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately

Specifies whether to enable or disable the logging thread. If set to true (the logging thread is enabled), the logs are stored in an internal queue to be written to the specified output by a dedicated logging thread. This setting also enables the log throttling feature, which allows the verbose level to be dynamically reduced when a logging performance issue is detected. Refer to the Framework Management Layer User's Guide for more information about the log throttling feature.

If this option is set to false (the logging thread is disabled), each log is written directly to the outputs by the thread that initiated the log request. This setting also disables the log throttling feature.

expire

Default Value: 10
Valid Values:

false	No expiration; all generated segments are stored.
<number> file or <number>	Sets the maximum number of log files to store. Specify a number from 1–1000.
<number> day	Sets the maximum number of days before log files are deleted. Specify a number from 1–100.

Changes Take Effect: Immediately

Determines whether log files expire. If they do, sets the measurement for determining when they expire, along with the maximum number of files (segments) or days before the files are removed. This option is ignored if log output is not configured to be sent to a log file.

Important

If the option’s value is set incorrectly—out of range of the valid values— it will be automatically reset to 10.

keep-startup-file

Default Value: false
Valid Values:

false	No startup segment of the log is kept.
true	A startup segment of the log is kept. The size of the segment equals the value of the segment option.
<number> KB	Sets the maximum size, in kilobytes, for a startup segment of the log.
<number> MB	Sets the maximum size, in megabytes, for a startup segment of the log.

Changes Take Effect: After restart

Specifies whether a startup segment of the log, containing the initial configuration options, is to be kept. If it is, this option can be set to true or to a specific size. If set to true, the size of the initial segment will be equal to the size of the regular log segment defined by the segment option. The value of this option will be ignored if segmentation is turned off (that is, if the segment option is set to false).

memory

Default Value: No default value
Valid Values: <string> (memory file name)
Changes Take Effect: Immediately

Specifies the name of the file to which the application regularly prints a snapshot of the memory output, if it is configured to do this (see “Log Output Options” on page 21). The new snapshot overwrites the previously written data. If the application terminates abnormally, this file will contain the latest log messages. Memory output is not recommended for processors with a CPU frequency lower than 600 MHz.

Important

If the file specified as the memory file is located on a network drive, the application does not create a snapshot file (with the extension *.memory.log). Logging output to a file at a network location is not recommended and could cause performance degradation.

memory-storage-size

Default Value: 2 MB
Valid Values:

<number> KB or <number>	The size of the memory output, in kilobytes. The minimum value is 128 KB.
<number> MB	The size of the memory output, in megabytes. The maximum value is 64 MB.

Changes Take Effect: When memory output is created

Specifies the buffer size for log output to the memory, if configured. See also “Log Output Options” on page 21.

message-format

Default Value: short
Valid Values:

short	An application uses compressed headers when writing log records in its log file.
full	An application uses complete headers when writing log records in its log file.

Changes Take Effect: Immediately

Specifies the format of log record headers that an application uses when writing logs in the log file. Using compressed log record headers improves application performance and reduces the log file’s size. With the value set to short:

• A header of the log file or the log file segment contains information about the application (such as the application name, application type, host type, and time zone), whereas single log records within the file or segment omit this information.
• A log message priority is abbreviated to Std, Int, Trc, or Dbg, for Standard, Interaction, Trace, or Debug messages, respectively.
• The message ID does not contain the prefix GCTI or the application type ID.

A log record in the full format looks like this:

2002-05-07T18:11:38.196 Standard localhost cfg_dbserver GCTI-00-05060 Application started

A log record in the short format looks like this:

2002-05-07T18:15:33.952 Std 05060 Application started

Important

Whether the full or short format is used, time is printed in the format specified by the time_format option.

messagefile

Default Value: As specified by a particular application
Valid Values: Any valid message file (<filename>.lms)
Changes Take Effect: Immediately, if an application cannot find its *.lms file at startup

Specifies the file name for application-specific log events. The name must be valid for the operating system on which the application is running. The option value can also contain the absolute path to the application-specific *.lms file. Otherwise, the application looks for the file in its working directory.

Warning

An application that does not find its *.lms file at startup cannot generate application-specific log events and send them to Message Server.

no-memory-mapping

Default Value: false
Valid Values: true, false
Changes Take Effect: At restart

Specifies if memory-mapped files, including memory log output (with file extension .memory.log) and snapshot files (with file extension .snapshot.log) are disabled for file outputs.

print-attributes

Default Value: false
Valid Values:

true	Attaches extended attributes, if any exist, to a log event sent to log output.
false	Does not attach extended attributes to a log event sent to log output.

Changes Take Effect: Immediately

Specifies whether the application attaches extended attributes, if any exist, to a log event that it sends to log output. Typically, log events of the Interaction log level and Audit-related log events contain extended attributes. Setting this option to true enables audit capabilities, but negatively affects performance.

Genesys recommends enabling this option for Solution Control Server and Configuration Server when using audit tracking. For other applications, refer to Framework Combined Log Events Help to find out whether an application generates Interaction-level and Audit-related log events; if it does, enable the option only when testing new interaction scenarios.

segment

Default Value: 100 MB
Valid Values:

false	No segmentation is allowed.
<number> KB or <number>	Sets the maximum segment size, in kilobytes. The minimum segment size is 100 KB.
<number> MB	Sets the maximum segment size, in megabytes.
<number> hr	Sets the number of hours for the segment to stay open. The minimum number is 1 hour.

Changes Take Effect: Immediately

Specifies whether there is a segmentation limit for a log file. If there is, sets the mode of measurement, along with the maximum size. If the current log segment exceeds the size set by this option, the file is closed and a new one is created. This option is ignored if log output is not configured to be sent to a log file.

snapshot

Default Value: No value
Valid Values:

No value or not specified (default)	Snapshot is created in log output folder.
<path>/<folder>	Full or relative path and folder in which snapshot is created.

Changes Take Effect: Immediately

A snapshot file is created for each log output file to temporarily store logs that have not been flushed to the log file. This option specifies the folder, either a full path or a path relative to the application’s working directory, in which the application creates the memory-mapped snapshot file associated with the log file. If this option is not configured, or a value is not specified (the default), the file is created in the log output folder.

Important

Do not write the snapshot file to a network drive, because disconnection of the network drive might cause application failure. If the application detects that the output folder is a network drive, the snapshot file will be disabled. However, this detection may not be possible for Storage Area Network (SAN) devices because of operating system limitations.

spool

Default Value: The application’s working directory
Valid Values: Any valid folder, with the full path to it
Changes Take Effect: Immediately

Specifies the folder, including full path to it, in which an application creates temporary files related to network log output. If you change the option value while the application is running, the change does not affect the currently open network output.

throttle-period

Default Value: 30
Valid Values: 0–3600
Changes Take Effect: Immediately

Specifies, in seconds, how long to keep the throttled verbose level. When this period of time has expired, the original log verbose level will be restored when the log queue size has decreased to less than 50% of the threshold.

Important

This option applies only if enable-thread is set to true.

throttle-threshold

Default Value: 5000
Valid Values: 0–10000
Changes Take Effect: Immediately

Specifies the size of the internal log queue at which the verbose level is to be reduced so as to lessen the load generated by logging. If this option is set to 0 (zero), throttling does not occur. For more information about log throttling, refer to the Framework 8.5 Management Layer User’s Guide.

Important

This option applies only if enable-thread is set to true.

time_convert

Default Value: Local
Valid Values:

local	The time of log record generation is expressed as a local time, based on the time zone and any seasonal adjustments. Time zone information of the application’s host computer is used.
utc	The time of log record generation is expressed as Coordinated Universal Time (UTC).

Changes Take Effect: Immediately

Specifies the system in which an application calculates the log record time when generating a log file. The time is converted from the time in seconds since 00:00:00 UTC, January 1, 1970.

time_format

Default Value: time
Valid Values:

time	The time string is formatted according to the HH:MM:SS.sss (hours, minutes, seconds, and milliseconds) format.
locale	The time string is formatted according to the system’s locale.
ISO8601	The date in the time string is formatted according to the ISO 8601 format. Fractional seconds are given in milliseconds.

Changes Take Effect: Immediately

Specifies how to represent, in a log file, the time when an application generates log records.

A log record’s time field in the ISO 8601 format looks like this: 2001-07-24T04:58:10.123

time_format

Default Value: all
Valid Values:

all	All log events (that is, log events of the Standard, Trace, Interaction, and Debug levels) are generated.
debug	The same as all.
trace	Log events of Trace level and higher (that is, log events of Standard, Interaction, and Trace levels) are generated, but log events of the Debug level are not generated.
interaction	Log events of Interaction level and higher (that is, log events of Standard and Interaction levels) are generated, but log events of Trace and Debug levels are not generated.
standard	Log events of Standard level are generated, but log events of Interaction, Trace, and Debug levels are not generated.
none	No log output is produced.

Changes Take Effect: Immediately

Specifies if log output is created, and if so, the minimum level of log events generated. Log event levels, starting with the highest priority level, are Standard, Interaction, Trace, and Debug. See also “Log Output Options” on page 35.

Important

For definitions of the Standard, Interaction, Trace, and Debug log levels, refer to the Management Layer User's Guide or Framework Genesys Administrator Help.