跳到主要内容

loki-logger

loki-logger 插件通过 Loki HTTP API /loki/api/v1/push 将请求和响应日志分批推送到 Grafana Loki。启用后，插件会将请求上下文信息序列化为 JSON 对象 并将其添加到队列中，然后再推送到 Loki。该插件还支持自定义日志格式。

示例​

下面的示例展示了如何在不同场景下配置 loki-logger 插件。

要跟随示例操作，请在 Docker 中启动一个 Loki 实例：

wget https://raw.githubusercontent.com/grafana/loki/v3.0.0/cmd/loki/loki-local-config.yaml -O loki-config.yaml
docker run --name loki -d -v $(pwd):/mnt/config -p 3100:3100 grafana/loki:3.2.1 -config.file=/mnt/config/loki-config.yaml

此外，启动一个 Grafana 实例来查看和可视化日志：

docker run -d --name=apisix-quickstart-grafana \
  -p 3000:3000 \
  grafana/grafana-oss

要连接 Loki 和 Grafana，请访问 http://localhost:3000 的 Grafana。在 Connections > Data sources 下，添加一个新的数据源并选择 Loki。你的连接 URL 应遵循 http://{your_ip_address}:3100 的格式。保存新数据源时，Grafana 还应该测试连接，你应该看到 Grafana 通知数据源已成功连接。

使用默认日志格式记录请求和响应​

以下示例展示了如何在路由上配置 loki-logger 插件，以记录经过该路由的请求和响应。

创建一个启用了 loki-logger 插件并配置了 Loki 地址的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "loki-logger-route",
    "uri": "/anything",
    "plugins": {
      "loki-logger": {
        "endpoint_addrs": ["http://192.168.1.5:3100"]
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ 替换为 Loki 地址。在 Kubernetes 中，请使用集群内 Service 地址 http://loki.aic.svc:3100。

发送几个请求到该路由以生成日志条目：

curl "http://127.0.0.1:9080/anything"

你应该收到所有请求的 HTTP/1.1 200 OK 响应。

导航到 Grafana explore 视图 并运行查询 job = apisix。你应该看到许多与你的请求对应的日志，例如：

{
  "route_id": "loki-logger-route",
  "response": {
    "status": 200,
    "headers": {
      "date": "Fri, 03 Jan 2025 03:54:26 GMT",
      "server": "APISIX/3.13.0",
      "access-control-allow-credentials": "true",
      "content-length": "391",
      "access-control-allow-origin": "*",
      "content-type": "application/json",
      "connection": "close"
    },
    "size": 619
  },
  "start_time": 1735876466,
  "client_ip": "192.168.65.1",
  "service_id": "",
  "apisix_latency": 5.0000038146973,
  "upstream": "34.197.122.172:80",
  "upstream_latency": 666,
  "server": {
    "hostname": "0b9a772e68f8",
    "version": "3.13.0"
  },
  "request": {
    "headers": {
      "user-agent": "curl/8.6.0",
      "accept": "*/*",
      "host": "127.0.0.1:9080"
    },
    "size": 85,
    "method": "GET",
    "url": "http://127.0.0.1:9080/anything",
    "querystring": {},
    "uri": "/anything"
  },
  "latency": 671.0000038147
}

这证实了 Loki 已收到来自 APISIX 的日志。你也可以在 Grafana 中创建仪表板以进一步可视化和分析日志。

使用插件元数据自定义日志格式​

以下示例展示了如何使用 插件元数据 自定义日志格式。

创建一个启用了 loki-logger 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "loki-logger-route",
    "uri": "/anything",
    "plugins": {
      "loki-logger": {
        "endpoint_addrs": ["http://192.168.1.5:3100"]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

配置 loki-logger 的插件元数据，这将更新所有记录请求的路由的日志格式：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/loki-logger" -X PUT \
  -H 'X-API-KEY: ${ADMIN_API_KEY}' \
  -d '{
    "log_format": {
      "host": "$host",
      "client_ip": "$remote_addr",
      "route_id": "$route_id",
      "@timestamp": "$time_iso8601"
    }
  }'

发送请求到该路由以生成新的日志条目：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应。

导航到 Grafana explore 视图 并运行查询 job = apisix。你应该看到与你的请求对应的日志条目，类似于：

{
  "@timestamp":"2025-01-03T21:11:34+00:00",
  "client_ip":"192.168.65.1",
  "route_id":"loki-logger-route",
  "host":"127.0.0.1"
}

如果路由上的插件指定了特定的日志格式，它将优先于插件元数据中指定的日志格式。例如，更新上一个路由上的插件如下：

curl "http://127.0.0.1:9180/apisix/admin/routes/loki-logger-route" -X PATCH \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "plugins": {
      "loki-logger": {
        "log_format": {
          "route_id": "$route_id",
          "client_ip": "$remote_addr",
          "@timestamp": "$time_iso8601"
        }
      }
    }
  }'

发送请求到该路由以生成新的日志条目：

curl -i "http://127.0.0.1:9080/anything"

你应该收到 HTTP/1.1 200 OK 响应。

导航到 Grafana explore 视图 并重新运行查询 job = apisix。你应该看到与你的请求对应的日志条目，与路由上配置的格式一致，类似于：

{
  "client_ip":"192.168.65.1",
  "route_id":"loki-logger-route",
  "@timestamp":"2025-01-03T21:19:45+00:00"
}

有条件地记录请求体​

以下示例展示了如何有条件地记录请求体。

创建一个启用了 loki-logger 的路由如下：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "loki-logger-route",
    "uri": "/anything",
    "plugins": {
      "loki-logger": {
        "endpoint_addrs": ["http://192.168.1.5:3100"],
        "include_req_body": true,
        "include_req_body_expr": [["arg_log_body", "==", "yes"]]
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ include_req_body: 设置为 true 以包含请求体。

❷ include_req_body_expr: 仅当 URL 查询字符串 log_body 为 yes 时包含请求体。

使用满足条件的 URL 查询字符串发送请求到该路由：

curl -i "http://127.0.0.1:9080/anything?log_body=yes" -X POST -d '{"env": "dev"}'

导航到 Grafana explore 视图 并运行查询 job = apisix。你应该看到与你的请求对应的日志条目，其中记录了请求体：

{
  "route_id": "loki-logger-route",
  ...,
  "request": {
    "headers": {
      ...
    },
    "body": "{\"env\": \"dev\"}",
    "size": 182,
    "method": "POST",
    "url": "http://127.0.0.1:9080/anything?log_body=yes",
    "querystring": {
      "log_body": "yes"
    },
    "uri": "/anything?log_body=yes"
  },
  "latency": 809.99994277954
}

发送不带任何 URL 查询字符串的请求到该路由：

curl -i "http://127.0.0.1:9080/anything" -X POST -d '{"env": "dev"}'

导航到 Grafana explore 视图 并运行查询 job = apisix。你应该看到与你的请求对应的日志条目，其中未记录请求体：

{
  "route_id": "loki-logger-route",
  ...,
  "request": {
    "headers": {
      ...
    },
    "size": 169,
    "method": "POST",
    "url": "http://127.0.0.1:9080/anything",
    "querystring": {},
    "uri": "/anything"
  },
  "latency": 557.00016021729
}
信息

如果你在设置 include_req_body 或 include_resp_body 为 true 的同时自定义了 log_format，插件将不会在日志中包含请求体或响应体。

作为一种变通方法，你可以在日志格式中使用 NGINX 变量 $request_body，例如：

{
  "loki-logger": {
    ...,
    "log_format": {"body": "$request_body"}
  }
}