log4cmd

All Top-level Files
Login

All Top-level Files

All Tip Tree-View Trunk

Files in the top-level directory in any check-in

log4cmd - a configurable log proxy for the windows command line

This is a configurable command-line logger for Windows, written in VBScript.

It can be invoked directly from the Windows command line or included in a VBScript program.

It can be configured to send the same message to each of several "loggers", subject to "log-level filtering".

Development repository: https://chiselapp.com/user/eschen42/repository/log4cmd/timeline?r=trunk

Interpretation of logging levels

The following interpretation of non-testing logging levels is assumed:

The following interpretation of test-logging levels is assumed:

One more logging level can be used as a placeholder:

Usage

Direct invocation

To log a message, you can invoke log4vbs.vbs directly: 

cscript //nologo log4vbs.vbs /lvl:{debug|info|note|warn|error|fatal|none|pass|fail|skip} /msg:your-message-in-double-quotes [/src:override-default-configured-source]
e.g.: 
cscript //nologo log4vbs.vbs /lvl:info /msg:"This is only a test."

Invocation via convenience scripts

To make invocations more succinct, you can also use one of the "convenience scripts" for general purpose logging:

or for reporting test results:

There is also a "no-operation" dummy script that does absolutely nothing; you can use this when you temporarily want to suppress another logging operation from your script:

Each of these scripts takes the log message in double quotes as the first argument, and optionally an alternative source (without quotes), e.g.: 

log_debug "Wow! This is wonderful" myDebugLogSource
log_fatal "Bummer. Cannot continue. Sorry"
Note that:

log_level_async.cmd

The convenience scripts all call log_level_async.cmd; some error messages reference this script rather than the calling script.

Creating paths for supplementary logs

To create a path to a "supplementary log", as described in the Supplementary Logs section below, and assign it to the MY_SUPPLEMENATARY_LOG_PATH environment variable: 

log4cmd_newlog.cmd MY_SUPPLEMENATARY_LOG_PATH sourceName logName
Note, however, that this path will not be enclosed in double quotes; if it contains spaces then you must enclose it in double quotes when you reference it, e.g.: 
type "%MY_SUPPLEMENATARY_LOG_PATH%"

How to use - quick start

TL;DR

:: Set up registry keys and create directory where log files will be written.
install_example.cmd

:: Write some log messages.
demo_log4cmd.cmd

:: Run some tests if you like.
test\run_tests.cmd

:: Create mySourceName subdirectory in log directory and generate a path for a
::   uniquely named file in that directory, but do not create that file yet.
log4cmd_newlog.cmd MY_LOGNAME_LOG mySourceName myLogName

Default Behavior

Windows Registry

In the Windows registry:

Log Source

The default "log source" is named log4vbs:

Log Messages

As long as an alternative log source has not been specified, log messages will be written to %USERPROFILE%\AppData\Local\log4cmd\log4vbs-CCYY-MM-DD.log:

Synchronous Logging by LOG_*.CMD Scripts

By default, all LOG_*.CMD scripts wait for all loggers to finish running before returning.

EXPERIMENTAL If you define the LOG4CMD_ASYNC environment variable before calling, however, these will delegate logging to a background task and return immediately. This has reliability issues at the moment, however, so don't assume that it's going to work.

Demonstration

To see log4cmd in action, assuming that the default settings seem acceptable to you:

Set Up

Logging

Supplementary Logs

Customization

(For a more advanced approach that may be easier to maintain, see Alternative Customization Technique - "tail patching" below.)

Customizations will hopefully be straightforward.

Loggers

Presently there are three loggers:

Log-level Filtering

The log levels that will be accepted for logging (i.e., not silently ignored) may be assigned to the logLevelFilter in log4vbs_config.vbs, which filters logging to all loggers.

The Select Case statement in the Loggers function in log4vbs_config_example.vbs supports logger-specific log-level filtering through the logLevelFilterForFile and logLevelFilterForStdOut VBScript variables.

Security

A hallmark of secure logging is that logs be written where they cannot be modified or erased. If you have a need for secure logging, you could create a logger to interact with such a logging facility. The file logger included here is not intended to meet any security requirements.

The Windows Event Log is set up to achieve such non-redactability to a great degree, for unpriviliged users at least; however, an unprivileged user can only write to the Application Log "event source" unless an administrator creates an application-specific event source, so it may be too much of a jumble to be worthwhile. If you want to do this, you might find what you need to get started at https://ss64.com/vb/logevent.html.

Alternative Customization Technique - "tail patching"

A "tail patch" is applying after some code has executed. This makes minor configuration changes easier both to read and to maintain.

log4vbs_config.vbs

If you do not need to change the loggers but merely want to override the values assigned to some variables, one alternative to copying log4vbs_config_example.vbs to log4vbs_config.vbs is to create log4vbs_config.vbs as follows: 

include ".\log4vbs_config_example.vbs"
logSource = "myOwnLogSource"
logLevelFilter = "debug|info|note|warn|error|fatal"
Note that include is a function defined in log4vbs.vbs; it is not a standard part of VBScript.

log4cmd_regkey.cmd

Similarly, you can override just the logging location by creating log4cmd_regkey.cmd as follows: 

@call "%~dp0\log4cmd_regkey_example.cmd"
@set LOG4CMD_ROOT_EX=%TEMP%\log4cmd
@set LOG4CMD_ROOT_IN=%%TEMP%%\log4cmd