Logging

Logging

Logging is implemented within Fusee.Base.Core.Diagnostics.cs.

Log levels

The following log levels are usable:

• Diagnostics.Debug (used for generic, short, debug messages)
• Diagnostics.Info (used for messages that should be displayed in debug, as well as release builds)
• Diagnostics.Warning (used for warning messages, which do not lead to any crashes)
• Diagnostics.Error (used for fatal errors, e. g. exceptions)
• Diagnostics.Log (obsolete, legacy logging)

with these parameters:

• object msg, the debug message (.ToString() is called within this method)
• Exception ex, a possible exception (can be null)
• object[] args, additional arguments that can and/or should be displayed during logging (can be null)

Examples

Debug

var t = float4x4.Identity;
Diagnostics.Debug("Identity matrix created");

Warning (with args)

var invMat = float4x4.Invert(mat);
var invMat2 = float4x4.Invert(mat2);
if(invMat.Equals(mat) && invMat2.Equals(mat2))
    Diagnostics.Warn($"The following matrices could not be inverted!", null, new float4x4[] { mat, mat2 });

Error (with exception and args)

try 
{
   var compiledShader = CreateShader(ef.VertexShaderSrc, ef.PixelShaderSrc);
}
catch(Exception ex)
{
    Diagnostics.Error("Error while compiling the shader.", ex, new string[] { ef.VertexShaderSrc, ef.PixelShaderSrc });
}

Format

Per default each debug message follows this pattern:

[CallingMethod():LineNumber] Message

everything else (warning, error, etc.):

DD.MM.YYYY HH:MM:SS, [SeverityLevel] [FileName.cs] [CallingMethod():LineNumber] Message

One can overwrite the format of every log message by setting the Formater delegate via SetFormat(Formater formater).

Example

Diagnostics.SetFormat((caller, lineNmbr, sourceFile, logLvl, msg, ex, args) => {

    var l = $"{sourceFile} said: within my method {caller} at the line number {lineNmbr}, the following message, with the severity level {logLvl} appeared: {msg}.";

    if (ex != null)
        l += $"\nOh no, a wild exception appears: {ex}";

    return l;
});

Log targets

There are three log targets:

• Console output
• Debug output (where System.Diagnostics.Debug writes its' output)
• File

Console and debug output are enabled by default. The file target is disabled and can be activated with Diagnostics.LogToTextFile(bool log, string logFileName = "").

Targets and severity levels with different build configurations

Within a debug build, every log message is displayed for every available target. A release build also displays every log message per default but the Diagnostics.Debug() method is removed completely.

Furthermore, one can adapt every minimal log level for every target with the following three methods:

• Diagnostics.SetMinConsoleLoggingSeverityLevel(lvl)
• Diagnostics.SetMinDebugOutputLoggingSeverityLevel(lvl)
• Diagnostics.SetMinTextFileLoggingSeverityLevel(lvl)

💡 Note: this does not bring back the output of the Diagnostics.Debug() method within a release build! This functionality is implemented differently with the help of pre-compiler flags.

Examples

Display no debug messages on the console

Diagnostics.SetMinConsoleLoggingSeverityLevel(SeverityLevel.INFO);

Display only error messages on the console and display no debug messages on the debug output

Diagnostics.SetMinConsoleLoggingSeverityLevel(SeverityLevel.ERROR);
Diagnostics.SetMinDebugOutputLoggingSeverityLevel(SeverityLevel.INFO);

Display nothing on the console and display only warning and error messages on the debug output

Diagnostics.SetMinConsoleLoggingSeverityLevel(SeverityLevel.NONE);
Diagnostics.SetMinDebugOutputLoggingSeverityLevel(SeverityLevel.WARN);

Enable file logging for warnings and errors, display no debug messages on the console

// enable file logging to Fusee.Log.txt
Diagnostics.LogToTextFile(true, "Fusee.Log.txt"); 
// log warnings and errors to file 
Diagnostics.SetMinTextFileLoggingSeverityLevel(SeverityLevel.WARN); 

// disable debug output on console
Diagnostics.SetMinConsoleLoggingSeverityLevel(SeverityLevel.INFO); 
// display everything within the debug output target
Diagnostics.SetMinDebugOutputLoggingSeverityLevel(SeverityLevel.DEBUG); // this is also the default value

💡 Note: file logging is currently not supported for android and produces a NotImplementedException()

---

👷 Engine Developer

for more information browse Diagnostics.cs