Skip to content

Integrate logging in code

Get LogSession

The LogSession instance is a singleton, the global variable globalLogSession, instantiated in the script's Initialize. Always use this method to retrieve the current LogSession, trying to do Dim logSess as New LogSession() 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

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

    Call globalLogSession.createLogEntry(LOG_DEBUG, "Entered doProcessing", "", "")
    Try
        If (passedVal > 4) Then
            Error 4000, "Invalid entry"
        End If
        Call globalLogSession.createLogEntry(LOG_DEBUG, "Ran doProcessing successfully", "", "")
    Catch
        Call globalLogSession.createLogEntry(LOG_ERROR, "Error encountered", "Value passed: " & passedVal, "")
    Finally
        Call globalLogSession.createLogEntry(LOG_DEBUG, "Finished doProcessing", "", "")
    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. The class name the current code is in.

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:

1
2
3
4
5
6
7
8
9
    Dim i as Integer

    Do
        Call doProcessing(i++)
        If (Not IsEmpty(globalLogSession.getLogEntriesByLevel(LOG_FATAL, LOG_FATAL)) Then
            Print "Exiting at " & --i ' (1)!
            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