« 简介 使用 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

其他应用程序

您所要做的就是在 logback.xml 中使用 co.elastic.logging.logback.EcsEncoder 而不是默认的模式编码器

<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 字段，该字段由 Logs 应用程序的机器学习作业使用，以查找日志速率中的异常情况。

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 来启用它。

第二步：配置 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 将递归地取消点号（de-dot）解码后的 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 时

编辑

通常，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 进行结构化日志记录 »