Modding:Modder Guide/APIs/Logging

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

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 produce entries in the log with a timestamp, log level, name of the mod writing the log entry, and the log message itself:

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

Log levels

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

level	purpose
Trace	Tracing info is intended for developers, and are usually low-level 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	Debug info contains troubleshooting details that may be relevant to the developer.
Info	Info messages are relevant to the player, logging when general or higher-level events happen. This should be used judiciously.
Warn	Warnings are for announcing potential problems that could happen that the player should be aware of. This should be used rarely.
Error	Error messages describe a problem that happened or something that went wrong.
Alert	Alerts are severe errors that the mod cannot recover from. They contain important information to highlight what player action is needed (e.g., new version available). This should be used rarely to avoid alert fatigue.

Log once

The LogOnce method lets you log a message just like the above, but only once per game launch. For example, you can use it to show a compatibility warning for an API call:

this.Monitor.LogOnce("Some Mod Name used the deprecated X API.", LogLevel.Warn);

Verbose logging

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);

FAQs

Where is the log file created?

It's output to the game's ErrorLogs data folder. See smapi.io/log for help finding the log file, and you can also upload your log there to see what it looks like. The log file is always created (even if there are no errors) and it's written continuously (so you don't need to exit the game to see the log so far).