« 简介 使用 log4j2 进行结构化日志记录 »
Elastic 文档 ›

入门

编辑

入门编辑

步骤 1：配置应用程序日志记录编辑

如果您使用的是 Elastic APM Java 代理，将日志转换为与 ECS 兼容的 JSON 格式的最简单方法是通过 log_ecs_reformatting 配置选项。仅设置此选项，Java 代理将自动导入正确的 ECS 日志记录库并配置您的日志记录框架以使用它（OVERRIDE/REPLACE）或除了（SHADE）您当前的配置之外。无需其他更改！确保查看其他 日志记录配置选项 以充分利用此选项的潜力。

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

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

添加依赖项编辑

Logback 的最低要求版本为 1.1。

下载 Elastic 日志记录的最新版本：Maven Central

向您的应用程序添加依赖项

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

如果您没有使用依赖项管理工具，例如 maven，则必须手动将 logback-ecs-encoder 和 ecs-logging-core jar 文件添加到类路径。例如，添加到 $CATALINA_HOME/lib 目录。除此之外，没有其他必需的依赖项。

使用 ECS 编码器/格式化程序/布局编辑

Spring Boot 应用程序

在 src/main/resources/logback-spring.xml 中

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <property name="LOG_FILE" value="${LOG_FILE:-${LOG_PATH:-${LOG_TEMP:-${java.io.tmpdir:-/tmp}}}/spring.log}"/>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    <include resource="org/springframework/boot/logging/logback/console-appender.xml" />
    <include resource="org/springframework/boot/logging/logback/file-appender.xml" />
    <include resource="co/elastic/logging/logback/boot/ecs-console-appender.xml" />
    <include resource="co/elastic/logging/logback/boot/ecs-file-appender.xml" />
    <root level="INFO">
        <appender-ref ref="ECS_JSON_CONSOLE"/>
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="ECS_JSON_FILE"/>
        <appender-ref ref="FILE"/>
    </root>
</configuration>

您还需要将以下属性配置到您的 application.properties 中

spring.application.name=my-application
# for Spring Boot 2.2.x+
logging.file.name=/path/to/my-application.log
# for older Spring Boot versions
logging.file=/path/to/my-application.log

其他应用程序

您要做的就是使用 co.elastic.logging.logback.EcsEncoder 来代替 logback.xml 中的默认模式编码器

<encoder class="co.elastic.logging.logback.EcsEncoder">
    <serviceName>my-application</serviceName>
    <serviceVersion>my-application-version</serviceVersion>
    <serviceEnvironment>my-application-environment</serviceEnvironment>
    <serviceNodeName>my-application-cluster-node</serviceNodeName>
</encoder>

编码器参数

参数名称 类型 默认值 描述

serviceName

字符串

设置 service.name 字段，以便您可以按特定服务名称筛选日志

serviceVersion

字符串

设置 service.version 字段，以便您可以按特定服务版本筛选日志

serviceEnvironment

字符串

设置 service.environment 字段，以便您可以按特定服务环境筛选日志

serviceNodeName

字符串

设置 service.node.name 字段，以便您可以按特定集群服务的节点筛选日志

eventDataset

字符串

${serviceName}

设置 event.dataset 字段，该字段由日志应用程序的机器学习作业使用以查找日志速率中的异常情况。

includeMarkers

布尔值

false

将 标记 作为 tags 记录

stackTraceAsArray

布尔值

false

将 error.stack_trace 序列化为 JSON 数组，其中每个元素都位于新行中，以提高可读性。请注意，这需要更复杂的 Filebeat 配置。

includeOrigin

布尔值

false

如果为 true，则添加 log.origin.file.name、log.origin.file.line 和 log.origin.function 字段。请注意，如果您使用的是异步附加器，则还需要在附加器上设置 <includeCallerData>true</includeCallerData>。

要在输出中包含任何自定义字段，请使用以下语法

<additionalField>
    <key>key1</key>
    <value>value1</value>
</additionalField>
<additionalField>
    <key>key2</key>
    <value>value2</value>
</additionalField>

如果您使用的是 Elastic APM Java 代理，则日志关联从版本 1.30.0 开始默认启用。在之前的版本中，日志关联默认处于关闭状态，但可以通过将 enable_log_correlation 配置设置为 true 来启用。

步骤 2：配置 Filebeat编辑

  1. 按照 Filebeat 快速入门 进行操作
  2. 将以下配置添加到您的 filebeat.yaml 文件中。

对于 Filebeat 7.16+

filebeat.yaml。

filebeat.inputs:
- type: filestream 
  paths: /path/to/logs.json
  parsers:
    - ndjson:
      overwrite_keys: true 
      add_error_key: true 
      expand_keys: true 

processors: 
  - add_host_metadata: ~
  - add_cloud_metadata: ~
  - add_docker_metadata: ~
  - add_kubernetes_metadata: ~

使用 filestream 输入从活动日志文件读取行。

解码后的 JSON 对象中的值会覆盖 Filebeat 通常在发生冲突时添加的字段（类型、源、偏移量等）。

如果发生 JSON 反序列化错误，Filebeat 会添加“error.message”和“error.type: json”键。

Filebeat 会递归地对解码后的 JSON 中的键进行去点操作，并将它们扩展为分层对象结构。

处理器可以增强您的数据。有关更多信息，请参阅 处理器。

对于 Filebeat < 7.16

filebeat.yaml。

filebeat.inputs:
- type: log
  paths: /path/to/logs.json
  json.keys_under_root: true
  json.overwrite_keys: true
  json.add_error_key: true
  json.expand_keys: true

processors:
- add_host_metadata: ~
- add_cloud_metadata: ~
- add_docker_metadata: ~
- add_kubernetes_metadata: ~

有关更多信息，请参阅 Filebeat 参考。

当 stackTraceAsArray 启用时 edit

Filebeat 通常只能在每行只有一个 JSON 对象的情况下解码 JSON。当 stackTraceAsArray 启用时，每个堆栈跟踪元素将有一行，这将提高可读性。但是，当将多行设置与 decode_json_fields 结合使用时，我们还可以处理多行 JSON

filebeat.inputs:
  - type: log
    paths: /path/to/logs.json
    multiline.pattern: '^{'
    multiline.negate: true
    multiline.match: after
processors:
  - decode_json_fields:
      fields: message
      target: ""
      overwrite_keys: true
  # flattens the array to a single string
  - script:
      when:
        has_fields: ['error.stack_trace']
      lang: javascript
      id: my_filter
      source: >
        function process(event) {
            event.Put("error.stack_trace", event.Get("error.stack_trace").join("\n"));
        }
« 简介 使用 log4j2 进行结构化日志记录 »