Integrate logging in code

Get LogSession

The LogSession instance is a singleton, accessed by the global variable globalLogSession. It is instantiated in the script's Initialize method. Always use globalLogSession to access the LogSession instance. Attempting to create a new LogSession using the New() constructor will throw an error.

Info

VoltScript objects cannot persist between script runs. So when the Sub Initialize is first triggered, the LogSession instance will be new and empty. When the Sub Initialize ends, the LogSession instance will be deleted.

Create log entries

Tip

The recommended best practice is to always create log entries of all levels, not to change code when you want to log or use conditionals to check whether or not to create a log entry. Instead, use conditionals when adding the LogWriters to the LogSession or setting the LogWriter level. This ensures cleaner code and simplicity for the flexible requirement of changing logging levels.

The following snippet shows an example of creating log entries:

Function doProcessing(passedVal as Integer) as Boolean

    Print |doProcessing(| & passedVal & |)|
    Call globalLogSession.createLogEntry(LOG_DEBUG, "Entered doProcessing", "", Nothing)
    Try
        If (passedVal > 4) Then Error 4000, "Invalid entry"

        Call globalLogSession.createLogEntry(LOG_DEBUG, "Ran doProcessing successfully", "", Nothing)
    Catch
        If (passedVal > 6) Then 
            Call globalLogSession.createLogEntry(LOG_FATAL, "Error encountered", "Value passed: " & passedVal, Nothing)
        Else 
            Call globalLogSession.createLogEntry(LOG_ERROR, "Error encountered", "Value passed: " & passedVal, Nothing)
        End If 
    Finally
        Call globalLogSession.createLogEntry(LOG_DEBUG, "Finished doProcessing", "", Nothing)
    End Try

End Function

The parameters are:

1. Log level. Using the constants is recommended, and the code ensures a valid log level is passed.
2. A log message, typically not verbose.
3. Extended information in string format.
4. An ErrorEntry object from which to extract previously processed values.

A unique identifier will be assigned to the LogEntry and a timestamp captured in UTC ISO 8601 format. The full stack trace will also be captured, as will the script name and method. Consequently, this information does not need to be included in the message or extended info.

Log levels

The following log levels can be passed, from most severe to least:

1. LOG_FATAL
2. LOG_ERROR
3. LOG_WARNING
4. LOG_INFO
5. LOG_DEBUG
6. LOG_TRACE

Filter log entries

You can check for log entries at or above a specific level at any point. A use case for this might be to abort processing because there are problems that require fixing, as below:

Dim i as Integer

Do
    Call doProcessing(i++)
    If (Not IsEmpty(globalLogSession.getLogEntriesByLevel(LOG_FATAL, LOG_FATAL))) Then
        Print "Exiting at " & --i 
        Exit Sub
    End If
Loop

1. Line 4 has already incremented i from the value that caused the problem. So we decrement it before including in the Print statement.

See sample code