Docker 日志驱动插件

本文档描述了 Docker 的日志驱动插件。

日志驱动使用户能够将容器日志转发到另一个服务进行处理。Docker 内置了多种日志驱动，但无法仅凭内置驱动满足所有使用场景。插件使 Docker 能够支持广泛的日志服务，而无需将这些服务的客户端库嵌入到主 Docker 代码库中。有关更多信息，请参阅插件文档。

创建一个日志插件

日志插件的主接口使用与其他插件类型相同的 JSON+HTTP RPC 协议。请参见示例插件以获取日志插件的参考实现。该示例封装了内置的 jsonfilelog 日志驱动程序。

LogDriver 协议

日志插件必须在插件激活期间注册为 LogDriver。一旦激活，用户可以将该插件指定为日志驱动程序。

日志插件必须实现两个 HTTP 端点：

`/LogDriver.StartLogging`

向插件发出信号，表示容器正在启动，插件应开始接收日志。

日志将通过请求中定义的文件进行流式传输。在 Linux 上，该文件是一个 FIFO（命名管道）。目前 Windows 不支持日志插件。

请求：

{
  "File": "/path/to/file/stream",
  "Info": {
          "ContainerID": "123456"
  }
}

File 是需要消费的日志流的路径。每次调用 StartLogging 都应提供不同的文件路径，即使该插件此前已接收过该容器的日志。该文件由 Docker 创建，并带有随机生成的名称。

Info 是关于正在记录日志的容器的详细信息。这部分内容相对自由，但由以下结构定义定义：

type Info struct {
	Config              map[string]string
	ContainerID         string
	ContainerName       string
	ContainerEntrypoint string
	ContainerArgs       []string
	ContainerImageID    string
	ContainerImageName  string
	ContainerCreated    time.Time
	ContainerEnv        []string
	ContainerLabels     map[string]string
	LogPath             string
	DaemonName          string
}

ContainerID 将始终与此结构一起提供，但其他字段可能为空或缺失。

响应：

{
  "Err": ""
}

如果在此请求期间发生错误，请将错误消息添加到响应中的 Err 字段。如果没有错误，您可以发送空响应（{}）或为 Err 字段发送空值。

此时，驱动程序应开始从传入的文件中消费日志消息。如果消息未被消费，可能会导致容器在尝试向其标准输入/输出流写入时发生阻塞。

日志流消息被编码为 Protocol Buffers。Protobuf 定义位于 moby 仓库。

由于 Protocol Buffers 不是自定界的，因此必须使用以下流格式对其进行解码：

[size][message]

其中 size 是一个 4 字节的大端序二进制编码的 uint32。size 在此处定义了下一条消息的大小。message 是实际的日志条目。

流式编解码器的参考 Golang 实现可以在这里找到。

`/LogDriver.StopLogging`

向插件发出信号，停止从指定文件收集日志。收到响应后，Docker 将删除该文件。在响应此请求之前，您必须确保已收集中断流上的所有日志，否则有丢失日志数据的風險。

对此端点的请求并不意味着容器已被删除，仅表示它已停止。

请求：

{
  "File": "/path/to/file/stream"
}

响应：

{
  "Err": ""
}

如果在此请求期间发生错误，请将错误消息添加到响应中的 Err 字段。如果没有错误，您可以发送空响应（{}）或为 Err 字段发送空值。

可选端点

日志插件可以实现两个额外的日志端点：

`/LogDriver.Capabilities`

定义日志驱动器的功能。您必须实现此端点，Docker 才能利用任何已定义的功能。

请求：

{}

响应：

{
  "ReadLogs": true
}

支持的功能：

ReadLogs - 这表示该插件具备向客户端回读日志的能力。报告支持 ReadLogs 的插件必须实现 /LogDriver.ReadLogs 端点

`/LogDriver.ReadLogs`

将日志读取回客户端。当调用 docker logs <container> 时使用。

为了使 Docker 能够使用此端点，插件必须在调用 /LogDriver.Capabilities 时进行指定。

请求：

{
  "ReadConfig": {},
  "Info": {
    "ContainerID": "123456"
  }
}

ReadConfig 是读取选项列表，它由以下 golang 结构体定义：

type ReadConfig struct {
	Since  time.Time
	Tail   int
	Follow bool
}

Since 定义应发送的最旧日志。
Tail 定义要读取的行数（例如，类似于命令 tail -n 10）
Follow 表示客户端希望在读取完现有日志后保持连接，以接收新产生的日志消息。

Info 与 /LogDriver.StartLogging 中定义的类型相同。它应用于确定要读取的日志集。

响应：

{{ log stream }}

响应应使用与插件从 Docker 消费的消息相同的格式对日志消息进行编码。