This thread is intended to be a companion to my 2013 conference presentation on the same subject and to serve as a future repository for information about the MivaScript debug log mechanism and its use. I'll be updating the first few posts over the next couple days to include additional technical information and examples.
Basic Information
Debug logging is supported on MivaScript engine versions 5.10 and newer.
Configuration: Windows
On Windows, there is a simple configuration dialog that allows the debug log to be configured.
debug_logging_dialog.jpg
Mia has a single debug logging setting that is applied to all scripts. On IIS, the settings can be applied to an entire website, a directory or an individual file.
Configuration: UNIX
Logging functionality on UNIX is identical to Windows and is configured differently depending on which configuration library you are using.
If using the environment-variable based configuration library, the following environment variables are used:
MvCONFIG_LOG_FILE specifies the name of the debug log file
MvCONFIG_LOG_LEVEL specifies the individual logging functions that should be enabled
MvCONFIG_LOG_FILTER specifies what filtering rules, if any, are applied
The 3.x configuration library uses the following configuration directives:
logfile specifies the name of the debug log file
loglevel specifies the individual logging functions that should be enabled
logfilter specifies what filtering rules, if any, are applied
The values for the directives are the same for either configuration library.
Configuration: Log File
On UNIX, the log file is always created in the mivadata directory. On Windows a full path is provided.
Configuration: Log Level
The log level is a bitfield, with each field controlling a single loggable item. In practice, this means that there is a particular numeric value assigned to each item and to enable multiple item you just add their numeric values together to obtain the final log level value. On Windows, the configuration dialog takes care of this for you and it is a simple matter of checking the checkboxes for the items you would like logged.
Below is a list of the loggable items and their assigned numeric values. (This list may also be found in mivapi.h in the UNIX VM distribution packages)
Using the list above, if you wanted to enable MvCALL and Application Timeout logging, you would add their two values together. 1048576+134217728= 135266304, so you would use the value 135266304 for your log level.
Configuration: Log Filter
In v5.13 or higher, you may apply an additional filter to the debug log to limit the log messages to those that were generated by particular source code. When a filter is specified, only those lines of code which match the filter will be logged.
The log filter directive takes the following form:
sourcefile[:[start_line][-[end_line]],...
"sourcefile" corresponds to the name of the MivaScript source file. This is generally the exact value that was passed to the MivaScript compiler when the source code was compiled.
"start_line" and "end_line" refer to source code line numbers within the source file. A range may be specified like this: "1-10". Within a range, either the start or end may be omitted. For example, "-100" means lines 1-100 and "100-" means lines 100 through the end of the file.
Source filenames and line numbers will generally be determined by examining the source code being debugged. However, they may also be inferred by generating a debug log without a filter and gathering sourcefile and line number values from the log.
Multiple filters may be specified by separating them with a comma.
v5.17 extends the filtering mechanism to add the concept of an exclusionary filter. By preceeding the filter value with "!", its function is reversed and any lines of code that do NOT match the filter are logged. Inclusionary and exclusionary filters may be combined, and will be applied in left to right order.
Log Cookie
The 5.18 engine will introduce a new type of filtering. Instead of (or in addition to) limiting the logging based on the source code, the log cookie setting allows you to restrict the logging to requests generated by clients containing a particular cookie value. There are two major components to the log cookie mechanism:
1. The log cookie configuration setting. On Windows, the cookie value is configured within the same debug log settings dialog as the rest of the settings. On UNIX, it is set using the logcookie configuration directive (3.x configuration) or MvCONFIG_LOG_COOKIE environment variable (environment based configuration).
2. The diagnostic tool which allows you to set the cookie on a target client.
I will provide additional information and screenshots on this section after the 5.18 engine release
Log File Format
The log file is a tab delimited text file containing the following fields:
Date/Time Stamp
Process ID
Type of Log Message
Compiled MivaScript file path
Source file
Source line number
Message-specific data (function return values, parameter values, MvCALL data, etc...)
Basic Information
Debug logging is supported on MivaScript engine versions 5.10 and newer.
Configuration: Windows
On Windows, there is a simple configuration dialog that allows the debug log to be configured.
debug_logging_dialog.jpg
Mia has a single debug logging setting that is applied to all scripts. On IIS, the settings can be applied to an entire website, a directory or an individual file.
Configuration: UNIX
Logging functionality on UNIX is identical to Windows and is configured differently depending on which configuration library you are using.
If using the environment-variable based configuration library, the following environment variables are used:
MvCONFIG_LOG_FILE specifies the name of the debug log file
MvCONFIG_LOG_LEVEL specifies the individual logging functions that should be enabled
MvCONFIG_LOG_FILTER specifies what filtering rules, if any, are applied
The 3.x configuration library uses the following configuration directives:
logfile specifies the name of the debug log file
loglevel specifies the individual logging functions that should be enabled
logfilter specifies what filtering rules, if any, are applied
The values for the directives are the same for either configuration library.
Configuration: Log File
On UNIX, the log file is always created in the mivadata directory. On Windows a full path is provided.
Configuration: Log Level
The log level is a bitfield, with each field controlling a single loggable item. In practice, this means that there is a particular numeric value assigned to each item and to enable multiple item you just add their numeric values together to obtain the final log level value. On Windows, the configuration dialog takes care of this for you and it is a simple matter of checking the checkboxes for the items you would like logged.
Below is a list of the loggable items and their assigned numeric values. (This list may also be found in mivapi.h in the UNIX VM distribution packages)
Code:
MvCONFIG_LOG_FUNC_CALL 16 Calls to native (MivaScript) functions MvCONFIG_LOG_FUNC_PARAM 32 Parameters to native (MivaScript) functions MvCONFIG_LOG_FUNC_RETVAL 64 Return values from native (MivaScript) functions MvCONFIG_LOG_FUNC_RETURN 128 Return from native (MivaScript) functions MvCONFIG_LOG_EXTERNAL_FUNC_CALL 256 Calls to builtin or other external functions MvCONFIG_LOG_EXTERNAL_FUNC_PARAM 512 Parameters to builtin or other external functions MvCONFIG_LOG_EXTERNAL_FUNC_RETVAL 1024 Return values from builtin or other external functions MvCONFIG_LOG_EXTERNAL_FUNC_RETURN 2048 Return from builtin or other external functions MvCONFIG_LOG_MvDO_FILE_ENTER 4096 MvDO of an entire file has begun MvCONFIG_LOG_MvDO_FILE_EXIT 8192 MvDO of an entire file has ended MvCONFIG_LOG_MvCALL 1048576 Logs raw request and response data for the MvCALL tag (requires v5.13) MvCONFIG_LOG_APPLICATION_TIMEOUT 134217728 Logs globaltimeout terminations (requires v5.13) MvCONFIG_LOG_RUNTIME_ERROR 268435456 All runtime errors MvCONFIG_LOG_FATAL_ERROR 536870912 All fatal errors MvCONFIG_LOG_TRACE 1073741824 Logs each line of source code executed
Configuration: Log Filter
In v5.13 or higher, you may apply an additional filter to the debug log to limit the log messages to those that were generated by particular source code. When a filter is specified, only those lines of code which match the filter will be logged.
The log filter directive takes the following form:
sourcefile[:[start_line][-[end_line]],...
"sourcefile" corresponds to the name of the MivaScript source file. This is generally the exact value that was passed to the MivaScript compiler when the source code was compiled.
"start_line" and "end_line" refer to source code line numbers within the source file. A range may be specified like this: "1-10". Within a range, either the start or end may be omitted. For example, "-100" means lines 1-100 and "100-" means lines 100 through the end of the file.
Source filenames and line numbers will generally be determined by examining the source code being debugged. However, they may also be inferred by generating a debug log without a filter and gathering sourcefile and line number values from the log.
Multiple filters may be specified by separating them with a comma.
v5.17 extends the filtering mechanism to add the concept of an exclusionary filter. By preceeding the filter value with "!", its function is reversed and any lines of code that do NOT match the filter are logged. Inclusionary and exclusionary filters may be combined, and will be applied in left to right order.
Log Cookie
The 5.18 engine will introduce a new type of filtering. Instead of (or in addition to) limiting the logging based on the source code, the log cookie setting allows you to restrict the logging to requests generated by clients containing a particular cookie value. There are two major components to the log cookie mechanism:
1. The log cookie configuration setting. On Windows, the cookie value is configured within the same debug log settings dialog as the rest of the settings. On UNIX, it is set using the logcookie configuration directive (3.x configuration) or MvCONFIG_LOG_COOKIE environment variable (environment based configuration).
2. The diagnostic tool which allows you to set the cookie on a target client.
I will provide additional information and screenshots on this section after the 5.18 engine release
Log File Format
The log file is a tab delimited text file containing the following fields:
Date/Time Stamp
Process ID
Type of Log Message
Compiled MivaScript file path
Source file
Source line number
Message-specific data (function return values, parameter values, MvCALL data, etc...)
Comment