Logs - your secret weapon

Most developers don't take the time to consider the log messages' importance when adding them. However, logs are not just a formality; they are your secret weapon, helping you understand the flow of operations and simplify troubleshooting. Neglecting to provide detailed and context-rich log messages can significantly hinder the troubleshooting process, leading to longer resolution times and potentially impacting the user experience.

Most of the time, the developer will add generic log messages such as:

1. Created account successfully.


2. An error has occurred.


3. Updated preferences.


4. Invalid Type.

The above message gives you a rough idea of what has happened, but it does not provide context for what account was created, what error occurred, or who/what preferences were updated.

However, with some little changes, you can improve the message by providing some context:

1. Account [email protected] was created.


2. Error creating an account for [email protected]
   


3. Preferences updated for [email protected]
   


4. The product type is invalid.

With those changes, at a glance, you have some context of what happened.

1. An account was created using the email address [email protected]
   


2. When trying to create an account, [email protected] failed


3. The preference for [email protected]

Log Levels

Most logging frameworks have different log levels; you can control which level is visible in your environments.

Debug

Detailed information about your application's internal workings can be helpful for debugging. For example, essential logic is applied when processing a request.

You should treat debug log messages as unsafe for production environments and only have them for non-production environments.

Information

A critical step in the application has started or been completed. This is useful for tracking its progress.

Warning

Something unexpected happened, but the application can still be continued.

For example, if you check a user's preferred language and it has not been set, you default it to English.

Error

A single operation (like processing an HTTP request) has failed.

Fatal

A very serious error has happened, causing the whole application or system to crash.

Formatting your message

A typical pattern I follow when creating log messages is the wrap dynamic values between square brackets for a couple of reasons:

1. It is easy to identify what value(s) are dynamic


2. You know the start and end of the value. Helpful with string values.


3. You can parse messages more quickly since you can ignore anything between the brackets.

Examples

1. Account [[email protected]] was created.


2. Error creating an account for [[email protected]]


3. Preferences updated for [[email protected]]


4. Error creating an account for []

Structured Logs

To enhance your logging, you should use structured logs. Stackify has a good article on structured logs.

Stackify article

Depending on your logging framework, you can add fields that provide more context about the message and where you are processing your request.

When adding additional fields, keep a couple of things in mind:

1. Think about PII and other sensitive data that should not appear in logs.


2. Include a request/trace ID to help you see the whole picture.


3. Build up the additional field while you process the request. This way, you don't know to jump between different logs to see the details you need


4. If you are processing a batch, include a batch ID.
   Include your service version; this can help identify if an issue was introduced in a specific version.

You can import structure logs to tools like New Relic, Data Dog, sentry ... to make searching, filtering and alerting easier

Pointers to improve log messages

1. When developing/testing your code, if you wished you had some data when troubleshooting, include it in your log message


2. If troubleshooting a missing log message would make future changes easier, add it to make future debugging sessions easier.


3. Think about what metadata, such as:
   
   
   
   
   • Record ID
   
   
   • Request ID
   
   
   • Data of the entity (Person name, product details)
   
   
   • The source of the request (which application)
   
   
   • Make your message self-documenting
   
   
   
   


4. What log level to use? It can help with filtering.