loki-logger
#
描述loki-logger
插件通过 Loki HTTP API /loki/api/v1/push
将请求和响应日志批量推送到 Grafana Loki。该插件还支持自定义日志格式。
启用后,插件会将请求上下文信息序列化为 JSON object 并将其添加到队列中,然后再将其推送到 Loki。有关更多详细信息,请参阅批处理处理器 batch processor。
#
属性名称 | 类型 | 必选项 | 默认值 | 有效值 |
---|---|---|---|---|
end_addrs | array[string] | 是 | ||
end_uri | string | 否 | /loki/api/v1/push | |
tenant_id | string | 否 | fake | |
log_labels | object | 否 | {job = "apisix"} | |
ssl_verify | boolean | 否 | true | |
timeout | integer | 否 | 3000 | [1, 60000] |
keepalive | boolean | 否 | true | |
keepalive_timeout | integer | 否 | 60000 | >=1000 |
keepalive_pool | integer | 否 | 5 | >=1 |
log_format | object | 否 | ||
name | string | 否 | loki-logger | |
include_req_body | boolean | 否 | false | |
include_req_body_expr | array[array] | 否 | ||
include_resp_body | boolean | 否 | false | |
include_resp_body_expr | array[array] | 否 |
该插件支持使用批处理器对条目(日志/数据)进行批量聚合和处理,避免了频繁提交数据的需求。批处理器每隔 5
秒或当队列中的数据达到 1000
时提交数据。有关更多信息或设置自定义配置,请参阅 批处理器。
#
Plugin Metadata您还可以使用 Plugin Metadata 全局配置日志格式,该 Plugin Metadata 配置所有 loki-logger
插件实例的日志格式。如果在单个插件实例上配置的日志格式与在 Plugin Metadata 上配置的日志格式不同,则在单个插件实例上配置的日志格式优先。
名称 | 类型 | 必选项 | 默认值 | 描述 |
---|---|---|---|---|
log_format | object | 否 | 日志格式以 JSON 格式声明为键值对。值只支持字符串类型。可以通过在字符串前面加上 $ 来使用 APISIX 变量 和 NGINX 变量 。 |
#
示例下面的示例演示了如何为不同场景配置 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,请访问 Grafana,网址为 http://localhost:3000
。在 Connections > Data sources 下,添加新数据源并选择 Loki。您的连接 URL 应遵循 http://{your_ip_address}:3100
的格式。保存新数据源时,Grafana 还应测试连接,您应该会看到 Grafana 通知数据源已成功连接。
note
您可以这样从 config.yaml
中获取 admin_key
并存入环境变量:
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
#
以默认日志格式记录请求和响应以下示例演示了如何在路由上配置 loki-logger
插件以记录通过路由的请求和响应。
使用 loki-logger
插件创建路由并配置 Loki 的地址:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${admin_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"
}
}'
向路由发送一些请求以生成日志条目:
curl "http://127.0.0.1:9080/anything"
您应该会收到所有请求的“HTTP/1.1 200 OK”响应。
导航到 Grafana explore view 并运行查询 job = apisix
。您应该会看到与您的请求相对应的许多日志,例如以下内容:
{
"route_id": "loki-logger-route",
"response": {
"status": 200,
"headers": {
"date": "Fri, 03 Jan 2025 03:54:26 GMT",
"server": "APISIX/3.11.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.11.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 中创建仪表板,以进一步可视化和分析日志。
#
使用 Plugin Metadata 自定义日志格式以下示例演示了如何使用 Plugin Metadata 自定义日志格式。
使用 loki-logger
插件创建路由:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${admin_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
配置 Plugin Metadata,它将更新所有需要记录请求的路由的日志格式:
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/loki-logger" -X PUT \
-H 'X-API-KEY: ${admin_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 view 并运行查询 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"
}
如果路由上的插件指定了特定的日志格式,它将优先于 Plugin Metadata 中指定的日志格式。例如,按如下方式更新上一个路由上的插件:
curl "http://127.0.0.1:9180/apisix/admin/routes/loki-logger-route" -X PATCH \
-H "X-API-KEY: ${admin_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 view 并重新运行查询 job = apisix
。您应该会看到与您的请求相对应的日志条目,与路由上配置的格式一致,类似于以下内容:
{
"client_ip":"192.168.65.1",
"route_id":"loki-logger-route",
"@timestamp":"2025-01-03T21:19:45+00:00"
}
#
有条件地记录请求主体以下示例演示了如何有条件地记录请求主体。
使用 loki-logger
创建路由,仅在 URL 查询字符串 log_body
为 yes
时记录请求主体:
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${admin_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"
}
}'
使用满足条件的 URL 查询字符串向路由发送请求:
curl -i "http://127.0.0.1:9080/anything?log_body=yes" -X POST -d '{"env": "dev"}'
您应该会收到 HTTP/1.1 200 OK
响应。
导航到 Grafana explore view 并重新运行查询 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"}'
您应该会收到 HTTP/1.1 200 OK
响应。
导航到 Grafana explore view 并重新运行查询 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
}
info
如果您除了将 include_req_body
或 include_resp_body
设置为 true
之外还自定义了 log_format
,则插件不会在日志中包含正文。
作为一种解决方法,您可以在日志格式中使用 NGINX 变量 $request_body
,例如:
{
"kafka-logger": {
...,
"log_format": {"body": "$request_body"}
}
}
#
FAQ#
日志未正确推送请查看 error.log
文件以获取此类日志。
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
中的日志,查找此类日志。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 的速率正确推送日志。