Logging Recommendations and Guidelines¶
Log messages are often the only source of information for your application users about what went wrong. For this reason, you'll want to capture enough useful information to help your users troubleshoot errors.
This section provides some useful recommendations and guidelines.
Log Level Recommendations¶
Logging severity levels allow you to assign a level of importance to a log message. However, if you log too many events without properly distinguishing between the importance of the messages, you can end up generating too many logs.
Therefore, it's important that you understand when to use each log level. SAP recommends that you use the log levels as follows:
Debug and info log levels to trace the current states of your application. Log these messages extensively. Use these logs when your code handles different conditions of an operation, or when the state of your app changes such as in the case of a lost connection.
Warn log level for errors that allow your app to function without having an impact on the user experience.
Error log level for errors that put your app’s stability at risk or indicate a malfunction, incorrect usage, or runtime error. Typical examples include catching an error or exception, detecting invalid user input, or situations where your app is about to terminate unexpectedly.
SAP recommends that you provide your users with a mechanism in your application, such as a configuration setting, that lets them enable or disable different log levels.
Log Message Guidelines¶
As well as logging messages at the proper levels and in the correct locations, it's equally important that you log useful messages. A simple message such as "Error!" isn't helpful when you're analyzing what went wrong.
Use these guidelines when you're writing messages:
Clear – Keep your wording simple, avoid complex sentences, and put yourself in the shoes of someone who does not know your code. Explain what is going on and what the problem could be.
Brief – Try to keep each message to no more than one or two lines. Make sure it contains enough information to allow your users to analyze what happened.
Complete – Make sure your error message contains all information necessary to debug the error and understand what the application was doing. Don't use log messages such as "I am here!" or "Finished!" Instead, use log messages like
NumberGenerator: User entered invalid number. Number was 256. Showing error popup.
Root cause – When you catch an error or exception and log a message, make sure you also log the root cause, that is, the error you have caught. This lets you trace back to where the error originated. This is invaluable information when it comes to debugging.
Data Privacy and Security¶
Logging is an invaluable tool for error analysis and must be an essential part of your application’s source code. However, logging can pose a threat to data privacy. Make sure that you never log private data that must not leave the app or device.
Data privacy depends on your specific use case and on the data privacy regulations of the countries where you plan to ship your application.
You should also keep in mind that logging can be a security risk. Logging passwords or other user credentials may give attackers a chance to compromise your application and your users’ security. Make sure that every developer is aware of the risks and the potential consequences of logging data.