Logging

QB64-PE starting in v4.0.0 includes built-in logging support, allowing you to capture and display logging from QB64-PE programs. This includes both logging from QB64-PE internals ("libqb") and the program itself (via the provided statements).

Purpose

The logging functionality provides an easy way to get output from your program without having to draw it on the screen (or otherwise combine it with the output of your existing program). This allows you to easily get information you need for debugging without needing to somehow display it on the screen (or write it to a file).

Additionally, the logging functionality is always built-in to your program and is enabled via environment variables. This means you can take any built program (from v4.0.0 or later) and get logging output from it without having to rebuild the program.

Usage

There are 4 levels of logging, listed in order of how verbose they should be - Trace, Information, Warning, and Error. The Error level is special as the log message will also include a stacktrace of your program from the point the log statement was made. Below is the log message generated by _LOGINFO "Example log message":

   [0.13800] INFO QB64 Main QB64 Code: 1: Example log message

• [0.13800] is the number of seconds since the start of the program.
• INFO is the log level.
• QB64 is the scope.
• Main QB64 Code is the Sub/Function name that executed the log statement, or Main QB64 Code when called from the top level code.
• 1 is the line number of the _LOGINFO command.
• Example log message is the string that was passed to _LOGINFO.

IDE

The IDE includes support for displaying the logging output to you, via the Run -> Display Logging Output option. When this option is checked, a console window will open alongside your program and the logging output will be displayed in it. The IDE currently displays logging at the Information level of higher, with every logging scope enabled.

On Linux, the IDE will make a best effort to find an installed Terminal Emulator and provide the proper configuration for it. If you want to change the default selected Terminal Emulator, you can do so via the Run -> Change Terminal option.

Scopes

Scopes are categories separating the various types of logging from your program. The logging output can be configured to only log specific scopes, letting you avoid seeing extra logging you don't need.

    ┌─────────┬────────────────────────────────────────────────────────────────────────┐
    │  Scope  │  Description                                                           │
    ├─────────┼────────────────────────────────────────────────────────────────────────┤
    │ Runtime │ Information about incorrect logging configuration. Cannot be disabled. │
    ├─────────┼────────────────────────────────────────────────────────────────────────┤
    │   QB64  │ Logging from the QB64 program (Ex. _LOGINFO).                          │
    ├─────────┼────────────────────────────────────────────────────────────────────────┤
    │  libqb  │ Logging from the QB64 C++ internals.                                   │
    ├─────────┼────────────────────────────────────────────────────────────────────────┤
    │  Image  │ Logging from the image subsystem.                                      │
    └─────────┴────────────────────────────────────────────────────────────────────────┘

Handlers

The logging output can be sent to one or more handlers, which are different places to write the logging information too.

    ┌─────────┬────────────────────────────────────────────────┐
    │ Handler │  Description                                   │
    ├─────────┼────────────────────────────────────────────────┤
    │ console │ Writes logging output to the console/terminal. │
    ├─────────┼────────────────────────────────────────────────┤
    │   file  │ Writes logging output to a specified file.     │
    └─────────┴────────────────────────────────────────────────┘

Environment Variables

    ┌──────────────────────┬───────────────────────────────────────────────────────────────┐
    │      Variable        │  Description                                                  │
    ├──────────────────────┼───────────────────────────────────────────────────────────────┤
    │ QB64PE_LOG_HANDLERS  │ Comma separated list of log handlers to use. Ex. console,file │
    ├──────────────────────┼───────────────────────────────────────────────────────────────┤
    │   QB64PE_LOG_SCOPES  │ Comma separated list of scopes to log. Ex. QB64,libqb         │
    ├──────────────────────┼───────────────────────────────────────────────────────────────┤
    │   QB64PE_LOG_LEVEL   │ Minimum log level to capture. Ex. Information                 │
    ├──────────────────────┼───────────────────────────────────────────────────────────────┤
    │ QB64PE_LOG_FILE_PATH │ File path for the file handler output. Ex. C:\log.txt         │
    └──────────────────────┴───────────────────────────────────────────────────────────────┘

Stacktrace

A stacktrace is the list of Subs and Functions that were called to reach the error logging. If the logging is from a _LOGERROR statement, then the stacktrace will only include Sub and Function names from your program. If the error logging is generated by the QB64 internals then it will also include the name of internal C++ functions (useful for sharing in bug reports).

An example stacktrace is below:

   [0.12100] ERROR QB64 BAR (QB64): 9: This is an error
   #1  [0x00007FF6664AFA7E] in BAR() (QB64)
   #2  [0x00007FF6664AF948] in FOO() (QB64)
   #3  [0x00007FF6664AF891] in Main QB64 code

• The stacktrace is in order of most recently called, so this stacktrace shows the main code calling FOO, which then called BAR.
• Any symbols that have '(QB64)' after them were Subs or Functions from the QB64 program.
• The memory addresses can mostly be ignored, but could be used to resolve the stacktrace back to specific line numbers in the generated C++.

The example stacktrace was generated from the below example code:

foo END SUB foo bar END SUB SUB bar _LOGERROR "This is an error" END SUB

See also

• _LOGMINLEVEL
• _LOGTRACE, _LOGINFO, _LOGWARN, _LOGERROR

QB64 Programming References

Wiki Pages Main Page with Articles and Tutorials QB64 specific keywords (alphabetical) Original QBasic keywords (alphabetical) QB64 OpenGL keywords (alphabetical) Keywords by Usage Got a question about something? Frequently Asked Questions about QB64 QB64 Phoenix Edition Community Forum Links to other QBasic Sites: Pete's QBasic Forum Pete's QBasic Downloads