API

Log4j 2 API

概述

Log4j 2 API提供应用程序应该编写的接口，并提供开发人员创建日志记录实现所需的适配器组件。尽管Log4j 2在API和实现之间被分开，但这样做的主要目的不是允许多个实现，尽管这当然是可以这样做，但要明确定义哪些类和方法可以安全地在“普通”应用程序代码中使用。

Hello World!

程序没有使用Hello , World进行介绍是不完整的，首先，从LogManager获取名为“HelloWorld”的Logger。 接下来，使用logger编写“Hello，World！” 但是，仅当Logger配置了相应的日志级别时日志才会输出.

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
 
public class HelloWorld {
    private static final Logger logger = LogManager.getLogger("HelloWorld");
    public static void main(String[] args) {
        logger.info("Hello, World!");
    }
}

调用logger.info（）的输出会因使用的不同配置而有很大差异。有关详细信息，请参阅“Configuration”部分。

替换参数

日志记录的目的通常是提供有关系统中发生的事情的信息，这需要日志输出中包含有关被操纵对象的信息。 在Log4j 1.x中，这可以通过以下方式完成：

if (logger.isDebugEnabled()) {
logger.debug("Logging in user " + user.getName() + " with birthday " + user.getBirthdayCalendar());
}

反复执行此操作会使代码感觉更像是关于日志记录而不是手头的实际任务。 此外，它会导致两次检查日志记录级别; 一次调用isDebugEnabled，一次调试方法。 一个更好的选择是：

logger.debug("Logging in user {} with birthday {}", user.getName(), user.getBirthdayCalendar());

使用上面的代码，只会检查一次日志记录级别，并且字符串构造只会在使能debug日志输出时发生。

格式化参数

如果toString()不是您想要的格式，Formatter Loggers可以按照你需要的方式格式化。 为了便于格式化，您可以使用与Java的Formatter相同的格式字符串。 例如：

public static Logger logger = LogManager.getFormatterLogger("Foo");
 
logger.debug("Logging in user %s with birthday %s", user.getName(), user.getBirthdayCalendar());
logger.debug("Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());
logger.debug("Integer.MAX_VALUE = %,d", Integer.MAX_VALUE);
logger.debug("Long.MAX_VALUE = %,d", Long.MAX_VALUE);

要使用logger的formatter，必须调用其中一个LogManager的getFormatterLogger方法。此示例的输出显示，与自定义格式相比，calendar toString（）比较冗长：

2012-12-12 11:56:19,633 [main] DEBUG: User John Smith with birthday java.util.GregorianCale
2012-12-12 11:56:19,643 [main] DEBUG: User John Smith with birthday 05 23, 1995
2012-12-12 11:56:19,643 [main] DEBUG: Integer.MAX_VALUE = 2,147,483,647
2012-12-12 11:56:19,643 [main] DEBUG: Long.MAX_VALUE = 9,223,372,036,854,775,807

将Logger与格式化Logger混合

Formatter记录器对输出格式进行细粒度控制，但缺点是必须指定正确的类型（例如，为％d格式参数传递十进制整数以外的任何内容会产生异常）

如果您的主要使用的是使用{}式参数，但偶尔需要进行细粒度控制
输出格式，你可以使用printf方法：

public static Logger logger = LogManager.getLogger("Foo");
 
logger.debug("Opening connection to {}...", someDataSource);
logger.printf(Level.INFO, "Logging in user %1$s with birthday %2$tm %2$te,%2$tY", user.getName(), user.getBirthdayCalendar());

Java 8 lambda支持更简洁的编写日志输出代码

在2.4版中，Logger接口添加了对lambda表达式的支持。 这允许客户端代码简洁的编写日志输出代码，而无需显式检查是否启用了请求的日志级别。 例如，以前你会写：

// pre-Java 8 style optimization: 显式检查日志级别
// 确保仅在必要时调用expensiveOperation（）方法
if (logger.isTraceEnabled()) {
logger.trace("Some long-running operation returned {}", expensiveOperation());
}

使用Java 8，您可以使用lambda表达式实现相同的效果。 你不再需要
显式检查日志级别：

// Java-8 style optimization: 不需要显示的检查日志级别
// 如果未启用TRACE级别，则不执行lambda表达式
logger.trace("Some long-running operation returned {}", () -> expensiveOperation());

Logger 名称

大多数日志记录实现使用分层方案将Logger名称与日志记录配置进行匹配 在此方案中，记录器名称层次结构由记录器名称中的“.”字符表示，其方式与用于Java包名称的层次结构非常相似。例如，org.apache.logging.appender和org.apache.logging.filter都将org.apache.logging作为其父级。 在大多数情况下，应用程序通过将当前类的名称传递给LogManager.getLogger（...）来命名其记录器。 因为这种用法非常常见，所以当logger name参数被省略或为null时，Log4j 2将当前类名作为默认值。 例如，在下面的所有示例中，Logger的名称为“org.apache.test.MyTest”

package org.apache.test;
 
public class MyTest {
    private static final Logger logger = LogManager.getLogger(MyTest.class);
}

package org.apache.test;
 
public class MyTest {
    private static final Logger logger = LogManager.getLogger(MyTest.class.getName());
}

package org.apache.test;
 
public class MyTest {
    private static final Logger logger = LogManager.getLogger();
}

• log4j2使用手册（中文）第一章 介绍
• log4j2使用手册（中文）第二章 架构
• log4j2使用手册（中文）第三章 Log4j 1.x 迁移至Log4j 2
• log4j2使用手册（中文）第四章 API
• log4j2使用手册（中文）第五章 Configuration
• log4j2使用手册（中文）第六章 使用
• log4j2使用手册（中文）第七章 Web Applications and JSPs
• log4j2使用手册（中文）第八章 Lookups