Logging (Serilog)

UltraStar Play uses Serilog as logging library.

See also the wiki page for the log file location.

Using Serilog

The Serilog logger has been configured in Log.cs and can be accessed using the static field Log.Logger:

using UnityEngine;
using Serilog;

public class MyLoggingBehaviour : MonoBehaviour
{
    private void Start()
    {
        // Simple logging (using placeholders)
        Log.Logger.Information("This is an info from {name}", this.name);
        
        // Structured logging via @ (object serialized to JSON)
        Log.Logger.Information("Default PlayerProfile values are {@playerProfile}", new PlayerProfile());
        
        // Exception logging
        try
        {
            throw new Exception("This is an exeption");
        }
        catch (Exception ex)
        {
            // Note that the exception is the *FIRST* parameter! Otherwiese the stack-trace will not be logged.
            Log.Logger.Error(ex, "This is the logged message for the Exception");
        }
    }
}

Logging Targets (Sinks)

Serilog will pass the log message to each of its configured logging targets, which are called sinks (ILogEventSink).

The current configuration (Dec 2020) in Log.cs is as follows:

• Rolling file

  • Logs are saved to Application.persistentDataPath + "/Logs"
  • Log file changes daily
  • Max 5 files
  • Max 250 MB per file

• UnityLogEventSink

  • Logs are passed to Unity's Console

Note that

• Unity's logging methods (Debug.Log and related) are also passed to Serilog (via Application.logMessageReceived)
  • Thus, you can also use Debug.Log as usual and use Serilog only for advanced features (structured logging).
• Serilog logging is also passed to Unity's logging (via UnityLogEventSink).
  • Thus, logging statements done with Log.Logger are also visible in the Unity Console.
  • To prevent cycles, a marker is added to the log message (depending on the original source this is unityLogEventSinkMarker or skipUnityLogEventSinkPropertyName)

Structured Logging

Serilog provides structured logging features. This means, objects can be serialized and their properties stored for later queries (if the logging target allows that, e.g., a database).

In the simple log file, structured logging will create a JSON string of the properties.

Log.Logger.Information("Default PlayerProfile values are {@playerProfile}", new PlayerProfile());
// 2020-12-23 11:17:35.899 [INF] Default PlayerProfile values are {"Name":"New Player","Difficulty":"Medium","Avatar":"GenericPlayer01","IsEnabled":true,"IsSelected":true,"$type":"PlayerProfile"}