糟糕的日志可能让人抓狂。好的日志可能成为魔杖
在软件系统中编写有用且可读的日志的经验法则
引言
在本文中，我想分享我写日志的个人经验。糟糕的日志可能让人抓狂。好的日志可能成为魔杖。在我职业生涯中，我写过几份日志，并总结出了一些经验法则。我不能说我的日志已经成为我的终极魔杖，但肯定的是，当我遵循这些经验法则时，我做噩梦的次数显著减少了。本文不是关于哪种日志库更好，而是关于如何写日志。
假设
- 系统至少包含2个模块（例如，服务器和客户端）。
- 至少有100个用户同时使用该系统。
- 用户至少可以通过2种不同的流程使用该系统（应用程序）。
规则
-
日志是可交付的，应该像对待UI、API和其他软件系统组件一样对待和测试它。
这条规则的意思是——日志不是一个垃圾桶，我们可以随意往里面扔任何东西。日志是一个证人，我们将向它询问以下问题：
- 发生了什么？
- 这是什么时候发生的？
- 为什么会发生？
- 客户的说法正确吗？
因此，日志的设计应该像我们设计所有软件组件一样。
-
随着系统的发展，日志也会随之改变。
这条规则说：当我们开始开发一个软件系统时，通常我们不知道它将来会如何变化，以及在软件发布的第一版之后的一两年里，我们会收到产品部门或用户的哪些需求。软件可能会改变，因此日志也应该相应地改变。
-
日志必须有一个统一的时间线。
正如本文的假设部分所述，我们的软件系统至少有2个组件（例如，客户端和服务器）。客户端模块运行在最终用户的机器上，它有自己的时区，可能与服务器的时区不同。我建议所有日志组件都使用UTC。在这里，你可能会问：如果我们想知道事件在本地客户端时间的时间呢？那么我建议使用另一个字段，我将在其中存储事件的客户端本地时间戳。
-
日志文件的大小应该便于你喜欢的文本编辑器加载和搜索。
每个组件的日志文件不应该太大。它应该能被你喜欢的编辑器轻松加载。如果组件非常详细，并且写了很多日志，我建议使用文件滚动。大多数开源日志库允许定义取决于文件大小的文件滚动参数。如果日志超过了指定大小，库会创建一个新文件并添加一个索引。
-
所有软件系统组件的日志应汇集到一个方便查询和调查的存储库中。
如果软件系统由多个组件组成，每个组件都有自己的日志文件存储位置。如果日志文件被滚动，将所有文件合并并调查跨组件问题将非常复杂。日志存储库将解决这个问题。顺便说一下，如果我们使用存储库，我们可以忽略规则#4。
-
日志应该是单调的。
这条规则的意思是：如果第X行日志说明系统在T0时间处于状态A。在某个时刻T1，软件系统移动到状态B，这意味着日志中应该有一行明确说明系统状态已在T1时间更改为B。换句话说：每个系统状态更改都应该明确地写在日志文件中。我们不应该猜测系统处于什么状态——我们必须从日志中明确知道它。
-
如果系统做出了决定，应该在日志中记录。
这条规则可以用一个例子来演示。例如，我们正在记录用户认证过程。我们必须记录用户已认证或未认证。这两个决定都应该记录在日志中。事后阅读日志，我们可以清楚地理解认证过程究竟做出了什么决定。只记录负面决定（也存在这种方法），我们可能会部分影响规则#6：日志可能变得不单调。
-
日志消息应与源代码关联。
通过阅读日志，我们应该能够轻松找到负责特定日志消息的源代码部分。一些框架允许添加文件名和行号。
-
有些消息比其他消息更重要。
有些行对我们来说比其他行更重要。例如，我们希望以最快的方式知道系统中是否发生了异常。通常，我们为每条日志消息使用严重性。最常见的严重性是FATAL——致命异常，ERROR——错误，INFO和DEBUG。有时，还有更多的严重性，如WARNING、TRACE等。
-
日志应该是连续的。
让我们想象一下，用户抱怨他/她看到了一个错误消息。我们的开发或DevOps团队访问日志存储库，查询该错误消息，并找到相应的日志消息。这很好，但几乎无用。为什么？因为我们知道用户是对的，这很好，但如果我们能知道在这种特定情况下错误的根本原因是什么，那就更好了。为了能够调查，显然我们需要看到在错误发生前几分钟为该用户编写的一些日志消息。为了解决这个问题，我提出了连续的方法。连续方法的意思是：当用户开始某个流程时，我们会为其分配一个唯一的ID。我们会用这个唯一的ID标记该流程的每条日志消息。当流程结束时，该ID将被取消。所以回到前面的例子，一旦我们通过唯一的流程ID找到了与用户看到的错误消息相关的日志消息，我们将能够找到在显示错误消息之前编写的所有日志消息。如果日志是按照这些规则编写的，我们将能够轻松理解是什么导致系统出现这个特定用户的错误消息。
-
我们写日志是为了以后能读到它们。
日志是为了阅读而写的——所以它应该是清晰的！最好没有错别字。根据规则#1：我们应该将日志视为可交付的（例如UI）。我们不会发布不清晰或有错别字的UI，所以我们也不应该发布有错别字或不清晰的日志。
结论
以上是我写日志的经验法则。你的呢？你怎么看？我很乐意讨论并充实我的观点。
历史
- 2020-01-12 - 初始版本