Logging is vital for any modern software team, and it’s essential to get it right. A poorly-implemented logging strategy could cause you more headaches than it solves. In this article, we’ll discuss PHP logging and the main best practices you should be aware of and adopt.
We’ll start with a brief explanation of why logging is so essential and then cover the best practices. Some of them will be general logging best practices, common to most programming languages, while others will be specific to PHP. Before sharing our final thoughts and parting ways, we explain how, in this day and age, logging can be valuable in ways other than being a mere troubleshooting mechanism.
Why Is Logging Important?
Let’s start by understanding why logging is crucial for software organizations. It all comes down to software being complicated. No matter how great your quality strategy is, your application is bound to have problems. When things inevitably go wrong, you need a mechanism to understand the production process, user actions, and so on. Logging is such a mechanism.
However, troubleshooting isn’t the only value to logging. With a well-thought-out log management strategy including log aggregation, you could leverage your log files and go beyond putting out fires.
PHP Logging Best Practices: Here Are 5 You Should Put in Practice
Use a Proper Logging Library
The first best practice on our list is the good old “don’t reinvent the wheel.” Yes, you probably could come up with your own homegrown PHP logging solution, but it doesn’t mean you should. A tried-and-true logging tool allows you to stand on the shoulders of giants and leverage the knowledge and experience of people who have solved logging challenges many times. This allows you to save time and money by having your team focus on core business problems.
This isn’t the only reason to use a logging library, however. Standardization is another big advantage you gain by adopting a logging library adhering to the PSR-3 Log Interface proposed by the PHP Framework Interop Group. When existing tools conform to a known standard, it becomes easier to swap one library for another. The learning curve also becomes virtually nonexistent, despite each library’s capability of extending the interface by adding their own methods. What matters most is for the basic functionality to be uniform across all tools implementing the interface.
Employ the Standard Logging Levels
Speaking of standardization, another essential practice in not only PHP logging but general logging is the use of proper logging levels.
Log levels are labels we include in each log entry to categorize them according to the nature and severity of the event they’re recording. The most common use for levels is probably searching and filtering, but it’s not the only one. By applying levels efficiently, you can improve the signal vs. noise ratio in your logs, creating different channels (also called targets, or destinations) for each severity. This way you can prevent crucial warning or emergency log entries from being lost in the sea of less imminent events.
So, what are the “proper” levels in PHP? The PSR-3 defines the following levels:
- Emergency – Someone should be woken up in the middle of the night. The system is down.
- Alert – Someone should take measures immediately.
- Critical – Critical conditions.
- Error – “Normal” error conditions. As in, somewhat expected errors you can recover from.
- Warning – It’s not an error, but you should pay attention.
- Notice – Significant, but still normal, condition.
- Info – Informational messages. Something interesting, but normal happened.
- Debug – Debug-level messages, used in development.
When logging in PHP, it’s crucial you use the levels above according to the nature of your event. If you’re using a logging tool following the PSR-3 Logging interface—and you should—then you won’t need to worry about this.
Use UTC for Your Timestamps
It’s not much use knowing something happened without being able to pin down exactly when it happened. This is why timestamps are a critical bit of information you should add to every log entry.
Unfortunately, handling time and date issues in software development is tricky, to say the least. And one of the trickiest parts of this tricky challenge is wrapping your head around time zones and all the complexity they bring. When it comes to logging, the tip here is simple: log using either UTC of the local time plus the offset from UTC. So, the two log entries below would be equivalent:
[2020-03-13T14:44:00-03:00] channel-name.INFO: This is a log entry!
[2020-03-13T11:44:00] channel-name.INFO: This is a log entry!Both timestamps refer to the same instant in time. One is expressed in UTC, which is great since it avoids problems like invalid or ambiguous date and time combinations due to things like daylight saving time (or your government deciding to skip a whole day).
Express Dates and Times Using the Standard Format
Another hard challenge of date and time handling is dealing with formats. We humans can’t make up our minds when it comes to expressing a point in time. This results in a plethora of different formats being used.
As it turns out, there’s a solution for that. The solution is an international standard for handling date and time exchange. This standard is called ISO-8601 and it defines, among other things, formats to express date and/or time in an unambiguous way. This is the format we’ve used in the log entries from the previous section.
Using this format will allow your log entries to be more easily analyzed by machine. It’s also easy for humans to read because it’s one standard format to learn vs. the many different formats used by each country and culture.
Write Parseable and Readable Log Entries
You often need to perform some automated processing to your log entries. Some auditing might be needed, for instance. To be able to do this, it’s important you write your log messages in an easily parseable manner. However, this isn’t enough.
Your log entries shouldn’t be only parseable; you should also strive to make them as readable as possible. By having logs people find easy to read and are also easily parseable, you achieve the best of both worlds.
Take Your PHP Logging to the Next Level
Logging is an essential tool in the arsenal of a modern software development company. A sound logging strategy is often the difference between diagnosing and fixing issues in production blazingly fast or being oblivious to them until they cause serious damage. This is true for any programming language or platform, but it’s especially important for languages used in web development.
Knowing about basic best practices is a first step when trying to improve your logging strategy. A good additional step is being aware of tools designed to make your life easier. For instance, you might want to know SolarWinds® Papertrail™ better. Papertrail is a cloud-based log management system. It can help you aggregate, organize, and manage your logs from many different sources, including PHP. Give Papertrail a try today. If you happen to be using the Laravel PHP framework, checkout this blog. It walks you through troubleshooting tips to shorten debugging time.
This post was written by Carlos Schults. Carlos is a .NET software developer with experience in both desktop and web development, and he’s now trying his hand at mobile. He has a passion for writing clean and concise code, and he’s interested in practices to help you improve app health, such as code review, automated testing, and continuous build.