lingsamuel commented on code in PR #9687: URL: https://github.com/apache/apisix/pull/9687#discussion_r1234824483
########## docs/zh/latest/plugins/loki-logger.md: ########## @@ -0,0 +1,165 @@ +--- +title: loki-logger +keywords: + - Apache APISIX + - API 网关 + - Plugin + - Loki-logger + - Grafana Loki +description: 本文件包含关于 Apache APISIX loki-logger 插件的信息。 +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +## 描述 + +`loki-logger` 插件用于将日志转发到 [Grafana Loki](https://grafana.com/oss/loki/) 进行分析和存储。 + +当插件启用时，APISIX 将把请求上下文信息序列化为 [JSON 中的日志条目](https://grafana.com/docs/loki/latest/api/#push-log-entries-to-loki) 并提交给批处理队列。当超过最大批处理量时，队列中的数据会被推送到 Grafana Loki。更多细节见 [batch processor](../batch-processor.md)。 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +|--|---|---|---|---| +| endpoint_addrs | array[string] | True | | Loki API 基础 URL，格式如 http://127.0.0.1:3100，支持 HTTPS 和域名。如果配置了多个端点，它们将被随机写入。 | +| endpoint_uri | string | False | /loki/api/v1/push | 如果你使用与 Loki Push API 兼容的日志收集服务，你可以使用这个配置项来定制 API 路径。 | +| tenant_id | string | False | fake | Loki 租户 ID。根据 Loki 的 [多租户文档](https://grafana.com/docs/loki/latest/operations/multi-tenancy/#multi-tenancy)，其默认值被设置为单租户下的默认值 `fake`。 | +| log_labels | object | False | {job = "apisix"} | Loki 日志标签。[APISIX 变量](../apisix-variable.md) 和 [Nginx 变量](http://nginx.org/en/docs/varindex.html) 可以通过在字符串前加上 `$` 来使用，包括单独和组合，如 `$host` 或 `$remote_addr:$remote_port`。 | +| ssl_verify | boolean | False | true | 当设置为 `true` 时，验证 SSL 证书。| +| timeout | integer | False | 3000ms | Loki 服务 HTTP 调用的超时。范围从 1 到 60,000ms。 | +| keepalive | boolean | False | true | 当设置为 `true` 时，为多个请求保持连接。 | +| keepalive_timeout | integer | False | 60000ms | 空闲时间之后连接被关闭。大于或等于 1000ms 的范围。 | +| keepalive_pool | integer | False | 5 | 连接池限制。大于或等于 1 的范围。 | +| log_format | object | False | | 日志格式以 JSON 格式的键值对声明。值只支持字符串。[APISIX 变量](../apisix-variable.md) 和 [Nginx 变量](http://nginx.org/en/docs/varindex.html) 可以通过在字符串前加上 `$` 来使用。 | +| include_req_body | boolean | False | false | 当设置为 `true` 时，在日志中包括请求正文。如果请求正文太大，不能保存在内存中，由于 Nginx 的限制，它不能被记录下来。 | +| include_req_body_expr | array | False | | 当 `include_req_body` 属性被设置为 `true` 时的过滤器。只有当这里设置的表达式评估为 `true` 时，才会记录请求正文。更多信息请参见 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 | +| include_resp_body | boolean | False | false | 当设置为 `true` 时，在日志中包括响应体。 | +| include_resp_body_expr | array | False | | 当 `include_resp_body` 属性被设置为 `true` 时的过滤器。只有当这里设置的表达式评估为 `true` 时，才会记录响应体。更多信息请参见 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 | + +这个插件支持使用批处理程序来聚集和处理条目（日志/数据）的批次。这避免了频繁提交数据的需要。批处理程序每 `5` 秒或当队列中的数据达到 `1000` 时提交数据。参见 [批处理程序](../batch-processor.md#configuration) 了解更多信息或设置你的自定义配置。 + +## 元数据 + +你还可以通过配置插件元数据来设置日志的格式。以下配置是可用的： + +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +|------|------|----------|--|-------------| +| log_format | object | False | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX variables](../apisix-variable.md) and [Nginx variables](http://nginx.org/en/docs/varindex.html) can be used by prefixing the string with `$`. | + +:::info 重要信息 + +配置插件元数据的范围是全局的。这意味着它将对所有使用 `loki-logger` 插件的路由和服务生效。 + +::: + +下面的例子显示了你如何通过 Admin API 进行配置： + +```shell +curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/loki-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "log_format": { + "host": "$host", + "@timestamp": "$time_iso8601", + "client_ip": "$remote_addr" + } +}' +``` + +在这种配置下，你的日志将被格式化为如下所示： + +```shell +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +``` + +## 启用插件 + +下面的例子显示你如何在一个特定的路由上启用 `loki-logger` 插件： + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "plugins": { + "loki-logger": { + "endpoint_addrs" : ["http://127.0.0.1:3100";] + } + }, + "upstream": { + "nodes": { + "127.0.0.1:1980": 1 + }, + "type": "roundrobin" + }, + "uri": "/hello" +}' +``` + +## 使用示例 + +现在，如果你向 APISIX 发出请求，它将被记录在你的 Loki 服务器中: + +```shell +curl -i http://127.0.0.1:9080/hello +``` + +## 删除插件 + +当你需要删除 `loki-logger` 插件时，你可以用以下命令删除相应的 JSON 配置，APISIX 将自动重新加载相关配置，而不需要重新启动服务： + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "methods": ["GET"], + "uri": "/hello", + "plugins": {}, + "upstream": { + "type": "roundrobin", + "nodes": { + "127.0.0.1:1980": 1 + } + } +}' +``` + +## FAQ + +### 日志不能正常推送 + +看一下 `error.log` 这样的日志。 + +```text +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 +``` + +该错误可以根据 `未能处理条目：loki 服务器返回状态： 401, body: no org id` 和 loki 服务器的响应体。 + +### 当 RPS 较高时出现错误？ + +- 确保 `keepalive` 相关的配置被正确设置。更多信息见 [Attributes](#attributes)。 +- 检查 `error.log` 中的日志，寻找这样的日志记录。 + + ```text + 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 相关的日志看起来像上面的内容。错误是：`用户 tenant_1（限制：4194304 字节/秒）在试图摄取 '1000' 行共计 '616307' 字节时超过了消化率限制，减少日志量或联系你的 Loki 管理员，看看是否可以增加限制`。 Review Comment: Same as above. The error message should be kept as is -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
