Log4j 2 API

Thread Context

Introduction

Log4j 引入了“Map 诊断上下文”或 MDC 的概念。它已在许多地方记录和讨论，包括Log4j MDC：什么和为什么和Log4j 和 Map 的诊断上下文。此外，Log4j 1.x 还支持嵌套诊断上下文或 NDC。它也已在Log4j NDC等各个地方进行了记录和讨论。 SLF4J/Logback 带有自己的 MDC 实现，在Map 诊断上下文处有很好的记录。

Log4j 2 延续了 MDC 和 NDC 的思想，但将它们合并为一个线程上下文。线程上下文 Map 等效于 MDC，线程上下文堆栈等效于 NDC。尽管它们通常用于诊断问题以外的目的，但由于这些缩写词已经众所周知，因此在 Log4j 2 中仍经常将它们称为 MDC 和 NDC。

Fish Tagging

大多数实际系统必须同时处理多个 Client 端。在这种系统的典型多线程实现中，不同的线程将处理不同的 Client 端。日志记录特别适合跟踪和调试复杂的分布式应用程序。区分一个 Client 端的日志记录输出与另一个 Client 端的日志记录输出的常用方法是为每个 Client 端实例化一个新的单独的日志 Logger。这促进了 Logger 的扩散，并增加了记录的 Management 开销。

一种更轻松的技术是唯一标记从相同 Client 端交互发起的每个日志请求。尼尔·哈里森(Neil Harrison)在 R. Martin，D。Riehle 和 F.Buschmann(Addison-Wesley，1997)编辑的《程序设计 3 的模式语言》一书“记录诊断消息的模式”中描述了这种方法。正如可以标记鱼并对其运动进行跟踪一样，使用通用标签或数据元素集对日志事件进行标记可以允许跟踪 Transaction 或请求的完整流程。我们称之为鱼标签。

Log4j 提供了两种执行鱼标记的机制；线程上下文 Map 和线程上下文堆栈。线程上下文 Map 允许添加任何数量的项，并使用键/值对进行标识。线程上下文堆栈允许将一个或多个项目推入堆栈，然后通过它们在堆栈中的 Sequences 或数据本身进行标识。由于键/值对更加灵活，因此当在请求的处理过程中可能添加数据项或一个或两个以上项时，建议使用“线程上下文 Map”。

为了使用线程上下文堆栈唯一地标记每个请求，用户将上下文信息压入堆栈。

ThreadContext.push(UUID.randomUUID().toString()); // Add the fishtag;

logger.debug("Message 1");
.
.
.
logger.debug("Message 2");
.
.
ThreadContext.pop();

线程上下文堆栈的替代方法是线程上下文 Map。在这种情况下，与正在处理的请求关联的属性在开头添加，并在结尾删除，如下所示：

ThreadContext.put("id", UUID.randomUUID().toString()); // Add the fishtag;
ThreadContext.put("ipAddress", request.getRemoteAddr());
ThreadContext.put("loginId", session.getAttribute("loginId"));
ThreadContext.put("hostName", request.getServerName());
.
logger.debug("Message 1");
.
.
logger.debug("Message 2");
.
.
ThreadContext.clear();

CloseableThreadContext

将项目放置在堆栈或 Map 上时，有必要在适当时再次将其删除。为此，CloseableThreadContext 实现了AutoCloseable interface。这允许将项目推入堆栈或放入 Map 中，并在调用 close()方法时将其删除-或作为 try-with-resources 的一部分自动进行删除。例如，要将某些东西暂时推入堆栈，然后将其删除：

// Add to the ThreadContext stack for this try block only;
try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.push(UUID.randomUUID().toString())) {

    logger.debug("Message 1");
.
.
    logger.debug("Message 2");
.
.
}

或者，暂时在 Map 上放置一些东西：

// Add to the ThreadContext map for this try block only;
try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.put("id", UUID.randomUUID().toString())
                                                                .put("loginId", session.getAttribute("loginId"))) {

    logger.debug("Message 1");
.
.
    logger.debug("Message 2");
.
.
}

如果使用线程池，则可以使用 putAll(final Map<String, String> values)和/或 pushAll(List messages)方法初始化 CloseableThreadContext。

for( final Session session : sessions ) {
    try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.put("loginId", session.getAttribute("loginId"))) {
        logger.debug("Starting background thread for user");
        final Map<String, String> values = ThreadContext.getImmutableContext();
        final List<String> messages = ThreadContext.getImmutableStack().asList();
        executor.submit(new Runnable() {
        public void run() {
            try (final CloseableThreadContext.Instance ctc = CloseableThreadContext.putAll(values).pushAll(messages)) {
                logger.debug("Processing for user started");
                .
                logger.debug("Processing for user completed");
            }
        });
    }
}

Implementation details

堆栈和 Map 是按线程 Management 的，默认情况下基于ThreadLocal。可以将 Map 配置为使用InheritableThreadLocal(请参见Configuration部分)。通过这种方式配置后，Map 的内容将传递给子线程。但是，如在Executors类中讨论的，以及在其他使用线程池的情况下，ThreadContext 可能不会始终自动传递给工作线程。在这些情况下，池化机制应提供这样做的手段。 getContext()和 cloneStack()方法可分别用于获取 Map 和 Stack 的副本。

请注意，ThreadContext类的所有方法都是静态的。

Configuration

将系统属性 disableThreadContextMap 设置为 true 可以禁用线程上下文 Map。
将系统属性 disableThreadContextStack 设置为 true 可以禁用线程上下文堆栈。
将系统属性 disableThreadContext 设置为 true 可以禁用线程上下文 Map 和堆栈。
将系统属性“ log4j2.isThreadContextMapInheritable”设置为“ true”，以使子线程能够继承线程上下文 Map。

编写日志时包括 ThreadContext

PatternLayout提供了用于打印ThreadContextMap 和堆栈内容的机制。

单独使用％X 可以包含 Map 的全部内容。
使用％X{key}包含指定的密钥。
使用％x 包含Stack的全部内容。

用于非线程本地上下文数据的自定义上下文数据注入器

可以使用 ThreadContext 记录日志语句，以便可以通过这些标签链接以某种方式相关的日志条目。限制是，这仅适用于在同一应用程序线程(或配置时的子线程)上完成的日志记录。

某些应用程序具有将工作委托给其他线程的线程模型，在这种模型中，一个线程中放入线程本地 Map 的标记属性在其他线程中不可见，而在其他线程中完成的日志记录将不会显示这些属性。

Log4j 2.7 添加了一种灵活的机制，可以使用来自 ThreadContext 之外的其他来源的上下文数据标记日志记录语句。有关详细信息，请参见extending Log4j上的手册页。

Docs

Docs4dev

Title here