# HTTP Logger 配置选项

http-logger 插件将请求和响应日志批量发送到 HTTP 或 HTTPS 端点，并支持自定义日志格式。<!-- --> <!-- -->配置涵盖插件参数和插件元数据。

## 参数[​](#参数 "参数的直接链接")

请参阅插件[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)，了解所有插件通用的配置选项。

* uri

  string

  必填

  ***

  HTTP(S) 服务器的 URI。

* auth\_header

  string

  ***

  HTTP(S) 服务器所需的授权头（如果需要）。该值在存储到 etcd 前会使用 AES 加密。

* timeout

  integer

  默认值：`3`

  有效值：

  大于 0

  ***

  向 HTTP(S) 服务器发送日志时，连接、写入和读取操作的套接字超时时间（秒）。

* log\_format

  object

  ***

  使用 JSON 格式的键值对的自定义日志格式。值可以引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

  如果 `include_req_body` 或 `include_resp_body` 为 true，请引用 `$request_body` 或 `$resp_body`，将已收集的请求体或响应体添加到自定义日志条目中。这些选项不会自动向自定义格式添加 Body 字段。

  在 APISIX 3.15.0 及更高版本中，日志格式嵌套结构支持最多五层深度。在 API7 企业版中，仅支持扁平键值结构；尚不支持嵌套结构。

  你还可以使用[插件元数据](https://docs.apiseven.com/apisix/key-concepts/plugin-metadata.md)在全局范围内配置日志格式，这将为所有 `http-logger` 插件实例配置日志格式。如果单个插件实例上配置的日志格式与插件元数据上配置的日志格式不同，则以单个插件实例上配置的日志格式为准。

* log\_format\_extra

  object

  ***

  用于向默认日志条目添加额外字段，使用 JSON 格式的键值对。值可引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。已配置的字段不会覆盖现有默认字段。插件实例优先于插件元数据；在实例上设置空对象会禁用元数据值。配置 `log_format` 时，`log_format_extra` 会被忽略。

  使用[插件元数据](https://docs.apiseven.com/apisix/key-concepts/plugin-metadata.md)为所有 `http-logger` 实例配置额外字段。请参阅[示例](https://docs.apiseven.com/hub/http-logger.md#使用插件元数据添加字段)了解更多详情。

  自 API7 企业版 3.9.15、3.10.2 和 APISIX 3.18.0 起引入。

* include\_req\_body

  boolean

  默认值：`false`

  ***

  如果为 true，则收集请求体并将其包含在默认日志字段中。无论请求体缓存在内存还是临时文件中，都可以记录；`max_req_body_bytes` 限制所记录请求体的大小。

* include\_req\_body\_expr

  array\[array]

  ***

  一个或多个 [APISIX 表达式](https://docs.apiseven.com/apisix/reference/apisix-expressions.md) 条件组成的数组。当 `include_req_body` 为 true 时，表达式控制是否主动读取请求体，以及默认日志格式中的 `request.body` 字段。即使表达式计算结果为 false，引用 `$request_body` 的自定义 `log_format` 或 `log_format_extra` 字段仍可能包含 NGINX 已缓冲的请求体。请勿将此选项用作数据脱敏边界。

* include\_resp\_body

  boolean

  默认值：`false`

  ***

  如果为 true，则在日志中包含响应体。

* include\_resp\_body\_expr

  array\[array]

  ***

  一个或多个 [APISIX 表达式](https://docs.apiseven.com/apisix/reference/apisix-expressions.md) 形式的条件数组。当 `include_resp_body` 为 true 时使用。仅当此处配置的表达式评估为 true 时，才会记录响应体。

* max\_req\_body\_bytes

  integer

  默认值：`524288`

  有效值：

  大于或等于 1

  ***

  日志中包含的请求体大小上限（字节）。如果请求体超过此值，将被截断。自 APISIX 3.16.0 起可用。

* max\_resp\_body\_bytes

  integer

  默认值：`524288`

  有效值：

  大于或等于 1

  ***

  日志中包含的响应体大小上限（字节）。如果响应体超过此值，将被截断。自 APISIX 3.16.0 起可用。

* concat\_method

  string

  默认值：`json`

  有效值：

  `json` 或 `new_line`

  ***

  连接日志的方法。设置为 `json` 时，对所有挂起的日志使用 `json.encode`。设置为 `new_line` 时，也使用 `json.encode`，但使用换行符 ``连接行。

* ssl\_verify

  boolean

  默认值：`false`

  ***

  如果为 true，则验证服务器的 SSL 证书。

* name

  string

  默认值：`http logger`

  ***

  批处理器中的插件唯一标识符。如果使用 [Prometheus](https://docs.apiseven.com/hub/prometheus.md) 监控 APISIX 指标，该名称会导出到 `apisix_batch_process_entries` 中。

* batch\_max\_size

  integer

  默认值：`1000`

  有效值：

  大于 0

  ***

  一个批次允许的日志条目数。达到该数量后，批次会发送到日志服务。将此参数设置为 1 可启用立即处理。

* inactive\_timeout

  integer

  默认值：`5`

  有效值：

  大于 0

  ***

  发送批次前等待新日志的最长时间，单位为秒。该值应小于 `buffer_duration`。

* buffer\_duration

  integer

  默认值：`60`

  有效值：

  大于 0

  ***

  从最早条目起计，发送批次前允许等待的最长时间，单位为秒。

* retry\_delay

  integer

  默认值：`1`

  有效值：

  大于或等于 0

  ***

  批次失败后重试前的等待时间，单位为秒。

* max\_retry\_count

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

  丢弃日志条目前允许的最大失败重试次数。

## 插件元数据[​](#插件元数据 "插件元数据的直接链接")

* log\_format

  object

  ***

  使用 JSON 格式的键值对的自定义日志格式。值可以引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

  在 APISIX 3.15.0 及更高版本中，日志格式嵌套结构支持最多五层深度。在 API7 企业版中，仅支持扁平键值结构；尚不支持嵌套结构。

* log\_format\_extra

  object

  ***

  用于向默认日志条目添加额外字段，使用 JSON 格式的键值对。值可引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。已配置的字段不会覆盖现有默认字段。插件实例优先于插件元数据；在实例上设置空对象会禁用元数据值。配置 `log_format` 时，`log_format_extra` 会被忽略。

  自 API7 企业版 3.9.15、3.10.2 和 APISIX 3.18.0 起引入。

* max\_pending\_entries

  integer

  默认值：`8192`

  有效值：

  大于或等于 1

  ***

  批处理器中等待处理的最大条目数。当积压达到此限制时，新条目会被丢弃。

  此参数在 API7 企业版 3.8.17 和 APISIX 3.15.0 中引入。

  在 APISIX 3.18.0、API7 企业版 3.9 分支的 3.9.19 以及 3.10 分支的 3.10.6 中，默认值变更为 `8192`。在 API7 企业版 3.9.18、3.10.5 及更早的 APISIX 版本中，省略该参数会使积压队列不设上限。

  有关容量规划和验证指南，请参见[批处理器](https://docs.apiseven.com/apisix/reference/batch-processor.md#配置待处理条目上限)。
