Message Logging

Keep an eye on what's happening in and around your site.

Messages are notifications that are automatically generated by different parts of your Statamic website. We’ve included a couple within the Statamic core itself (with more on the way), and every add-on has tools to log messages with helpful tidbits of information.

These messages exist for two purposes:

• Help you understand what’s happening behind the scenes
• Making you aware of errors and other bad situations on your site

A sample action that logs a message is when a page is not found. The site will record the severity level as error, the date and time of when it happened, the page the user tried to access unsuccessfully, and a message telling you if the user came directly to this page, or if they clicked on a bad link from another page (along with which page it was they came from).

Severity Levels

Every message that’s recorded to your site’s log has a severity level associated with it. The five levels (from least- to most-severe):

• A debug message is the least serious of all severity levels, it’s used to mark points in the code where things happen to show you that they’re happening; production-level servers shouldn’t capture debug-level messages
• An info message is a note explaining why something happened, but whatever that “thing” was isn’t something you need to be overly concerned about, more along the lines of something you’d want to know rather than need to know; production-level servers probably do not want to capture info-level messages
• A warn message is essentially an error that the system automatically fixed for you, but is something you probably should look into when you have a chance; production-level servers should capture warn-level messages
• An error message is an alert that something didn’t work as expected, and that the user’s experience may have been affected, these should be investigated as soon as possible; production-level servers should capture error-level messages
• A fatal message is the most severe of notification, triggered when something has gone wrong and the user is absolutely stuck; these incidents should be looked into immediately; production-level servers should capture fatal-level messages

Configuring

There are four settings in your settings.yaml master configuration file to configure logging.

• _log_enabled will turn logging on or off
• _log_level is the lowest severity level to log for this server — this is another great place where using environments can come in handy — any messages that are lower than the _log_level defined will be ignored and not written to the logs
• _log_file_path is where log files will be kept
• _log_file_prefix helps name your log files — you might change this if you’re running a server with many sites on it and want all of your logs going into one folder, this prefix will separate each site’s logs from one another

Reading Logs

Log files are simple text files that can be read in virtually any text editor, but we’ve also created a nice interface in the Control Panel to help you stay alert on the go.

The Logs page in the Control Panel color-codes your messages based on severity level, and also parses messages for Markdown (allowing for easier-to-read messaging than with most other systems). You can also filter by severity level, or look through your log history to see what’s been happening in the last week, month, year, etc.

The larger-screen table view for logs in the Control Panel has a number of columns with helpful information:

• Level indicates the severity level logged by the message
• When tells you the time that the message was logged
• What Caused This is a two-part-column, the first part is the general area of the code where things went wrong, the second part is a more specific region — this column becomes helpful when trying to debug an error, knowing which part of the internals logged the messages tells you who to ask for help
• Page is the URL that was hit causing the message
• Message is the message itself, hopefully written in a way that is helpful for understanding what happened