在本文中，你将学习如何收集 Spring Boot 应用程序日志并将其发送到 Grafana Loki。为此，我们将使用 Loki4j Logback appender 功能。Loki 是一个受 Prometheus 启发的可水平扩展、高度可用的日志聚合系统。我将逐步展示如何配置应用程序与 Loki 之间的集成。不过，你也可以使用我自动配置的用于记录 HTTP 请求和响应的库，它将为你完成所有这些步骤。

源码 {#源码}

如果你想自己尝试，可以克隆我的 GitHub 仓库。点击 此处 查看包含我的自定义 Spring Boot 日志库的源代码仓库。然后按照我的说明操作即可。

使用 Loki4j Logback Appender {#使用-loki4j-logback-appender}

为了使用 Loki4j Logback Appender，我们需要在 Maven pom.xml 中加入一个依赖。该库的当前版本为 1.4.1：

<dependency>
    <groupId>com.github.loki4j</groupId>
    <artifactId>loki-logback-appender</artifactId>
    <version>1.4.1</version>
</dependency>

然后，我们需要在 src/main/resources 目录下创建 logback-spring.xml 文件。我们的 Loki 实例在 http://localhost:3100 地址 (1) 下可用。Loki 不会索引日志内容，只会索引元数据标签。有一些静态标签，如应用程序名称、日志级别或主机名。我们可以在 format.label 字段 (2) 中设置它们。我们还将设置一些动态标签，因此要启用日志回溯标记功能 (3) 。最后，我们将设置日志格式模式 (4)。为了简化 LogQL（Loki 查询语言）的潜在转换，我们将使用 JSON 符号。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

  <springProperty name="name" source="spring.application.name" />

  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>
        %d{HH:mm:ss.SSS} %-5level %logger{36} %X{X-Request-ID} - %msg%n
      </pattern>
    </encoder>
  </appender>

  <appender name="LOKI" class="com.github.loki4j.logback.Loki4jAppender">
    <!-- (1) -->
    <http>
      <url>http://localhost:3100/loki/api/v1/push</url>
    </http>
    <format>
      <!-- (2) -->
      <label>
        <pattern>app=${name},host=${HOSTNAME},level=%level</pattern>
        <!-- (3) -->
        <readMarkers>true</readMarkers>
      </label>
      <message>
        <!-- (4) -->
        <pattern>
{
   "level":"%level",
   "class":"%logger{36}",
   "thread":"%thread",
   "message": "%message",
   "requestId": "%X{X-Request-ID}"
}
        </pattern>
      </message>
    </format>
  </appender>

  <root level="INFO">
    <appender-ref ref="CONSOLE" />
    <appender-ref ref="LOKI" />
  </root>

</configuration>

除了静态标签外，我们还可以发送动态数据，例如仅针对当前请求的特定数据。假设我们有一个管理人员的服务，我们希望记录请求中目标人员的 id。正如我之前提到的，使用 Loki4j，我们可以使用 Logback 标记来实现这一点。在经典的 Logback 中，标记主要用于过滤日志记录。使用 Loki，我们只需定义包含动态字段 key/value Map 的 LabelMarker 对象 (1) 。然后将该对象传递给当前日志行 (2)。

@RestController
@RequestMapping("/persons")
public class PersonController {

    private final Logger LOG = LoggerFactory
       .getLogger(PersonController.class);
    private final List<Person> persons = new ArrayList<>();

    @GetMapping
    public List<Person> findAll() {
        return persons;
    }

    @GetMapping("/{id}")
    public Person findById(@PathVariable("id") Long id) {
        Person p = persons.stream().filter(it -> it.getId().equals(id))
                .findFirst()
                .orElseThrow();
        LabelMarker marker = LabelMarker.of("personId", () -> 
           String.valueOf(p.getId())); // (1)
        LOG.info(marker, "Person successfully found"); // (2)
        return p;
    }

    @GetMapping("/name/{firstName}/{lastName}")
    public List<Person> findByName(
       @PathVariable("firstName") String firstName,
       @PathVariable("lastName") String lastName) {
       
       return persons.stream()
          .filter(it -> it.getFirstName().equals(firstName)
                        && it.getLastName().equals(lastName))
          .toList();
    }

    @PostMapping
    public Person add(@RequestBody Person p) {
        p.setId((long) (persons.size() + 1));
        LabelMarker marker = LabelMarker.of("personId", () -> 
           String.valueOf(p.getId()));
        LOG.info(marker, "New person successfully added");
        persons.add(p);
        return p;
    }

    @DeleteMapping("/{id}")
    public void delete(@PathVariable("id") Long id) {
        Person p = persons.stream()
           .filter(it -> it.getId().equals(id))
           .findFirst()
           .orElseThrow();
        persons.remove(p);
        LabelMarker marker = LabelMarker.of("personId", () -> 
           String.valueOf(id));
        LOG.info(marker, "Person successfully removed");
    }

    @PutMapping
    public void update(@RequestBody Person p) {
        Person person = persons.stream()
                .filter(it -> it.getId().equals(p.getId()))
                .findFirst()
                .orElseThrow();
        persons.set(persons.indexOf(person), p);
        LabelMarker marker = LabelMarker.of("personId", () -> 
            String.valueOf(p.getId()));
        LOG.info(marker, "Person successfully updated");
    }

}

假设我们在单个日志行中有多个动态字段，我们就必须以这种方式创建 LabelMarker 对象：

LabelMarker marker = LabelMarker.of(() -> Map.of("audit", "true",
                    "X-Request-ID", MDC.get("X-Request-ID"),
                    "X-Correlation-ID", MDC.get("X-Correlation-ID")));

使用 Spring Boot 运行 Loki {#使用-spring-boot-运行-loki}

在本地计算机上运行 Loki 的最简单方法是使用 Docker 容器。除了 Loki 实例，我们还将运行 Grafana 来显示和搜索日志。下面是包含所有所需服务的 docker-compose.yml。你可以使用 docker compose up 命令来运行它们。不过，还有另一种方法 - 直接使用 Spring Boot 应用程序。

docker-compose.yml:

version: "3"

networks:
  loki:

services:
  loki:
    image: grafana/loki:2.8.2
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
    networks:
      - loki

  grafana:
    environment:
      - GF_PATHS_PROVISIONING=/etc/grafana/provisioning
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    entrypoint:
      - sh
      - -euc
      - |
        mkdir -p /etc/grafana/provisioning/datasources
        cat <<EOF > /etc/grafana/provisioning/datasources/ds.yaml
        apiVersion: 1
        datasources:
        - name: Loki
          type: loki
          access: proxy
          orgId: 1
          url: http://loki:3100
          basicAuth: false
          isDefault: true
          version: 1
          editable: false
        EOF
        /run.sh        
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    networks:
      - loki

为了利用 Spring Boot Docker Compose 支持，我们需要将 docker-compose.yml 放在应用程序根目录下。然后，我们必须在 Maven pom.xml 中加入 Spring-boot-docker-compose 依赖：

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-docker-compose</artifactId>
  <optional>true</optional>
</dependency>

完成所有必要步骤后，我们就可以运行应用程序了。例如，使用以下 Maven 命令：

$ mvn spring-boot:run

此时，在应用程序运行之前，Spring Boot 会启动在 docker-compose.yml 中定义的容器。

让我们只显示正在运行的容器列表。正如你所看到的，由于 Loki 监听的是本地端口 3100，所以一切正常：

$ docker ps            
CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS         PORTS                    NAMES
d23390fbee06   grafana/loki:2.8.2       "/usr/bin/loki -conf..."   4 minutes ago   Up 2 minutes   0.0.0.0:3100->3100/tcp   sample-spring-boot-web-loki-1
84a47637a50b   grafana/grafana:latest   "sh -euc 'mkdir -p /..."   2 days ago      Up 2 minutes   0.0.0.0:3000->3000/tcp   sample-spring-boot-web-grafana-1

测试 Spring Boot REST 应用的日志记录 {#测试-spring-boot-rest-应用的日志记录}

运行应用程序后，我们可以对 REST API 进行一些测试调用。首先，让我们添加一些 person：

$ curl 'http://localhost:8080/persons' \
  -H 'Content-Type: application/json' \
  -d '{"firstName": "AAA","lastName": "BBB","age": 20,"gender": "MALE"}'

$ curl 'http://localhost:8080/persons' \
  -H 'Content-Type: application/json' \
  -d '{"firstName": "CCC","lastName": "DDD","age": 30,"gender": "FEMALE"}'

$ curl 'http://localhost:8080/persons' \
  -H 'Content-Type: application/json' \
  -d '{"firstName": "EEE","lastName": "FFF","age": 40,"gender": "MALE"}'

然后，我们可以用不同的条件多次调用 "查询" 端点：

$ curl http://localhost:8080/persons/1
$ curl http://localhost:8080/persons/2
$ curl http://localhost:8080/persons/3

下面是控制台中的应用程序日志。只有简单的日志行，没有 JSON 格式。

现在，让我们切换到 Grafana。我们已经配置了与 Loki 的集成。在新的仪表板中，我们需要选择 Loki。

以下是存储在 Loki 中的应用程序日志的历史记录。

如你所见，我们使用 JSON 格式记录日志。某些日志行包含 Loki4j Logback appender 中的动态标签。

我们在一些日志中添加了 personId 标签，这样就可以轻松过滤只包含特定人员请求的记录。下面是过滤 personId=1 的记录的 LogQL 查询：

{app="first-service"} |= `` | personId = `1`

下面是 Grafana 面板上显示的结果：

我们还可以使用 LogQL 对日志进行格式化。由于采用了 JSON 格式，我们可以准备一个解析整个日志信息的查询。

{app="first-service"} |= `` | json

如你所见，现在 Loki 将所有 JSON 字段都视为元数据标签：

使用 Spring Boot Loki Starter {#使用-spring-boot-loki-starter}

如果你不想自己配置这些东西，可以使用我的 Spring Boot 库，它提供了自动配置功能。此外，它还会自动记录所有传入的 HTTP 请求和传出的 HTTP 响应。如果默认设置已经足够，你只需将单个 Spring Boot starter 作为依赖项即可：

<dependency>
  <groupId>com.github.piomin</groupId>
  <artifactId>logstash-logging-spring-boot-starter</artifactId>
  <version>2.0.2</version>
</dependency>

该库用多个默认标签记录每个请求和响应，例如 requestId 或 correlationId。

参考：https://piotrminkowski.com/2023/07/05/logging-in-spring-boot-with-loki/