佳佳的博客

Appearance

Logback 手册 - 第十二章：接收器 ​

🏷️ Logback 手册

来源：https://logback.qos.ch/manual/receivers.html
作者：Ceki Gülcü, Sébastien Pennec, Carl Harris
版权所有 © 2000-2022 QOS.ch Sarl

本文档使用 知识共享署名 - 非商业 - 相同方式共享 2.5 许可协议

You cannot swim for new horizons until you have courage to lose sight of the shore.

在你有勇气失去岸的视线之前，你无法游向新的地平线。

——威廉·福克纳

WARNING

为了运行本章中的示例，确保类路径上存在某些 jar 文件。请参考 设置页面 以获取更多详细信息。

什么是接收器？ ​

接收器 是 Logback 组件，它从远程追加器接收日志事件，并根据本地策略记录每个接收到的事件。使用基于套接字的追加器和接收器的组合，可以构建复杂的拓扑结构，用于在网络上分发应用程序的日志事件。

接收器扩展了 ch.qos.logback.classic.​net.ReceiverBase 类。由于接收器扩展了这个类，因此接收器参与了 Logback 组件的 LifeCycle，并且接收器是 ContextAware 的一部分。

在 Logback 中，历史上提供了通过网络连接传递日志事件的支持，这是通过 SocketAppender 和相应的 SimpleSocketServer 完成的。**追加器充当客户端，启动到服务器应用程序的网络连接，并通过网络连接传递日志事件。**接收器组件和相应的追加器支持提供了更大的灵活性。

接收器组件在 logback.xml 中进行配置，就像配置任何其他 Logback 组件一样。这允许利用 Joran 的全部功能来配置接收器组件。此外，任何 应用程序都可以通过简单配置一个或多个接收器组件来接收来自远程追加器的日志事件。

**追加器和接收器之间的连接初始化可以在任一方向上进行。**接收器可以作为服务器角色被动地监听来自远程追加器客户端的连接。另外，接收器也可以作为客户端角色，启动到作为服务器角色的远程追加器的连接。无论追加器和接收器的各自角色如何，日志事件始终从追加器流向接收器。

允许接收器发起到追加器的连接尤其在某些情况下特别有用：

  • 出于安全原因，中央日志服务器可能位于不允许传入连接的网络防火墙后面。使用作为客户端角色的接收器组件，中央日志服务器（在防火墙内部）可以发起到感兴趣的应用程序（在防火墙外部）的连接。
  • 开发人员工具（例如 IDE 插件）和企业管理应用程序通常希望能够访问运行中应用程序的日志事件流。传统上，Logback 已经支持这一点（例如在 Logback Beagle 中），方法是要求接收端应用程序（例如在 IDE 中运行的开发人员工具）以服务器角色被动地监听来自远程追加器的连接。这可能很难管理，特别是对于在开发人员工作站上运行的工具，这些工具可能确实是移动的。然而，现在可以使用作为客户端角色的 Logback 接收器组件来实现此类工具，以便接收本地显示、过滤和警报的日志事件。

Logback 配置可以包括任意数量的接收器组件，这些组件可以以任何组合的服务器或客户端角色进行操作。唯一的限制是每个作为服务器角色的接收器必须监听不同的端口，并且每个作为客户端角色的接收器将连接到一个远程追加器。

作为服务器角色的接收器 ​

配置为作为服务器角色被动地监听来自远程追加器的连接的接收器。这在功能上等同于使用独立的 SimpleSocketServer 应用程序，只不过通过使用接收器组件，任何 使用 Logback Classic 的应用程序都可以通过简单在 logback.xml 中配置接收器来接收来自远程追加器的日志事件。

Logback 包括两个作为服务器角色的接收器组件；ServerSocketReceiver 及其启用 SSL 的子类型 SSLServerSocketReceiver。这两个接收器组件均设计为接受来自传入 SocketAppender（或 SSLSocketAppender）客户端的连接。

ServerSocketReceiver 组件提供以下可配置属性：

属性名称类型描述
addressString接收器将监听的本地网络接口地址。如果未指定此属性，则接收器将在所有网络接口上监听。
portint接收器将监听的 TCP 端口。如果未指定此属性，将使用默认值。
sslSSLConfiguration仅对 SSLServerSocketReceiver 支持，该属性提供接收器将使用的 SSL 配置，如 使用 SSL 中所述。

使用 ServerSocketReceiver ​

以下配置使用 ServerSocketReceiver 组件，配合最小的本地追加器和记录器配置。从远程追加器接收到的日志事件将由根记录器匹配，并传递给本地控制台追加器。

示例：基本的 ServerSocketReceiver 配置（logback-examples/​src/main/resources/​chapters/receivers/​socket/receiver1.​xml）

接收器组件的 class 属性标识了我们希望使用的接收器子类型。在这个示例中，我们使用了 ServerSocketReceiver。

我们的示例服务器应用程序在功能和设计上与 SimpleSocketServer 非常相似。它只是将一个 logback 配置文件的路径作为命令行参数接受，并运行给定的配置。尽管我们的示例有些琐碎，但请记住，您可以在 任何 应用程序中配置 logback 的 ServerSocketReceiver（或 SSLServerSocketReceiver）组件。

在 logback-examples 目录的 shell 中，我们可以按如下方式运行我们的示例服务器应用程序 [1]：

bash
java -Dport=6000 chapters.receivers.socket.ReceiverExample \ 
      src/main/java/chapters/receivers/socket/receiver1.xml

我们可以使用配置了 SocketAppender 的客户端应用程序连接到正在运行的接收器。我们的示例客户端应用程序只是加载一个 logback 配置，该配置将一个 socket appender 连接到我们的示例接收器。然后，它等待用户输入，以消息的形式将消息传递给接收器。我们可以按如下方式运行示例客户端应用程序 [2]：

bash
java -Dhost=localhost -Dport=6000 \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender1.xml

使用 SSLServerSocketReceiver ​

以下配置重复了相同的最小追加器和记录器配置，但使用了扮演服务器角色的启用了 SSL 的接收器组件。

示例：基本的 SSLServerSocketReceiver 配置（logback-examples/​src/main/resources/​chapters/receivers/​socket/receiver2.​xml）

这个配置与之前使用 ServerSocketReceiver 的示例之间的主要区别在于在 class 属性中指定了 SSLServerSocketReceiver，并且存在嵌套的 ssl 属性，用于在此处使用替换变量指定接收器私钥和证书的密钥库的位置和密码。有关为 Logback 组件配置 SSL 属性的详细信息，请参阅 Using SSL。

我们可以使用相同的示例服务器配置运行此配置，只需添加几个额外的配置属性：

bash
java -Dport=6001 \
      -Dkeystore=file:src/main/java/chapters/appenders/socket/ssl/keystore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.ReceiverExample \
      src/main/java/chapters/receivers/socket/receiver2.xml

请注意，命令行中给出的 keystore 属性指定了一个文件 URL，用于标识密钥库的位置。您还可以使用类路径 URL，如 Using SSL 中所述。

我们可以使用配置了 SSLSocketAppender 的客户端应用程序连接到正在运行的接收器。我们使用前面示例中使用的示例客户端应用程序，并使用启用 SSL 的 appender 配置文件。我们如下运行示例：

bash
java -Dhost=localhost -Dport=6001 \
      -Dtruststore=file:src/main/java/chapters/appenders/socket/ssl/truststore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender2.xml

请注意，我们的示例使用了一个自签名的 X.509 凭据，仅适用于测试和实验。在生产环境中，您应该获取一个适当的 X.509 凭证来标识您的启用 SSL 的 logback 组件。有关更多信息，请参阅 Using SSL。

扮演客户端角色的接收器 ​

配置为扮演客户端角色的接收器将发起与远程 appender 的连接。远程 appender 必须是服务器类型，如 ServerSocketAppender。

Logback 包含两个以客户端角色扮演的接收器组件：SocketReceiver 及其启用 SSL 的子类型 SSLSocketReceiver。这两个接收器组件都设计用于发起与作为 ServerSocketAppender（或 SSLServerSocketAppender）的远程 appender 的连接。

以下配置属性由 SocketReceiver 子类型支持：

属性名称类型描述
remoteHostString远程服务器套接字 appender 的主机名或地址。
portint远程服务器套接字 appender 的端口号。
reconnectionDelayint表示连接失败后等待重新连接的毫秒数的正整数。默认值为 30000（30 秒）。
sslSSLConfiguration仅适用于 SSLSocketReceiver，此属性提供将用于此接收器的 SSL 配置，如 Using SSL 中所述。

使用 SocketReceiver ​

SocketReceiver 的配置与之前使用 ServerSocketReceiver 的示例非常相似。区别在于客户端和服务器的角色相反；SocketReceiver 类型的接收器是客户端，远程 appender 充当服务器。

示例：基本的 SocketReceiver 配置（logback-examples/​src/main/resources/​chapters/receivers/​socket/receiver3.​xml）

这个配置将导致 logback 连接到由 host 和 port 替换变量指定的主机和端口上运行的 ServerSocketAppender。接收到的来自远程 appender 的日志事件将通过控制台 appender（根据此处的配置）在本地记录。

假设您位于 logback-examples/ 目录中，您可以使用以下命令运行此示例配置：

bash
java -Dhost=localhost -Dport=6000 \
      chapters.receivers.socket.ReceiverExample \
      src/main/java/chapters/receivers/socket/receiver3.xml

该示例加载配置，然后只是等待来自远程 appender 的日志事件。如果运行此示例时远程 appender 没有运行，则会周期性地在日志输出中出现 "connection refused" 消息。接收器将周期性地尝试重新连接到远程 appender，直到成功或直到关闭记录器上下文为止。尝试之间的延迟间隔可以使用 reconnectionDelay 属性进行配置，如示例配置所示。

我们可以提供一个远程 appender，我们的示例接收器可以连接到该 appender，使用之前使用的相同的 appender 示例。该示例加载包含 ServerSocketAppender 的 logback 配置，然后等待用户输入，输入的消息将发送到连接的接收器。我们可以按以下方式运行示例 appender 应用程序：

bash
java -Dport=6000 \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender3.xml

如果在接收器未连接时输入要发送的消息，请注意该消息将被简单地丢弃。

使用 SSLSocketReceiver ​

SSLSocketReceiver 所需的配置与 SocketReceiver 使用的配置非常相似。主要区别在于指定接收器的类以及能够嵌套 ssl 属性以指定 SSL 配置属性。以下示例演示了基本配置：

示例：基本的 SSLSocketReceiver 配置（logback-examples/​src/main/resources/​chapters/receivers/​socket/receiver4.​xml）

请注意，class 属性现在指定为 SSLSocketReceiver，除了上一个示例中显示的配置属性之外，此配置还包含一个 SSL 配置，指定将用于验证远程 appender 受信任的信任存储库的位置和密码。有关配置 SSL 属性的更多信息，请参见 使用 SSL。

您可以使用以下命令运行此示例配置：

bash
java -Dhost=localhost -Dport=6001 \
      -Dtruststore=file:src/main/java/chapters/appenders/socket/ssl/truststore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.ReceiverExample \
      src/main/java/chapters/receivers/socket/receiver4.xml

启动后，接收器会尝试连接到指定的远程 appender。假设 appender 尚未运行，则会周期性地在日志输出中出现一个 "connection refused" 消息；接收器将在延迟 reconnectionDelay 属性指定的时间段后周期性地重试连接到远程 appender。

我们可以提供一个远程 appender，我们的示例接收器可以连接到该 appender，使用之前使用的相同的 appender 示例。该示例加载包含 SSLServerSocketAppender 的 logback 配置，然后等待用户输入，输入的消息将传递给连接的接收器。我们可以按以下方式运行示例 appender 应用程序：

bash
java -Dport=6001 \
      -Dkeystore=file:src/main/java/chapters/appenders/socket/ssl/keystore.jks \
      -Dpassword=changeit \
      chapters.receivers.socket.AppenderExample \
      src/main/java/chapters/receivers/socket/appender4.xml

如果在接收器未连接时输入要发送的消息，请注意该消息将被简单地丢弃。

再次强调，我们的示例使用的是适用于测试和实验的自签名 X.509 凭据。在生产环境中，您应该获得一个适当的 X.509 凭据来识别您的启用 SSL 的 logback 组件。有关更多信息，请参见 使用 SSL。

  1. chapters.receivers.socket.ReceiverExample ↩︎

  2. chapters.receivers.socket.AppenderExample ↩︎