良好的日志是运维、开发人员排查问题的好工具，本文建议定义 JSON 格式的结构化日志格式，从而有效优化人工以及机器排查日志的效能，并能方便创建机器索引。原文: The Art of Logging
从历史上看，日志对于诊断应用程序和基础设施性能非常重要，被广泛应用于业务仪表板的可视化和性能分析。
对日志文件中的数据进行结构化，以便能够有效提取、操作和分析数据(除了便于人类理解，也便于机器分析)的重要性正在迅速上升。此外，微服务的兴起也带来了另一个挑战，即怎样在整个系统中跟踪请求的传播。
本文将介绍便于人和机器解析、理解的日志结构的最佳格式，特别是跟用户登录有关的关键信息及数据结构的建议，并将尝试提供一些重要的注意事项。
为什么日志应该是人类可读的?
尽管日志最初是由机器来解析、处理和存储的，但现在正越来越多的由人类来读取、理解和诊断。日志是我们调查凶杀现场的最佳指标，而凶手正是我们的死敌: Bug!🐛
没什么比试图理解冗长而且非结构化的日志线中丢失的信息更令人沮丧和耗时的了。日志必须有有意义，并且人们应该可以很容易理解和深入挖掘与他们有关的内容。
66.249.65.159 - - [06/Nov/2014:19:10:38 +0000] "GET /news/53f8d72920ba2744fe873ebc.html HTTP/1.1" 404 177 "-" "Debian APT-HTTP/1.3 (0.8.16~exp12ubuntu10.16)"
尽管我们已经习惯了默认的 Nginx 格式，但上面的示例仍然很难阅读和处理。例如，这是为了再现生产 bug 而提取的巨大日志文件的一部分，很难理解其背后含义是什么。
JSON 相对于其他数据交换格式(如 XML)的优势非常明显，这是一种在数组中有序嵌套的键值对的简单语法，对人类来说很容易读、写和理解。
那么，用 JSON 编写的日志消息是什么样子的呢？以下是与之前相同的 JSON 格式的 Nginx web 服务器日志示例:
{ "time": "06/May/2022:19:10:38 +0100", "remote_ip": "66.249.65.159", "remote_user": "-", "request": "GET /news/53f8d72920ba2744fe873ebc.html HTTP/1.1", "response": 404, "bytes": 177, "referrer": "-", "agent": "Debian APT-HTTP/1.3 (0.8.16~exp12ubuntu10.16)" }
为什么日志应该是对机器友好的?
再次考虑上面的日志线示例:
66.249.65.159 - - [06/Nov/2014:19:10:38 +0000] "GET /news/53f8d72920ba2744fe873ebc.html HTTP/1.1" 404 177 "-" "Debian APT-HTTP/1.3 (0.8.16~exp12ubuntu10.16)"
为了理解，我们需要:
- 理解语法
- 编写逻辑来解析消息并提取需要的数据
不幸的是，这种逻辑很脆弱，如果日志格式发生了更改(比如开发人员添加了一个新字段或更改了字段顺序)，那么解析器就会崩溃，相信任何人都有面对或经历类似问题的时候。
而这就是像 JSON 这样的结构化格式可以提供帮助的地方。键值对使提取特定值和跨数据集筛选和搜索变得容易，如果添加了新的键值对，解析日志消息的软件将只是忽略那些非期望的键，而不会完全失效。
Alex Knight@Unsplash
在机器上使用 JSON 日志的好处是:
- 具有结构化的格式，因此便于分析日志和查询每个字段。
- 每种编程语言都可以对其进行解析。
通常，我们可以在日志解析系统(ELK、newRelic、Datadog 等)中聚合 JSON 数据，从而为我们提供强大的报告、搜索和对数据的洞察能力。这些工具使索引某些字段变得更容易，从而解决在微服务环境下跟踪请求的问题。
应该包含哪些信息?
这里列举了应该包含在日志中的信息列表，有些元素是可选的，字段名前面的(o)表示可选字段。
message: 用于描述情况的人类可读的信息，在过滤时易于阅读，以获得对内容的概述。level: 优先级级别的数值表示(下一节将详细介绍)，对于将消息按不同优先级排序或生成包含系统概述的仪表板非常有用。level_name: 优先级级别的字符串表示(更多细节将在下一节中介绍)。datetime_iso: iso8601格式的日期，因为我们需要将时间与其他事件相关联，因此是必填项。尽管可以使用服务器的日期-时间，但可能会产生误导，因为服务器的时间可能并不一致，甚至可能位于不同的时区。correlation_id: 这是微服务环境的一个重要字段，我们将基于解析后的消息/请求的 correlation id 来跟踪服务之间整个链路的请求。- (o)
hostname: 用于确定是哪台机器生成了此日志，建议在微服务环境中使用。当服务器日志已经从 docker 的服务名映射到原始主机时，可能是多余的。 - (o)
build_id: 记录信息的软件版本，可以帮助跟踪不兼容问题，特别是那些在服务器端软件部署期间发生的问题。 - (o)
application: 用于识别哪个设备或应用程序生成了此日志。 - (o)
owner_id: 报告用户 id 或 API key id(如果有的话)，可以追踪用户执行了哪些步骤来再现他的操作。 - (o)
tenant_id: 报告可用的租户 id，对于多租户系统非常有用。 - (o)
tags: 可以是一个元素数组，包含关于请求的元信息，如类型、使用的协议等。 - (o)
stacktrace:: 有 stack trace 时以字符串格式显示 stack trace。 - (o)
exception:: 有异常消息时显示异常消息。
日志级别和相关日志码
建议格式
那么，用 JSON 编写的日志消息是什么样的呢？
以下是示例建议的日志概念格式:
使用 carbon 生成的示例消息
观察
- 在日志服务器中，应该为以下元素建立索引，以便更快搜索:
owner_id、tenant_id、correlation_id、level、level_name和application。 - 当可选字段可用时，应该添加到日志中，只能在没有的时候将其忽略，而在调试系统时，它们的值将是可见的。
- context 元素可以包含其他有用的字段(比如传入请求的打印)。
- 出于安全性或合规性原因(个人信息保护)，日志应该对请求中可能出现的关键字段(比如密码)设置一些过滤器，以便在输出内容之前匿名化。
- 每个服务都应该转发收到的
correlation_id，如果这个值不存在，应该生成一个新值并将其传递给下一个服务。API 网关(如果有的话)应该始终关注该字段是否存在、是否需要生成。
最佳实践
- 花时间设计日志结构，使格式满足我们的需要，并且可以很容易复制。然而，有些团队可能需要不同的版本，还要考虑适合需求的粒度级别。通常，公司内部的"日志概念"文档可以让所有团队遵循同一种模式，并且有新的开发人员加入时会非常有用。
- 尽可能多的记录日志。在发生致命异常时知道模块和行号，或者在遇到安全漏洞时知道 IP/用户名，对于更快、更准确解决问题是非常宝贵的。如果想避免一些不必要的噪音，仍然可以调整级别，通过经验可以知道什么级别最适合当前项目！
- 保持一致性是每个人的首要任务。JSON 消息中适当的键和准确的值使调试更容易、更有效。Correlation Id 和日志级别可以明确证明这一点。
- 编写代码的同时记录日志，像编写单元测试一样，尝试保持相同的风格并记录系统交互。为了避免丢失函数的上下文和边缘情况，当场完成比稍后添加更容易。
最后
- 本文不是要推动标准，而是要尝试创建一种逻辑化组织的日志格式，以优化如 newRelic 或 ELK 等日志解析系统。这一格式将帮助我们生成有用的仪表板、指标和事件通知(例如，在错误百分比超过 5%时触发警报)。
- 在应用程序中实现标准化日志系统将花费一定的时间和金钱，调试也需要付出代价，特别是有关关键边界条件信息的情况下。在做出决定的时候应该权衡考虑。
- 日志记录是一个公说公有理、婆说婆有理的话题，有时还会引起分歧。但是，无论使用哪种格式，总是比完全不用日志要好。
- 建议使用异步日志记录来避免性能问题。
