Modding:Modder Guide/APIs/Logging

From Stardew Valley Wiki
Jump to: navigation, search
Modder's guide to creating mods SMAPI mascot.png

The monitor API, available through this.Monitor in your mod class, mainly lets you write messages to the console window and log file.

Logging

Overview

You can log messages by calling this.Monitor.Log with a string message and a log level. These messages will appear in the SMAPI console and log file.

For example, this code:

this.Monitor.Log("a trace message", LogLevel.Trace);
this.Monitor.Log("a debug message", LogLevel.Debug);
this.Monitor.Log("an info message", LogLevel.Info);
this.Monitor.Log("a warning message", LogLevel.Warn);
this.Monitor.Log("an error message", LogLevel.Error);

will log something like this:

[18:00:00 TRACE Mod Name] a trace message
[18:00:00 DEBUG Mod Name] a debug message
[18:00:00 INFO Mod Name] an info message
[18:00:00 WARN Mod Name] a warning message
[18:00:00 ERROR Mod Name] an error message

Log levels

The log level is semantic, meaning that the level itself conveys information (a Trace levels means something different from a Error level). You should use the log level that's closest to your message's purpose:

level purpose
Trace Tracing info intended for developers, usually troubleshooting details that are useful when someone sends you their error log. Trace messages won't appear in the console window by default (unless you have the "SMAPI for developers" version), though they're always written to the log file.
Debug Troubleshooting info that may be relevant to the player.
Info Info relevant to the player. This should be used judiciously.
Warn An issue the player should be aware of. This should be used rarely.
Error A message indicating something went wrong.
Alert Important information to highlight for the player when player action is needed (e.g. new version available). This should be used rarely to avoid alert fatigue.

Verbose logging

The following describes the upcoming SMAPI 2.8, and may change before release.

You can have messages appear in the log (and console in the for developers version) only if SMAPI's verbose logging option is enabled. This is meant for diagnostic information that's sometimes needed to troubleshoot, but doesn't need to be logged in most cases. Players can enable verbose logging by editing the smapi-internal/StardewModdingAPI.config.json file.

There are two ways to use it:

// log a TRACE message if verbose logging is enabled
this.Monitor.VerboseLog("This will only appear if verbose logging is enabled.");

// check the verbose option
if (this.Monitor.IsVerbose)
   this.Monitor("This will only appear if verbose logging is enabled.", LogLevel.Trace);

Emergency shutdown

In extraordinary cases, you can cause an emergency game shutdown by calling this.Monitor.ExitGameImmediately. This will immediately crash the game, bypassing all SMAPI error checks. This should only be invoked when an irrecoverable error happens that risks save corruption or game-breaking bugs.