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

佳佳_2023-12-15 17:07

来源：logback.qos.ch/manual/rece... 作者：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.

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

------威廉·福克纳

为了运行本章中的示例，确保类路径上存在某些 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 组件提供以下可配置属性：

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

使用 ServerSocketReceiver

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

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

传统格式

xml 复制代码 
<configuration debug="true">

  <appender name="CONSOLE" class="ch.qos.logback.​core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE" />
  </root>

  <receiver class="ch.qos.logback.​classic.net.server.​ServerSocketReceiver">
    <port>${port}</port>
  </receiver>

</configuration>

规范格式 (1.3)

xml 复制代码 
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>

<configuration debug="true">
  <import class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"/>
  <import class="ch.qos.logback.​core.ConsoleAppender"/>
  <import class="ch.qos.logback.​classic.net.server.​ServerSocketReceiver"/>

  <appender name="CONSOLE" class="ConsoleAppender">
    <encoder class="PatternLayoutEncoder">
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE"/>
  </root>
  <receiver class="​ServerSocketReceiver">
    <port>${port}</port>
  </receiver>
</configuration>

接收器组件的 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）

传统格式

xml 复制代码 
<configuration debug="true">

  <appender name="CONSOLE" class="ch.qos.logback.​core.ConsoleAppender">
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE" />
  </root>

  <receiver class="ch.qos.logback.​classic.net.server.​SSLServerSocketReceiver">
    <port>${port}</port>
    <ssl>
      <keyStore>
        <location>${keystore}</location>
        <password>${password}</password>
      </keyStore>
    </ssl>
  </receiver>

</configuration>

规范格式 (1.3)

xml 复制代码 
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>

<configuration debug="true">
  <import class="ch.qos.logback.core.net.ssl.SSLConfiguration"/>
  <import class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"/>
  <import class="ch.qos.logback.​core.ConsoleAppender"/>
  <import class="ch.qos.logback.core.net.ssl.KeyStoreFactoryBean"/>
  <import class="ch.qos.logback.​classic.net.server.​SSLServerSocketReceiver"/>

  <appender name="CONSOLE" class="ConsoleAppender">
    <encoder class="PatternLayoutEncoder">
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE"/>
  </root>
  <receiver class="​SSLServerSocketReceiver">
    <port>${port}</port>
    <ssl class="SSLConfiguration">
      <keyStore class="KeyStoreFactoryBean">
        <location>${keystore}</location>
        <password>${password}</password>
      </keyStore>
    </ssl>
  </receiver>
</configuration>

这个配置与之前使用 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 子类型支持：

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

使用 SocketReceiver

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

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

传统格式

xml 复制代码 
<configuration debug="true">
    
  <appender name="CONSOLE" class="ch.qos.logback.​core.ConsoleAppender">    
    <encoder>
      <pattern>%date %-5level [%thread] %logger - %message%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE" />
  </root>  

  <receiver class="ch.qos.logback.​classic.net.SocketReceiver">
    <remoteHost>${host}</remoteHost>
    <port>${port}</port>
    <reconnectionDelay>10000</reconnectionDelay>
  </receiver>

</configuration>

规范格式 (1.3)

xml 复制代码 
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>

<configuration debug="true">
  <import class="ch.qos.logback.​classic.net.SocketReceiver"/>
  <import class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"/>
  <import class="ch.qos.logback.​core.ConsoleAppender"/>

  <appender name="CONSOLE" class="ConsoleAppender">
    <encoder class="PatternLayoutEncoder">
      <pattern>%date %-5level [%thread] %logger - %message%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE"/>
  </root>
  <receiver class="SocketReceiver">
    <remoteHost>${host}</remoteHost>
    <port>${port}</port>
    <reconnectionDelay>10000</reconnectionDelay>
  </receiver>
</configuration>

这个配置将导致 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）

传统格式

xml 复制代码 
<configuration debug="true">

  <appender name="CONSOLE" class="ch.qos.logback.​core.ConsoleAppender">    
    <encoder>
      <pattern>%date %-5level [%thread] %logger - %message%n</pattern>
    </encoder>         
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE" />
  </root>  
 
  <receiver class="ch.qos.logback.​classic.net.SSLSocketReceiver">
    <remoteHost>${host}</remoteHost>
    <port>${port}</port>
    <reconnectionDelay>10000</reconnectionDelay>
    <ssl>
      <trustStore>
        <location>${truststore}</location>
        <password>${password}</password>
      </trustStore>
    </ssl>
  </receiver>

</configuration>

规范格式 (1.3)

xml 复制代码 
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration>

<configuration debug="true">
  <import class="ch.qos.logback.core.net.ssl.SSLConfiguration"/>
  <import class="ch.qos.logback.core.net.ssl.KeyManagerFactoryFactoryBean"/>
  <import class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"/>
  <import class="ch.qos.logback.​core.ConsoleAppender"/>
  <import class="ch.qos.logback.​classic.net.SSLSocketReceiver"/>

  <appender name="CONSOLE" class="ConsoleAppender">
    <encoder class="PatternLayoutEncoder">
      <pattern>%date %-5level [%thread] %logger - %message%n</pattern>
    </encoder>
  </appender>

  <root level="DEBUG">
    <appender-ref ref="CONSOLE"/>
  </root>
  <receiver class="SSLSocketReceiver">
    <remoteHost>${host}</remoteHost>
    <port>${port}</port>
    <reconnectionDelay>10000</reconnectionDelay>
    <ssl class="SSLConfiguration">
      <trustStore class="KeyManagerFactoryFactoryBean">
        <location>${truststore}</location>
        <password>${password}</password>
      </trustStore>
    </ssl>
  </receiver>
</configuration>

请注意，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。

版权声明：本文为博主「佳佳」的原创文章，遵循 CC 4.0 BY-NC-SA 版权协议，转载请附上原文出处链接及本声明。

原文链接：www.liujiajia.me/2023/12/7/l...

Footnotes

  1. chapters.receivers.socket.ReceiverExample ↩

  2. chapters.receivers.socket.AppenderExample ↩

相关推荐
阿飞OnePiece8 个月前
springboot工程中使用slf4j+logback实现日志唯一编号
spring boot·apache log4j
洛小豆8 个月前
SpringBoot日志管理 —— 解决Logback生成 "LOG_PATH_IS_UNDEFINED" 文件夹问题
spring boot·后端·apache log4j
半夏之沫9 个月前
十年经验竟不懂Springboot日志
spring boot·spring·apache log4j
不识君9 个月前
动态调整Logback的Appender的解决方案
java·apache log4j
用户4266705916910 个月前
项目中如何配置和使用Log4j2.x
后端·apache log4j
hashcon10 个月前
【硬核】Log4j2 与 Logback 当初的选型以及在当前云原生环境下的反思与展望
java·spring·apache log4j
winjeg1 年前
logback VS log4j2 那些你注意不到的性能差距...
java·spring·apache log4j
乐乐家的乐乐1 年前
怎么说，手写一个日志框架
java·后端·apache log4j
佳佳_1 年前
Logback 手册 - 第八章：映射诊断上下文
apache log4j
佳佳_1 年前
Logback 手册 - 第六章：布局 - 2
apache log4j
热门推荐
01〔AI 绘画〕Stable Diffusion 之 解决绘制多人或面部很小的人物时面部崩坏问题 篇02ARM学习（31）编译器对overlay方式的支持03玄机平台应急响应—webshell查杀04DisplayPort AltMode On Type-c协议_Ver2.0(学习笔记)05校验 GPT-4 真实性的三个经典问题：快速区分 GPT-3.5 与 GPT-4，并提供免费测试网站06Docker 夺命连环 15 问076个主流的工业3D管道设计软件08基于大语言模型（LLM）的合成数据生成、策展和评估的综述09(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明10树莓派 5 AI 套件（Hailo-8L）使用教程