快猫-记录生活 记录你_记录或不记录-使记录器成为您朋友的另一种策略

快猫-记录生活 记录你

Logging is universally present in software projects and has many different forms, requirements, and flavors.

日志记录普遍存在于软件项目中，并具有许多不同的形式，要求和风格。

Logging is everywhere, from small 1-person-startups to large enterprises. Even a simple algorithmic programming question involves some logging along the way.

从小型的1人创业公司到大型企业，日志无处不在。 即使是一个简单的算法编程问题，也涉及到一些日志记录。

We rely so much on logging to develop, maintain, and keep our programs up and running. However, not much attention has been paid to how to design logging within our systems.

我们非常依赖日志记录来开发，维护和保持程序的正常运行。 但是，如何在我们的系统中设计日志记录并没有引起太多关注。

Often times, logging is treated as a second thought – it's only sprinkled into source code upon implementation like some magic powder that helps lighten the day-to-day operational abyss in our systems.

通常，日志记录被当作第二个想法-它只是在实现时像一些神奇的粉末一样散布在源代码中，有助于减轻我们系统中的日常操作深渊。

Just like how any piece of code written will eventually become technical debt – a process that we can only slow down with great discipline – loggers rot at an unbelievable speed. After a while, we find ourselves fixing problems caused by loggers more often than the loggers give us useful information.

就像任何编写的代码最终将变成技术债一样-我们只有严格遵守纪律才能放慢这个过程-记录器以惊人的速度腐烂。 一段时间之后，我们发现自己修复记录器引起的问题的频率比记录器提供给我们有用信息的频率更高。

So how can we manage this mess with loggers and turn them into one of our allies rather than legacy ghosts haunting us from past development mistakes?

那么，我们如何与记录器一起管理这种混乱情况，将它们变成我们的盟友之一，而不是让遗留的鬼魂困扰我们过去的开发错误？

“最先进的” (“State of The Art”)

Before I dive deeper into my proposed solution, let’s define a concrete problem statement based on my observations.

在更深入地提出建议的解决方案之前，让我们根据自己的观察定义一个具体的问题陈述。

So what exactly is logging? Here's an interesting and on-point one-liner that I found from Colin Eberhardt’s article:

那么究竟是什么日志？ 这是我从Colin Eberhardt的文章中发现的有趣且即时的单点代码：

Logging is the process of recording application actions and state to a secondary interface.

日志记录是将应用程序操作和状态记录到辅助接口的过程。

This is exactly how logging is woven into systems. We all seem to subconsciously agree that loggers don't belong to any particular layers of our systems. Instead, we consider them to be application-wide and shared amongst different components.

这正是将日志记录编织到系统中的方式。 我们所有人似乎都下意识地同意记录器不属于我们系统的任何特定层。 相反，我们认为它们是应用程序范围的，并且在不同组件之间共享。

A simple diagram where logging has been fit into a system that is designed with clean architecture would look something like this:

一个简单的图表，其中已将日志记录适合采用干净架构设计的系统中，如下所示：

We can safely say that logging itself is a subsystem within our application. And we can safely say that, without careful consideration, it often spirals out of control faster than we think.

我们可以肯定地说，日志记录本身是我们应用程序中的一个子系统。 我们可以肯定地说，如果没有仔细考虑，它通常会比我们想象的更快地失控。

While designing logging to be a subsystem within our applications is not wrong, the traditional perception of logging (with 4 to 6 levels of

info

,

warn

,

error

,

debug

, and so on) often makes developers focus on the wrong thing. It makes us focus on the format rather than the actual purpose of why we are writing logs.

虽然将日志记录设计为应用程序中的子系统是没有错的，但是传统的日志记录感知(具有4到6级的

info

，

warn

，

error

，

debug

等等)通常会使开发人员专注于错误的事情。 它使我们专注于格式而不是编写日志的实际目的。

This is one of the reasons why we log errors out without thinking twice about how to handle them. It's also why we log at every step of our code while ironically being unable to debug effectively if there is a production issue.

这是我们注销错误而没有三思而后行的原因之一。 这也是为什么我们在代码的每一步都记录日志的原因，而讽刺的是，如果出现生产问题，我们将无法有效地进行调试。

This is why I am proposing an alternative framework for logging and in turn, how we can design logging into our systems reliably.

这就是为什么我提出了一个替代性的日志记录框架，然后又提出了如何可靠地将日志记录设计到系统中的原因。

黄金三镖客 (The Good, The Bad, and The Ugly)

This is a framework for how I think we should strategize our logging. It has three – and only three – categories or concerns for our logs.

这是我认为应该如何制定日志记录策略的框架。 对于我们的日志，它具有三个类别，也只有三个类别。

记录的第一条规则：不要记录 (First rule of logging: Don’t log)

Overlogging is detrimental to our teams’ productivity and ability to handle business-as-usual operations.

过度记录不利于我们团队的生产力和处理常规业务的能力。

There’re tons of reasons why we should not “Log whenever you can” as advised by some observability fanfare. Logging means more code to maintain, it incurs expense in terms of system performance, and more logging subjects us to more data privacy regulatory audits.

有很多原因导致我们不应该像某些可观察性的宣传所建议的那样“尽可能随时记录”。 日志记录意味着需要维护更多的代码，在系统性能方面会产生费用，更多的日志记录会使我们受到更多的数据隐私法规审计。

If you need more reasons to refrain from logging, check out this post by Nikita Sobolev or this post by Jeff Atwood.

如果您出于其他原因需要避免登录，请查看Nikita Sobolev的 这篇文章或Jeff Atwood的这篇文章 。

Nevertheless, I’m not advising that you eliminate logs altogether. I think logging, used correctly, can significantly help us keep our systems running reliably.

但是，我不建议您完全消除日志。 我认为正确使用日志记录可以极大地帮助我们保持系统可靠运行。

I’m just proposing we start without logging and work our way up to identify places where we need to log, rather than “log everywhere as we might need to look at them”.

我只是建议我们从不进行日志记录开始，然后逐步确定需要记录的位置，而不是“随处可见，因为可能需要查看它们”。

My rule of thumb for adding a line of logging is “if we can’t pin down an exact reason or a scenario when we will look at the log, don’t log".

我添加一条记录行的经验法则是“如果我们无法确定确切的原因或查看记录的情况， 请不要记录 ”。

With that being said, how can we safely introduce logging when it’s absolutely necessary? How should we structure our logs and format their content? What information is necessary to include in logs?

话虽如此，当绝对必要时，我们如何安全地引入日志记录呢？ 我们应该如何构造日志并格式化其内容？ 日志中需要包含哪些信息？

丑陋的 (The Ugly)

These are the first type of logs that I want to describe, and they are also the ones that I find least frequently. (If we find them too often, we might have bigger issues in our systems!)

这些是我要描述的第一类日志，也是我最不常发现的日志。 (如果我们经常发现它们，那么我们的系统中可能会有更大的问题！)

“The Ugly” is the kind of log under catastrophic or unexpected scenarios that requires immediate action (like catastrophic errors that need an application restart). We can argue that, under these circumstances, it makes more sense to use alerting tools like Sentry.

“丑陋”是在灾难性或意外情况下需要立即采取措施(例如需要重新启动应用程序的灾难性错误)的日志。 我们可以认为，在这种情况下，使用诸如Sentry之类的警报工具更为有意义。

Nevertheless, an error log might still be useful to provide ourselves with more context surrounding these errors which are not available in their stack trace. But they could help with reproducing these errors, like user inputs.

但是，错误日志可能仍然有用，可以为我们提供围绕这些错误的更多上下文，而这些错误在堆栈跟踪中不可用。 但是它们可以帮助重现这些错误，例如用户输入。

Just like the errors that they accompany, these logs should be kept to a minimum in our code and placed in a single location. They should also be designed/documented in the spec as a required system behavior for error handling. Also, they should be woven into the source code around where the error handling happens.

就像它们伴随的错误一样，这些日志应在我们的代码中保持最少，并放在一个位置。 还应将它们设计/记录在规范中，作为错误处理所需的系统行为。 而且，应该将它们编织到发生错误处理的地方的源代码中。

While format and level for “The Ugly” logs are completely preferential on a team-by-team basis, I would recommend using

log.error

or

log.fatal

before a graceful shutdown and restart of the application. You should also attach the full error stack trace and the function or requests’ input data for reproduction if necessary.

虽然“丑陋”日志的格式和级别在逐个团队的基础上是完全优先的，但我建议在正常关闭和重新启动应用程序之前使用

log.error

或

log.fatal

。 如有必要，还应附加完整的错误堆栈跟踪和函数或请求的输入数据以进行复制。

坏人 (The Bad)

“The Bad” is the type of logs that addresses expected, handled errors like network issues and user input validation. This type of log only requires developers’ attention if there’s an anomaly with them.

“不良”是用于处理预期的已处理错误(如网络问题和用户输入验证)的日志类型。 如果这类日志存在异常，则仅需要开发人员注意。

Together with a monitor set up to alert developers upon an error, these logs are handy to mitigate potential serious infrastructure or security problems.

这些日志与用于在发生错误时警告开发人员的监视器一起使用，可以缓解潜在的严重基础结构或安全问题。

This type of log should be spec-ed inside error handling technical requirements as well, and can actually be bundled if we are handling expected and unexpected errors in the same code location.

这种类型的日志也应在错误处理技术要求内指定，如果我们在同一代码位置处理预期的和意外的错误，则可以将其捆绑在一起。

Based on the nature of what they are making “visible” for developers,

log.warn

or

log.error

can be used for “The Bad” logs given a team's convention.

根据他们对开发人员“可见”的性质，给定团队惯例，

log.warn

或

log.error

可用于“不良”日志。

善良 (The Good)

Last but definitely not least, “The Good” is the type of log that should appear most often in our source code – but it's often the most difficult to get right. “The Good” kind of logs are those associated with the “happy” steps of our applications, indicating the success of operations.

最后但并非最不重要的一点是，“好”日志是应该在我们的源代码中最常出现的日志类型，但是通常最难正确处理。 “良好”类日志是与应用程序的“愉快”步骤相关联的日志，表示操作成功。

For its very nature of indicating starting/successful execution operations in our system, “The Good” is often abused by developers who are seduced by the mantra “Just one more bit of data in the log, we might need it”.

由于在系统中指示启动/成功执行操作的本质，“ The Good”经常被开发人员滥用，他们被“只需要在日志中增加一点数据，我们可能需要它”这一口号所吸引。

Again, I would circle back to our very first rule of logging: “Don’t log unless you absolutely have to”. To prevent this kind of over-logging from happening, we should document “The Good” as part of our technical requirements complementing the main business logic.

再次，我将回到我们的第一个日志记录规则：“除非绝对必要，否则不要记录”。 为了防止这种过度记录的发生，我们应该记录“良好”一词，作为对主要业务逻辑的补充的技术要求的一部分。

On top of that, for every single one of “The Good” logs that are inside our technical spec, they need to pass the litmus test: are there any circumstances under which we would look at the log (be it a customer support request, an external auditor’s inquiry)? Only this way will

log.info

not be a dreaded legacy that obscures developers’ vision into our applications.

最重要的是，对于我们技术规格中的每一个“优质”日志，他们都必须通过石蕊测试：在任何情况下，我们都会查看该日志(无论是客户支持请求，外部审计师的询问)？ 只有这样，

log.info

才不会成为使开发人员对我们的应用程序

log.info

的可怕遗产。

剩下的(你需要知道的) (The Rest (That You Need to Know))

By now I assume you've noticed that the general theme of my proposed logging strategy revolves around clear and specific documenting of the log's purpose. It is important that we treat logging as part of our requirements, and that we're specific about what keywords and messages we want to tag in each log's context for them to be effectively indexed.

到现在为止，我假设您已经注意到，我提议的日志记录策略的总体主题围绕着日志目的的清晰而具体的记录。 重要的是，我们将日志记录作为要求的一部分，并且要具体确定我们要在每个日志的上下文中标记哪些关键字和消息，以便对其进行有效索引。

Only by doing that can we be aware of each and every log that we produce, and in turn, have a clear vision into our systems.

只有这样做，我们才能知道我们生成的每一个日志，进而对我们的系统有清晰的了解。

As logs are upgraded to first-class citizens with concrete technical requirements in our specs, the implications are that they would need to be:

随着原木升级为具有我们规范中具体技术要求的一等公民，其含义是它们需要：

• maintained and updated as the business and technical requirements evolve
  随着业务和技术要求的发展而维护和更新
• covered by unit and integration tests
  单元和集成测试涵盖

This might sound like a lot of extra work to get our logs right. However, I argue that this is the kind of attention and effort logging deserves so it can be useful.

听起来可能需要做很多额外工作才能使我们的日志正确无误。 但是，我认为这是日志记录应得到的关注和努力，因此它很有用。

Serve our logs, and we will be rewarded splendidly!

提供我们的日志，我们将获得出色的回报！

实用的迁移指南 (A Practical Migration Guide)

I reckon there’s no use for a new logging strategy (or any new strategies/frameworks for that matter) for legacy projects if there’s no way of moving them from their messy state to the proposed ideal.

我认为，如果没有办法将遗留项目从凌乱的状态转移到建议的理想状态，则无需为遗留项目使用新的日志记录策略(或与此相关的任何新策略/框架)。

So I have a three-step general plan for anyone who is frustrated with their system's logs and is willing to invest the time to log more effectively.

因此，对于那些对系统日志感到沮丧并愿意花时间来更有效地进行日志记录的人，我有一个三步走的总体计划。

确定通常的嫌疑犯 (Identify The Usual Suspects)

Since the idea is to reduce garbage logs, our first step is to identify where the criminals are hiding. With the powerful text editors and IDEs we have nowadays (or

grep

if you are reading this in the past through a window-to-the-future), all occurrences of logging can be easily identified.

由于该想法是减少垃圾日志，因此我们的第一步是确定罪犯躲藏的地方。 如今，有了功能强大的文本编辑器和IDE(或者

grep

如果您过去是通过“未来之窗”阅读的，则可以使用

grep

)，可以轻松识别所有日志记录。

A document (or spreadsheet if you would like to be organised) documenting all of these logging occurrences might be necessary if there are too many of them.

如果记录过多，则可能需要一个文档(或您希望组织的电子表格)。

定罪他们坏演员！ (Convict Them Bad Actors!)

After identifying all suspects, it’s time to weed out the bad apples. Logs which are duplicated or unreachable are low hanging fruits that we can immediately eliminate from our source code.

在确定所有嫌疑人之后，该是清除坏苹果的时候了。 重复或无法访问的日志是低挂的果实，我们可以立即从源代码中消除它们。

For the rest of our logging occurrences, it’s time to involve other stakeholders like the “inception” engineer who started the project (if that is possible), product managers, customer support, or compliance folks to answer the question: Do we need each one of these logs, and if so, what are they being used for?

对于其余的日志记录事件，是时候让其他利益相关者，例如启动项目的“初始”工程师(如果可能)，产品经理，客户支持或合规人员来回答这个问题：我们需要每个人吗？这些日志，如果是的话，它们是用来做什么的？

光在隧道的尽头 (Light At the End of the Tunnel)

Now that we have a narrowed-down list of absolutely necessary logs, turning them into technical requirements with documented purpose for each one of them is essential to nail down a contract (or we can call it specification) for our logging subsystem. Ask yourself what to do when a

log.error

happens, and who are we

log.info

-ing for?

现在，我们已经缩小了绝对必要日志的列表，将它们转变为具有文档目的的技术要求，对于确定每个日志子系统的合同(或称为规范)至关重要。 问问自己，当一个做什么

log.error

发生，而我们是谁

log.info

-ing呢？

After this, it’s just a matter of discipline in the same way that we write and maintain software in general. Let's all work together and make logging awesome!

此后，就像我们一般编写和维护软件一样，这只是纪律问题。 让我们一起努力，让日志记录变得很棒！

You can reach out to me on Twitter with any questions or comments.

如有任何问题或评论，您可以在Twitter上与我联系 。

翻译自: https://www.freecodecamp.org/news/how-to-use-logs-effectively-in-your-code/

快猫-记录生活 记录你