日志工作原理

Caddy 拥有强大而灵活的日志功能，但它们可能与您习惯的不同，尤其是如果您来自更古老的共享托管或其他传统 Web 服务器。

概述

日志有两个主要方面：发射和消费。

发射意味着生成消息。它包括三个步骤

收集相关信息（上下文）
构建有用的表示（编码）
将该表示发送到输出（写入）

此功能内置于 Caddy 的核心，使 Caddy 代码库或模块（插件）的任何部分都能发射日志。

消费是消息的摄取和处理。为了有用，发射的日志必须被消费。仅仅写入但从未读取的日志没有价值。消费日志可以像管理员读取控制台输出一样简单，也可以像将日志聚合工具或云服务附加到日志消息以进行过滤、计数和索引一样高级。

Caddy 的作用

Caddy 是一个日志发射器。它不消费日志，除了编码和写入日志所需的最小处理。这很重要，因为它使 Caddy 的核心更简单，从而导致更少的错误和边缘情况，同时减少维护负担。最终，日志处理超出了 Caddy 核心的范围。

但是，始终有可能存在一个消费日志的 Caddy 应用程序模块。（据我们所知，它还不存在。）

结构化日志

与大多数现代应用程序一样，Caddy 的日志是结构化的。这意味着消息中的信息不仅仅是一个不透明的字符串或字节切片。相反，数据保持强类型，并通过各个字段名称进行键控，直到需要对消息进行编码并将其写入为止。

比较传统的非结构化日志——例如与传统 HTTP 服务器一起使用的过时的通用日志格式 (CLF)

127.0.0.1 - - [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.1" 200 2326

此格式“具有结构”，但不是“结构化”：它只能用于记录 HTTP 请求。没有（有效）的方法以不同的方式对其进行编码，因为它是一个不透明的字节字符串。它还缺少很多信息。它甚至不包括请求的 Host 标头！此日志格式仅在托管单个站点时以及获取有关请求的最基本信息时才有用。

现在比较来自 Caddy 的等效结构化日志消息，以 JSON 编码并以易于显示的格式进行格式化

{
	"level": "info",
	"ts": 1646861401.5241024,
	"logger": "http.log.access",
	"msg": "handled request",
	"request": {
		"remote_ip": "127.0.0.1",
		"remote_port": "41342",
		"client_ip": "127.0.0.1",
		"proto": "HTTP/2.0",
		"method": "GET",
		"host": "localhost",
		"uri": "/",
		"headers": {
			"User-Agent": ["curl/7.82.0"],
			"Accept": ["*/*"],
			"Accept-Encoding": ["gzip, deflate, br"],
		},
		"tls": {
			"resumed": false,
			"version": 772,
			"cipher_suite": 4865,
			"proto": "h2",
			"server_name": "example.com"
		}
	},
	"bytes_read": 0,
	"user_id": "",
	"duration": 0.000929675,
	"size": 10900,
	"status": 200,
	"resp_headers": {
		"Server": ["Caddy"],
		"Content-Encoding": ["gzip"],
		"Content-Type": ["text/html; charset=utf-8"],
		"Vary": ["Accept-Encoding"]
	}
}

您可以看到结构化日志如何更有用，并包含更多信息。此日志消息中大量的信息不仅有用，而且几乎没有性能开销：Caddy 的日志是零分配的。结构化日志对数据类型或上下文没有限制：它们可以在任何代码路径中使用，并包含任何类型的信息。

由于日志是结构化和强类型的，因此它们可以编码为任何格式。因此，如果您不想使用 JSON，日志可以编码为任何其他表示形式。Caddy 通过日志编码器模块支持其他格式，甚至可以添加更多格式。

最重要的是，在结构化日志和传统格式之间的区别中，结构化日志可以转换为传统的通用日志格式，但反之则不行。从 CLF 到结构化格式并非易事（或至少效率低下），考虑到信息的缺乏，这是不可能的。

本质上，高效的结构化日志通常会促进以下理念

太多日志胜过太少日志
过滤胜过丢弃
推迟编码以获得更大的灵活性和互操作性

发射

在代码中，日志发射类似于以下内容

logger.Debug("proxy roundtrip",
	zap.String("upstream", di.Upstream.String()),
	zap.Object("request", caddyhttp.LoggableHTTPRequest{Request: req}),
	zap.Object("headers", caddyhttp.LoggableHTTPHeader(res.Header)),
	zap.Duration("duration", duration),
	zap.Int("status", res.StatusCode),
)

您可以看到，此函数调用包含日志级别、消息和几个数据字段。所有这些都是强类型的，Caddy 使用零分配日志库，因此日志发射速度快，效率高，几乎没有开销。

logger 变量是一个 zap.Logger，它可能与它关联任何数量的上下文，其中包括名称和数据字段。这使得记录器可以很好地“继承”自父上下文，从而实现高级跟踪和指标。

从那里，消息将通过高效的处理管道发送，在该管道中它被编码并写入。

日志管道

如您在上面看到的，消息由记录器发射。然后将消息发送到日志以进行处理。

Caddy 允许您配置多个日志，这些日志可以处理消息。日志由编码器、写入器、最小级别、采样率以及要包含或排除的记录器列表组成。在 Caddy 中，始终存在一个名为 default 的默认日志。您可以通过在此对象中指定一个键为 "default" 的日志来自定义它。

编码器：日志的格式。将内存中的数据表示转换为字节切片。编码器可以访问日志消息的所有字段。
写入器：日志输出。可以是任何日志写入器模块，例如写入文件或网络套接字。它只是写入字节。
级别：日志具有不同的级别，从 DEBUG 到 FATAL。低于指定级别的消息将被日志忽略。
采样：极其热点的路径可能会发射比有效处理更多的日志；启用采样是一种在仍然产生代表性消息样本的同时减少负载的方法。
包含/排除：每条消息都由记录器发射，记录器具有名称（通常来自模块 ID）。日志可以包含或排除来自某些记录器的消息。

当 Caddy 发射日志消息时

将原始记录器的名称与每个日志的包含/排除列表进行检查；如果包含（或未排除），则将其允许进入该日志。
如果启用了采样，则快速计算将确定是否保留日志消息。
使用日志配置的编码器对消息进行编码。
然后将编码后的字节写入日志配置的写入器。

默认情况下，所有消息都将发送到所有配置的日志。这符合上面描述的结构化日志的值。您可以通过设置它们的包含/排除列表来限制哪些消息发送到哪些日志，但这主要用于过滤来自不同模块的消息；它不打算用作日志聚合服务。为了使 Caddy 的日志管道保持精简和高效，日志消息的高级处理被推迟到消费。

消费

消息发送到输出后，消费者将读取它们，解析它们，并相应地处理它们。

这是一个与发射日志完全不同的问题域，Caddy 的核心不处理消费（尽管 Caddy 应用程序模块当然可以）。您可以使用许多工具来处理 JSON 消息流（或其他格式）并查看、过滤、索引和查询日志。您甚至可以编写或实现自己的工具。

例如，如果您运行需要根据特定字段（例如主机名）将 CLF 分隔到不同文件的传统软件，您可以使用或编写一个简单的工具，该工具读取 JSON，调用 sprintf() 来创建 CLF 字符串，然后根据 request.host 字段中的值将其写入文件。

Caddy 的日志功能也可以用于实现指标和跟踪：指标基本上会统计具有某些特征的消息，而跟踪会根据它们之间的共性将多个消息链接在一起。

通过消费 Caddy 的日志，您可以做无数的事情！