loki-logger

描述

loki-logger 插件用于将日志转发到 Grafana Loki 进行分析和存储。

当启用该插件时，APISIX 将把请求上下文信息序列化为 JSON 中的日志条目 并将其提交到批处理队列中。当队列中的数据量超过最大批处理大小时，数据将被推送到 Grafana Loki。有关更多详细信息，请参阅批处理处理器 batch processor。

属性

名称类型必选项默认值描述
endpoint_addrsarray[string]TrueLoki API 基础 URL，格式如 http://127.0.0.1:3100，支持 HTTPS 和域名。如果配置了多个端点，它们将随机选择一个进行写入
endpoint_uristringFalse/loki/api/v1/push如果您正在使用与 Loki Push API 兼容的日志收集服务，您可以使用此配置项自定义 API 路径。
tenant_idstringFalsefakeLoki 租户 ID。根据 Loki 的 多租户文档，在单租户模式下，默认值设置为 fake。
log_labelsobjectFalse{job = “apisix”}Loki 日志标签。您可以使用 APISIX 变量 和 Nginx 变量 只需在字符串前面加上 $ 符号即可，可以使用单个变量或组合变量，例如 $host 或 $remote_addr:$remote_port。
ssl_verifybooleanFalsetrue当设置为 true 时，将验证 SSL 证书。
timeoutintegerFalse3000msLoki 服务 HTTP 调用的超时时间，范围从 1 到 60,000 毫秒。
keepalivebooleanFalsetrue当设置为 true 时，会保持连接以供多个请求使用。
keepalive_timeoutintegerFalse60000ms连接空闲时间后关闭连接。范围大于或等于 1000 毫秒。
keepalive_poolintegerFalse5连接池限制。范围大于或等于 1。
log_formatobjectFalse以 JSON 格式声明的键值对形式的日志格式。值仅支持字符串类型。可以通过在字符串前面加上 $ 来使用 APISIX 变量 和 Nginx 变量 。
include_req_bodybooleanFalsefalse当设置为 true 时，日志中将包含请求体。如果请求体太大而无法在内存中保存，则由于 Nginx 的限制，无法记录请求体。
include_req_body_exprarrayFalse当 include_req_body 属性设置为 true 时的过滤器。只有当此处设置的表达式求值为 true 时，才会记录请求体。有关更多信息，请参阅 lua-resty-expr 。
include_resp_bodybooleanFalsefalse当设置为 true 时，日志中将包含响应体。
include_resp_body_exprarrayFalse当 include_resp_body 属性设置为 true 时的过滤器。只有当此处设置的表达式求值为 true 时，才会记录响应体。有关更多信息，请参阅 lua-resty-expr 。

该插件支持使用批处理器对条目（日志/数据）进行批量聚合和处理，避免了频繁提交数据的需求。批处理器每隔 5 秒或当队列中的数据达到 1000 时提交数据。有关更多信息或设置自定义配置，请参阅 批处理器。

默认日志格式示例

  1. {
  2.   "request": {
  3.     "headers": {
  4.       "connection": "close",
  5.       "host": "localhost",
  6.       "test-header": "only-for-test#1"
  7.     },
  8.     "method": "GET",
  9.     "uri": "/hello",
  10.     "url": "http://localhost:1984/hello",
  11.     "size": 89,
  12.     "querystring": {}
  13.   },
  14.   "client_ip": "127.0.0.1",
  15.   "start_time": 1704525701293,
  16.   "apisix_latency": 100.99994659424,
  17.   "response": {
  18.     "headers": {
  19.       "content-type": "text/plain",
  20.       "server": "APISIX/3.7.0",
  21.       "content-length": "12",
  22.       "connection": "close"
  23.     },
  24.     "status": 200,
  25.     "size": 118
  26.   },
  27.   "route_id": "1",
  28.   "loki_log_time": "1704525701293000000",
  29.   "upstream_latency": 5,
  30.   "latency": 105.99994659424,
  31.   "upstream": "127.0.0.1:1980",
  32.   "server": {
  33.     "hostname": "localhost",
  34.     "version": "3.7.0"
  35.   },
  36.   "service_id": ""
  37. }

元数据

您还可以通过配置插件元数据来设置日志的格式。以下配置项可供选择：

名称类型必选项默认值描述
log_formatobjectFalse日志格式以 JSON 格式声明为键值对。值只支持字符串类型。可以通过在字符串前面加上 $ 来使用 APISIX 变量 和 Nginx 变量 。
loki-logger - 图1重要提示

配置插件元数据具有全局范围。这意味着它将对使用 loki-logger 插件的所有路由和服务生效。

以下示例展示了如何通过 Admin API 进行配置：

  1. curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/loki-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "log_format": {
  4.         "host": "$host",
  5.         "@timestamp": "$time_iso8601",
  6.         "client_ip": "$remote_addr"
  7.     }
  8. }'

使用这个配置，您的日志将被格式化为以下形式：

  1. {"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
  2. {"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}

启用插件

以下示例展示了如何在特定的路由上启用 loki-logger 插件：

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "loki-logger": {
  5.             "endpoint_addrs" : ["http://127.0.0.1:3100"]
  6.         }
  7.     },
  8.     "upstream": {
  9.        "nodes": {
  10.            "127.0.0.1:1980": 1
  11.        },
  12.        "type": "roundrobin"
  13.     },
  14.     "uri": "/hello"
  15. }'

示例用法

现在，如果您向 APISIX 发出请求，该请求将被记录在您的 Loki 服务器中：

  1. curl -i http://127.0.0.1:9080/hello

删除插件

当您需要删除 loki-logger 插件时，您可以使用以下命令删除相应的 JSON 配置，APISIX 将自动重新加载相关配置，而无需重启服务：

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uri": "/hello",
  5.     "plugins": {},
  6.     "upstream": {
  7.         "type": "roundrobin",
  8.         "nodes": {
  9.             "127.0.0.1:1980": 1
  10.         }
  11.     }
  12. }'

FAQ

日志未正确推送

请查看 error.log 文件以获取此类日志。

  1. 2023/04/30 13:45:46 [error] 19381#19381: *1075673 [lua] batch-processor.lua:95: Batch Processor[loki logger] failed to process entries: loki server returned status: 401, body: no org id, context: ngx.timer, client: 127.0.0.1, server: 0.0.0.0:9081

可以根据错误代码 failed to process entries: loki server returned status: 401, body: no org id 和 loki 服务器的响应正文来诊断错误。

当请求每秒 (RPS) 较高时出现错误？

  • 请确保 keepalive 相关的配置已正确设置。有关更多信息，请参阅属性 。

  • 请检查 error.log 中的日志，查找此类日志。

    1. 2023/04/30 13:49:34 [error] 19381#19381: *1082680 [lua] batch-processor.lua:95: Batch Processor[loki logger] failed to process entries: loki server returned status: 429, body: Ingestion rate limit exceeded for user tenant_1 (limit: 4194304 bytes/sec) while attempting to ingest '1000' lines totaling '616307' bytes, reduce log volume or contact your Loki administrator to see if the limit can be increased, context: ngx.timer, client: 127.0.0.1, server: 0.0.0.0:9081

    • 通常与高 QPS 相关的日志如上所示。错误信息为：Ingestion rate limit exceeded for user tenant_1 (limit: 4194304 bytes/sec) while attempting to ingest '1000' lines totaling '616307' bytes, reduce log volume or contact your Loki administrator to see if the limit can be increased。

    • 请参考 Loki 文档 ，添加默认日志量和突发日志量的限制，例如 ingestion_rate_mb 和 ingestion_burst_size_mb。

      在开发过程中进行测试时，将 ingestion_burst_size_mb 设置为 100 可以确保 APISIX 以至少 10000 RPS 的速率正确推送日志。