当前位置：首页 > news >正文

Elasticsearch：Java ECS 日志记录 - log4j2

news 2025/8/24 6:31:54

ECS 记录器是你最喜欢的日志库的格式化程序/编码器插件。它们可让你轻松将日志格式化为与 ECS 兼容的 JSON。ECS 兼容的 JSON 日志记录可以帮我们简化很多分析，可视化及解析的工作。在今天的文章里，我来详述如何在 Java 应用里生成 ECS 相兼容的日志。

如果大家对完整的项目感兴趣，你可以在地址下载示例代码。

git clone https://github.com/liu-xiao-guo/elasticsearch-java-ecs

步骤1：生成模板 Spring boot 应用

我们可以在 https://start.spring.io/ 生成一个模板的 Spring boot 应用：

我们下载所生成的代码，并解压缩到我们的电脑目录中。我们可以使用我们所喜欢的 IDE 来进行导入。

步骤 2：配置应用程序日志记录

如果你使用的是 Elastic APM Java 代理，将日志转换为与 ECS 兼容的 JSON 格式的最简单方法是通过 log_ecs_reformatting 配置选项。只需设置此选项，Java 代理就会自动导入正确的 ECS 日志库并配置你的日志框架以使用它来代替（覆盖/替换）或补充（遮蔽）你当前的配置。无需进行其他更改！请务必查看其他日志配置选项以充分发挥此选项的潜力。

否则，请按照以下步骤通过你的日志框架配置手动应用 ECS 格式。支持以下日志框架：

Logback（Spring Boot 的默认设置）
Log4j2
Log4j
java.util.logging (JUL)
JBoss 日志管理器

在今天的文章里，我们来展示如何使用 Log4j2 来进行生成 ECS 相兼容的日志。更多的资料可以在地址查看。

添加 dependency

所需的最低 log4j2 版本为 2.6。下载最新版本的 Elastic 日志记录：Maven Central v1.6.0

向你的应用程序添加依赖项：

		<dependency><groupId>co.elastic.logging</groupId><artifactId>log4j2-ecs-layout</artifactId><version>${ecs-logging-java.version}</version></dependency>

提示：如果你不使用依赖项管理工具（如 maven），则必须手动将 log4j2-ecs-layout 和 ecs-logging-core jar 添加到类路径。例如，添加到 $CATALINA_HOME/lib 目录。除此之外，没有必需的依赖项。

除此之外，我们还必须添加如下的 dependency：

		<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-log4j2</artifactId></dependency>

这个是为了记录日志之用。

由于 Spring Boot 使用 logback 作为默认记录器，因此我们将其从 spring-boot-starter 依赖项中排除。我们需要做如下的修改：

		<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><exclusions><exclusion><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-logging</artifactId></exclusion></exclusions></dependency>

在上面，为了能够使得它能在 Java 1.8 下进行编译，我必须把上面的 spring-boot-starter 修改为 spring-boot-starter-web，否则会有错误。

添加 log4j2.xml 文件

接下来，在 src/main/resources 中为 log4j2 记录器 log4j2.xml 添加一个 log4j2 配置。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="DEBUG"><Appenders><Console name="LogToConsole" target="SYSTEM_OUT"><EcsLayout serviceName="my-app" serviceVersion="my-app-version" serviceEnvironment="my-app-environment" serviceNodeName="my-app-cluster-node"/></Console><File name="LogToFile" fileName="logs/app.log"><EcsLayout serviceName="my-app" serviceVersion="my-app-version" serviceEnvironment="my-app-environment" serviceNodeName="my-app-cluster-node"/></File></Appenders><Loggers><Root level="info"><AppenderRef ref="LogToFile"/><AppenderRef ref="LogToConsole"/></Root></Loggers>
</Configuration>

在上面，我们定义了日志的文件名 logs/app.log。里面参数的描述请参考链接。

修改 application.properties 文件

我们修改 application.properties 文件为：

spring.application.name=elasticsearch-java-ecs
spring.main.allow-circular-references=true

在应用中使用 Log4j2 来记录日志

我们在 ElasticController class 中使用如下的方式来记录日志：

ElasticController.java

package com.liuxg.elasticsearch_java_ecs;import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.Date;import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.message.StringMapMessage;import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;@RestController
class ElasticController {private static final Logger LOG = LogManager.getLogger(ElasticController.class);@AutowiredRestTemplate restTemplete;@BeanRestTemplate restTemplate() {return new RestTemplate();}@RequestMapping(value = "/")public String home() {String homeMessage = "Welcome to Elastic ECS logging demo";LOG.info(homeMessage);return homeMessage;}@RequestMapping(value = "/elk")public String helloWorld() {String response = "Welcome to JAVA " + new Date();LOG.info(new StringMapMessage().with("message", "API called").with("customer.id", "client-1").with("product.id", "25a76f91-41dd-49da-8020-3553c9100267").with("customer.action", "CREATE"));return response;}@RequestMapping(value = "/exception")public String exception() {String response = "";try {throw new Exception("Opps Exception raised....");} catch (Exception e) {e.printStackTrace();LOG.error(e);StringWriter sw = new StringWriter();PrintWriter pw = new PrintWriter(sw);e.printStackTrace(pw);String stackTrace = sw.toString();LOG.error("Exception - " + stackTrace);response = stackTrace;}return response;}
}

如上所示，我们可以使用 Log.info() 来记录日志。在上面的代码中，我们使用了三种方式来记录日志：

```
LOG.info(homeMessage);
```

LOG.info(new StringMapMessage().with("message", "API called").with("customer.id", "client-1").with("product.id", "25a76f91-41dd-49da-8020-3553c9100267").with("customer.action", "CREATE"));

```
LOG.error(e);
```

我们为 Spring Boot 应用定义了三个接口。运行我们的 Spring Boot 应用：

它将在程序的更目录下的 logs 下生成一个叫做 app.log 的文件：

从上面的日志输出中，我们可以看出来日志是一个 ECS 相兼容的 JSON 日志文件。我们相下滚动直到文件的底部：

上面的最后一条日志就是我们刚生成的日志。

我们接着访问另外一个接口：

我们滚动到最后的一条日志：

上面显示的是我们的一条自定义的日志。

我们再接着访问一个 exception 接口：

同样的我们滚动到最后查看 app.log 日志的内容：

我们可以看到日志的内容。

把日志写入到 Elasticsearch

我们配置 filebeat.yml 文件：

Filebeat 7.16+

filebeat.yaml

filebeat.inputs:
- type: filestream paths: /path/to/app.logparsers:- ndjson:overwrite_keys: true add_error_key: true expand_keys: true processors: - add_host_metadata: ~- add_cloud_metadata: ~- add_docker_metadata: ~- add_kubernetes_metadata: ~

Filebeat < 7.16

filebeat.yaml

filebeat.inputs:
- type: logpaths: /path/to/logs.jsonjson.keys_under_root: truejson.overwrite_keys: truejson.add_error_key: truejson.expand_keys: trueprocessors:
- add_host_metadata: ~
- add_cloud_metadata: ~
- add_docker_metadata: ~
- add_kubernetes_metadata: ~

针对 exception 这类的错误信息。我们可能需要进行特殊的处理。请参考文章 “Beats：使用 Filebeat 传送多行日志”。

更多关于如何写入 ECS 相兼容的 JSON 日志文件，请详细阅读文章：