跳到主要内容

参数​

请参阅插件通用配置，了解所有插件通用的配置选项。

  • broker_list

    object

    已废弃，请改用 brokers。Kafka broker 主机及其端口的映射。broker_list 和 brokers 二选一配置。

  • brokers

    array

    有效值：

    大于 0

    Kafka broker 节点列表。brokers 和已废弃的 broker_list 二选一配置。

    • host

      string

      必填

      Kafka broker 的主机。

    • port

      integer

      必填

      Kafka broker 的端口。

    • sasl_config

      object

      Kafka broker 的 SASL 配置。

      • mechanism

        string

        默认值：PLAIN

        有效值：

        PLAIN、SCRAM-SHA-256 或 SCRAM-SHA-512

        SASL 配置的机制。

        SCRAM-SHA-256 和 SCRAM-SHA-512 选项在 API7 企业版 3.8.16 及更高版本和 APISIX 3.15.0 及更高版本中可用。

      • user

        string

        必填

        SASL 配置的用户名。

      • password

        string

        必填

        SASL 配置的密码。该值在存储到 etcd 前会使用 AES 加密。

  • tls

    object

    连接 Kafka broker 时使用的 TLS 配置。配置该对象即表示以 TLS 连接；不配置则以明文连接。自 API7 企业版 3.9.x 系列的 3.9.17 版本起可用，3.10.x 系列自 3.10.4 版本起可用；在 APISIX 中自 3.18.0 版本起可用。

    • verify

      boolean

      默认值：false

      如果为 true，则根据已配置的受信任 CA 校验 Kafka broker 的 TLS 证书。

      默认值为 false，此时配置 tls 只会加密连接，但不会校验 broker 身份，存在中间人攻击风险。生产环境请设置为 true。

  • kafka_topic

    string

    必填

    用于组织推送日志的目标主题。

  • producer_type

    string

    默认值：async

    有效值：

    async 或 sync

    Kafka 生产者模式。在 async 模式下，消息会先在本地缓冲，再发送到 Kafka；在 sync 模式下，消息不会使用异步生产者缓冲区，而是直接发送。

  • required_acks

    integer

    默认值：1

    有效值：

    -1 或 1

    leader 需要接收到的确认数量，以便生产者认为请求已完成。这控制了发送记录的持久性。有关更多信息，请参阅 Kafka 文档。尚不支持 acks=0。

  • api_version

    integer

    默认值：1

    有效值：

    0、1 或 2

    向 broker 发送消息时使用的 Kafka Produce API 版本。只有版本 2 会携带消息时间戳，使 broker 能够存储它；使用默认值 1 时，消息可能在没有可用时间戳的情况下被记录。版本 2 要求 Kafka 0.10 或更高版本。自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起引入。

  • key

    string

    用于为消息分配分区的键。

  • timeout

    integer

    默认值：3

    有效值：

    大于 0

    上游发送数据的超时时间。

  • meta_format

    string

    默认值：default

    有效值：

    default 或 origin

    收集请求信息的格式。设置为 default 时以 JSON 格式收集信息，设置为 origin 时保留原始 HTTP 请求格式。有关更多信息，请参阅示例。

  • log_format

    object

    使用 JSON 格式的键值对的自定义日志格式。值可以引用内置变量。

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

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

    当 meta_format 为 origin 时，此参数会被忽略。

    你还可以使用插件元数据在全局范围内配置日志格式，这将为所有 kafka-logger 插件实例配置日志格式。如果单个插件实例上配置的日志格式与插件元数据上配置的日志格式不同，则以单个插件实例上配置的日志格式为准。请参阅示例了解更多详情。

  • log_format_extra

    object

    用于向默认日志条目添加额外字段，使用 JSON 格式的键值对。值可引用内置变量。已配置的字段不会覆盖现有默认字段。插件实例优先于插件元数据；在实例上设置空对象会禁用元数据值。配置 log_format 或将 meta_format 配置为 origin 时，log_format_extra 会被忽略。

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

  • include_req_body

    boolean

    默认值：false

    如果为 true，则收集请求体。当 meta_format 为 default 时，将其添加到默认日志字段；当 meta_format 为 origin 时，将其追加到原始 HTTP 请求。无论请求体缓存在内存还是临时文件中，都可以记录；max_req_body_bytes 限制所记录请求体的大小。

  • include_req_body_expr

    array[array]

    一个或多个 APISIX 表达式 形式的条件数组。当 include_req_body 为 true 时使用。仅当此处配置的表达式评估为 true 时，才会记录请求体。

  • max_req_body_bytes

    integer

    默认值：524288

    有效值：

    大于或等于 1

    允许的最大请求体（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置的值，则在推送到 Kafka 之前将截断该主体。

  • include_resp_body

    boolean

    默认值：false

    如果为 true，则收集响应体。使用默认日志字段时，它会添加到 response.body；使用自定义 log_format 时，请引用 $resp_body 将其添加到日志条目中。当 meta_format 为 origin 时，不会添加响应体。max_resp_body_bytes 参数限制所记录响应体的大小。

  • include_resp_body_expr

    array[array]

    一个或多个 APISIX 表达式 形式的条件数组。当 include_resp_body 为 true 时使用。仅当此处配置的表达式评估为 true 时，才会记录响应体。

  • max_resp_body_bytes

    integer

    默认值：524288

    有效值：

    大于或等于 1

    允许的最大响应体（以字节为单位）。在此限制内的响应体将被推送到 Kafka。如果大小超过配置的值，则在推送到 Kafka 之前将截断该主体。

  • cluster_name

    integer

    默认值：1

    有效值：

    大于或等于 1

    集群名称。当有两个或多个 Kafka 集群时使用。仅当 producer_type 设置为 async 时有效。

  • producer_batch_num

    integer

    默认值：200

    有效值：

    大于或等于 1

    一批发送的消息数量。与 lua-resty-kafka 中的 batch_num 参数相同。

  • producer_batch_size

    integer

    默认值：1048576

    有效值：

    大于或等于 0

    发送数据时使用的 TCP 发送缓冲区大小。与 lua-resty-kafka 中的 batch_size 参数相同，但以字节为单位。

  • producer_max_buffering

    integer

    默认值：50000

    有效值：

    大于或等于 1

    异步生产者可在本地缓冲的 Kafka 生产者消息数上限。与 lua-resty-kafka 中的 max_buffering 参数相同。此缓冲区不受 max_pending_entries 限制；内存用量还取决于 worker 数量、batch_max_size、日志格式，以及是否记录请求体或响应体。

  • producer_time_linger

    integer

    默认值：1

    有效值：

    大于或等于 1

    刷新时间。与 lua-resty-kafka 中的 flush_time 参数相同，但以秒为单位。

  • meta_refresh_interval

    integer

    默认值：30

    有效值：

    大于或等于 1

    自动刷新元数据的时间间隔。与 lua-resty-kafka 中的 refresh_interval 参数相同，但以秒为单位。

  • name

    string

    默认值：kafka logger

    批处理器的插件唯一标识符。如果你使用 Prometheus 监控 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 格式的键值对的自定义日志格式。值可以引用内置变量。

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

    对于 meta_format 为 origin 的插件实例，此配置会被忽略。

  • log_format_extra

    object

    用于向默认日志条目添加额外字段，使用 JSON 格式的键值对。值可引用内置变量。已配置的字段不会覆盖现有默认字段。插件实例优先于插件元数据；在实例上设置空对象会禁用元数据值。配置 log_format 或插件实例使用 meta_format: origin 时，log_format_extra 会被忽略。

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

  • max_pending_entries

    integer

    默认值：在 APISIX 3.18.0 与 API7 企业版 3.9.19、3.10.6 中为 `8192`；API7 企业版 3.9.18 与 3.10.5 中无默认值

    有效值：

    大于或等于 1

    批处理器中等待处理的最大条目数。当积压达到此限制时，新条目会被丢弃。此设置不限制 Kafka 异步生产者的本地缓冲区。

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

    有关容量规划和验证指南，请参见批处理器。