5. Monitoring & Logging¶
This chapter you will found informations about monitoring and logging.
We generate logging based on the transactions processed by the system. The definition of transaction processing according to Wikipedia:
Transaction processing is designed to maintain a system’s Integrity (typically a database or some modern filesystems) in a known, consistent state, by ensuring that interdependent operations on the system are either all completed successfully or all canceled successfully.
Examples of transactions in diferent contexts:
- Database: database transaction (commit/rollback);
- Web Application/API: request/response cycle;
- Worker: process a message;
- Business Transactions: bill a credit card, cancel a contract.
General practices for logging generation:
- You should use the framework/language tools for logging (eg. python’s
- You should not use
echo()to produce log messages;
- You must start your log entry with a timestamp using UTC timezone.
- You should use a standard output device to produce log (
- Errors in code (programming errors) should be handled apart of business failures (transactional failures). See Error Reporting;
- You should not produce multi-line log messages (
\n) for non-debugging logs (see Log Format).
- It’s recommended to take care about the amount and the relevance of log you generate to avoid the blindness caused by excess of noise in logs and to reduce the costs of storing it.
- No sensitive or private information could be logged. You should mask all all informations that need to be protected by the Terms of Service of our product or GDPR laws. Informations like secret keys, passwords, financial informations, personal informations and implementation details of our system or infrastructure (eg. database/database table names, full paths of deployments, etc);
- We recommend that you create an unique ID for each transaction and print it on logs to make it easy to track all sub-transactions and operations inside of a transaction;
- You should use string representations or safely encoded strings in logs to avoid encoding & decoding issues with non-ascii caracters;
- Production environments must enable at least
INFOlog-level. For staging, and local development environments we use
There are two different kinds of error logs that need to be managed
separatadely. The software errors (see Error Reporting) must be
reported in a specific system for error tracking and, transactional errors, that
occurs when something goes wrong with the business rules, must be logged as a
regular log with log level
ERROR (see Log Levels).
The modern systems for log agregation offers a lot of indexing, searching, and analytics tools to be used by developers.
To make this possible this systems recommends that we generate logs in a structured way. That’s why we recommend you to use JSON-serialized log messages.
- Send the plain JSON-serialized string in a single line for each log record.
- The log structure must contains at least the following information:
LOGLEVEL: the level of the log message;
TIMESTAMP: Timestamp in
asctimeformat and UTC timezone;
GUID(optional) - GUID (eg.
UUIDv4string) of transaction (if available);
FILE/FUNCTION:LINENO(optional): file, function and line number where the log was generated. This information must be included only in
- Detailed information about the whole transaction and it sub-transactions. You
can print detailed and verbose information about the internal state of
transaction like variables, call trace (in cases where of
TRACEis supported), etc. It is important to take care of customers’ private data and sensible informations. By default this log level is not enabled in live production servers but, besides that, could be enabled for live production debugging purposes.
- Summarized information about a successfully finished transaction. You should
put one or more key information that make this transaction trackable inside
the system and you should describe what transaction executed (eg.
operation=bill credit card (capture), customer_id=XYZ123). This log level should be enabled in live production environments. In cases where the system generates a huge amount of data (eg. request/response log) you could agreggate the information in batches or route the logs to an specific system that can handle these logs in a better way.
- Something exceptional happened during the transaction processing but the
system was able to recover from this exception (eg.
operation=bill credit card (capture), customer_id=XYZ123, result=timeout connection (retrying #1 of 3)).
- The transaction failed in a way where the system could not recover itself (eg.
operation=bill credit card (capture), customer_id=XYZ123, result=failed after all retry attempts.). Errors caused by the end user must not be logged as a error (eg. Invalid username/password errors).
- The transaction failed and the system breaks completely due to this failure. This error shoud be logged in but need to raise an exception to the systems that manages error reports (see Error Reporting).
5.3. Error Reporting¶
Errors in code are caused by some part of the code that is wrongly created by the developer. Usually it raises a language exception that are not handled by the code.
You must not send these errors to the transactional logs (see Logging).