文档
Kafka 3.6 文档
先前版本:0.7.x、 0.8.0、 0.8.1.X、 0.8.2.X、 0.9.0.X、 0.10.0.X、 0.10.1.X、 0.10.2.X、 0.11.0 .X、 1.0.X、 1.1.X、 2.0.X、 2.1.X、 2.2.X、 2.3.X、 2.4.X、 2.5.X、 2.6.X、 2.7.X、 2.8.X、 3.0.X、 3.1.X、 3.2.X、 3.3.X、 3.4.X、 3.5.X。1. 入门
1.1 简介
什么是事件流?
事件流相当于人体中枢神经系统的数字化。它是“永远在线”世界的技术基础,在这个世界中,企业越来越多地由软件定义和自动化,软件的用户更多地是软件。
从技术上讲,事件流是以事件流的形式从数据库、传感器、移动设备、云服务和软件应用程序等事件源实时捕获数据的实践;持久存储这些事件流以供以后检索;实时和回顾性地操作、处理事件流并对其做出反应;并根据需要将事件流路由到不同的目标技术。因此,事件流可确保数据的连续流动和解释,以便正确的信息在正确的时间出现在正确的地点。
我可以使用事件流做什么?
事件流适用于 众多行业和组织的各种用例。它的许多例子包括:
- 实时处理支付和金融交易,例如在证券交易所、银行和保险中。
- 实时跟踪和监控汽车、卡车、车队和货运,例如物流和汽车行业。
- 持续捕获和分析来自物联网设备或其他设备(例如工厂和风电场)的传感器数据。
- 收集客户互动和订单并立即做出反应,例如零售、酒店和旅游业以及移动应用程序。
- 监测医院护理中的患者并预测病情变化,以确保在紧急情况下及时得到治疗。
- 连接、存储并提供公司不同部门生成的数据。
- 作为数据平台、事件驱动架构和微服务的基础。
Apache Kafka® 是一个事件流平台。这意味着什么?
Kafka 结合了三个关键功能,因此您可以使用 一个经过实战检验的解决方案来实现端到端事件流的 用例:
- 发布(写入)和订阅(读取)事件流,包括从其他系统持续导入/导出数据。
- 根据需要持久可靠地存储事件 流。
- 在事件发生时或回顾性地 处理 事件流。
所有这些功能都是以分布式、高度可扩展、弹性、容错和安全的方式提供的。Kafka 可以部署在裸机硬件、虚拟机和容器上,也可以部署在本地和云端。您可以选择自行管理 Kafka 环境,也可以选择使用各种供应商提供的完全托管服务。
简而言之,Kafka 是如何工作的?
Kafka是一个分布式系统,由通过高性能TCP网络协议进行通信的服务器和客户端组成。它可以部署在本地和云环境中的裸机硬件、虚拟机和容器上。
服务器:Kafka 作为一台或多台服务器的集群运行,可以跨越多个数据中心或云区域。其中一些服务器形成存储层,称为代理。其他服务器运行 Kafka Connect以持续导入和导出数据作为事件流,以将 Kafka 与您现有的系统(例如关系数据库以及其他 Kafka 集群)集成。为了让您实现关键任务用例,Kafka 集群具有高度可扩展性和容错性:如果其中任何服务器发生故障,其他服务器将接管其工作,以确保连续运行而不会丢失任何数据。
客户端:它们允许您编写分布式应用程序和微服务,即使在网络问题或机器故障的情况下,也可以以容错的方式并行、大规模地读取、写入和处理事件流。Kafka 附带了一些此类客户端,并由 Kafka 社区提供的数十个客户端进行了扩充:客户端可用于 Java 和 Scala,包括更高级别的 Kafka Streams库,适用于 Go、Python、C/C++ 和许多其他编程语言以及 REST API。
主要概念和术语
事件记录了世界上或您的企业中“发生了一些事情”的事实。在文档中也称为记录或消息。当您向 Kafka 读取或写入数据时,您以事件的形式执行此操作。从概念上讲,事件具有键、值、时间戳和可选的元数据标头。这是一个示例事件:
- 事件键:“爱丽丝”
- 事件值:“向 Bob 支付了 200 美元”
- 事件时间戳:“2020 年 6 月 25 日下午 2:06”
生产者是将事件发布(写入)到 Kafka 的客户端应用程序,而消费者是订阅(读取和处理)这些事件的客户端应用程序。在 Kafka 中,生产者和消费者彼此完全解耦且互不可知,这是实现 Kafka 闻名的高可扩展性的关键设计元素。例如,生产者永远不需要等待消费者。Kafka 提供了各种保证,例如一次性处理事件的能力。
事件被组织并持久存储在主题中。非常简单,主题类似于文件系统中的文件夹,事件是该文件夹中的文件。示例主题名称可以是“付款”。Kafka 中的主题始终是多生产者和多订阅者:一个主题可以有零个、一个或多个向其写入事件的生产者,以及零个、一个或多个订阅这些事件的消费者。主题中的事件可以根据需要随时读取——与传统消息传递系统不同,事件在使用后不会被删除。相反,您可以通过每个主题的配置设置来定义 Kafka 应保留事件的时间,之后旧事件将被丢弃。Kafka 的性能在数据大小方面实际上是恒定的,因此长时间存储数据是完全可以的。
主题是分区的,这意味着一个主题分布在位于不同 Kafka 代理上的多个“桶”中。这种数据的分布式放置对于可扩展性非常重要,因为它允许客户端应用程序同时从多个代理读取数据或向多个代理写入数据。当新事件发布到主题时,它实际上会附加到主题的分区之一。具有相同事件键(例如,客户或车辆 ID)的事件被写入同一分区,并且 Kafka保证给定主题分区的任何消费者将始终按照与写入的顺序完全相同的顺序读取该分区的事件。
为了使您的数据具有容错性和高可用性,每个主题都可以复制,甚至可以跨地理区域或数据中心进行复制,因此始终有多个代理拥有数据副本,以防出现问题时,您希望对经纪人进行维护等等。常见的生产设置是复制因子为 3,即始终存在数据的三个副本。此复制是在主题分区级别执行的。
这本入门读物对于介绍来说应该足够了。如果您有兴趣,文档的设计部分详细解释了 Kafka 的各种概念。
Kafka API
除了用于管理和管理任务的命令行工具之外,Kafka 还有五个适用于 Java 和 Scala 的核心 API:
- 用于管理和检查主题、代理和其他 Kafka 对象的 管理 API 。
- Producer API,用于将事件流发布(写入)到一个或多个 Kafka 主题。
- Consumer API用于订阅(读取)一个或多个主题并处理为其生成的事件流。
- Kafka Streams API用于实现流处理应用程序和微服务。它提供了更高级别的函数来处理事件流,包括转换、有状态操作(例如聚合和连接)、窗口、基于事件时间的处理等等。从一个或多个主题读取输入,以便生成一个或多个主题的输出,从而有效地将输入流转换为输出流。
- Kafka Connect API用于构建和运行可重用的数据导入/导出连接器,这些连接器消耗(读取)或生成(写入)来自外部系统和应用程序的事件流,以便它们可以与 Kafka 集成。例如,关系数据库(如 PostgreSQL)的连接器可能会捕获对一组表的每个更改。然而,在实践中,您通常不需要实现自己的连接器,因为 Kafka 社区已经提供了数百个现成的连接器。
从这往哪儿走
- 要获得 Kafka 的实践经验,请按照快速入门进行操作。
- 要更详细地了解 Kafka,请阅读文档。您还可以选择Kafka书籍和学术论文。
- 浏览用例,了解我们全球社区中的其他用户如何从 Kafka 中获取价值。
- 加入当地的 Kafka 聚会小组, 观看Kafka 社区主要会议 Kafka Summit 的演讲。
1.2 使用案例
以下是 Apache Kafka® 的一些流行用例的描述。有关其中一些正在实施的领域的概述,请参阅此博客文章。
消息传递
Kafka 可以很好地替代更传统的消息代理。使用消息代理的原因有多种(将处理与数据生产者分离、缓冲未处理的消息等)。与大多数消息系统相比,Kafka 具有更好的吞吐量、内置分区、复制和容错能力,这使其成为大规模消息处理应用程序的良好解决方案。根据我们的经验,消息传递的使用通常吞吐量相对较低,但可能需要较低的端到端延迟,并且通常依赖于 Kafka 提供的强大的持久性保证。
在这个领域,Kafka 可以与ActiveMQ或 RabbitMQ等传统消息系统相媲美。
网站活动跟踪
Kafka 的最初用例是能够将用户活动跟踪管道重建为一组实时发布-订阅源。这意味着站点活动(页面浏览、搜索或用户可能执行的其他操作)将发布到中心主题,每种活动类型一个主题。这些源可用于一系列用例的订阅,包括实时处理、实时监控以及加载到 Hadoop 或离线数据仓库系统中以进行离线处理和报告。活动跟踪的量通常非常大,因为每个用户页面视图都会生成许多活动消息。
指标
Kafka常用于运行监控数据。这涉及聚合来自分布式应用程序的统计数据以生成集中的操作数据源。日志聚合
许多人使用 Kafka 作为日志聚合解决方案的替代品。日志聚合通常从服务器收集物理日志文件,并将它们放在一个中心位置(可能是文件服务器或 HDFS)进行处理。Kafka 抽象了文件的详细信息,并将日志或事件数据作为消息流提供了更清晰的抽象。这可以实现更低延迟的处理,并更轻松地支持多个数据源和分布式数据消费。与 Scribe 或 Flume 等以日志为中心的系统相比,Kafka 提供同样良好的性能、由于复制而提供更强的持久性保证以及更低的端到端延迟。流处理
Kafka 的许多用户在由多个阶段组成的处理管道中处理数据,其中原始输入数据从 Kafka 主题中消费,然后聚合、丰富或以其他方式转换为新主题以供进一步消费或后续处理。例如,用于推荐新闻文章的处理管道可能会从 RSS 源中抓取文章内容并将其发布到“文章”主题;进一步处理可能会规范化或删除重复内容,并将清理后的文章内容发布到新主题;最后的处理阶段可能会尝试向用户推荐该内容。此类处理管道根据各个主题创建实时数据流图。从 0.10.0.0 开始,Apache Kafka 中提供了一个轻量级但功能强大的流处理库(称为Kafka Streams) 来执行上述数据处理。除了 Kafka Streams 之外,替代的开源流处理工具还包括Apache Storm和 Apache Samza。事件溯源
事件溯源是一种应用程序设计风格,其中状态更改被记录为按时间排序的记录序列。Kafka 对非常大的存储日志数据的支持使其成为以此风格构建的应用程序的出色后端。提交日志
Kafka 可以充当分布式系统的一种外部提交日志。日志有助于在节点之间复制数据,并充当故障节点恢复数据的重新同步机制。Kafka 中的日志压缩功能有助于支持这种用法。在这种用法中,Kafka 类似于Apache BookKeeper项目。1.3 快速入门
第二步:启动Kafka环境
注意:您的本地环境必须安装 Java 8+。
Apache Kafka 可以使用 ZooKeeper 或 KRaft 启动。要开始使用任一配置,请按照以下部分之一进行操作,但不能同时进行这两个部分的操作。
Kafka与动物园管理员
运行以下命令以便以正确的顺序启动所有服务:
# Start the ZooKeeper service
$ bin/zookeeper-server-start.sh config/zookeeper.properties
打开另一个终端会话并运行:
# Start the Kafka broker service
$ bin/kafka-server-start.sh config/server.properties
所有服务成功启动后,您将拥有一个正在运行并可供使用的基本 Kafka 环境。
Kafka与 Kraft
生成集群 UUID
$ KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
设置日志目录格式
$ bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c config/kraft/server.properties
启动Kafka服务器
$ bin/kafka-server-start.sh config/kraft/server.properties
一旦 Kafka 服务器成功启动,您将拥有一个正在运行并可供使用的基本 Kafka 环境。
第 3 步:创建一个主题来存储您的事件
Kafka 是一个分布式事件流平台,可让您跨多台机器读取、写入、存储和处理 事件(在文档中 也称为记录或 消息)。
示例事件包括支付交易、手机的地理位置更新、运输订单、物联网设备或医疗设备的传感器测量等等。这些事件被组织并存储在 主题中。非常简单,主题类似于文件系统中的文件夹,事件是该文件夹中的文件。
因此,在编写第一个事件之前,您必须创建一个主题。打开另一个终端会话并运行:
$ bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092
所有 Kafka 的命令行工具都有附加选项:运行kafka-topics.sh
不带任何参数的命令来显示使用信息。例如,它还可以向您显示
新主题的
分区计数等详细信息:
$ bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092
Topic: quickstart-events TopicId: NPmZHyhbR9y00wMglMH2sg PartitionCount: 1 ReplicationFactor: 1 Configs:
Topic: quickstart-events Partition: 0 Leader: 0 Replicas: 0 Isr: 0
第四步:将一些事件写入主题
Kafka 客户端通过网络与 Kafka 代理进行通信以写入(或读取)事件。一旦收到,代理将以持久且容错的方式存储事件,只要您需要,甚至永远存储。
运行控制台生产者客户端以将一些事件写入您的主题。默认情况下,您输入的每一行都会导致将一个单独的事件写入主题。
$ bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092
This is my first event
This is my second event
Ctrl-C
您可以随时
停止生产者客户端。
第五步:阅读事件
打开另一个终端会话并运行控制台消费者客户端来读取您刚刚创建的事件:
$ bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092
This is my first event
This is my second event
Ctrl-C
您可以随时停止消费者客户端。
请随意尝试:例如,切换回生产者终端(上一步)以编写其他事件,并查看事件如何立即显示在消费者终端中。
由于事件持久存储在 Kafka 中,因此它们可以被任意数量的消费者读取任意多次。您可以通过打开另一个终端会话并再次重新运行之前的命令来轻松验证这一点。
第 6 步:使用 Kafka Connect 将数据作为事件流导入/导出
您可能在关系数据库或传统消息传递系统等现有系统中拥有大量数据,以及已经使用这些系统的许多应用程序。 Kafka Connect允许您不断地将数据从外部系统摄取到 Kafka 中,反之亦然。它是一个运行连接器的可扩展工具 ,它实现与外部系统交互的自定义逻辑。因此,将现有系统与 Kafka 集成非常容易。为了使这个过程更加容易,有数百个这样的连接器可供使用。
在本快速入门中,我们将了解如何使用简单的连接器运行 Kafka Connect,将数据从文件导入到 Kafka 主题,并将数据从 Kafka 主题导出到文件。
首先,确保添加connect-file-3.6.0.jar
到plugin.path
Connect 工作线程配置中的属性。出于本快速入门的目的,我们将使用相对路径并将连接器的包视为 uber jar,它在从安装目录运行快速入门命令时起作用。但是,值得注意的是,对于生产部署,使用绝对路径始终是更好的选择。有关如何设置此配置的详细说明,
请参阅plugin.path 。
编辑config/connect-standalone.properties
文件,添加或更改与plugin.path
以下内容匹配的配置属性,然后保存文件:
> echo "plugin.path=libs/connect-file-3.6.0.jar"
然后,首先创建一些种子数据进行测试:
> echo -e "foo\nbar" > test.txt或者在 Windows 上:
> echo foo> test.txt > echo bar>> test.txt
接下来,我们将启动两个以独立模式运行的连接器,这意味着它们在单个本地专用进程中运行。我们提供三个配置文件作为参数。第一个始终是 Kafka Connect 进程的配置,包含常见配置,例如要连接的 Kafka 代理和数据的序列化格式。其余配置文件各自指定要创建的连接器。这些文件包括唯一的连接器名称、要实例化的连接器类以及连接器所需的任何其他配置。
> bin/connect-standalone.sh config/connect-standalone.properties config/connect-file-source.properties config/connect-file-sink.properties
这些示例配置文件包含在 Kafka 中,使用您之前启动的默认本地集群配置并创建两个连接器:第一个是源连接器,用于从输入文件读取行并将每行生成到 Kafka 主题,第二个是接收器连接器从 Kafka 主题读取消息并将每条消息生成为输出文件中的一行。
在启动过程中,您将看到许多日志消息,其中包括一些指示连接器正在实例化的日志消息。一旦 Kafka Connect 进程启动,源连接器应开始从test.txt
主题读取行并将其生成到主题connect-test
,接收器连接器应开始从主题读取消息connect-test
并将其写入文件test.sink.txt
。我们可以通过检查输出文件的内容来验证数据是否已通过整个管道传递:
> more test.sink.txt foo bar
请注意,数据存储在 Kafka topic 中connect-test
,因此我们还可以运行控制台消费者来查看主题中的数据(或使用自定义消费者代码来处理它):
> bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning {"schema":{"type":"string","optional":false},"payload":"foo"} {"schema":{"type":"string","optional":false},"payload":"bar"} ...
连接器继续处理数据,因此我们可以将数据添加到文件并查看它在管道中移动:
> echo Another line>> test.txt
您应该看到该行出现在控制台使用者输出和接收器文件中。
第 7 步:使用 Kafka Streams 处理您的事件
将数据作为事件存储在 Kafka 中后,您可以使用适用于 Java/Scala 的Kafka Streams客户端库 处理数据 。它允许您实现关键任务实时应用程序和微服务,其中输入和/或输出数据存储在 Kafka 主题中。Kafka Streams 将客户端编写和部署标准 Java 和 Scala 应用程序的简单性与 Kafka 服务器端集群技术的优点相结合,使这些应用程序具有高度可扩展性、弹性、容错性和分布式性。该库支持一次性处理、有状态操作和聚合、窗口、连接、基于事件时间的处理等等。
为了让您初步体验一下,以下是如何实现流行的WordCount
算法:
KStream<String, String> textLines = builder.stream("quickstart-events");
KTable<String, Long> wordCounts = textLines
.flatMapValues(line -> Arrays.asList(line.toLowerCase().split(" ")))
.groupBy((keyIgnored, word) -> word)
.count();
wordCounts.toStream().to("output-topic", Produced.with(Serdes.String(), Serdes.Long()));
Kafka Streams 演示 和 应用程序开发教程 演示了如何从头到尾编码和运行此类流应用程序。
步骤8:终止Kafka环境
现在您已经完成了快速入门,可以随意拆除 Kafka 环境,或者继续尝试。
Ctrl-C
如果您还没有这样做, 请使用 停止生产者和消费者客户端。-
使用 停止 Kafka 代理
Ctrl-C
。 -
最后,如果遵循 Kafka with ZooKeeper 部分,请使用 停止 ZooKeeper 服务器
Ctrl-C
。
如果您还想删除本地 Kafka 环境的任何数据,包括您在此过程中创建的任何事件,请运行以下命令:
$ rm -rf /tmp/kafka-logs /tmp/zookeeper /tmp/kraft-combined-logs
恭喜!
您已成功完成 Apache Kafka 快速入门。
要了解更多信息,我们建议执行以下后续步骤:
- 阅读简短的简介 ,了解 Kafka 在高层次上的工作原理、主要概念以及与其他技术的比较。要更详细地了解 Kafka,请访问 文档。
- 浏览用例,了解我们全球社区中的其他用户如何从 Kafka 中获取价值。
- 加入当地的 Kafka 聚会小组, 观看Kafka 社区主要会议 Kafka Summit 的演讲。
1.4 生态系统
在主发行版之外,有大量与 Kafka 集成的工具。生态系统页面列出了其中的许多内容,包括流处理系统、Hadoop 集成、监控和部署工具。1.5 旧版本升级
Upgrading to 3.6.0 from any version 0.8.x through 3.5.x
升级基于ZooKeeper的集群
如果您要从 2.1.x 之前的版本升级,请参阅下面步骤 5 中有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.5
、3.4
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.5
、3.4
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本3.6
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 3.6 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
升级基于KRaft的集群
如果您是从 3.3.0 之前的版本升级,请参阅下面步骤 3 中的注释。将metadata.version更改为最新版本后,将无法降级到3.3-IV0之前的版本。
对于滚动升级:
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。
- 一旦集群的行为和性能得到验证,通过运行来提升metadata.version
./bin/kafka-features.sh upgrade --metadata 3.6
- 请注意,此版本不支持集群元数据降级,因为它有元数据更改。3.2.x之后的每个MetadataVersion
都有一个布尔参数,指示是否有元数据更改(即
IBP_3_3_IV3(7, "3.3", "IV3", true)
表示该版本有元数据更改)。鉴于您的当前版本和目标版本,只有在版本之间没有元数据更改的情况下才可能降级。
3.6.0 中的显着变化
- Apache Kafka 现在支持在同一端口上同时拥有 IPv4 和 IPv6 侦听器。此更改仅适用于非广告监听器(广告监听器已具有此功能)
- 由于 3.6 即将终止,Apache Zookeeper 依赖项已升级到 3.8.1。要将 Kafka 和 Zookeeper 集群升级到最新版本:
- >=2.4 Kafka集群可直接更新。运行与 Kafka 2.4 或更高版本捆绑的二进制文件的 Zookeeper 集群可以直接更新。
- <2.4的Kafka集群首先需要更新到大于2.4且小于3.6的版本。运行与低于 2.4 的 Kafka 版本捆绑的二进制文件的 Zookeeper 集群需要更新为与高于 2.4 且低于 3.6 的 Kafka 版本捆绑的任何二进制文件。然后您可以按照第一个要点进行操作。
- 该配置
log.message.timestamp.difference.max.ms
已弃用。添加了两个新配置log.message.timestamp.before.max.ms
和。log.message.timestamp.after.max.ms
欲了解更多详细信息,请参阅KIP-937。 -
Kafka Streams 引入了一个新的任务分配器 ,
RackAwareTaskAssignor
用于计算任务分配,可以在某些条件下最大限度地减少跨机架流量。它适用于现有的StickyTaskAssignor
和HighAvailabilityTaskAssignor
. 有关更多详细信息,请参阅KIP-925 和Kafka Streams 开发人员指南。 - 为了解决 3.1.0 版本中引入的兼容性中断问题,MirrorMaker 2 添加了一个新
replication.policy.internal.topic.separator.enabled
属性。如果从 3.0.x 或更早版本升级,可能需要将此属性设置为false
;有关更多详细信息,请参阅酒店的 文档。 - 分层存储功能已开放抢先体验,不建议在生产环境中使用。欢迎测试并向我们提供任何反馈。有关抢先体验分层存储功能的更多信息,请查看KIP-405和 分层存储抢先体验发行说明。
- 数据分区中添加了事务分区验证 ( KIP-890 ),以防止事务挂起。使用压缩的工作负载可能会遇到 InvalidRecordExceptions 和 UnknownServerExceptions。
transaction.partition.verification.enable
可以通过设置为 false 来禁用此功能。请注意,3.6 的默认值为 true。配置也可以动态更新并应用于代理。这将在 3.6.1 中修复。有关更多详细信息, 请参阅KAFKA-15653 。
Upgrading to 3.5.0 from any version 0.8.x through 3.4.x
升级基于ZooKeeper的集群
如果您要从 2.1.x 之前的版本升级,请参阅下面步骤 5 中有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- Update server.properties on all brokers and add the following properties. CURRENT_KAFKA_VERSION refers to the version you
are upgrading from. CURRENT_MESSAGE_FORMAT_VERSION refers to the message format version currently in use. If you have previously
overridden the message format version, you should keep its current value. Alternatively, if you are upgrading from a version prior
to 0.11.0.x, then CURRENT_MESSAGE_FORMAT_VERSION should be set to match CURRENT_KAFKA_VERSION.
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g.
3.4
,3.3
, etc.) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION (See potential performance impact following the upgrade for the details on what this configuration does.)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g.
3.4
,3.3
, etc.)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g.
- Upgrade the brokers one at a time: shut down the broker, update the code, and restart it. Once you have done so, the brokers will be running the latest version and you can verify that the cluster's behavior and performance meets expectations. It is still possible to downgrade at this point if there are any problems.
- Once the cluster's behavior and performance has been verified, bump the protocol version by editing
inter.broker.protocol.version
and setting it to3.5
. - Restart the brokers one by one for the new protocol version to take effect. Once the brokers begin using the latest protocol version, it will no longer be possible to downgrade the cluster to an older version.
- If you have overridden the message format version as instructed above, then you need to do one more rolling restart to upgrade it to its latest version. Once all (or most) consumers have been upgraded to 0.11.0 or later, change log.message.format.version to 3.5 on each broker and restart them one by one. Note that the older Scala clients, which are no longer maintained, do not support the message format introduced in 0.11, so to avoid conversion costs (or to take advantage of exactly once semantics), the newer Java clients must be used.
Upgrading KRaft-based clusters
If you are upgrading from a version prior to 3.3.0, please see the note in step 3 below. Once you have changed the metadata.version to the latest version, it will not be possible to downgrade to a version prior to 3.3-IV0.
For a rolling upgrade:
- Upgrade the brokers one at a time: shut down the broker, update the code, and restart it. Once you have done so, the brokers will be running the latest version and you can verify that the cluster's behavior and performance meets expectations.
- 一旦集群的行为和性能得到验证,通过运行来提升metadata.version
./bin/kafka-features.sh upgrade --metadata 3.5
- 请注意,此版本不支持集群元数据降级,因为它有元数据更改。3.2.x之后的每个MetadataVersion
都有一个布尔参数,指示是否有元数据更改(即
IBP_3_3_IV3(7, "3.3", "IV3", true)
表示该版本有元数据更改)。鉴于您的当前版本和目标版本,只有在版本之间没有元数据更改的情况下才可能降级。
3.5.0 中的显着变化
- Kafka Streams 引入了一种新的状态存储类型,即版本化键值存储,用于每个键存储多个记录版本,从而使带时间戳的检索操作能够返回指定时间戳的最新记录(每个键)。 有关更多详细信息,请参阅KIP-889 和KIP-914 。如果在 DSL 中使用新的存储类型,则将应用改进的处理语义,如 KIP-914中所述。
- KTable 聚合语义通过KIP-904得到了进一步改进 ,现在避免了虚假的中间结果。
- Kafka Streams
ProductionExceptionHandler
通过 KIP-399进行了改进,现在还涵盖了序列化错误。 - MirrorMaker 现在默认使用增量AlterConfigs API 来同步主题配置,而不是已弃用的 alterConfigs API。引入了一个名为 的新设置,
use.incremental.alter.configs
允许用户控制要使用的 API。当始终使用增量AlterConfigs API 时,此新设置已标记为已弃用,并将在下一个主要版本中删除。有关更多详细信息, 请参阅KIP-894 。 - JmxTool、EndToEndLatency、StreamsResetter、ConsumerPerformance 和 ClusterTool 已迁移到工具模块。“kafka.tools”包已弃用,并将在下一个主要版本中更改为“org.apache.kafka.tools”。有关更多详细信息, 请参阅KAFKA-14525 。
Upgrading to 3.4.0 from any version 0.8.x through 3.3.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.3
、3.2
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.3
、3.2
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本3.4
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 3.4 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
Upgrading a KRaft-based cluster to 3.4.0 from any version 3.0.x through 3.3.x
如果您是从 3.3.0 之前的版本升级,请参阅下面的注释。将metadata.version更改为最新版本后,将无法降级到3.3-IV0之前的版本。
对于滚动升级:
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。
- 一旦集群的行为和性能得到验证,通过运行来提升metadata.version
./bin/kafka-features.sh upgrade --metadata 3.4
- 请注意,此版本不支持集群元数据降级,因为它有元数据更改。3.2.x之后的每个MetadataVersion
都有一个布尔参数,指示是否有元数据更改(即
IBP_3_3_IV3(7, "3.3", "IV3", true)
表示该版本有元数据更改)。鉴于您的当前版本和目标版本,只有在版本之间没有元数据更改的情况下才可能降级。
3.4.0 中的显着变化
- 自 Apache Kafka 3.4.0 起,我们添加了一个系统属性(“org.apache.kafka.disallowed.login.modules”)来禁用 SASL JAAS 配置中有问题的登录模块使用。默认情况下,“com.sun.security.auth.module.JndiLoginModule”在 Apache Kafka 3.4.0 中被禁用。
Upgrading to 3.3.1 from any version 0.8.x through 3.2.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.2
、3.1
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.2
、3.1
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本3.3
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 3.3 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
Upgrading a KRaft-based cluster to 3.3.1 from any version 3.0.x through 3.2.x
如果您要从 3.3.1 之前的版本升级,请参阅下面的注释。将metadata.version更改为最新版本后,将无法降级到3.3-IV0之前的版本。
对于滚动升级:
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。
- 一旦集群的行为和性能得到验证,通过运行来提升metadata.version
./bin/kafka-features.sh upgrade --metadata 3.3
- 请注意,此版本不支持集群元数据降级,因为它有元数据更改。3.2.x之后的每个MetadataVersion
都有一个布尔参数,指示是否有元数据更改(即
IBP_3_3_IV3(7, "3.3", "IV3", true)
表示该版本有元数据更改)。鉴于您的当前版本和目标版本,只有在版本之间没有元数据更改的情况下才可能降级。
3.3.1 中的显着变化
- KRaft 模式已为新集群做好生产准备。 有关更多详细信息(包括限制), 请参阅KIP-833 。
- 默认情况下用于没有键的记录的分区器已得到改进,以避免当一个或多个代理速度缓慢时出现病态行为。新逻辑可能会影响批处理行为,可以使用
batch.size
和/或linger.ms
配置设置来调整批处理行为。可以通过设置恢复以前的行为partitioner.class=org.apache.kafka.clients.producer.internals.DefaultPartitioner
。有关更多详细信息, 请参阅KIP-794 。 - 如上所述,现在 KRaft 集群的升级过程与基于 ZK 的集群略有不同。
- 引入了一个新的 API,如果不存在,
addMetricIfAbsent
它将Metrics
创建一个新的指标;如果已经注册,则返回相同的指标。请注意,此行为与 API 不同,后者在尝试创建已存在的指标时addMetric
抛出。IllegalArgumentException
( 有关更多详细信息, 请参阅KIP-843 )。
Upgrading to 3.2.0 from any version 0.8.x through 3.1.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.1
、3.0
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.1
、3.0
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本3.2
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 3.2 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
3.2.0 中的显着变化
- 如果没有设置冲突的配置,默认情况下会启用生产者的幂等性。当向 2.8.0 之前的经纪商生产时,
IDEMPOTENT_WRITE
需要许可。有关详细信息,请检查KIP-679的兼容性部分 。在 3.0.0 和 3.1.0 中,一个错误阻止了应用此默认值,这意味着除非用户明确设置enable.idempotence
为 true,否则幂等性仍然处于禁用状态(有关更多详细信息,请参阅KAFKA-13598)。此问题已修复,默认值已在 3.0.1、3.1.1 和 3.2.0 中正确应用。 - 一个值得注意的例外是 Connect,它默认禁用所有生产者的幂等行为,以便统一支持使用各种 Kafka 代理版本。用户可以更改此行为,以通过 Connect Worker 和/或连接器配置为部分或所有生产者启用幂等性。Connect 可能会在未来的主要版本中默认启用幂等生产者。
- 出于安全考虑,Kafka 用 reload4j 取代了 log4j。这仅影响指定日志记录后端的模块(
connect-runtime
和kafka-tools
是两个这样的示例)。许多模块(包括 )kafka-clients
将其留给应用程序来指定日志记录后端。更多信息可以在reload4j找到。依赖于 Kafka 项目中受影响模块的项目应使用 slf4j-log4j12 版本 1.7.35 或更高版本或 slf4j-reload4j 以避免 源自日志记录框架的可能的兼容性问题。 - 示例连接器
FileStreamSourceConnector
和FileStreamSinkConnector
已从默认类路径中删除。要在 Kafka Connect 独立或分布式模式下使用它们,需要显式添加它们,例如CLASSPATH=./lib/connect-file-3.2.0.jar ./bin/connect-distributed.sh
.
Upgrading to 3.1.0 from any version 0.8.x through 3.0.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.0
、2.8
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
3.0
、2.8
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本3.1
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 3.1 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
3.1.1 中的显着变化
- 如果没有设置冲突的配置,默认情况下会启用生产者的幂等性。当向 2.8.0 之前的经纪商生产时,
IDEMPOTENT_WRITE
需要许可。有关详细信息,请检查KIP-679的兼容性部分 。一个错误阻止了生产者幂等性默认值的应用,这意味着除非用户明确设置enable.idempotence
为 true,否则它仍然处于禁用状态。有关更多详细信息,请参阅KAFKA-13598 。此问题已修复并且默认值已正确应用。 - 一个值得注意的例外是 Connect,它默认禁用所有生产者的幂等行为,以便统一支持使用各种 Kafka 代理版本。用户可以更改此行为,以通过 Connect Worker 和/或连接器配置为部分或所有生产者启用幂等性。Connect 可能会在未来的主要版本中默认启用幂等生产者。
- 出于安全考虑,Kafka 用 reload4j 取代了 log4j。这仅影响指定日志记录后端的模块(
connect-runtime
和kafka-tools
是两个这样的示例)。许多模块(包括 )kafka-clients
将其留给应用程序来指定日志记录后端。更多信息可以在reload4j找到。依赖于 Kafka 项目中受影响模块的项目应使用 slf4j-log4j12 版本 1.7.35 或更高版本或 slf4j-reload4j 以避免 源自日志记录框架的可能的兼容性问题。
3.1.0 中的显着变化
- Apache Kafka 支持 Java 17。
- 以下指标已被弃用:
bufferpool-wait-time-total
、io-waittime-total
和iotime-total
。请使用bufferpool-wait-time-ns-total
、io-wait-time-ns-total
、 和io-time-ns-total
代替。 有关更多详细信息,请参阅KIP-773 。 - IBP 3.1 将主题 ID 作为KIP-516的一部分引入 FetchRequest 。
Upgrading to 3.0.1 from any version 0.8.x through 2.8.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.8
、2.7
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.8
、2.7
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本3.0
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 3.0 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
3.0.1 中的显着变化
- 如果没有设置冲突的配置,默认情况下会启用生产者的幂等性。当向 2.8.0 之前的经纪商生产时,
IDEMPOTENT_WRITE
需要许可。有关详细信息,请检查KIP-679的兼容性部分 。一个错误阻止了生产者幂等性默认值的应用,这意味着除非用户明确设置enable.idempotence
为 true,否则它仍然处于禁用状态。有关更多详细信息,请参阅KAFKA-13598 。此问题已修复并且默认值已正确应用。
3.0.0 中的显着变化
- 默认情况下,生产者具有更强的交付保证:
idempotence
已启用并acks
设置all
为而不是1
。有关详细信息,请参阅KIP-679。在 3.0.0 和 3.1.0 中,一个错误阻止应用幂等默认值,这意味着除非用户明确设置enable.idempotence
为 true,否则它仍然处于禁用状态。请注意,该错误并不影响acks=all
更改。有关更多详细信息,请参阅KAFKA-13598 。此问题已修复,默认值已在 3.0.1、3.1.1 和 3.2.0 中正确应用。 - 自 Apache Kafka 3.0 起,Java 8 和 Scala 2.12 支持已被弃用,并将在 Apache Kafka 4.0 中删除。有关更多详细信息,请参阅KIP-750 和KIP-751 。
- ZooKeeper已升级至3.6.3版本。
- KRaft 模式的预览版可用,但无法从 2.8 早期访问版本升级到该模式。有关详细信息,请参阅KRaft 部分。
- 发布 tarball 不再包含测试、源、javadoc 和测试源 jar。这些仍然发布到 Maven 中央存储库。
- 现在,运行时类路径(而不是编译和运行时类路径)中提供了许多实现依赖项 jar 。升级后的编译错误可以通过显式添加缺少的依赖项 jar 或更新应用程序以不使用内部类来修复。
- 消费者配置的默认值
session.timeout.ms
从 10 秒增加到 45 秒。有关更多详细信息,请参阅 KIP-735 。 - 代理配置
log.message.format.version
和主题配置message.format.version
已被弃用。两种配置的值始终假定为3.0
if或inter.broker.protocol.version
更高3.0
。如果设置了log.message.format.version
或message.format.version
,我们建议在升级到 3.0 的同时清除它们inter.broker.protocol.version
。这将避免降级时潜在的兼容性问题inter.broker.protocol.version
。有关更多详细信息,请参阅KIP-724 。 - Streams API 删除了在 2.5.0 或更早版本中已弃用的所有已弃用的 API。有关已删除 API 的完整列表,请比较详细的 Kafka Streams 升级说明。
- Kafka Streams 不再对“connect:json”模块有编译时依赖性 ( KAFKA-5146 )。依赖这种传递依赖的项目必须显式声明它。
- 通过指定的自定义主体构建器实现
principal.builder.class
现在必须实现该KafkaPrincipalSerde
接口以允许在代理之间转发。有关 KafkaPrincipalSerde 使用的更多详细信息,请参阅KIP-590 。 - 许多已弃用的类、方法和工具已从、 和
clients
模块connect
中删除:core
tools
- Scala
Authorizer
和SimpleAclAuthorizer
相关类已被删除。请使用JavaAuthorizer
和AclAuthorizer
代替。 - 该
Metric#value()
方法已被删除(KAFKA-12573)。 - 和
Sum
类Total
已被删除(KAFKA-12584)。请使用WindowedSum
andCumulativeSum
代替。 - 和
Count
类SampledTotal
被删除。请分别使用WindowedCount
和WindowedSum
来代替。 - 、
PrincipalBuilder
和DefaultPrincipalBuilder
类ResourceFilter
已被删除。 SslConfigs
、SaslConfigs
和AclBinding
中 删除了各种常量和构造函数AclBindingFilter
。- 这些
Admin.electedPreferredLeaders()
方法已被删除。请改用Admin.electLeaders
。 - 命令行工具
kafka-preferred-replica-election
已被删除。请改用kafka-leader-election
。 - 该
--zookeeper
选项已从kafka-topics
和kafka-reassign-partitions
命令行工具中删除。请改用--bootstrap-server
。 - 在
kafka-configs
命令行工具中,该--zookeeper
选项仅支持更新SCRAM 凭证配置 以及在代理未运行时描述/更新动态代理配置。请用于--bootstrap-server
其他配置操作。 - 构造函数
ConfigEntry
被删除(KAFKA-12577)。请改用剩余的公共构造函数。 default
客户端配置的配置值client.dns.lookup
已被删除。万一您显式设置此配置,我们建议您保留该配置未设置(use_all_dns_ips
默认情况下使用)。- 和
ExtendedDeserializer
类ExtendedSerializer
已被删除。请使用Deserializer
andSerializer
代替。 - 该
close(long, TimeUnit)
方法已从生产者、消费者和管理客户端中删除。请使用close(Duration)
. - 和
ConsumerConfig.addDeserializerToConfig
方法ProducerConfig.addSerializerToConfig
已被删除。这些方法无意成为公共 API,并且没有替代方法。 - 该
NoOffsetForPartitionException.partition()
方法已被删除。请改用partitions()
。 - 默认值
partition.assignment.strategy
更改为“[RangeAssignor, CooperativeStickyAssignor]”,默认情况下将使用 RangeAssignor,但允许升级到 CooperativeStickyAssignor,只需一次滚动弹跳即可从列表中删除 RangeAssignor。请在此处查看客户端升级路径指南以了解更多详细信息。 - Scala
kafka.common.MessageFormatter
被删除了。请使用Javaorg.apache.kafka.common.MessageFormatter
. - 该
MessageFormatter.init(Properties)
方法已被删除。请改用configure(Map)
。 - 该
checksum()
方法已从ConsumerRecord
和中删除RecordMetadata
。消息格式 v2(从 0.11 开始一直是默认格式)将校验和从记录移至记录批次。因此,这些方法没有意义,也不存在替代方法。 - 该类
ChecksumMessageFormatter
已被删除。它不是公共 API 的一部分,但可能已与kafka-console-consumer.sh
. 它报告了每条记录的校验和,自消息格式 v2 以来不再支持该校验和。 - 该类
org.apache.kafka.clients.consumer.internals.PartitionAssignor
已被删除。请改用org.apache.kafka.clients.consumer.ConsumerPartitionAssignor
。 - 和配置已被删除 (
quota.producer.default
KAFKA -12591 )。必须改用动态配额默认值。quota.consumer.default
- 和配置已被
port
删除host.name
。请改用listeners
。 - 和配置已被
advertised.port
删除advertised.host.name
。请改用advertised.listeners
。 - 已弃用的工作程序配置
rest.host.name
已从Kafka Connect 工作程序配置中rest.port
删除 ( KAFKA-12482 )。请改用listeners
。 - 该
Producer#sendOffsetsToTransaction(Map offsets, String consumerGroupId)
方法已被弃用。请Producer#sendOffsetsToTransaction(Map offsets, ConsumerGroupMetadata metadata)
改用,其中ConsumerGroupMetadata
可以通过 检索KafkaConsumer#groupMetadata()
以获得更强的语义。请注意,完整的消费者组元数据集只有代理或 2.5 或更高版本才能理解,因此您必须升级您的 kafka 集群以获得更强大的语义。否则,您可以直接new ConsumerGroupMetadata(consumerGroupId)
与老经纪人合作。有关更多详细信息, 请参阅KIP-732 。 -
连接
internal.key.converter
和internal.value.converter
属性已被完全删除。自版本 2.0.0 以来,已弃用这些 Connect 工作线程属性的使用。现在,工作人员被硬编码为使用 JSON 转换器并schemas.enable
设置为false
。如果您的集群一直在使用不同的内部键或值转换器,您可以按照KIP-738中概述的迁移步骤 将 Connect 集群安全升级到 3.0。 - 基于 Connect 的 MirrorMaker (MM2) 包括对支持的更改
IdentityReplicationPolicy
,无需重命名主题即可实现复制。默认情况下仍使用现有的DefaultReplicationPolicy
,但可以通过replication.policy
配置属性启用身份复制。这对于从较旧的 MirrorMaker (MM1) 迁移的用户,或者对于具有简单单向复制拓扑(不希望主题重命名)的用例特别有用。请注意IdentityReplicationPolicy
,与 不同DefaultReplicationPolicy
, 无法阻止基于主题名称的复制循环,因此在构建复制拓扑时请注意避免循环。 - 最初的 MirrorMaker (MM1) 和相关类已被弃用。请使用基于 Connect 的 MirrorMaker (MM2),如 异地复制部分中所述。
Upgrading to 2.8.1 from any version 0.8.x through 2.7.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.7
、2.6
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.7
、2.6
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本2.8
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 2.8 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
2.8.0 中的显着变化
- 2.8.0 版本向KIP-679 中引入的授权者接口添加了一个新方法 。其动机是解锁我们未来的计划,以默认启用最强的消息传递保证。自定义授权者应考虑提供更有效的实现,支持审核日志记录和任何自定义配置或访问规则。
- IBP 2.8 将主题 ID 作为KIP-516 的一部分引入主题 。使用 ZooKeeper 时,此信息存储在 TopicZNode 中。如果集群降级到以前的 IBP 或版本,未来的主题将不会获得主题 ID,并且不保证主题将在 ZooKeeper 中保留其主题 ID。这意味着再次升级时,某些主题或所有主题将被分配新的 ID。
- Kafka Streams 引入了类型安全
split()
运算符作为已弃用方法的替代KStream#branch()
(参见KIP-418)。
Upgrading to 2.7.0 from any version 0.8.x through 2.6.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.6
、2.5
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.6
、2.5
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本2.7
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 2.7 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
2.7.0 中的显着变化
- 2.7.0 版本包含 KIP-595中指定的核心 Raft 实现。有一个单独的“raft”模块包含大部分逻辑。在与控制器的集成完成之前,用户可以使用一个独立的服务器来测试 Raft 实现的性能。详细信息请参见 raft 模块中的 README.md
- KIP-651添加了 对使用 PEM 文件进行密钥和信任存储的 支持。
- KIP-612添加了 对强制代理范围和每个侦听器连接创建速率的支持。2.7.0 版本包含 KIP-612 的第一部分,动态配置将在 2.8.0 版本中出现。
- 能够限制主题和分区创建或主题删除,以防止集群因 KIP-599受到损害
-
当 Kafka 推出新功能时,存在两个主要问题:
- Kafka 客户端如何了解代理功能?
- 经纪商如何决定启用哪些功能?
ConsoleConsumer
现在可以通过KIP-431 打印记录偏移量和标题- KIP-554 的添加 继续朝着从 Kafka 中删除 Zookeeper 的目标迈进。添加 KIP-554 意味着您不必再直接连接到 ZooKeeper 来管理 SCRAM 凭据。
- 更改现有侦听器的不可重新配置的配置会导致
InvalidRequestException
. 相比之下,之前的(意外的)行为会导致更新的配置被保留,但直到代理重新启动后才会生效。有关更多讨论,请参阅KAFKA-10479 。请参阅DynamicBrokerConfig.DynamicSecurityConfigs
和SocketServer.ListenerReconfigurableConfigs
了解现有侦听器支持的可重新配置配置。 - Kafka Streams 在 KStreams DSL 中 添加了对滑动 Windows 聚合的支持。
- 状态存储上的反向迭代可使用KIP-617 实现更高效的最新更新搜索
- Kafka Steams 中的端到端延迟指标请参阅 KIP-613 了解更多详细信息
- Kafka Streams 添加了使用KIP-607 报告默认 RocksDB 属性的指标
- KIP-616 提供更好的 Scala 隐式 Serdes 支持
Upgrading to 2.6.0 from any version 0.8.x through 2.5.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.5
、2.4
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.5
、2.4
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本2.6
。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 2.6 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
2.6.0 中的显着变化
- Kafka Streams 添加了一种新的处理模式(需要代理 2.5 或更高版本),该模式使用一次性保证提高应用程序可扩展性(参见KIP-447)
- Java 11 或更高版本默认启用 TLSv1.3。如果客户端和服务器都支持 TLSv1.3,则将协商 TLSv1.3,否则回退到 TLSv1.2。有关更多详细信息, 请参阅 KIP-573 。
- 配置的默认值
client.dns.lookup
已从 更改default
为use_all_dns_ips
。如果主机名解析为多个 IP 地址,客户端和代理现在将尝试按顺序连接到每个 IP,直到成功建立连接。 有关更多详细信息, 请参阅 KIP-602 。 NotLeaderForPartitionException
已被弃用并替换为NotLeaderOrFollowerException
. 如果代理不是副本,则仅针对领导者或追随者的获取请求和其他请求将返回 NOT_LEADER_OR_FOLLOWER(6) 而不是 REPLICA_NOT_AVAILABLE(9),确保所有客户端将重新分配期间的短暂错误作为可重试异常进行处理。
Upgrading to 2.5.0 from any version 0.8.x through 2.4.x
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.4
、2.3
等) - log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
2.4
、2.3
等)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (例如
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑协议版本
inter.broker.protocol.version
并将其设置为 来提升协议版本2.5
。 - Restart the brokers one by one for the new protocol version to take effect. Once the brokers begin using the latest protocol version, it will no longer be possible to downgrade the cluster to an older version.
- If you have overridden the message format version as instructed above, then you need to do one more rolling restart to upgrade it to its latest version. Once all (or most) consumers have been upgraded to 0.11.0 or later, change log.message.format.version to 2.5 on each broker and restart them one by one. Note that the older Scala clients, which are no longer maintained, do not support the message format introduced in 0.11, so to avoid conversion costs (or to take advantage of exactly once semantics), the newer Java clients must be used.
- There are several notable changes to the reassignment tool
kafka-reassign-partitions.sh
following the completion of KIP-455. This tool now requires the--additional
flag to be provided when changing the throttle of an active reassignment. Reassignment cancellation is now possible using the--cancel
command. Finally, reassignment with--zookeeper
has been deprecated in favor of--bootstrap-server
. See the KIP for more detail.
Notable changes in 2.5.0
- When
RebalanceProtocol#COOPERATIVE
is used,Consumer#poll
can still return data while it is in the middle of a rebalance for those partitions still owned by the consumer; in additionConsumer#commitSync
now may throw a non-fatalRebalanceInProgressException
to notify users of such an event, in order to distinguish from the fatalCommitFailedException
and allow users to complete the ongoing rebalance and then reattempt committing offsets for those still-owned partitions. - For improved resiliency in typical network environments, the default value of
zookeeper.session.timeout.ms
has been increased from 6s to 18s andreplica.lag.time.max.ms
from 10s to 30s. - New DSL operator
cogroup()
has been added for aggregating multiple streams together at once. - Added a new
KStream.toTable()
API to translate an input event stream into a KTable. - Added a new Serde type
Void
to represent null keys or null values from input topic. - Deprecated
UsePreviousTimeOnInvalidTimestamp
and replaced it withUsePartitionTimeOnInvalidTimeStamp
. - Improved exactly-once semantics by adding a pending offset fencing mechanism and stronger transactional commit consistency check, which greatly simplifies the implementation of a scalable exactly-once application. We also added a new exactly-once semantics code example under examples folder. Check out KIP-447 for the full details.
- Added a new public api
KafkaStreams.queryMetadataForKey(String, K, Serializer) to get detailed information on the key being queried. It provides information about the partition number where the key resides in addition to hosts containing the active and standby partitions for the key.
- Provided support to query stale stores (for high availability) and the stores belonging to a specific partition by deprecating
KafkaStreams.store(String, QueryableStoreType)
and replacing it withKafkaStreams.store(StoreQueryParameters)
. - 添加了一个新的公共 api,用于访问实例本地存储的滞后信息
KafkaStreams.allLocalStorePartitionLags()
。 - 不再支持 Scala 2.11。详细信息请参阅 KIP-531 。
- 包中的所有 Scala 类
kafka.security.auth
均已弃用。 有关 2.4.0 中添加的新 Java 授权者 API 的详细信息,请参阅 KIP-504 。请注意,kafka.security.auth.Authorizer
和kafka.security.auth.SimpleAclAuthorizer
在 2.4.0 中已弃用。 - 默认情况下,TLSv1 和 TLSv1.1 已被禁用,因为它们存在已知的安全漏洞。现在默认仅启用 TLSv1.2。
ssl.protocol
您可以通过在配置选项和 中显式启用 TLSv1 和 TLSv1.1 来继续使用它们ssl.enabled.protocols
。 - ZooKeeper 已升级到 3.5.7,如果 3.4 数据目录中没有快照文件,ZooKeeper 从 3.4.X 升级到 3.5.7 可能会失败。这通常发生在测试升级中,其中 ZooKeeper 3.5.7 尝试加载尚未创建快照文件的现有 3.4 数据目录。有关该问题的更多详细信息,请参阅ZOOKEEPER-3056。ZOOKEEPER-3056中给出了修复,即在升级之前
设置
snapshot.trust.empty=true
配置。zookeeper.properties
- ZooKeeper 版本 3.5.7 支持使用或不使用客户端证书与 ZooKeeper 进行 TLS 加密连接,并且可以使用其他 Kafka 配置来利用此功能。详细信息请参阅KIP-515。
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, 1.0.x, 1.1.x, 2.0.x or 2.1.x or 2.2.x or 2.3.x to 2.4.0
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.10.0、0.11.0、1.0、2.0、2.2)。
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(0.11.0、1.0、1.1、2.0、2.1、2.2、2.3)。
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑
inter.broker.protocol.version
并将其设置为 2.4 来提升协议版本。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 2.4 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
附加升级说明:
- ZooKeeper已升级至3.5.6。如果 3.4 数据目录中没有快照文件,ZooKeeper 从 3.4.X 升级到 3.5.6 可能会失败。这通常发生在测试升级中,其中 ZooKeeper 3.5.6 尝试加载尚未创建快照文件的现有 3.4 数据目录。有关该问题的更多详细信息,请参阅ZOOKEEPER-3056。ZOOKEEPER-3056中给出了修复,即在升级之前设置
snapshot.trust.empty=true
配置。zookeeper.properties
但我们观察到使用snapshot.trust.empty=true
config.js 进行独立集群升级时会出现数据丢失的情况。有关该问题的更多详细信息,请参阅ZOOKEEPER-3644。因此,如果 3.4 数据目录中没有快照文件,我们建议将空快照文件复制到 3.4 数据目录中的安全解决方法。有关解决方法的更多详细信息,请参阅ZooKeeper 升级常见问题解答。 -
An embedded Jetty based AdminServer added in ZooKeeper 3.5.
AdminServer is enabled by default in ZooKeeper and is started on port 8080.
AdminServer is disabled by default in the ZooKeeper config (
zookeeper.properties
) provided by the Apache Kafka distribution. Make sure to update your localzookeeper.properties
file withadmin.enableServer=false
if you wish to disable the AdminServer. Please refer AdminServer config to configure the AdminServer.
Notable changes in 2.4.0
- A new Admin API has been added for partition reassignments. Due to changing the way Kafka propagates reassignment information, it is possible to lose reassignment state in failure edge cases while upgrading to the new version. It is not recommended to start reassignments while upgrading.
- ZooKeeper has been upgraded from 3.4.14 to 3.5.6. TLS and dynamic reconfiguration are supported by the new version.
- The
bin/kafka-preferred-replica-election.sh
command line tool has been deprecated. It has been replaced bybin/kafka-leader-election.sh
. - The methods
electPreferredLeaders
in the JavaAdminClient
class have been deprecated in favor of the methodselectLeaders
. - Scala code leveraging the
NewTopic(String, int, short)
constructor with literal values will need to explicitly calltoShort
on the second literal. - The argument in the constructor
GroupAuthorizationException(String)
is now used to specify an exception message. Previously it referred to the group that failed authorization. This was done for consistency with other exception types and to avoid potential misuse. The constructorTopicAuthorizationException(String)
which was previously used for a single unauthorized topic was changed similarly. - The internal
PartitionAssignor
interface has been deprecated and replaced with a newConsumerPartitionAssignor
in the public API. Some methods/signatures are slightly different between the two interfaces. Users implementing a custom PartitionAssignor should migrate to the new interface as soon as possible. - The
DefaultPartitioner
now uses a sticky partitioning strategy. This means that records for specific topic with null keys and no assigned partition will be sent to the same partition until the batch is ready to be sent. When a new batch is created, a new partition is chosen. This decreases latency to produce, but it may result in uneven distribution of records across partitions in edge cases. Generally users will not be impacted, but this difference may be noticeable in tests and other situations producing records for a very short amount of time. - The blocking
KafkaConsumer#committed
methods have been extended to allow a list of partitions as input parameters rather than a single partition. It enables fewer request/response iterations between clients and brokers fetching for the committed offsets for the consumer group. The old overloaded functions are deprecated and we would recommend users to make their code changes to leverage the new methods (details can be found in KIP-520). - We've introduced a new
INVALID_RECORD
error in the produce response to distinguish from theCORRUPT_MESSAGE
error. To be more concrete, previously when a batch of records was sent as part of a single request to the broker and one or more of the records failed the validation due to various causes (mismatch magic bytes, crc checksum errors, null key for log compacted topics, etc), the whole batch would be rejected with the same and misleadingCORRUPT_MESSAGE
, and the caller of the producer client would see the corresponding exception from either the future object ofRecordMetadata
returned from thesend
call as well as in theCallback#onCompletion(RecordMetadata metadata, Exception exception)
Now with the new error code and improved error messages of the exception, producer callers would be better informed about the root cause why their sent records were failed. - 我们正在向客户端组协议引入增量合作重新平衡,该协议允许消费者在重新平衡期间保留所有分配的分区,并在最后仅撤销那些必须迁移到另一个消费者以实现整体集群平衡的分区。他们将选择
所有消费者支持的分配者普遍支持的
ConsumerCoordinator
最新版本。RebalanceProtocol
您可以使用新的内置CooperativeStickyAssignor
或插入您自己的自定义协作分配器。为此,您必须实现该ConsumerPartitionAssignor
接口并包含RebalanceProtocol.COOPERATIVE
在 . 返回的列表中ConsumerPartitionAssignor#supportedProtocols
。然后,您的自定义分配者可以利用ownedPartitions
每个使用者中的字段Subscription
,尽可能将分区返还给其以前的所有者。请注意,当要将分区重新分配给另一个使用者时,必须将其从新分配中删除,直到它从其原始所有者手中撤销。任何必须撤销分区的消费者都将触发后续重新平衡,以允许撤销的分区安全地分配给其新所有者。有关更多信息, 请参阅 ConsumerPartitionAssignor RebalanceProtocol javadocs 。
要从旧的(急切的)协议(在重新平衡之前总是撤销所有分区)升级到协作式重新平衡,您必须遵循特定的升级路径,以使所有客户端都使用支持协作式协议的相同协议ConsumerPartitionAssignor
。这可以通过两次滚动弹跳来完成,例如CooperativeStickyAssignor
:在第一次弹跳期间,将“合作粘性”添加到每个成员支持的分配器列表中(不删除先前的分配器 - 请注意,如果之前使用默认分配器) ,您也必须明确包含该内容)。然后您可以退回和/或升级它。一旦整个组处于 2.4+ 并且所有成员在其支持的分配者之间都具有“合作粘性”,请删除其他分配者并执行第二次滚动反弹,以便最终所有成员仅支持合作协议。有关协作再平衡协议和升级路径的更多详细信息,请参阅KIP-429。 ConsumerRebalanceListener
以及新的 API进行了一些行为更改。在侦听器的三个回调中的任何一个期间抛出的异常将不再被吞掉,而是会一直重新抛出直到调用为止Consumer.poll()
。onPartitionsLost
添加该方法是为了允许用户对消费者可能失去其分区所有权(例如错过重新平衡)并且无法提交偏移量的异常情况做出反应。默认情况下,这将简单地调用现有onPartitionsRevoked
API 来与之前的行为保持一致。但请注意,onPartitionsLost
当丢失的分区集为空时,不会调用该方法。这意味着在新消费者加入组的第一次重新平衡开始时不会调用回调。 当遵循上述合作重新平衡协议时,回调
的语义会进一步改变。ConsumerRebalanceListener's
此外onPartitionsLost
,onPartitionsRevoked
当撤销分区集为空时,也永远不会被调用。该回调通常仅在重新平衡结束时调用,并且仅在正在移动到另一个使用者的分区集上调用。然而,即使分区集为空,回调onPartitionsAssigned
也将始终被调用,作为通知用户重新平衡事件的一种方式(对于合作型和渴望型都是如此)。有关新回调语义的详细信息,请参阅ConsumerRebalanceListener javadocs。- Scala 特征
kafka.security.auth.Authorizer
已被弃用并被新的 Java API 取代org.apache.kafka.server.authorizer.Authorizer
。授权者实现类kafka.security.auth.SimpleAclAuthorizer
也已被弃用并被新的实现所取代kafka.security.authorizer.AclAuthorizer
。AclAuthorizer
使用新 API 支持的功能来改进授权日志记录,并与SimpleAclAuthorizer
. 有关更多详细信息,请参阅KIP-504。
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, 1.0.x, 1.1.x, 2.0.x or 2.1.x or 2.2.x to 2.3.0
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2、0.9.0、0.10.0、0.10.1、0.10.2、0.11.0、1.0、1.1)。
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(0.11.0、1.0、1.1、2.0、2.1、2.2)。
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑
inter.broker.protocol.version
并将其设置为 2.3 来提升协议版本。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 2.3 并一一重新启动它们。请注意,不再维护的旧版 Scala 客户端不支持 0.11 中引入的消息格式,因此为了避免转换成本(或利用恰好一次语义),必须使用较新的 Java 客户端。
2.3.0 中的显着变化
- 我们正在为 Kafka Connect 引入一种基于 增量合作再平衡的新再平衡协议。新协议不需要在 Connect 工作线程之间的重新平衡阶段停止所有任务。相反,只有需要在工作人员之间交换的任务才会停止,并在后续重新平衡中启动它们。从 2.3.0 开始,新的 Connect 协议默认启用。有关其工作原理以及如何启用急切再平衡的旧行为的更多详细信息,请查看 增量协作再平衡设计。
- 我们正在向消费者用户引入静态会员资格。此功能减少了正常应用程序升级或滚动弹跳期间不必要的重新平衡。有关如何使用它的更多详细信息,请查看静态成员资格设计。
- Kafka Streams DSL 切换其使用的存储类型。虽然此更改主要对用户是透明的,但在某些极端情况下可能需要更改代码。有关更多详细信息,请参阅Kafka Streams 升级部分。
- Kafka Streams 2.3.0 需要 0.11 消息格式或更高版本,并且不适用于较旧的消息格式。
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, 1.0.x, 1.1.x, 2.0.x or 2.1.x to 2.2.0
如果您要从 2.1.x 之前的版本升级,请参阅下面有关用于存储消费者偏移量的架构更改的注释。一旦您将 inter.broker.protocol.version 更改为最新版本,将无法降级到 2.1 之前的版本。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2、0.9.0、0.10.0、0.10.1、0.10.2、0.11.0、1.0、1.1)。
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(0.11.0、1.0、1.1、2.0)。
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。完成此操作后,代理将运行最新版本,您可以验证集群的行为和性能是否符合预期。如果出现任何问题,此时仍然可以降级。
- 验证集群的行为和性能后,通过编辑
inter.broker.protocol.version
并将其设置为 2.2 来提升协议版本。 - 一一重启broker,新协议版本即可生效。一旦代理开始使用最新的协议版本,就无法再将集群降级到旧版本。
- If you have overridden the message format version as instructed above, then you need to do one more rolling restart to upgrade it to its latest version. Once all (or most) consumers have been upgraded to 0.11.0 or later, change log.message.format.version to 2.2 on each broker and restart them one by one. Note that the older Scala clients, which are no longer maintained, do not support the message format introduced in 0.11, so to avoid conversion costs (or to take advantage of exactly once semantics), the newer Java clients must be used.
Notable changes in 2.2.1
- Kafka Streams 2.2.1 requires 0.11 message format or higher and does not work with older message format.
Notable changes in 2.2.0
- The default consumer group id has been changed from the empty string (
""
) tonull
. Consumers who use the new default group id will not be able to subscribe to topics, and fetch or commit offsets. The empty string as consumer group id is deprecated but will be supported until a future major release. Old clients that rely on the empty string group id will now have to explicitly provide it as part of their consumer config. For more information see KIP-289. - The
bin/kafka-topics.sh
command line tool is now able to connect directly to brokers with--bootstrap-server
instead of zookeeper. The old--zookeeper
option is still available for now. Please read KIP-377 for more information. - Kafka Streams depends on a newer version of RocksDBs that requires MacOS 10.13 or higher.
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, 1.0.x, 1.1.x, or 2.0.0 to 2.1.0
Note that 2.1.x contains a change to the internal schema used to store consumer offsets. Once the upgrade is complete, it will not be possible to downgrade to previous versions. See the rolling upgrade notes below for more detail.
For a rolling upgrade:
- Update server.properties on all brokers and add the following properties. CURRENT_KAFKA_VERSION refers to the version you
are upgrading from. CURRENT_MESSAGE_FORMAT_VERSION refers to the message format version currently in use. If you have previously
overridden the message format version, you should keep its current value. Alternatively, if you are upgrading from a version prior
to 0.11.0.x, then CURRENT_MESSAGE_FORMAT_VERSION should be set to match CURRENT_KAFKA_VERSION.
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g. 0.8.2, 0.9.0, 0.10.0, 0.10.1, 0.10.2, 0.11.0, 1.0, 1.1).
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION (See potential performance impact following the upgrade for the details on what this configuration does.)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (0.11.0, 1.0, 1.1, 2.0).
- Upgrade the brokers one at a time: shut down the broker, update the code, and restart it. Once you have done so, the brokers will be running the latest version and you can verify that the cluster's behavior and performance meets expectations. It is still possible to downgrade at this point if there are any problems.
- Once the cluster's behavior and performance has been verified, bump the protocol version by editing
inter.broker.protocol.version
and setting it to 2.1. - Restart the brokers one by one for the new protocol version to take effect. Once the brokers begin using the latest protocol version, it will no longer be possible to downgrade the cluster to an older version.
- If you have overridden the message format version as instructed above, then you need to do one more rolling restart to upgrade it to its latest version. Once all (or most) consumers have been upgraded to 0.11.0 or later, change log.message.format.version to 2.1 on each broker and restart them one by one. Note that the older Scala clients, which are no longer maintained, do not support the message format introduced in 0.11, so to avoid conversion costs (or to take advantage of exactly once semantics), the newer Java clients must be used.
Additional Upgrade Notes:
- Offset expiration semantics has slightly changed in this version. According to the new semantics, offsets of partitions in a group will not be removed while the group is subscribed to the corresponding topic and is still active (has active consumers). If group becomes empty all its offsets will be removed after default offset retention period (or the one set by broker) has passed (unless the group becomes active again). Offsets associated with standalone (simple) consumers, that do not use Kafka group management, will be removed after default offset retention period (or the one set by broker) has passed since their last commit.
- The default for console consumer's
enable.auto.commit
property when nogroup.id
is provided is now set tofalse
. This is to avoid polluting the consumer coordinator cache as the auto-generated group is not likely to be used by other consumers. - The default value for the producer's
retries
config was changed toInteger.MAX_VALUE
, as we introduceddelivery.timeout.ms
in KIP-91, which sets an upper bound on the total time between sending a record and receiving acknowledgement from the broker. By default, the delivery timeout is set to 2 minutes. - By default, MirrorMaker now overrides
delivery.timeout.ms
toInteger.MAX_VALUE
when configuring the producer. If you have overridden the value ofretries
in order to fail faster, you will instead need to overridedelivery.timeout.ms
. ListGroup
作为推荐的替代方案,API 现在期望访问Describe Group
用户应该能够列出的组。尽管Describe Cluster
仍支持旧的访问以实现向后兼容性,但不建议将其用于此 API。- KIP-336弃用了 ExtendedSerializer 和 ExtendedDeserializer 接口,并推广了 Serializer 和 Deserializer 的使用。ExtendedSerializer 和 ExtendedDeserializer 是随KIP-82引入的, 以 Java 7 兼容的方式为序列化器和反序列化器提供记录标头。现在我们整合了这些接口,因为 Java 7 支持已被删除。
2.1.0 中的显着变化
- Jetty 已升级到 9.4.12,默认情况下不包括 TLS_RSA_* 密码,因为它们不支持前向保密,有关更多信息,请参阅 https://github.com/eclipse/jetty.project/issues/2807。
unclean.leader.election.enable
当使用每个主题配置覆盖动态更新配置时,控制器会自动启用不干净的领导者选举。- 添加
AdminClient
了一个方法AdminClient#metrics()
。现在,任何使用 的应用程序都AdminClient
可以通过查看从 捕获的指标来获得更多信息和见解AdminClient
。欲了解更多信息,请参阅KIP-324 - Kafka 现在支持KIP-110的 Zstandard 压缩。您必须升级经纪商和客户端才能使用它。2.1.0 之前的消费者将无法读取使用 Zstandard 压缩的主题,因此在所有下游消费者升级之前,不应为主题启用它。有关更多详细信息,请参阅 KIP。
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, 1.0.x, or 1.1.x to 2.0.0
Kafka 2.0.0 引入了有线协议更改。通过遵循下面推荐的滚动升级计划,您可以保证升级期间不会出现停机。不过,请在升级之前查看2.0.0 中的显着变化。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2、0.9.0、0.10.0、0.10.1、0.10.2、0.11.0、1.0、1.1)。
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(0.11.0、1.0、1.1)。
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。
- 整个集群升级后,通过编辑
inter.broker.protocol.version
并将其设置为 2.0 来提升协议版本。 - 一一重启broker,新协议版本即可生效。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 2.0 并一一重新启动它们。请注意,较旧的 Scala 消费者不支持 0.11 中引入的新消息格式,因此为了避免下转换的性能成本(或利用恰好一次语义),必须使用较新的 Java 消费者。
附加升级说明:
- 如果您愿意接受停机,您可以简单地关闭所有代理,更新代码并重新启动它们。默认情况下,他们将从新协议开始。
- 升级代理后,可以随时更改协议版本并重新启动。它不一定是紧随其后。消息格式版本也类似。
- 如果您在 Kafka Streams 代码中使用 Java8 方法引用,您可能需要更新代码以解决方法歧义。仅热交换 jar 文件可能不起作用。
- 在更新集群中的所有代理之前,
不应将 ACL 添加到前缀资源(在KIP-290中添加)。
注意:如果集群再次降级,即使在集群完全升级之后,添加到集群的任何前缀 ACL 也将被忽略。
2.0.0 中的显着变化
- KIP-186将默认偏移量保留时间从 1 天增加到 7 天。这使得在不频繁提交的应用程序中“丢失”偏移量的可能性较小。它还会增加活动的偏移集,因此会增加代理上的内存使用量。请注意,控制台使用者当前默认启用偏移量提交,并且可能是大量偏移量的来源,此更改现在将保留 7 天而不是 1 天。您可以通过将代理配置设置为 1440 来保留现有行为
offsets.retention.minutes
。 - 对 Java 7 的支持已取消,Java 8 现在是所需的最低版本。
- 的默认值
ssl.endpoint.identification.algorithm
已更改为https
,它执行主机名验证(否则可能会发生中间人攻击)。设置ssl.endpoint.identification.algorithm
为空字符串以恢复之前的行为。 - KAFKA-5674 extends the lower interval of
max.connections.per.ip
minimum to zero and therefore allows IP-based filtering of inbound connections. - KIP-272
added API version tag to the metric
kafka.network:type=RequestMetrics,name=RequestsPerSec,request={Produce|FetchConsumer|FetchFollower|...}
. This metric now becomeskafka.network:type=RequestMetrics,name=RequestsPerSec,request={Produce|FetchConsumer|FetchFollower|...},version={0|1|2|3|...}
. This will impact JMX monitoring tools that do not automatically aggregate. To get the total count for a specific request type, the tool needs to be updated to aggregate across different versions. - KIP-225 changed the metric "records.lag" to use tags for topic and partition. The original version with the name format "{topic}-{partition}.records-lag" has been removed.
- The Scala consumers, which have been deprecated since 0.11.0.0, have been removed. The Java consumer has been the recommended option since 0.10.0.0. Note that the Scala consumers in 1.1.0 (and older) will continue to work even if the brokers are upgraded to 2.0.0.
- The Scala producers, which have been deprecated since 0.10.0.0, have been removed. The Java producer has been the recommended option since 0.9.0.0. Note that the behaviour of the default partitioner in the Java producer differs from the default partitioner in the Scala producers. Users migrating should consider configuring a custom partitioner that retains the previous behaviour. Note that the Scala producers in 1.1.0 (and older) will continue to work even if the brokers are upgraded to 2.0.0.
- MirrorMaker and ConsoleConsumer no longer support the Scala consumer, they always use the Java consumer.
- The ConsoleProducer no longer supports the Scala producer, it always uses the Java producer.
- A number of deprecated tools that rely on the Scala clients have been removed: ReplayLogProducer, SimpleConsumerPerformance, SimpleConsumerShell, ExportZkOffsets, ImportZkOffsets, UpdateOffsetsInZK, VerifyConsumerRebalance.
- The deprecated kafka.tools.ProducerPerformance has been removed, please use org.apache.kafka.tools.ProducerPerformance.
- New Kafka Streams configuration parameter
upgrade.from
added that allows rolling bounce upgrade from older version. - KIP-284 changed the retention time for Kafka Streams repartition topics by setting its default value to
Long.MAX_VALUE
. - Updated
ProcessorStateManager
APIs in Kafka Streams for registering state stores to the processor topology. For more details please read the Streams Upgrade Guide. -
In earlier releases, Connect's worker configuration required the
internal.key.converter
andinternal.value.converter
properties. In 2.0, these are no longer required and default to the JSON converter. You may safely remove these properties from your Connect standalone and distributed worker configurations:
internal.key.converter=org.apache.kafka.connect.json.JsonConverter
internal.key.converter.schemas.enable=false
internal.value.converter=org.apache.kafka.connect.json.JsonConverter
internal.value.converter.schemas.enable=false
- KIP-266添加了一个新的消费者配置
default.api.timeout.ms
,以指定用于可能阻塞的 API 的默认超时KafkaConsumer
。KIP 还为此类阻塞 API 添加了重载,以支持为每个 API 指定特定的超时,而不是使用default.api.timeout.ms
. 特别是,poll(Duration)
添加了一个新的 API,该 API 不会阻止动态分区分配。旧的poll(long)
API 已被弃用,并将在未来版本中删除。KafkaConsumer
还为其他方法添加了重载,例如partitionsFor
,listTopics
,offsetsForTimes
,beginningOffsets
,endOffsets
以及close
接受Duration
. - 另外,作为 KIP-266 的一部分,默认值
request.timeout.ms
已更改为 30 秒。考虑到重新平衡所需的最长时间,之前的值略高于 5 分钟。max.poll.interval.ms
现在,我们将重新平衡中的 JoinGroup 请求视为特殊情况,并使用从请求超时派生的值 。所有其他请求类型使用以下定义的超时request.timeout.ms
- 内部方法
kafka.admin.AdminClient.deleteRecordsBefore
已被删除。鼓励用户迁移到org.apache.kafka.clients.admin.AdminClient.deleteRecords
. - AclCommand 工具
--producer
便利选项在给定主题上使用KIP-277更细粒度的 ACL。 - KIP-176删除了
--new-consumer
所有基于消费者的工具的选项。此选项是多余的,因为如果定义了 --bootstrap-server,则会自动使用新的使用者。 - KIP-290添加了在前缀资源上定义 ACL 的能力,例如以“foo”开头的任何主题。
- KIP-283改进了 Kafka 代理上的消息下转换处理,这通常是一项内存密集型操作。KIP 添加了一种机制,通过一次向下转换分区数据块,操作会减少内存密集度,这有助于设定内存消耗的上限。通过这一改进,协议行为发生了变化
FetchResponse
,代理可以在响应结束时发送带有无效偏移量的超大消息批次。消费者客户端必须忽略此类过大的消息,就像KafkaConsumer
.KIP-283还添加了新的主题和代理配置
message.downconversion.enable
,log.message.downconversion.enable
分别控制是否启用下转换。禁用后,代理不会执行任何下转换,而是UNSUPPORTED_VERSION
向客户端发送错误。 - 在启动代理之前,可以使用 kafka-configs.sh 将动态代理配置选项存储在 ZooKeeper 中。此选项可用于避免在 server.properties 中存储明文密码,因为所有密码配置都可能以加密方式存储在 ZooKeeper 中。
- 如果连接尝试失败,ZooKeeper 主机现在会重新解析。但是,如果您的 ZooKeeper 主机名解析为多个地址,并且其中一些地址无法访问,那么您可能需要增加连接超时
zookeeper.connection.timeout.ms
。
新协议版本
- KIP-279:OffsetsForLeaderEpochResponse v1 引入了分区级
leader_epoch
字段。 - KIP-219:提高因配额违规而受到限制的非集群操作请求和响应的协议版本。
- KIP-290:提高 ACL 创建、描述和删除请求和响应的协议版本。
升级 1.1 Kafka Streams 应用程序
- 将 Streams 应用程序从 1.1 升级到 2.0 不需要代理升级。Kafka Streams 2.0 应用程序可以连接到 2.0、1.1、1.0、0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- 请注意,在 2.0 中,我们删除了 1.0 之前已弃用的公共 API;利用这些已弃用的 API 的用户需要相应地更改代码。有关更多详细信息,请参阅2.0.0 中的 Streams API 更改。
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x, 0.11.0.x, or 1.0.x to 1.1.x
Kafka 1.1.0 引入了有线协议更改。通过遵循下面推荐的滚动升级计划,您可以保证升级期间不会出现停机。不过,请在升级之前查看1.1.0 中的显着变化。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2、0.9.0、0.10.0、0.10.1、0.10.2、0.11.0、1.0)。
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(0.11.0 或 1.0)。
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。
- 整个集群升级后,通过编辑
inter.broker.protocol.version
并将其设置为 1.1 来提升协议版本。 - 一一重启broker,新协议版本即可生效。
- If you have overridden the message format version as instructed above, then you need to do one more rolling restart to upgrade it to its latest version. Once all (or most) consumers have been upgraded to 0.11.0 or later, change log.message.format.version to 1.1 on each broker and restart them one by one. Note that the older Scala consumer does not support the new message format introduced in 0.11, so to avoid the performance cost of down-conversion (or to take advantage of exactly once semantics), the newer Java consumer must be used.
Additional Upgrade Notes:
- If you are willing to accept downtime, you can simply take all the brokers down, update the code and start them back up. They will start with the new protocol by default.
- Bumping the protocol version and restarting can be done any time after the brokers are upgraded. It does not have to be immediately after. Similarly for the message format version.
- If you are using Java8 method references in your Kafka Streams code you might need to update your code to resolve method ambiguties. Hot-swapping the jar-file only might not work.
Notable changes in 1.1.1
- New Kafka Streams configuration parameter
upgrade.from
added that allows rolling bounce upgrade from version 0.10.0.x - See the Kafka Streams upgrade guide for details about this new config.
Notable changes in 1.1.0
- The kafka artifact in Maven no longer depends on log4j or slf4j-log4j12. Similarly to the kafka-clients artifact, users can now choose the logging back-end by including the appropriate slf4j module (slf4j-log4j12, logback, etc.). The release tarball still includes log4j and slf4j-log4j12.
- KIP-225 changed the metric "records.lag" to use tags for topic and partition. The original version with the name format "{topic}-{partition}.records-lag" is deprecated and will be removed in 2.0.0.
- Kafka Streams is more robust against broker communication errors. Instead of stopping the Kafka Streams client with a fatal exception,
Kafka Streams tries to self-heal and reconnect to the cluster. Using the new
AdminClient
you have better control of how often Kafka Streams retries and can configure fine-grained timeouts (instead of hard coded retries as in older version). - Kafka Streams rebalance time was reduced further making Kafka Streams more responsive.
- Kafka Connect now supports message headers in both sink and source connectors, and to manipulate them via simple message transforms. Connectors must be changed to explicitly use them. A new
HeaderConverter
is introduced to control how headers are (de)serialized, and the new "SimpleHeaderConverter" is used by default to use string representations of values. - 如果由于解码器等任何其他选项而显式或隐式启用打印数据日志,kafka.tools.DumpLogSegments 现在会自动设置深度迭代选项。
新协议版本
升级 1.0 Kafka Streams 应用程序
- 将 Streams 应用程序从 1.0 升级到 1.1 不需要代理升级。Kafka Streams 1.1 应用程序可以连接到 1.0、0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- 有关更多详细信息,请参阅1.1.0 中的 Streams API 更改。
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x, 0.10.2.x or 0.11.0.x to 1.0.0
Kafka 1.0.0 引入了有线协议更改。通过遵循下面推荐的滚动升级计划,您可以保证升级期间不会出现停机。不过,请在升级之前查看1.0.0 中的显着变化。
对于滚动升级:
- 更新所有代理上的 server.properties 并添加以下属性。CURRENT_KAFKA_VERSION 是指您要升级的版本。CURRENT_MESSAGE_FORMAT_VERSION 指当前使用的消息格式版本。如果您之前已覆盖消息格式版本,则应保留其当前值。或者,如果您要从 0.11.0.x 之前的版本升级,则应将 CURRENT_MESSAGE_FORMAT_VERSION 设置为与 CURRENT_KAFKA_VERSION 匹配。
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2、0.9.0、0.10.0、0.10.1、0.10.2、0.11.0)。
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION(有关此配置的详细信息,请参阅升级后的潜在性能影响。)
- inter.broker.protocol.version=0.11.0
- log.message.format.version=0.11.0
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。
- 整个集群升级后,通过编辑
inter.broker.protocol.version
并将其设置为 1.0 来提升协议版本。 - 一一重启broker,新协议版本即可生效。
- 如果您已按照上述说明覆盖消息格式版本,则需要再进行一次滚动重启才能将其升级到最新版本。一旦所有(或大多数)消费者升级到 0.11.0 或更高版本,将每个代理上的 log.message.format.version 更改为 1.0 并一一重新启动它们。如果您从 0.11.0 升级并且 log.message.format.version 设置为 0.11.0,则可以更新配置并跳过滚动重启。请注意,较旧的 Scala 消费者不支持 0.11 中引入的新消息格式,因此为了避免下转换的性能成本(或利用恰好一次语义),必须使用较新的 Java 消费者。
附加升级说明:
- 如果您愿意接受停机,您可以简单地关闭所有代理,更新代码并重新启动它们。默认情况下,他们将从新协议开始。
- 升级代理后,可以随时更改协议版本并重新启动。它不一定是紧随其后。消息格式版本也类似。
1.0.2 中的显着变化
- 添加了新的 Kafka Streams 配置参数
upgrade.from
,允许从版本 0.10.0.x 滚动弹跳升级 - 有关此新配置的详细信息, 请参阅Kafka Streams 升级指南。
1.0.1 中的显着变化
- 恢复了 AdminClient 的选项类(例如 CreateTopicsOptions、DeleteTopicsOptions 等)与 0.11.0.x 的二进制兼容性。二进制(但不是源代码)兼容性在 1.0.0 中被无意中破坏。
1.0.0 中的显着变化
- 现在默认启用主题删除,因为该功能现已稳定。希望保留以前行为的用户应将代理配置设置
delete.topic.enable
为false
。请记住,主题删除会删除数据,并且该操作是不可逆的(即不存在“取消删除”操作) - 对于支持时间戳搜索的主题,如果找不到分区的偏移量,则该分区现在包含在搜索结果中,且偏移量值为空。以前,分区不包含在地图中。进行此更改是为了使搜索行为与不支持时间戳搜索的主题的情况一致。
- 如果
inter.broker.protocol.version
是 1.0 或更高版本,即使存在脱机日志目录,代理现在也将保持在线状态以在实时日志目录上提供副本。由于硬件故障引起的IOException,日志目录可能会离线。用户需要监控每个broker的指标offlineLogDirectoryCount
来检查是否存在离线日志目录。 - 添加了 KafkaStorageException,这是一个可重试的异常。如果客户端的FetchRequest或ProducerRequest的版本不支持KafkaStorageException,则响应中的KafkaStorageException将转换为NotLeaderForPartitionException。
- -XX:+DisableExplicitGC was replaced by -XX:+ExplicitGCInvokesConcurrent in the default JVM settings. This helps avoid out of memory exceptions during allocation of native memory by direct buffers in some cases.
- The overridden
handleError
method implementations have been removed from the following deprecated classes in thekafka.api
package:FetchRequest
,GroupCoordinatorRequest
,OffsetCommitRequest
,OffsetFetchRequest
,OffsetRequest
,ProducerRequest
, andTopicMetadataRequest
. This was only intended for use on the broker, but it is no longer in use and the implementations have not been maintained. A stub implementation has been retained for binary compatibility. - The Java clients and tools now accept any string as a client-id.
- The deprecated tool
kafka-consumer-offset-checker.sh
has been removed. Usekafka-consumer-groups.sh
to get consumer group details. - SimpleAclAuthorizer now logs access denials to the authorizer log by default.
- Authentication failures are now reported to clients as one of the subclasses of
AuthenticationException
. No retries will be performed if a client connection fails authentication. - Custom
SaslServer
implementations may throwSaslAuthenticationException
to provide an error message to return to clients indicating the reason for authentication failure. Implementors should take care not to include any security-critical information in the exception message that should not be leaked to unauthenticated clients. - The
app-info
mbean registered with JMX to provide version and commit id will be deprecated and replaced with metrics providing these attributes. - Kafka metrics may now contain non-numeric values.
org.apache.kafka.common.Metric#value()
has been deprecated and will return0.0
in such cases to minimise the probability of breaking users who read the value of every client metric (via aMetricsReporter
implementation or by calling themetrics()
method).org.apache.kafka.common.Metric#metricValue()
can be used to retrieve numeric and non-numeric metric values. - Every Kafka rate metric now has a corresponding cumulative count metric with the suffix
-total
to simplify downstream processing. For example,records-consumed-rate
has a corresponding metric namedrecords-consumed-total
. - Mx4j will only be enabled if the system property
kafka_mx4jenable
is set totrue
. Due to a logic inversion bug, it was previously enabled by default and disabled ifkafka_mx4jenable
was set totrue
. - The package
org.apache.kafka.common.security.auth
in the clients jar has been made public and added to the javadocs. Internal classes which had previously been located in this package have been moved elsewhere. - 当使用授权者并且用户没有主题所需的权限时,代理将向请求返回 TOPIC_AUTHORIZATION_FAILED 错误,无论代理上是否存在主题。如果用户具有所需的权限并且主题不存在,则将返回 UNKNOWN_TOPIC_OR_PARTITION 错误代码。
- config/consumer.properties 文件已更新以使用新的消费者配置属性。
新协议版本
- KIP-112:LeaderAndIsrRequest v1 引入了分区级
is_new
字段。 - KIP-112:UpdateMetadataRequest v4 引入了分区级
offline_replicas
字段。 - KIP-112:MetadataResponse v5 引入了分区级
offline_replicas
字段。 - KIP-112:ProduceResponse v4 引入了 KafkaStorageException 的错误代码。
- KIP-112:FetchResponse v6 引入了 KafkaStorageException 的错误代码。
- KIP-152:添加了 SaslAuthenticate 请求以启用身份验证失败报告。如果 SaslHandshake 请求版本大于 0,则将使用此请求。
升级 0.11.0 Kafka Streams 应用程序
- 将 Streams 应用程序从 0.11.0 升级到 1.0 不需要代理升级。Kafka Streams 1.0 应用程序可以连接到 0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。但是,Kafka Streams 1.0 需要 0.10 消息格式或更新版本,并且不适用于较旧的消息格式。
- 如果您正在监视流指标,则需要对报告和监视代码中的指标名称进行一些更改,因为指标传感器层次结构已更改。
- 有一些公共 API,包括
ProcessorContext#schedule()
、Processor#punctuate()
和KStreamBuilder
,TopologyBuilder
已被新 API 弃用。我们建议您在升级时进行相应的代码更改,这些更改应该非常小,因为新的 API 看起来非常相似。 - 有关更多详细信息,请参阅1.0.0 中的 Streams API 更改。
升级 0.10.2 Kafka Streams 应用程序
- 将 Streams 应用程序从 0.10.2 升级到 1.0 不需要代理升级。Kafka Streams 1.0 应用程序可以连接到 1.0、0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- 如果您正在监视流指标,则需要对报告和监视代码中的指标名称进行一些更改,因为指标传感器层次结构已更改。
- 有一些公共 API,包括
ProcessorContext#schedule()
、Processor#punctuate()
和KStreamBuilder
,TopologyBuilder
已被新 API 弃用。我们建议您在升级时进行相应的代码更改,这些更改应该非常小,因为新的 API 看起来非常相似。 - 如果您在配置中指定了customized
key.serde
,value.serde
和timestamp.extractor
,建议使用它们替换的配置参数,因为这些配置已被弃用。 - 有关更多详细信息,请参阅0.11.0 中的 Streams API 更改。
升级 0.10.1 Kafka Streams 应用程序
- 将 Streams 应用程序从 0.10.1 升级到 1.0 不需要代理升级。Kafka Streams 1.0 应用程序可以连接到 1.0、0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- 您需要重新编译您的代码。仅交换 Kafka Streams 库 jar 文件是行不通的,并且会破坏您的应用程序。
- 如果您正在监视流指标,则需要对报告和监视代码中的指标名称进行一些更改,因为指标传感器层次结构已更改。
- 有一些公共 API,包括
ProcessorContext#schedule()
、Processor#punctuate()
和KStreamBuilder
,TopologyBuilder
已被新 API 弃用。我们建议您在升级时进行相应的代码更改,这些更改应该非常小,因为新的 API 看起来非常相似。 - 如果您在配置中指定了customized
key.serde
,value.serde
和timestamp.extractor
,建议使用它们替换的配置参数,因为这些配置已被弃用。 - 如果您使用自定义(即用户实现的)时间戳提取器,您将需要更新此代码,因为接口
TimestampExtractor
已更改。 - 如果您注册自定义指标,则需要更新此代码,因为
StreamsMetric
界面已更改。 - 有关更多详细信息,请参阅1.0.0 中的 Streams API 更改、 0.11.0 中的 Streams API 更改和 0.10.2 中的 Streams API 更改。
升级 0.10.0 Kafka Streams 应用程序
- 将 Streams 应用程序从 0.10.0 升级到 1.0 确实需要代理升级,因为 Kafka Streams 1.0 应用程序只能连接到 0.1、0.11.0、0.10.2 或 0.10.1 代理。
- 有一些 API 更改不向后兼容(请参阅1.0.0 中的 Streams API 更改、 0.11.0 中的 Streams API 更改、 0.10.2 中的 Streams API 更改和 0.10.1 中的 Streams API 更改了解更多详细信息)。因此,您需要更新并重新编译代码。仅交换 Kafka Streams 库 jar 文件是行不通的,并且会破坏您的应用程序。
- 从 0.10.0.x 升级到 1.0.2 需要两次滚动反弹,并
upgrade.from="0.10.0"
为第一个升级阶段设置配置(参见KIP-268)。作为替代方案,也可以进行离线升级。- 准备应用程序实例以进行滚动反弹,并确保将配置
upgrade.from
设置"0.10.0"
为新版本 0.11.0.3 - 将应用程序的每个实例退回一次
- 为新部署的 1.0.2 应用程序实例做好第二轮滚动跳出的准备;确保删除 config 的值
upgrade.from
- 再次弹跳应用程序的每个实例以完成升级
- 准备应用程序实例以进行滚动反弹,并确保将配置
- 从0.10.0.x升级到1.0.0或1.0.1需要离线升级(不支持滚动弹跳升级)
- 停止所有旧的(0.10.0.x)应用程序实例
- 更新您的代码并将旧代码和 jar 文件替换为新代码和新 jar 文件
- restart all new (1.0.0 or 1.0.1) application instances
Upgrading from 0.8.x, 0.9.x, 0.10.0.x, 0.10.1.x or 0.10.2.x to 0.11.0.0
Kafka 0.11.0.0 introduces a new message format version as well as wire protocol changes. By following the recommended rolling upgrade plan below, you guarantee no downtime during the upgrade. However, please review the notable changes in 0.11.0.0 before upgrading.
Starting with version 0.10.2, Java clients (producer and consumer) have acquired the ability to communicate with older brokers. Version 0.11.0 clients can talk to version 0.10.0 or newer brokers. However, if your brokers are older than 0.10.0, you must upgrade all the brokers in the Kafka cluster before upgrading your clients. Version 0.11.0 brokers support 0.8.x and newer clients.
For a rolling upgrade:
- Update server.properties on all brokers and add the following properties. CURRENT_KAFKA_VERSION refers to the version you
are upgrading from. CURRENT_MESSAGE_FORMAT_VERSION refers to the current message format version currently in use. If you have
not overridden the message format previously, then CURRENT_MESSAGE_FORMAT_VERSION should be set to match CURRENT_KAFKA_VERSION.
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g. 0.8.2, 0.9.0, 0.10.0, 0.10.1 or 0.10.2).
- log.message.format.version=CURRENT_MESSAGE_FORMAT_VERSION (See potential performance impact following the upgrade for the details on what this configuration does.)
- Upgrade the brokers one at a time: shut down the broker, update the code, and restart it.
- Once the entire cluster is upgraded, bump the protocol version by editing
inter.broker.protocol.version
and setting it to 0.11.0, but do not changelog.message.format.version
yet. - Restart the brokers one by one for the new protocol version to take effect.
- Once all (or most) consumers have been upgraded to 0.11.0 or later, then change log.message.format.version to 0.11.0 on each broker and restart them one by one. Note that the older Scala consumer does not support the new message format, so to avoid the performance cost of down-conversion (or to take advantage of exactly once semantics), the new Java consumer must be used.
Additional Upgrade Notes:
- If you are willing to accept downtime, you can simply take all the brokers down, update the code and start them back up. They will start with the new protocol by default.
- Bumping the protocol version and restarting can be done any time after the brokers are upgraded. It does not have to be immediately after. Similarly for the message format version.
- It is also possible to enable the 0.11.0 message format on individual topics using the topic admin tool (
bin/kafka-topics.sh
) prior to updating the global settinglog.message.format.version
. - If you are upgrading from a version prior to 0.10.0, it is NOT necessary to first update the message format to 0.10.0 before you switch to 0.11.0.
Upgrading a 0.10.2 Kafka Streams Application
- 将 Streams 应用程序从 0.10.2 升级到 0.11.0 不需要代理升级。Kafka Streams 0.11.0 应用程序可以连接到 0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- 如果您在配置中指定了customized
key.serde
,value.serde
和timestamp.extractor
,建议使用它们替换的配置参数,因为这些配置已被弃用。 - 有关更多详细信息,请参阅0.11.0 中的 Streams API 更改。
升级 0.10.1 Kafka Streams 应用程序
- 将 Streams 应用程序从 0.10.1 升级到 0.11.0 不需要代理升级。Kafka Streams 0.11.0 应用程序可以连接到 0.11.0、0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- 您需要重新编译您的代码。仅交换 Kafka Streams 库 jar 文件是行不通的,并且会破坏您的应用程序。
- 如果您在配置中指定了customized
key.serde
,value.serde
和timestamp.extractor
,建议使用它们替换的配置参数,因为这些配置已被弃用。 - 如果您使用自定义(即用户实现的)时间戳提取器,您将需要更新此代码,因为接口
TimestampExtractor
已更改。 - 如果您注册自定义指标,则需要更新此代码,因为
StreamsMetric
界面已更改。 - 有关更多详细信息,请参阅0.11.0 中的 Streams API 更改和 0.10.2 中的 Streams API 更改。
升级 0.10.0 Kafka Streams 应用程序
- 将 Streams 应用程序从 0.10.0 升级到 0.11.0 确实需要代理升级,因为 Kafka Streams 0.11.0 应用程序只能连接到 0.11.0、0.10.2 或 0.10.1 代理。
- 有一些 API 更改不向后兼容(请参阅0.11.0 中的 Streams API 更改、 0.10.2 中的 Streams API 更改和 0.10.1 中的 Streams API 更改以了解更多详细信息)。因此,您需要更新并重新编译代码。仅交换 Kafka Streams 库 jar 文件是行不通的,并且会破坏您的应用程序。
- 从 0.10.0.x 升级到 0.11.0.3 需要两次滚动反弹,并
upgrade.from="0.10.0"
为第一个升级阶段设置配置(参见KIP-268)。作为替代方案,也可以进行离线升级。- 准备应用程序实例以进行滚动反弹,并确保将配置
upgrade.from
设置"0.10.0"
为新版本 0.11.0.3 - 将应用程序的每个实例退回一次
- 准备新部署的 0.11.0.3 应用程序实例以进行第二轮滚动反弹;确保删除 config 的值
upgrade.from
- 再次弹跳应用程序的每个实例以完成升级
- 准备应用程序实例以进行滚动反弹,并确保将配置
- 从0.10.0.x升级到0.11.0.0、0.11.0.1或0.11.0.2需要离线升级(不支持滚动弹跳升级)
- 停止所有旧的(0.10.0.x)应用程序实例
- 更新您的代码并将旧代码和 jar 文件替换为新代码和新 jar 文件
- 重新启动所有新的(0.11.0.0、0.11.0.1 或 0.11.0.2)应用程序实例
0.11.0.3 中的显着变化
- 添加了新的 Kafka Streams 配置参数
upgrade.from
,允许从版本 0.10.0.x 滚动弹跳升级 - 有关此新配置的详细信息, 请参阅Kafka Streams 升级指南。
0.11.0.0 中的显着变化
- 现在默认禁用不干净的领导者选举。新的默认设置更注重持久性而不是可用性。希望保留以前行为的用户应将代理配置设置
unclean.leader.election.enable
为true
。 - 生产者配置
block.on.buffer.full
和metadata.fetch.timeout.ms
已timeout.ms
被删除。它们最初在 Kafka 0.9.0.0 中被弃用。 offsets.topic.replication.factor
现在,在自动创建主题时强制执行代理配置。内部自动主题创建将失败并出现 GROUP_COORDINATOR_NOT_AVAILABLE 错误,直到集群大小满足此复制因子要求。- 使用 snappy 压缩数据时,生产者和代理将使用压缩方案的默认块大小 (2 x 32 KB) 而不是 1 KB,以提高压缩率。有报告称,使用较小块大小压缩的数据比使用较大块大小压缩时大 50%。对于快速的情况,具有 5000 个分区的生产者将需要额外的 315 MB JVM 堆。
- 同样,当使用 gzip 压缩数据时,生产者和代理将使用 8 KB 而不是 1 KB 作为缓冲区大小。gzip 的默认值过低(512 字节)。
- 代理配置
max.message.bytes
现在适用于一批消息的总大小。以前,该设置应用于批量压缩消息,或单独应用于非压缩消息。消息批可能仅包含单个消息,因此在大多数情况下,对单个消息的大小的限制仅通过批处理格式的开销来减少。然而,消息格式转换有一些微妙的含义(更多详细信息请参见下文)。另请注意,虽然以前代理将确保每个提取请求中至少返回一条消息(无论总提取大小和分区级别提取大小如何),但现在相同的行为适用于一批消息。 - 默认启用 GC 日志轮换,详细信息请参阅 KAFKA-3754。
- RecordMetadata、MetricName 和 Cluster 类已弃用的构造函数已被删除。
- 通过提供用户标头读写访问的新标头接口添加了用户标头支持。
Headers headers()
ProducerRecord 和 ConsumerRecord 通过方法调用公开新的 Headers API 。- 引入了 ExtendedSerializer 和 ExtendedDeserializer 接口来支持标头的序列化和反序列化。如果配置的序列化器和反序列化器不是上述类,则标头将被忽略。
group.initial.rebalance.delay.ms
引入了新配置。GroupCoordinator
此配置指定延迟初始消费者重新平衡的时间(以毫秒为单位) 。当新成员加入该组时,重新平衡将进一步延迟 的值group.initial.rebalance.delay.ms
,最多为max.poll.interval.ms
。默认值为 3 秒。在开发和测试期间,可能需要将其设置为 0,以免延迟测试执行时间。org.apache.kafka.common.Cluster#partitionsForTopic
,partitionsForNode
并且availablePartitionsForTopic
方法将返回一个空列表null
(这被认为是一种不好的做法),以防所需主题的元数据不存在。- Streams API 配置参数
timestamp.extractor
、key.serde
和value.serde
已弃用并分别替换为default.timestamp.extractor
、default.key.serde
和default.value.serde
。 - 对于 Java 使用者 API 中的偏移提交失败,当 的实例传递给提交回调
commitAsync
时,我们不再公开根本原因。 有关更多详细信息,RetriableCommitFailedException
请参阅 KAFKA-5052 。
新协议版本
- KIP-107:FetchRequest v5 引入了分区级
log_start_offset
字段。 - KIP-107:FetchResponse v5 引入了分区级
log_start_offset
字段。 - KIP-82
header
:ProduceRequest v3在消息协议中引入了一个数组,包含key
field和value
field。 - KIP-82
header
:FetchResponse v5在消息协议中引入了一个数组,包含key
字段和value
字段。
关于 Exactly Once 语义的注释
Kafka 0.11.0 支持生产者中的幂等和事务功能。幂等传递可确保在单个生产者的生命周期内将消息恰好传递到特定主题分区一次。事务传递允许生产者将数据发送到多个分区,以便所有消息都成功传递,或者没有消息成功传递。这些功能共同实现了 Kafka 中的“恰好一次语义”。用户指南中提供了有关这些功能的更多详细信息,但下面我们添加了一些有关在升级的集群中启用这些功能的具体说明。请注意,启用 EoS 不是必需的,并且如果不使用,也不会影响代理的行为。
- 只有新的 Java 生产者和消费者支持 Exactly Once 语义。
- 这些功能主要取决于0.11.0 消息格式。尝试在旧格式上使用它们将导致版本不受支持的错误。
- Transaction state is stored in a new internal topic
__transaction_state
. This topic is not created until the the first attempt to use a transactional request API. Similar to the consumer offsets topic, there are several settings to control the topic's configuration. For example,transaction.state.log.min.isr
controls the minimum ISR for this topic. See the configuration section in the user guide for a full list of options. - For secure clusters, the transactional APIs require new ACLs which can be turned on with the
bin/kafka-acls.sh
. tool. - EoS in Kafka introduces new request APIs and modifies several existing ones. See KIP-98 for the full details
Notes on the new message format in 0.11.0
The 0.11.0 message format includes several major enhancements in order to support better delivery semantics for the producer (see KIP-98) and improved replication fault tolerance (see KIP-101). Although the new format contains more information to make these improvements possible, we have made the batch format much more efficient. As long as the number of messages per batch is more than 2, you can expect lower overall overhead. For smaller batches, however, there may be a small performance impact. See here for the results of our initial performance analysis of the new message format. You can also find more detail on the message format in the KIP-98 proposal.
One of the notable differences in the new message format is that even uncompressed messages are stored together as a single batch.
This has a few implications for the broker configuration max.message.bytes
, which limits the size of a single batch. First,
if an older client produces messages to a topic partition using the old format, and the messages are individually smaller than
max.message.bytes
, the broker may still reject them after they are merged into a single batch during the up-conversion process.
Generally this can happen when the aggregate size of the individual messages is larger than max.message.bytes
. There is a similar
effect for older consumers reading messages down-converted from the new format: if the fetch size is not set at least as large as
max.message.bytes
, the consumer may not be able to make progress even if the individual uncompressed messages are smaller
than the configured fetch size. This behavior does not impact the Java client for 0.10.1.0 and later since it uses an updated fetch protocol
which ensures that at least one message can be returned even if it exceeds the fetch size. To get around these problems, you should ensure
1) that the producer's batch size is not set larger than max.message.bytes
, and 2) that the consumer's fetch size is set at
least as large as max.message.bytes
.
Most of the discussion on the performance impact of upgrading to the 0.10.0 message format remains pertinent to the 0.11.0 upgrade. This mainly affects clusters that are not secured with TLS since "zero-copy" transfer is already not possible in that case. In order to avoid the cost of down-conversion, you should ensure that consumer applications are upgraded to the latest 0.11.0 client. Significantly, since the old consumer has been deprecated in 0.11.0.0, it does not support the new message format. You must upgrade to use the new consumer to use the new message format without the cost of down-conversion. Note that 0.11.0 consumers support backwards compatibility with 0.10.0 brokers and upward, so it is possible to upgrade the clients first before the brokers.
Upgrading from 0.8.x, 0.9.x, 0.10.0.x or 0.10.1.x to 0.10.2.0
0.10.2.0 has wire protocol changes. By following the recommended rolling upgrade plan below, you guarantee no downtime during the upgrade. However, please review the notable changes in 0.10.2.0 before upgrading.
Starting with version 0.10.2, Java clients (producer and consumer) have acquired the ability to communicate with older brokers. Version 0.10.2 clients can talk to version 0.10.0 or newer brokers. However, if your brokers are older than 0.10.0, you must upgrade all the brokers in the Kafka cluster before upgrading your clients. Version 0.10.2 brokers support 0.8.x and newer clients.
For a rolling upgrade:
- Update server.properties file on all brokers and add the following properties:
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION (e.g. 0.8.2, 0.9.0, 0.10.0 or 0.10.1).
- log.message.format.version=CURRENT_KAFKA_VERSION (See potential performance impact following the upgrade for the details on what this configuration does.)
- Upgrade the brokers one at a time: shut down the broker, update the code, and restart it.
- Once the entire cluster is upgraded, bump the protocol version by editing inter.broker.protocol.version and setting it to 0.10.2.
- If your previous message format is 0.10.0, change log.message.format.version to 0.10.2 (this is a no-op as the message format is the same for 0.10.0, 0.10.1 and 0.10.2). If your previous message format version is lower than 0.10.0, do not change log.message.format.version yet - this parameter should only change once all consumers have been upgraded to 0.10.0.0 or later.
- Restart the brokers one by one for the new protocol version to take effect.
- If log.message.format.version is still lower than 0.10.0 at this point, wait until all consumers have been upgraded to 0.10.0 or later, then change log.message.format.version to 0.10.2 on each broker and restart them one by one.
Note: If you are willing to accept downtime, you can simply take all the brokers down, update the code and start all of them. They will start with the new protocol by default.
Note: Bumping the protocol version and restarting can be done any time after the brokers were upgraded. It does not have to be immediately after.
Upgrading a 0.10.1 Kafka Streams Application
- Upgrading your Streams application from 0.10.1 to 0.10.2 does not require a broker upgrade. A Kafka Streams 0.10.2 application can connect to 0.10.2 and 0.10.1 brokers (it is not possible to connect to 0.10.0 brokers though).
- You need to recompile your code. Just swapping the Kafka Streams library jar file will not work and will break your application.
- If you use a custom (i.e., user implemented) timestamp extractor, you will need to update this code, because the
TimestampExtractor
interface was changed. - If you register custom metrics, you will need to update this code, because the
StreamsMetric
interface was changed. - See Streams API changes in 0.10.2 for more details.
Upgrading a 0.10.0 Kafka Streams Application
- Upgrading your Streams application from 0.10.0 to 0.10.2 does require a broker upgrade because a Kafka Streams 0.10.2 application can only connect to 0.10.2 or 0.10.1 brokers.
- There are couple of API changes, that are not backward compatible (cf. Streams API changes in 0.10.2 for more details). Thus, you need to update and recompile your code. Just swapping the Kafka Streams library jar file will not work and will break your application.
- Upgrading from 0.10.0.x to 0.10.2.2 requires two rolling bounces with config
upgrade.from="0.10.0"
set for first upgrade phase (cf. KIP-268). As an alternative, an offline upgrade is also possible.- prepare your application instances for a rolling bounce and make sure that config
upgrade.from
is set to"0.10.0"
for new version 0.10.2.2 - bounce each instance of your application once
- prepare your newly deployed 0.10.2.2 application instances for a second round of rolling bounces; make sure to remove the value for config
upgrade.from
- bounce each instance of your application once more to complete the upgrade
- prepare your application instances for a rolling bounce and make sure that config
- Upgrading from 0.10.0.x to 0.10.2.0 or 0.10.2.1 requires an offline upgrade (rolling bounce upgrade is not supported)
- stop all old (0.10.0.x) application instances
- update your code and swap old code and jar file with new code and new jar file
- restart all new (0.10.2.0 or 0.10.2.1) application instances
Notable changes in 0.10.2.2
- New configuration parameter
upgrade.from
added that allows rolling bounce upgrade from version 0.10.0.x
Notable changes in 0.10.2.1
- StreamsConfig 类的两个配置的默认值已更改,以提高 Kafka Streams 应用程序的弹性。内部 Kafka Streams 生产者
retries
默认值从 0 更改为 10。内部 Kafka Streams 消费者max.poll.interval.ms
默认值从 300000 更改为Integer.MAX_VALUE
。
0.10.2.0 中的显着变化
- Java 客户端(生产者和消费者)已经获得了与旧代理进行通信的能力。版本 0.10.2 客户端可以与版本 0.10.0 或更高版本的代理进行通信。请注意,使用较旧的代理时,某些功能不可用或受到限制。
InterruptException
如果调用线程被中断,Java 使用者上的多个方法现在可能会抛出异常。请参阅KafkaConsumer
Javadoc 以获取有关此更改的更深入的说明。- Java 消费者现在正常关闭。默认情况下,使用者最多等待 30 秒才能完成待处理的请求。添加了一个带有超时的新关闭 API
KafkaConsumer
以控制最大等待时间。 - 可以通过 --whitelist 选项将多个以逗号分隔的正则表达式传递给新 Java 使用者的 MirrorMaker。这使得使用旧的 Scala 消费者时的行为与 MirrorMaker 一致。
- 将 Streams 应用程序从 0.10.1 升级到 0.10.2 不需要代理升级。Kafka Streams 0.10.2 应用程序可以连接到 0.10.2 和 0.10.1 代理(但无法连接到 0.10.0 代理)。
- Zookeeper 依赖项已从 Streams API 中删除。Streams API现在使用Kafka协议来管理内部主题,而不是直接修改Zookeeper。这消除了直接访问 Zookeeper 的权限的需要,并且不应再在 Streams 应用程序中设置“StreamsConfig.ZOOKEEPER_CONFIG”。如果 Kafka 集群受到保护,Streams 应用程序必须具有创建新主题所需的安全权限。
- StreamsConfig 类中添加了几个新字段,包括“security.protocol”、“connections.max.idle.ms”、“retry.backoff.ms”、“reconnect.backoff.ms”和“request.timeout.ms”。用户应注意默认值并根据需要进行设置。更多详细信息请参考3.5 Kafka Streams配置。
新协议版本
- KIP-88
topics
:如果数组设置为 ,OffsetFetchRequest v2 支持检索所有主题的偏移量null
。 - KIP-88:OffsetFetchResponse v2 引入了一个顶级
error_code
字段。 - KIP-103:UpdateMetadataRequest v3
listener_name
向数组元素引入了一个字段end_points
。 - KIP-108:CreateTopicsRequest v1 引入了一个
validate_only
字段。 - KIP-108:CreateTopicsResponse v1
error_message
向数组元素引入了一个字段topic_errors
。
Upgrading from 0.8.x, 0.9.x or 0.10.0.X to 0.10.1.0
0.10.1.0 进行了有线协议更改。通过遵循下面推荐的滚动升级计划,您可以保证升级期间不会出现停机。但是,请在升级之前注意0.10.1.0 中的潜在重大更改。注意:由于引入了新协议,因此在升级客户端之前升级 Kafka 集群非常重要(即 0.10.1.x 客户端仅支持 0.10.1.x 或更高版本的代理,而 0.10.1.x 代理也支持旧客户端) 。
对于滚动升级:
- 更新所有代理上的 server.properties 文件并添加以下属性:
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2.0、0.9.0.0或0.10.0.0)。
- log.message.format.version=CURRENT_KAFKA_VERSION(有关此配置的详细信息, 请参阅升级后的潜在性能影响。)
- 一次升级一个代理:关闭代理,更新代码,然后重新启动。
- 整个集群升级后,通过编辑 inter.broker.protocol.version 并将其设置为 0.10.1.0 来提升协议版本。
- 如果您以前的消息格式是 0.10.0,请将 log.message.format.version 更改为 0.10.1(这是无操作,因为 0.10.0 和 0.10.1 的消息格式相同)。如果您之前的消息格式版本低于 0.10.0,请不要更改 log.message.format.version - 只有在所有使用者升级到 0.10.0.0 或更高版本后,此参数才应更改。
- 一一重启broker,新协议版本即可生效。
- 如果此时 log.message.format.version 仍然低于 0.10.0,请等到所有消费者都升级到 0.10.0 或更高版本,然后在每个代理上将 log.message.format.version 更改为 0.10.1 并将它们一一重新启动。
注意:如果您愿意接受停机,您只需关闭所有代理,更新代码并启动所有代理即可。默认情况下,他们将从新协议开始。
注意:在代理升级后,可以随时更改协议版本并重新启动。它不一定是紧随其后。
0.10.1.2 中的显着变化
- 添加了新的配置参数
upgrade.from
,允许从版本 0.10.0.x 滚动弹跳升级
0.10.1.0 中潜在的重大变化
- 日志保留时间不再基于日志段的最后修改时间。相反,它将基于日志段中消息的最大时间戳。
- 日志滚动时间不再取决于日志段创建时间。相反,它现在基于消息中的时间戳。进一步来说。如果段中第一条消息的时间戳为T,则当新消息的时间戳大于或等于T + log.roll.ms时,日志将被转出
- The open file handlers of 0.10.0 will increase by ~33% because of the addition of time index files for each segment.
- The time index and offset index share the same index size configuration. Since each time index entry is 1.5x the size of offset index entry. User may need to increase log.index.size.max.bytes to avoid potential frequent log rolling.
- Due to the increased number of index files, on some brokers with large amount the log segments (e.g. >15K), the log loading process during the broker startup could be longer. Based on our experiment, setting the num.recovery.threads.per.data.dir to one may reduce the log loading time.
Upgrading a 0.10.0 Kafka Streams Application
- Upgrading your Streams application from 0.10.0 to 0.10.1 does require a broker upgrade because a Kafka Streams 0.10.1 application can only connect to 0.10.1 brokers.
- There are couple of API changes, that are not backward compatible (cf. Streams API changes in 0.10.1 for more details). Thus, you need to update and recompile your code. Just swapping the Kafka Streams library jar file will not work and will break your application.
- Upgrading from 0.10.0.x to 0.10.1.2 requires two rolling bounces with config
upgrade.from="0.10.0"
set for first upgrade phase (cf. KIP-268). As an alternative, an offline upgrade is also possible.- prepare your application instances for a rolling bounce and make sure that config
upgrade.from
is set to"0.10.0"
for new version 0.10.1.2 - bounce each instance of your application once
- prepare your newly deployed 0.10.1.2 application instances for a second round of rolling bounces; make sure to remove the value for config
upgrade.from
- bounce each instance of your application once more to complete the upgrade
- prepare your application instances for a rolling bounce and make sure that config
- Upgrading from 0.10.0.x to 0.10.1.0 or 0.10.1.1 requires an offline upgrade (rolling bounce upgrade is not supported)
- stop all old (0.10.0.x) application instances
- update your code and swap old code and jar file with new code and new jar file
- restart all new (0.10.1.0 or 0.10.1.1) application instances
Notable changes in 0.10.1.0
- The new Java consumer is no longer in beta and we recommend it for all new development. The old Scala consumers are still supported, but they will be deprecated in the next release and will be removed in a future major release.
- The
--new-consumer
/--new.consumer
switch is no longer required to use tools like MirrorMaker and the Console Consumer with the new consumer; one simply needs to pass a Kafka broker to connect to instead of the ZooKeeper ensemble. In addition, usage of the Console Consumer with the old consumer has been deprecated and it will be removed in a future major release. - Kafka clusters can now be uniquely identified by a cluster id. It will be automatically generated when a broker is upgraded to 0.10.1.0. The cluster id is available via the kafka.server:type=KafkaServer,name=ClusterId metric and it is part of the Metadata response. Serializers, client interceptors and metric reporters can receive the cluster id by implementing the ClusterResourceListener interface.
- The BrokerState "RunningAsController" (value 4) has been removed. Due to a bug, a broker would only be in this state briefly before transitioning out of it and hence the impact of the removal should be minimal. The recommended way to detect if a given broker is the controller is via the kafka.controller:type=KafkaController,name=ActiveControllerCount metric.
- The new Java Consumer now allows users to search offsets by timestamp on partitions.
- The new Java Consumer now supports heartbeating from a background thread. There is a new configuration
max.poll.interval.ms
which controls the maximum time between poll invocations before the consumer will proactively leave the group (5 minutes by default). The value of the configurationrequest.timeout.ms
(default to 30 seconds) must always be smaller thanmax.poll.interval.ms
(default to 5 minutes), since that is the maximum time that a JoinGroup request can block on the server while the consumer is rebalance. Finally, the default value ofsession.timeout.ms
has been adjusted down to 10 seconds, and the default value ofmax.poll.records
has been changed to 500. - When using an Authorizer and a user doesn't have Describe authorization on a topic, the broker will no longer return TOPIC_AUTHORIZATION_FAILED errors to requests since this leaks topic names. Instead, the UNKNOWN_TOPIC_OR_PARTITION error code will be returned. This may cause unexpected timeouts or delays when using the producer and consumer since Kafka clients will typically retry automatically on unknown topic errors. You should consult the client logs if you suspect this could be happening.
- Fetch responses have a size limit by default (50 MB for consumers and 10 MB for replication). The existing per partition limits also apply (1 MB for consumers and replication). Note that neither of these limits is an absolute maximum as explained in the next point.
- Consumers and replicas can make progress if a message larger than the response/partition size limit is found. More concretely, if the first message in the first non-empty partition of the fetch is larger than either or both limits, the message will still be returned.
- 添加了重载的构造函数
kafka.api.FetchRequest
,并kafka.javaapi.FetchRequest
允许调用者指定分区的顺序(因为顺序在 v3 中很重要)。以前存在的构造函数已被弃用,并且在发送请求之前会对分区进行洗牌以避免饥饿问题。
新协议版本
- ListOffsetRequest v1支持基于时间戳的精确偏移搜索。
- MetadataResponse v2 引入了一个新字段:“cluster_id”。
- FetchRequest v3 支持限制响应大小(除了现有的每个分区限制),如果需要取得进展,它会返回大于限制的消息,并且请求中的分区顺序现在很重要。
- JoinGroup v1 引入了一个新字段:“rebalance_timeout”。
Upgrading from 0.8.x or 0.9.x to 0.10.0.0
0.10.0.0 具有潜在的重大更改(请在升级前查看),并且 升级后可能会影响性能。通过遵循下面推荐的滚动升级计划,您可以保证升级期间和升级后不会出现停机且不会影响性能。
注意:由于引入了新协议,因此在升级客户端之前升级 Kafka 集群非常重要。
版本 0.9.0.0 的客户端注意事项:由于 0.9.0.0 中引入的错误,依赖 ZooKeeper(旧的 Scala 高级 Consumer 和 MirrorMaker,如果与旧的 Consumer 一起使用)的客户端将无法与 0.10.0.x 代理一起使用。因此,在代理升级到0.10.0.x之前, 0.9.0.0客户端应升级到0.9.0.1。对于 0.8.X 或 0.9.0.1 客户端,无需执行此步骤。
对于滚动升级:
- 更新所有代理上的 server.properties 文件并添加以下属性:
- inter.broker.protocol.version=CURRENT_KAFKA_VERSION(例如0.8.2或0.9.0.0)。
- log.message.format.version=CURRENT_KAFKA_VERSION(有关此配置的详细信息, 请参阅升级后的潜在性能影响。)
- 升级经纪人。只需将代理关闭、更新代码并重新启动即可一次完成此操作。
- 整个集群升级后,通过编辑 inter.broker.protocol.version 并将其设置为 0.10.0.0 来提升协议版本。注意:您还不应该触摸 log.message.format.version - 只有在所有使用者都升级到 0.10.0.0 后,此参数才应更改
- 一一重启broker,新协议版本即可生效。
- 所有消费者升级到 0.10.0 后,将每个代理上的 log.message.format.version 更改为 0.10.0 并一一重新启动它们。
注意:如果您愿意接受停机,您只需关闭所有代理,更新代码并启动所有代理即可。默认情况下,他们将从新协议开始。
注意:在代理升级后,可以随时更改协议版本并重新启动。它不一定是紧随其后。
升级到 0.10.0.0 后的潜在性能影响
0.10.0 中的消息格式包括一个新的时间戳字段,并使用压缩消息的相对偏移量。磁盘消息格式可以通过 server.properties 文件中的 log.message.format.version 配置。默认磁盘消息格式为 0.10.0。如果消费者客户端使用的是 0.10.0.0 之前的版本,则它只能理解 0.10.0 之前的消息格式。在这种情况下,代理能够将消息从 0.10.0 格式转换为较早的格式,然后再将响应发送给旧版本的使用者。但是,在这种情况下,经纪商不能使用零拷贝传输。Kafka 社区关于性能影响的报告显示,升级后 CPU 利用率从之前的 20% 上升到 100%,这迫使所有客户端立即升级以使性能恢复正常。为了避免在消费者升级到 0.10.0.0 之前发生此类消息转换,可以在将代理升级到 0.10.0.0 时将 log.message.format.version 设置为 0.8.2 或 0.9.0。这样,broker仍然可以使用零拷贝传输将数据发送给旧的消费者。一旦消费者升级,就可以在代理上将消息格式更改为 0.10.0,并享受包括新时间戳和改进压缩的新消息格式。支持转换是为了确保兼容性,并且对于支持一些尚未更新到较新客户端的应用程序很有用,但即使在过度配置的集群上支持所有消费者流量也是不切实际的。因此,当代理已升级但大多数客户端尚未升级时,尽可能避免消息转换至关重要。
对于升级到 0.10.0.0 的客户端,不会产生性能影响。
注意:通过设置消息格式版本,可以证明所有现有消息均等于或低于该消息格式版本。否则 0.10.0.0 之前的消费者可能会崩溃。特别是,在消息格式设置为 0.10.0 后,不应将其更改回较早的格式,因为这可能会破坏 0.10.0.0 之前版本的消费者。
注意:由于每条消息中引入了额外的时间戳,发送小消息的生产者可能会因为开销增加而看到消息吞吐量下降。同样,复制现在每条消息额外传输 8 个字节。如果您的运行接近集群的网络容量,则可能会导致网卡不堪重负,并因过载而出现故障和性能问题。
注意:如果您在生产者上启用了压缩,您可能会注意到在某些情况下生产者吞吐量降低和/或代理上的压缩率降低。接收压缩消息时,0.10.0 代理会避免重新压缩消息,这通常会减少延迟并提高吞吐量。然而,在某些情况下,这可能会减少生产者的批处理大小,从而导致吞吐量下降。如果发生这种情况,用户可以调整生产者的linger.ms和batch.size以获得更好的吞吐量。此外,snappy 用于压缩消息的生产者缓冲区小于代理使用的缓冲区,这可能会对磁盘上消息的压缩率产生负面影响。我们打算在未来的 Kafka 版本中对此进行配置。
0.10.0.0 中潜在的重大变化
- 从Kafka 0.10.0.0开始,Kafka中的消息格式版本以Kafka版本表示。例如,消息格式0.9.0是指Kafka 0.9.0支持的最高消息版本。
- 已引入消息格式 0.10.0,并且默认使用该格式。它在消息中包含时间戳字段,并且相对偏移量用于压缩消息。
- 引入ProduceRequest/Response v2,默认支持消息格式0.10.0
- 引入FetchRequest/Response v2,默认支持消息格式0.10.0
- MessageFormatter 接口已更改
def writeTo(key: Array[Byte], value: Array[Byte], output: PrintStream)
为def writeTo(consumerRecord: ConsumerRecord[Array[Byte], Array[Byte]], output: PrintStream)
- MessageReader 接口已更改
def readMessage(): KeyedMessage[Array[Byte], Array[Byte]]
为def readMessage(): ProducerRecord[Array[Byte], Array[Byte]]
- MessageFormatter 的包已更改
kafka.tools
为kafka.common
- MessageReader 的包已更改
kafka.tools
为kafka.common
- MirrorMakerMessageHandler 不再公开该
handle(record: MessageAndMetadata[Array[Byte], Array[Byte]])
方法,因为它从未被调用。 - 0.7 KafkaMigrationTool 不再与 Kafka 一起打包。如果您需要从0.7迁移到0.10.0,请先迁移到0.8,然后按照记录的升级流程从0.8升级到0.10.0。
- 新的消费者已标准化其 API,以接受
java.util.Collection
作为方法参数的序列类型。现有代码可能需要更新才能与 0.10.0 客户端库一起使用。 - LZ4 压缩消息处理已更改为使用可互操作的帧规范 (LZ4f v1.5.1)。为了保持与旧客户端的兼容性,此更改仅适用于消息格式 0.10.0 及更高版本。使用 v0/v1(消息格式 0.9.0)生成/获取 LZ4 压缩消息的客户端应继续使用 0.9.0 帧实现。使用 Produce/Fetch 协议 v2 或更高版本的客户端应使用可互操作的 LZ4f 帧。可互操作的 LZ4 库列表位于https://www.lz4.org/
0.10.0.0 中的显着变化
- 从 Kafka 0.10.0.0 开始,一个名为Kafka Streams的新客户端库可用于对 Kafka 主题中存储的数据进行流处理。由于上述消息格式的变化,这个新的客户端库仅适用于 0.10.x 及更高版本的代理。有关更多信息,请阅读Streams 文档。
receive.buffer.bytes
对于新消费者来说,配置参数的默认值现在是 64K。- 新的消费者现在公开配置参数
exclude.internal.topics
以限制内部主题(例如消费者偏移主题)意外地包含在正则表达式订阅中。默认情况下,它是启用的。 - 旧的 Scala 生成器已被弃用。用户应尽快将其代码迁移到 kafka-clients JAR 中包含的 Java 生产者。
- 新的消费者 API 已标记为稳定。
Upgrading from 0.8.0, 0.8.1.X, or 0.8.2.X to 0.9.0.0
0.9.0.0 具有潜在的重大更改(请在升级前查看)以及与先前版本相比的经纪商间协议更改。这意味着升级后的经纪商和客户端可能与旧版本不兼容。在升级客户端之前升级 Kafka 集群非常重要。如果您使用 MirrorMaker,下游集群也应该首先升级。对于滚动升级:
- 更新所有代理上的 server.properties 文件并添加以下属性: inter.broker.protocol.version=0.8.2.X
- 升级经纪人。只需将代理关闭、更新代码并重新启动即可一次完成此操作。
- 整个集群升级后,通过编辑 inter.broker.protocol.version 并将其设置为 0.9.0.0 来提升协议版本。
- 一一重启broker,新协议版本生效
注意:如果您愿意接受停机,您只需关闭所有代理,更新代码并启动所有代理即可。默认情况下,他们将从新协议开始。
注意:在代理升级后,可以随时更改协议版本并重新启动。它不一定是紧随其后。
0.9.0.0 中潜在的重大变化
- 不再支持 Java 1.6。
- 不再支持 Scala 2.9。
- 1000 以上的经纪商 ID 现在默认保留为自动分配的经纪商 ID。如果您的集群的现有代理 ID 高于该阈值,请确保相应地增加served.broker.max.id 代理配置属性。
- 配置参数replica.lag.max.messages已删除。分区领导者在决定哪些副本同步时将不再考虑滞后消息的数量。
- 配置参数replica.lag.time.max.ms现在不仅指自上次从副本获取请求以来经过的时间,还指自副本上次赶上以来的时间。仍在从领导者获取消息但未赶上replica.lag.time.max.ms 中最新消息的副本将被视为不同步。
- 压缩主题不再接受没有密钥的消息,如果尝试这样做,生产者会抛出异常。在 0.8.x 中,没有 key 的消息将导致日志压缩线程随后抱怨并退出(并停止压缩所有压缩主题)。
- MirrorMaker 不再支持多个目标集群。因此,它只接受单个 --consumer.config 参数。要镜像多个源集群,每个源集群至少需要一个 MirrorMaker 实例,每个实例都有自己的使用者配置。
- 打包在org.apache.kafka.clients.tools.*下的工具已移至org.apache.kafka.tools.*。所有包含的脚本仍将照常运行,只有直接导入这些类的自定义代码才会受到影响。
- kafka-run-class.sh 中的默认 Kafka JVM 性能选项 (KAFKA_JVM_PERFORMANCE_OPTS) 已更改。
- kafka-topics.sh 脚本 (kafka.admin.TopicCommand) 现在在失败时以非零退出代码退出。
- 当主题名称因使用“.”而存在指标冲突风险时,kafka-topics.sh 脚本 (kafka.admin.TopicCommand) 现在将打印警告 或主题名称中的“_”,并且在实际冲突的情况下出错。
- kafka-console- Producer.sh脚本(kafka.tools.ConsoleProducer)将默认使用Java生产者而不是旧的Scala生产者,用户必须指定“old- Producer”才能使用旧生产者。
- 默认情况下,所有命令行工具都会将所有日志消息打印到 stderr 而不是 stdout。
0.9.0.1 中的显着变化
- 可以通过将broker.id. Generation.enable 设置为 false 来禁用新的代理 ID 生成功能。
- 配置参数 log.cleaner.enable 现在默认为 true。这意味着具有 cleanup.policy=compact 的主题现在将默认进行压缩,并且 128 MB 的堆将通过 log.cleaner.dedupe.buffer.size 分配给清理进程。您可能需要根据压缩主题的使用情况查看 log.cleaner.dedupe.buffer.size 和其他 log.cleaner 配置值。
- 新消费者的配置参数 fetch.min.bytes 的默认值现在默认为 1。
0.9.0.0 中的弃用
- 已弃用从 kafka-topics.sh 脚本 (kafka.admin.TopicCommand) 更改主题配置。今后,请使用 kafka-configs.sh 脚本 (kafka.admin.ConfigCommand) 来实现此功能。
- kafka-consumer-offset-checker.sh (kafka.tools.ConsumerOffsetChecker) 已被弃用。今后,请使用 kafka-consumer-groups.sh (kafka.admin.ConsumerGroupCommand) 来实现此功能。
- kafka.tools.ProducerPerformance 类已被弃用。今后,请使用 org.apache.kafka.tools.ProducerPerformance 来实现此功能(kafka- Producer-perf-test.sh 也将更改为使用新类)。
- 生产者配置 block.on.buffer.full 已被弃用,并将在未来版本中删除。目前其默认值已更改为 false。KafkaProducer将不再抛出BufferExhaustedException,而是使用max.block.ms值进行阻塞,之后它将抛出TimeoutException。如果 block.on.buffer.full 属性显式设置为 true,则会将 max.block.ms 设置为 Long.MAX_VALUE,并且metadata.fetch.timeout.ms 将不会被遵守
Upgrading from 0.8.1 to 0.8.2
0.8.2 与 0.8.1 完全兼容。只需将其关闭、更新代码并重新启动即可一次对一个代理进行升级。Upgrading from 0.8.0 to 0.8.1
0.8.1 与 0.8 完全兼容。只需将其关闭、更新代码并重新启动即可一次对一个代理进行升级。Upgrading from 0.7
版本 0.7 与较新的版本不兼容。为了添加复制(0.7 中缺少),对 API、ZooKeeper 数据结构、协议和配置进行了重大更改。从0.7升级到更高版本需要专门的迁移工具。此迁移无需停机即可完成。2. API
- Producer API 允许应用程序将数据流发送到 Kafka 集群中的主题 。
- Consumer API 允许应用程序从 Kafka 集群中的主题读取数据流。
- Streams API 允许将数据流从输入主题转换为输出主题 。
- Connect API 允许实现不断从某些源系统或应用程序拉取到 Kafka 或从 Kafka 推送到某些接收器系统或应用程序的连接器 。
- 管理API 允许管理和检查主题、代理和其他 Kafka 对象。
2.1 生产者API
Producer API 允许应用程序将数据流发送到 Kafka 集群中的主题。javadocs 中给出了展示如何使用生产者的示例 。
要使用生产者,您可以使用以下 Maven 依赖项:
<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-clients</artifactId>
<version>3.6.0</version>
</dependency>
2.2 消费者API
Consumer API 允许应用程序从 Kafka 集群中的主题读取数据流。javadocs 中给出了展示如何使用消费者的示例 。
要使用消费者,您可以使用以下 Maven 依赖项:
<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-clients</artifactId>
<version>3.6.0</version>
</dependency>
2.3 流API
Streams API 允许将数据流从输入主题转换为输出主题 。javadoc 中给出了展示如何使用该库的示例
有关使用 Streams API 的其他文档可在此处获取。
要使用 Kafka Streams,您可以使用以下 Maven 依赖项:
<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-streams</artifactId>
<version>3.6.0</version>
</dependency>
使用 Scala 时,您可以选择包含该kafka-streams-scala
库。开发人员指南中提供了有关使用 Scala 的 Kafka Streams DSL 的其他文档。
要在 Scala 2.13 中使用 Kafka Streams DSL for Scala,您可以使用以下 Maven 依赖项:
<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-streams-scala_2.13</artifactId>
<version>3.6.0</version>
</dependency>
2.4 连接API
Connect API 允许实现不断从某个源数据系统拉入 Kafka 或从 Kafka 推送到某个接收器数据系统的连接器。Connect 的许多用户不需要直接使用此 API,但他们可以使用预构建的连接器,而无需编写任何代码。有关使用 Connect 的更多信息可在此处获取。
想要实现自定义连接器的人可以查看javadoc。
2.5 管理接口
管理 API 支持管理和检查主题、代理、acls 和其他 Kafka 对象。要使用管理 API,请添加以下 Maven 依赖项:
<dependency>
<groupId>org.apache.kafka</groupId>
<artifactId>kafka-clients</artifactId>
<version>3.6.0</version>
</dependency>
有关管理 API 的更多信息,请参阅javadoc。
3. 配置
3.1 经纪商配置
基本配置如下:broker.id
log.dirs
zookeeper.connect
-
advertised.listeners
发布到 ZooKeeper 供客户端使用的侦听器(如果与
listeners
配置属性不同)。在 IaaS 环境中,这可能需要与代理绑定的接口不同。如果未设置,listeners
则将使用 的值。与 不同的是listeners
,通告 0.0.0.0 元地址是无效的。
与 不同的是listeners
,此属性中可以有重复的端口,以便可以将一个侦听器配置为通告另一个侦听器的地址。这在某些使用外部负载均衡器的情况下非常有用。Type: string Default: null Valid Values: Importance: high Update Mode: per-broker -
auto.create.topics.enable
在服务器上启用自动创建主题。
Type: boolean Default: true Valid Values: Importance: high Update Mode: read-only -
auto.leader.rebalance.enable
启用自动领导者平衡。后台线程定期检查分区领导者的分布,可通过leader.imbalance.check.interval.seconds进行配置。如果领导者不平衡超过leader.imbalance.per.broker.percentage,则会触发领导者重新平衡到分区的首选领导者。
Type: boolean Default: true Valid Values: Importance: high Update Mode: read-only -
background.threads
用于各种后台处理任务的线程数
Type: int Default: 10 Valid Values: [1,...] Importance: high Update Mode: cluster-wide -
broker.id
该服务器的代理 ID。如果未设置,将生成唯一的代理 ID。为了避免 ZooKeeper 生成的代理 ID 和用户配置的代理 ID 之间的冲突,生成的代理 ID 从served.broker.max.id + 1 开始。
Type: int Default: -1 Valid Values: Importance: high Update Mode: read-only -
compression.type
指定给定主题的最终压缩类型。此配置接受标准压缩编解码器('gzip'、'snappy'、'lz4'、'zstd')。它还接受“未压缩”,这相当于不压缩;“生产者”表示保留生产者设置的原始压缩编解码器。
Type: string Default: producer Valid Values: [uncompressed, zstd, lz4, snappy, gzip, producer] Importance: high Update Mode: cluster-wide -
control.plane.listener.name
用于控制器和代理之间通信的侦听器名称。代理将使用
control.plane.listener.name
在侦听器列表中定位端点,以侦听来自控制器的连接。例如,如果代理的配置是:listeners = INTERNAL://192.1.1.8:9092, EXTERNAL://10.1.1.5:9093, CONTROLLER://192.1.1.8:9094listener.security.protocol.map = INTERNAL:PLAINTEXT, EXTERNAL:SSL, CONTROLLER:SSLcontrol.plane.listener.name = CONTROLLER
启动时,代理将开始使用安全协议“SSL”侦听“192.1.1.8:9094”。
在控制器端,当它通过 ZooKeeper 发现代理的已发布端点时,它将使用 来control.plane.listener.name
查找端点,并使用该端点建立与代理的连接。
例如,如果代理在 ZooKeeper 上发布的端点是:
"endpoints" : ["INTERNAL://broker1.example.com:9092","EXTERNAL://broker1.example.com:9093","CONTROLLER://broker1.example.com:9094"]
并且控制器的配置是:listener.security.protocol.map = INTERNAL:PLAINTEXT, EXTERNAL:SSL, CONTROLLER:SSLcontrol.plane.listener.name = CONTROLLER
那么控制器将使用“broker1.example.com:9094”和安全协议“SSL”来连接到代理。
如果未显式配置,则默认值为 null,并且不会有用于控制器连接的专用端点。
如果显式配置,该值不能与 的值相同inter.broker.listener.name
。Type: string Default: null Valid Values: Importance: high Update Mode: read-only -
controller.listener.names
控制器使用的侦听器名称的逗号分隔列表。如果在 KRaft 模式下运行,这是必需的。当与控制器仲裁通信时,代理将始终使用此列表中的第一个侦听器。
注意:基于 ZooKeeper 的控制器不应设置此配置。Type: string Default: null Valid Values: Importance: high Update Mode: read-only -
controller.quorum.election.backoff.max.ms
开始新选举之前的最长时间(以毫秒为单位)。这用于二进制指数退避机制,有助于防止选举陷入僵局
Type: int Default: 1000 (1 second) Valid Values: Importance: high Update Mode: read-only -
controller.quorum.election.timeout.ms
在触发新选举之前无法从领导者获取数据的最长时间(以毫秒为单位)
Type: int Default: 1000 (1 second) Valid Values: Importance: high Update Mode: read-only -
controller.quorum.fetch.timeout.ms
在成为候选人并触发选民选举之前,从当前领导者那里成功获取信息的最长时间;在询问领导者是否有新纪元之前,没有收到来自大多数法定人数的提取的最长时间。
Type: int Default: 2000 (2 seconds) Valid Values: Importance: high Update Mode: read-only -
controller.quorum.voters
以逗号分隔的
{id}@{host}:{port}
条目列表中的一组投票者的 ID/端点信息的映射。例如:1@localhost:9092,2@localhost:9093,3@localhost:9094
Type: list Default: "" Valid Values: non-empty list Importance: high Update Mode: read-only -
delete.topic.enable
启用删除主题。如果关闭此配置,通过管理工具删除主题将不起作用
Type: boolean Default: true Valid Values: Importance: high Update Mode: read-only -
early.start.listeners
以逗号分隔的侦听器名称列表,可以在授权者完成初始化之前启动。当授权者依赖于集群本身进行引导时,这非常有用,就像 StandardAuthorizer(将 ACL 存储在元数据日志中)的情况一样。默认情况下,controller.listener.names 中包含的所有侦听器也将是早期启动侦听器。如果侦听器接受外部流量,则不应出现在此列表中。
Type: string Default: null Valid Values: Importance: high Update Mode: read-only -
leader.imbalance.check.interval.seconds
控制器触发分区重新平衡检查的频率
Type: long Default: 300 Valid Values: [1,...] Importance: high Update Mode: read-only -
leader.imbalance.per.broker.percentage
每个经纪人允许的领导者不平衡比率。如果每个经纪人的余额超过此值,控制器将触发领导者余额。该值以百分比指定。
Type: int Default: 10 Valid Values: Importance: high Update Mode: read-only -
listeners
侦听器列表 - 我们将侦听的 URI 的逗号分隔列表以及侦听器名称。如果监听器名称不是安全协议,
listener.security.protocol.map
也必须设置。
侦听器名称和端口号必须是唯一的,除非
一个侦听器是 IPv4 地址而另一个侦听器是
IPv6 地址(对于同一端口)。
将主机名指定为 0.0.0.0 以绑定到所有接口。
将主机名留空以绑定到默认接口。
合法侦听器列表的示例:
PLAINTEXT://myhost:9092,SSL://:9091
CLIENT://0.0.0.0:9092,REPLICATION://localhost:9093
PLAINTEXT://127.0.0.1:9092,SSL://[::1]:9092
Type: string Default: PLAINTEXT://:9092 Valid Values: Importance: high Update Mode: per-broker -
log.dir
保存日志数据的目录(log.dirs 属性的补充)
Type: string Default: /tmp/kafka-logs Valid Values: Importance: high Update Mode: read-only -
log.dirs
存储日志数据的目录的逗号分隔列表。如果未设置,则使用 log.dir 中的值。
Type: string Default: null Valid Values: Importance: high Update Mode: read-only -
log.flush.interval.messages
在消息刷新到磁盘之前日志分区上累积的消息数。
Type: long Default: 9223372036854775807 Valid Values: [1,...] Importance: high Update Mode: cluster-wide -
log.flush.interval.ms
任何主题中的消息在刷新到磁盘之前在内存中保留的最长时间(以毫秒为单位)。如果未设置,则使用 log.flush.scheduler.interval.ms 中的值
Type: long Default: null Valid Values: Importance: high Update Mode: cluster-wide -
log.flush.offset.checkpoint.interval.ms
我们更新充当日志恢复点的最后一次刷新的持久记录的频率。
Type: int Default: 60000 (1 minute) Valid Values: [0,...] Importance: high Update Mode: read-only -
log.flush.scheduler.interval.ms
日志刷新器检查是否有日志需要刷新到磁盘的频率(以毫秒为单位)
Type: long Default: 9223372036854775807 Valid Values: Importance: high Update Mode: read-only -
log.flush.start.offset.checkpoint.interval.ms
我们更新日志起始偏移量的持久记录的频率
Type: int Default: 60000 (1 minute) Valid Values: [0,...] Importance: high Update Mode: read-only -
log.retention.bytes
删除日志之前的最大大小
Type: long Default: -1 Valid Values: Importance: high Update Mode: cluster-wide -
log.retention.hours
删除日志文件之前保留日志文件的小时数(以小时为单位),第三级为 log.retention.ms 属性
Type: int Default: 168 Valid Values: Importance: high Update Mode: read-only -
log.retention.minutes
删除日志文件之前保留日志文件的分钟数(以分钟为单位),次要于 log.retention.ms 属性。如果未设置,则使用 log.retention.hours 中的值
Type: int Default: null Valid Values: Importance: high Update Mode: read-only -
log.retention.ms
删除日志文件之前保留日志文件的毫秒数(以毫秒为单位),如果未设置,则使用 log.retention.minutes 中的值。如果设置为 -1,则不应用时间限制。
Type: long Default: null Valid Values: Importance: high Update Mode: cluster-wide -
log.roll.hours
推出新日志段之前的最长时间(以小时为单位),次要于 log.roll.ms 属性
Type: int Default: 168 Valid Values: [1,...] Importance: high Update Mode: read-only -
log.roll.jitter.hours
从 logRollTimeMillis 中减去的最大抖动(以小时为单位),次要于 log.roll.jitter.ms 属性
Type: int Default: 0 Valid Values: [0,...] Importance: high Update Mode: read-only -
log.roll.jitter.ms
从 logRollTimeMillis 中减去的最大抖动(以毫秒为单位)。如果未设置,则使用 log.roll.jitter.hours 中的值
Type: long Default: null Valid Values: Importance: high Update Mode: cluster-wide -
log.roll.ms
推出新日志段之前的最长时间(以毫秒为单位)。如果未设置,则使用 log.roll.hours 中的值
Type: long Default: null Valid Values: Importance: high Update Mode: cluster-wide -
log.segment.bytes
单个日志文件的最大大小
Type: int Default: 1073741824 (1 gibibyte) Valid Values: [14,...] Importance: high Update Mode: cluster-wide -
log.segment.delete.delay.ms
从文件系统中删除文件之前等待的时间
Type: long Default: 60000 (1 minute) Valid Values: [0,...] Importance: high Update Mode: cluster-wide -
message.max.bytes
Kafka 允许的最大记录批量大小(如果启用压缩,则在压缩后)。如果增加此值并且存在早于 0.10.2 的消费者,则消费者的获取大小也必须增加,以便他们可以获取这么大的记录批次。在最新的消息格式版本中,为了提高效率,记录总是分组为批次。在以前的消息格式版本中,未压缩的记录不会分组为批次,并且此限制仅适用于这种情况下的单个记录。这可以使用主题级别配置针对每个主题进行设置
max.message.bytes
。Type: int Default: 1048588 Valid Values: [0,...] Importance: high Update Mode: cluster-wide -
metadata.log.dir
此配置决定了我们将 KRaft 模式下集群的元数据日志放置在哪里。如果未设置,元数据日志将放置在 log.dirs 中的第一个日志目录中。
Type: string Default: null Valid Values: Importance: high Update Mode: read-only -
metadata.log.max.record.bytes.between.snapshots
这是最新快照与生成新快照之前所需的高水位线之间日志中的最大字节数。默认值为20971520。要根据经过的时间生成快照,请参见
metadata.log.max.snapshot.interval.ms
配置。当达到最大时间间隔或达到最大字节数限制时,Kafka 节点将生成快照。Type: long Default: 20971520 Valid Values: [1,...] Importance: high Update Mode: read-only -
metadata.log.max.snapshot.interval.ms
如果日志中存在未包含在最新快照中的已提交记录,则这是等待生成快照的最大毫秒数。值为零将禁用基于时间的快照生成。默认值为3600000。如果要根据元数据字节数生成快照,请参见配置
metadata.log.max.record.bytes.between.snapshots
。当达到最大时间间隔或达到最大字节数限制时,Kafka 节点将生成快照。Type: long Default: 3600000 (1 hour) Valid Values: [0,...] Importance: high Update Mode: read-only -
metadata.log.segment.bytes
单个元数据日志文件的最大大小。
Type: int Default: 1073741824 (1 gibibyte) Valid Values: [12,...] Importance: high Update Mode: read-only -
metadata.log.segment.ms
推出新元数据日志文件之前的最长时间(以毫秒为单位)。
Type: long Default: 604800000 (7 days) Valid Values: Importance: high Update Mode: read-only -
metadata.max.retention.bytes
删除旧快照和日志文件之前元数据日志和快照的最大组合大小。由于在删除任何日志之前必须至少存在一个快照,因此这是一项软限制。
Type: long Default: 104857600 (100 mebibytes) Valid Values: Importance: high Update Mode: read-only -
metadata.max.retention.ms
删除元数据日志文件或快照之前保留的毫秒数。由于在删除任何日志之前必须至少存在一个快照,因此这是一项软限制。
Type: long Default: 604800000 (7 days) Valid Values: Importance: high Update Mode: read-only -
min.insync.replicas
当生产者将 acks 设置为“all”(或“-1”)时,
min.insync.replicas
指定必须确认写入才能被视为成功的最小副本数。如果无法满足此最小值,则生产者将引发异常( 或NotEnoughReplicas
)NotEnoughReplicasAfterAppend
。
当一起使用时,min.insync.replicas
ack 可以让你强制执行更好的持久性保证。典型的场景是创建一个复制因子为 3 的主题,设置min.insync.replicas
为 2,并使用“all”的 ack 进行生成。这将确保生产者在大多数副本未收到写入时引发异常。Type: int Default: 1 Valid Values: [1,...] Importance: high Update Mode: cluster-wide -
node.id
当“process.roles”非空时,与该进程所扮演的角色关联的节点 ID。这是在 KRaft 模式下运行时所需的配置。
Type: int Default: -1 Valid Values: Importance: high Update Mode: read-only -
num.io.threads
服务器用于处理请求的线程数,其中可能包括磁盘 I/O
Type: int Default: 8 Valid Values: [1,...] Importance: high Update Mode: cluster-wide -
num.network.threads
服务器用于从网络接收请求并向网络发送响应的线程数。注意:每个监听器(除了控制器监听器)都会创建自己的线程池。
Type: int Default: 3 Valid Values: [1,...] Importance: high Update Mode: cluster-wide -
num.recovery.threads.per.data.dir
每个数据目录用于启动时日志恢复和关闭时刷新的线程数
Type: int Default: 1 Valid Values: [1,...] Importance: high Update Mode: cluster-wide -
num.replica.alter.log.dirs.threads
可以在日志目录之间移动副本的线程数,其中可能包括磁盘 I/O
Type: int Default: null Valid Values: Importance: high Update Mode: read-only -
num.replica.fetchers
用于从每个源代理复制记录的获取器线程数。每个 Broker 上的 fetcher 总数
num.replica.fetchers
与集群中的 Broker 数量相乘。增加此值可以提高跟随者和领导者 Broker 中的 I/O 并行度,但代价是更高的 CPU 和内存利用率。Type: int Default: 1 Valid Values: Importance: high Update Mode: cluster-wide -
offset.metadata.max.bytes
与偏移提交关联的元数据条目的最大大小。
Type: int Default: 4096 (4 kibibytes) Valid Values: Importance: high Update Mode: read-only -
offsets.commit.required.acks
可以接受提交之前所需的确认。一般来说,不应覆盖默认值 (-1)。
Type: short Default: -1 Valid Values: Importance: high Update Mode: read-only -
offsets.commit.timeout.ms
偏移量提交将被延迟,直到偏移量主题的所有副本都收到提交或达到此超时。这类似于生产者请求超时。
Type: int Default: 5000 (5 seconds) Valid Values: [1,...] Importance: high Update Mode: read-only -
offsets.load.buffer.size
将偏移量加载到缓存中时从偏移量段读取的批量大小(软限制,如果记录太大则覆盖)。
Type: int Default: 5242880 Valid Values: [1,...] Importance: high Update Mode: read-only -
offsets.retention.check.interval.ms
检查过时偏移量的频率
Type: long Default: 600000 (10 minutes) Valid Values: [1,...] Importance: high Update Mode: read-only -
offsets.retention.minutes
对于订阅的消费者,在以下情况下,特定分区的提交偏移量将过期并被丢弃: 1)在消费者组失去所有消费者(即变空)后,此保留期已过;2) 自上次为该分区提交偏移量以来,该保留期已过,并且该组不再订阅相应的主题。对于独立消费者(使用手动分配),自上次提交以来的保留期过后,偏移量将过期。请注意,当通过delete-group请求删除一个组时,其提交的偏移量也将被删除,而无需额外的保留期;此外,当通过删除主题请求删除主题时,在传播元数据更新时,该主题的任何组的提交偏移量也将被删除,而无需额外的保留期。
Type: int Default: 10080 Valid Values: [1,...] Importance: high Update Mode: read-only -
offsets.topic.compression.codec
偏移量主题的压缩编解码器 - 压缩可用于实现“原子”提交。
Type: int Default: 0 Valid Values: Importance: high Update Mode: read-only -
offsets.topic.num.partitions
偏移提交主题的分区数量(部署后不应更改)。
Type: int Default: 50 Valid Values: [1,...] Importance: high Update Mode: read-only -
offsets.topic.replication.factor
偏移主题的复制因子(设置较高以确保可用性)。在集群大小满足此复制因子要求之前,内部主题创建将失败。
Type: short Default: 3 Valid Values: [1,...] Importance: high Update Mode: read-only -
offsets.topic.segment.bytes
偏移量主题段字节应保持相对较小,以便于更快的日志压缩和缓存加载。
Type: int Default: 104857600 (100 mebibytes) Valid Values: [1,...] Importance: high Update Mode: read-only -
process.roles
此流程扮演的角色:“经纪人”、“控制者”或“经纪人、控制者”(如果两者兼而有之)。此配置仅适用于KRaft(Kafka Raft)模式的集群(而不是ZooKeeper)。对于 ZooKeeper 集群,将此配置保留为未定义或为空。
Type: list Default: "" Valid Values: [broker, controller] Importance: high Update Mode: read-only -
queued.max.requests
在阻塞网络线程之前,数据平面允许的排队请求数
Type: int Default: 500 Valid Values: [1,...] Importance: high Update Mode: read-only -
replica.fetch.min.bytes
每个获取响应所需的最小字节数。如果没有足够的字节,请等待
replica.fetch.wait.max.ms
(代理配置)。Type: int Default: 1 Valid Values: Importance: high Update Mode: read-only -
replica.fetch.wait.max.ms
跟随者副本发出的每个 fetcher 请求的最大等待时间。该值应始终小于replica.lag.time.max.ms,以防止低吞吐量主题的ISR频繁收缩
Type: int Default: 500 Valid Values: Importance: high Update Mode: read-only -
replica.high.watermark.checkpoint.interval.ms
将高水位线保存到磁盘的频率
Type: long Default: 5000 (5 seconds) Valid Values: Importance: high Update Mode: read-only -
replica.lag.time.max.ms
如果追随者没有发送任何获取请求或者至少在这一次没有消耗到领导者日志结束偏移量,则领导者将从 isr 中删除追随者
Type: long Default: 30000 (30 seconds) Valid Values: Importance: high Update Mode: read-only -
replica.socket.receive.buffer.bytes
用于向领导者复制数据的网络请求的套接字接收缓冲区
Type: int Default: 65536 (64 kibibytes) Valid Values: Importance: high Update Mode: read-only -
replica.socket.timeout.ms
网络请求的套接字超时。它的值至少应该是replica.fetch.wait.max.ms
Type: int Default: 30000 (30 seconds) Valid Values: Importance: high Update Mode: read-only -
request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。
Type: int Default: 30000 (30 seconds) Valid Values: Importance: high Update Mode: read-only -
sasl.mechanism.controller.protocol
SASL机制用于与控制器通信。默认为 GSSAPI。
Type: string Default: GSSAPI Valid Values: Importance: high Update Mode: read-only -
socket.receive.buffer.bytes
套接字服务器套接字的 SO_RCVBUF 缓冲区。如果值为-1,将使用操作系统默认值。
Type: int Default: 102400 (100 kibibytes) Valid Values: Importance: high Update Mode: read-only -
socket.request.max.bytes
一次socket请求的最大字节数
Type: int Default: 104857600 (100 mebibytes) Valid Values: [1,...] Importance: high Update Mode: read-only -
socket.send.buffer.bytes
套接字服务器套接字的 SO_SNDBUF 缓冲区。如果值为-1,将使用操作系统默认值。
Type: int Default: 102400 (100 kibibytes) Valid Values: Importance: high Update Mode: read-only -
transaction.max.timeout.ms
事务允许的最大超时时间。如果客户端请求的交易时间超过此时间,则代理将在 InitProducerIdRequest 中返回错误。这可以防止客户端超时过大,从而导致消费者无法读取事务中包含的主题。
Type: int Default: 900000 (15 minutes) Valid Values: [1,...] Importance: high Update Mode: read-only -
transaction.state.log.load.buffer.size
将生产者 ID 和事务加载到缓存中时从事务日志段读取的批量大小(软限制,如果记录太大则覆盖)。
Type: int Default: 5242880 Valid Values: [1,...] Importance: high Update Mode: read-only -
transaction.state.log.min.isr
覆盖事务主题的 min.insync.replicas 配置。
Type: int Default: 2 Valid Values: [1,...] Importance: high Update Mode: read-only -
transaction.state.log.num.partitions
事务主题的分区数量(部署后不应更改)。
Type: int Default: 50 Valid Values: [1,...] Importance: high Update Mode: read-only -
transaction.state.log.replication.factor
事务主题的复制因子(设置较高以确保可用性)。在集群大小满足此复制因子要求之前,内部主题创建将失败。
Type: short Default: 3 Valid Values: [1,...] Importance: high Update Mode: read-only -
transaction.state.log.segment.bytes
事务主题段字节应保持相对较小,以便于更快的日志压缩和缓存加载
Type: int Default: 104857600 (100 mebibytes) Valid Values: [1,...] Importance: high Update Mode: read-only -
transactional.id.expiration.ms
在事务 ID 过期之前,事务协调器在未接收到当前事务的任何事务状态更新的情况下将等待的时间(以毫秒为单位)。当交易仍在进行时,交易 ID 不会过期。
Type: int Default: 604800000 (7 days) Valid Values: [1,...] Importance: high Update Mode: read-only -
unclean.leader.election.enable
指示是否将不在 ISR 集中的副本作为最后手段选举为领导者,即使这样做可能会导致数据丢失
Type: boolean Default: false Valid Values: Importance: high Update Mode: cluster-wide -
zookeeper.connect
以以下形式指定 ZooKeeper 连接字符串,
hostname:port
其中 host 和 port 是 ZooKeeper 服务器的主机和端口。要允许在 ZooKeeper 机器关闭时通过其他 ZooKeeper 节点进行连接,您还可以在表单中指定多个主机hostname1:port1,hostname2:port2,hostname3:port3
。
服务器还可以将 ZooKeeper chroot 路径作为其 ZooKeeper 连接字符串的一部分,该连接字符串将其数据放置在全局 ZooKeeper 命名空间中的某个路径下。例如,要给出 chroot 路径,/chroot/path
请将连接字符串给出为hostname1:port1,hostname2:port2,hostname3:port3/chroot/path
.Type: string Default: null Valid Values: Importance: high Update Mode: read-only -
zookeeper.connection.timeout.ms
客户端等待与 ZooKeeper 建立连接的最长时间。如果未设置,则使用zookeeper.session.timeout.ms中的值
Type: int Default: null Valid Values: Importance: high Update Mode: read-only -
zookeeper.max.in.flight.requests
客户端在阻塞之前向 ZooKeeper 发送的未确认请求的最大数量。
Type: int Default: 10 Valid Values: [1,...] Importance: high Update Mode: read-only -
zookeeper.metadata.migration.enable
启用 ZK 到 KRaft 迁移
Type: boolean Default: false Valid Values: Importance: high Update Mode: read-only -
zookeeper.session.timeout.ms
Zookeeper 会话超时
Type: int Default: 18000 (18 seconds) Valid Values: Importance: high Update Mode: read-only -
zookeeper.set.acl
设置客户端使用安全 ACL
Type: boolean Default: false Valid Values: Importance: high Update Mode: read-only -
broker.heartbeat.interval.ms
代理心跳之间的时间长度(以毫秒为单位)。在 KRaft 模式下运行时使用。
Type: int Default: 2000 (2 seconds) Valid Values: Importance: medium Update Mode: read-only -
broker.id.generation.enable
在服务器上启用自动代理 ID 生成。启用后,应检查为served.broker.max.id配置的值。
Type: boolean Default: true Valid Values: Importance: medium Update Mode: read-only -
broker.rack
经纪人的机架。这将用于机架感知复制分配以实现容错。示例:“RACK1”、“us-east-1d”
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
broker.session.timeout.ms
如果没有发出心跳,代理租约持续的时间长度(以毫秒为单位)。在 KRaft 模式下运行时使用。
Type: int Default: 9000 (9 seconds) Valid Values: Importance: medium Update Mode: read-only -
connections.max.idle.ms
空闲连接超时:服务器套接字处理器线程关闭空闲超过此时间的连接
Type: long Default: 600000 (10 minutes) Valid Values: Importance: medium Update Mode: read-only -
connections.max.reauth.ms
当显式设置为正数(默认为 0,不是正数)时,在 v2.2.0 或更高版本的客户端进行身份验证时,将向 v2.2.0 或更高版本的客户端传达不超过配置值的会话生存期。代理将断开在会话生命周期内未重新验证且随后用于除重新验证之外的任何目的的任何此类连接。配置名称可以选择以侦听器前缀和小写 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.oauthbearer.connections.max.reauth.ms=3600000
Type: long Default: 0 Valid Values: Importance: medium Update Mode: read-only -
controlled.shutdown.enable
启用服务器的受控关闭。
Type: boolean Default: true Valid Values: Importance: medium Update Mode: read-only -
controlled.shutdown.max.retries
受控关闭可能会因多种原因而失败。这决定了发生此类失败时的重试次数
Type: int Default: 3 Valid Values: Importance: medium Update Mode: read-only -
controlled.shutdown.retry.backoff.ms
在每次重试之前,系统需要时间从导致上次故障的状态中恢复(控制器故障转移、副本滞后等)。此配置确定重试之前等待的时间量。
Type: long Default: 5000 (5 seconds) Valid Values: Importance: medium Update Mode: read-only -
controller.quorum.append.linger.ms
领导者在将写入刷新到磁盘之前等待写入累积的持续时间(以毫秒为单位)。
Type: int Default: 25 Valid Values: Importance: medium Update Mode: read-only -
controller.quorum.request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。
Type: int Default: 2000 (2 seconds) Valid Values: Importance: medium Update Mode: read-only -
controller.socket.timeout.ms
控制器到代理通道的套接字超时。
Type: int Default: 30000 (30 seconds) Valid Values: Importance: medium Update Mode: read-only -
default.replication.factor
自动创建主题的默认复制因子。
Type: int Default: 1 Valid Values: Importance: medium Update Mode: read-only -
delegation.token.expiry.time.ms
令牌需要更新之前的令牌有效时间(以毫秒为单位)。默认值 1 天。
Type: long Default: 86400000 (1 day) Valid Values: [1,...] Importance: medium Update Mode: read-only -
delegation.token.master.key
已弃用:delegation.token.secret.key 的别名,应使用它来代替此配置。
Type: password Default: null Valid Values: Importance: medium Update Mode: read-only -
delegation.token.max.lifetime.ms
令牌具有最长生命周期,超过该生命周期就无法再续订。默认值 7 天。
Type: long Default: 604800000 (7 days) Valid Values: [1,...] Importance: medium Update Mode: read-only -
delegation.token.secret.key
用于生成和验证委托令牌的密钥。必须在所有代理之间配置相同的密钥。如果将 Kafka 与 KRaft 结合使用,还必须在所有控制器上设置密钥。如果密钥未设置或设置为空字符串,代理将禁用委托令牌支持。
Type: password Default: null Valid Values: Importance: medium Update Mode: read-only -
delete.records.purgatory.purge.interval.requests
删除记录请求purgatory的清除间隔(以请求数为单位)
Type: int Default: 1 Valid Values: Importance: medium Update Mode: read-only -
fetch.max.bytes
我们将为获取请求返回的最大字节数。必须至少为 1024。
Type: int Default: 57671680 (55 mebibytes) Valid Values: [1024,...] Importance: medium Update Mode: read-only -
fetch.purgatory.purge.interval.requests
获取请求炼狱的清除间隔(以请求数为单位)
Type: int Default: 1000 Valid Values: Importance: medium Update Mode: read-only -
group.initial.rebalance.delay.ms
组协调员在执行第一次重新平衡之前等待更多消费者加入新组的时间。较长的延迟意味着可能会减少重新平衡,但会增加处理开始之前的时间。
Type: int Default: 3000 (3 seconds) Valid Values: Importance: medium Update Mode: read-only -
group.max.session.timeout.ms
注册消费者允许的最大会话超时。较长的超时使消费者有更多的时间在心跳之间处理消息,但代价是检测故障的时间更长。
Type: int Default: 1800000 (30 minutes) Valid Values: Importance: medium Update Mode: read-only -
group.max.size
单个消费组可以容纳的最大消费者数量。
Type: int Default: 2147483647 Valid Values: [1,...] Importance: medium Update Mode: read-only -
group.min.session.timeout.ms
注册消费者允许的最短会话超时。更短的超时会导致更快的故障检测,但代价是更频繁的消费者心跳,这可能会压垮代理资源。
Type: int Default: 6000 (6 seconds) Valid Values: Importance: medium Update Mode: read-only -
initial.broker.registration.timeout.ms
最初向控制器仲裁注册时,在声明失败并退出代理进程之前等待的毫秒数。
Type: int Default: 60000 (1 minute) Valid Values: Importance: medium Update Mode: read-only -
inter.broker.listener.name
用于代理之间通信的侦听器名称。如果未设置,则侦听器名称由 security.inter.broker.protocol 定义。同时设置此属性和 security.inter.broker.protocol 属性是错误的。
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
inter.broker.protocol.version
指定将使用哪个版本的代理间协议。
在所有代理升级到新版本后,这通常会受到影响。
一些有效值的示例为: 0.8.0、0.8.1、0.8.1.1、0.8.2、0.8.2.0、0.8.2.1、0.9.0.0、0.9.0.1 检查 MetadataVersion 以获取完整列表。Type: string Default: 3.6-IV2 Valid Values: [0.8.0, 0.8.1, 0.8.2, 0.9.0, 0.10.0-IV0, 0.10.0-IV1, 0.10.1-IV0, 0.10.1-IV1, 0.10.1-IV2, 0.10.2-IV0, 0.11.0-IV0, 0.11.0-IV1, 0.11.0-IV2, 1.0-IV0, 1.1-IV0, 2.0-IV0, 2.0-IV1, 2.1-IV0, 2.1-IV1, 2.1-IV2, 2.2-IV0, 2.2-IV1, 2.3-IV0, 2.3-IV1, 2.4-IV0, 2.4-IV1, 2.5-IV0, 2.6-IV0, 2.7-IV0, 2.7-IV1, 2.7-IV2, 2.8-IV0, 2.8-IV1, 3.0-IV0, 3.0-IV1, 3.1-IV0, 3.2-IV0, 3.3-IV0, 3.3-IV1, 3.3-IV2, 3.3-IV3, 3.4-IV0, 3.5-IV0, 3.5-IV1, 3.5-IV2, 3.6-IV0, 3.6-IV1, 3.6-IV2] Importance: medium Update Mode: read-only -
log.cleaner.backoff.ms
没有日志需要清理时的睡眠时间
Type: long Default: 15000 (15 seconds) Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.cleaner.dedupe.buffer.size
所有清理器线程中用于日志重复数据删除的总内存
Type: long Default: 134217728 Valid Values: Importance: medium Update Mode: cluster-wide -
log.cleaner.delete.retention.ms
为日志压缩主题保留逻辑删除消息标记的时间量。此设置还规定了消费者必须完成读取的时间限制(如果消费者从偏移量 0 开始),以确保他们获得最后阶段的有效快照(否则可能会在消费者完成扫描之前收集逻辑删除消息)。
Type: long Default: 86400000 (1 day) Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.cleaner.enable
启用日志清理进程在服务器上运行。如果使用带有 cleanup.policy=compact 的任何主题(包括内部偏移主题),则应启用。如果禁用,这些主题将不会被压缩并不断增大。
Type: boolean Default: true Valid Values: Importance: medium Update Mode: read-only -
log.cleaner.io.buffer.load.factor
日志清理器重复数据删除缓冲区负载系数。重复数据删除缓冲区可能已满的百分比。较高的值将允许一次清理更多的日志,但会导致更多的哈希冲突
Type: double Default: 0.9 Valid Values: Importance: medium Update Mode: cluster-wide -
log.cleaner.io.buffer.size
所有清理器线程中用于日志清理器 I/O 缓冲区的总内存
Type: int Default: 524288 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.cleaner.io.max.bytes.per.second
日志清理器将受到限制,使其读取和写入 I/O 的总和平均小于该值
Type: double Default: 1.7976931348623157E308 Valid Values: Importance: medium Update Mode: cluster-wide -
log.cleaner.max.compaction.lag.ms
消息在日志中不符合压缩条件的最长时间。仅适用于正在压缩的日志。
Type: long Default: 9223372036854775807 Valid Values: [1,...] Importance: medium Update Mode: cluster-wide -
log.cleaner.min.cleanable.ratio
符合清理条件的日志中脏日志与总日志的最小比率。如果还指定了 log.cleaner.max.compaction.lag.ms 或 log.cleaner.min.compaction.lag.ms 配置,则日志压缩器会在以下情况下立即认为日志符合压缩条件:(i)已达到脏率阈值,并且日志在至少 log.cleaner.min.compaction.lag.ms 持续时间内有脏(未压缩)记录,或者 (ii) 如果日志在最多 log.cleaner.min.compaction.lag.ms 时间内有脏(未压缩)记录log.cleaner.max.compaction.lag.ms 周期。
Type: double Default: 0.5 Valid Values: [0,...,1] Importance: medium Update Mode: cluster-wide -
log.cleaner.min.compaction.lag.ms
消息在日志中保持未压缩状态的最短时间。仅适用于正在压缩的日志。
Type: long Default: 0 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.cleaner.threads
用于日志清理的后台线程数
Type: int Default: 1 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.cleanup.policy
超出保留窗口的段的默认清理策略。以逗号分隔的有效策略列表。有效的策略是:“删除”和“紧凑”
Type: list Default: delete Valid Values: [compact, delete] Importance: medium Update Mode: cluster-wide -
log.index.interval.bytes
我们向偏移索引添加条目的时间间隔。
Type: int Default: 4096 (4 kibibytes) Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.index.size.max.bytes
偏移索引的最大大小(以字节为单位)
Type: int Default: 10485760 (10 mebibytes) Valid Values: [4,...] Importance: medium Update Mode: cluster-wide -
log.local.retention.bytes
在分区符合删除条件之前可以增长的本地日志段的最大大小。默认值为-2,它表示要使用的“log.retention.bytes”值。有效值应始终小于或等于“log.retention.bytes”值。
Type: long Default: -2 Valid Values: [-2,...] Importance: medium Update Mode: cluster-wide -
log.local.retention.ms
在本地日志段符合删除条件之前保留本地日志段的毫秒数。默认值为-2,它表示要使用“log.retention.ms”值。有效值应始终小于或等于“log.retention.ms”值。
Type: long Default: -2 Valid Values: [-2,...] Importance: medium Update Mode: cluster-wide -
log.message.format.version
指定代理将用于将消息附加到日志的消息格式版本。该值应该是有效的 MetadataVersion。一些示例是:0.8.2、0.9.0.0、0.10.0,请检查 MetadataVersion 了解更多详细信息。通过设置特定的消息格式版本,用户可以证明磁盘上的所有现有消息都小于或等于指定的版本。错误地设置此值将导致使用旧版本的消费者崩溃,因为他们将收到他们不理解的格式的消息。
Type: string Default: 3.0-IV1 Valid Values: [0.8.0, 0.8.1, 0.8.2, 0.9.0, 0.10.0-IV0, 0.10.0-IV1, 0.10.1-IV0, 0.10.1-IV1, 0.10.1-IV2, 0.10.2-IV0, 0.11.0-IV0, 0.11.0-IV1, 0.11.0-IV2, 1.0-IV0, 1.1-IV0, 2.0-IV0, 2.0-IV1, 2.1-IV0, 2.1-IV1, 2.1-IV2, 2.2-IV0, 2.2-IV1, 2.3-IV0, 2.3-IV1, 2.4-IV0, 2.4-IV1, 2.5-IV0, 2.6-IV0, 2.7-IV0, 2.7-IV1, 2.7-IV2, 2.8-IV0, 2.8-IV1, 3.0-IV0, 3.0-IV1, 3.1-IV0, 3.2-IV0, 3.3-IV0, 3.3-IV1, 3.3-IV2, 3.3-IV3, 3.4-IV0, 3.5-IV0, 3.5-IV1, 3.5-IV2, 3.6-IV0, 3.6-IV1, 3.6-IV2] Importance: medium Update Mode: read-only -
log.message.timestamp.after.max.ms
此配置设置消息时间戳和代理时间戳之间允许的时间戳差异。消息时间戳可以晚于或等于代理的时间戳,最大允许差异由此配置中设置的值确定。如果 log.message.timestamp.type=CreateTime,则如果时间戳差异超过此指定阈值,消息将被拒绝。如果 log.message.timestamp.type=LogAppendTime,则忽略此配置。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.message.timestamp.before.max.ms
此配置设置代理时间戳和消息时间戳之间允许的时间戳差异。消息时间戳可以早于或等于代理的时间戳,最大允许差异由此配置中设置的值确定。如果 log.message.timestamp.type=CreateTime,则如果时间戳差异超过此指定阈值,消息将被拒绝。如果 log.message.timestamp.type=LogAppendTime,则忽略此配置。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.message.timestamp.difference.max.ms
[已弃用] 代理收到消息时的时间戳与消息中指定的时间戳之间允许的最大差异。如果 log.message.timestamp.type=CreateTime,则如果时间戳差异超过此阈值,消息将被拒绝。如果log.message.timestamp.type=LogAppendTime,则忽略此配置。允许的最大时间戳差异应不大于log.retention.ms,以避免不必要的频繁日志滚动。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
log.message.timestamp.type
定义消息中的时间戳是消息创建时间还是日志追加时间。该值应该是“CreateTime”或“LogAppendTime”。
Type: string Default: CreateTime Valid Values: [CreateTime, LogAppendTime] Importance: medium Update Mode: cluster-wide -
log.preallocate
创建新段时是否应该预先分配文件?如果您在 Windows 上使用 Kafka,则可能需要将其设置为 true。
Type: boolean Default: false Valid Values: Importance: medium Update Mode: cluster-wide -
log.retention.check.interval.ms
日志清理器检查是否有日志符合删除条件的频率(以毫秒为单位)
Type: long Default: 300000 (5 minutes) Valid Values: [1,...] Importance: medium Update Mode: read-only -
max.connection.creation.rate
我们在任何时候允许代理的最大连接创建速率。侦听器级别限制还可以通过在配置名称前添加侦听器前缀来配置,例如,
listener.name.internal.max.connection.creation.rate
应根据代理容量配置代理范围的连接速率限制,而应根据应用程序要求配置侦听器限制。如果达到侦听器或代理限制(代理间侦听器除外),新连接将受到限制。仅当达到侦听器级别的速率限制时,才会限制代理间侦听器上的连接。Type: int Default: 2147483647 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
max.connections
我们在任何时候允许代理的最大连接数。除了使用 max.connections.per.ip 配置的任何每 ip 限制之外,还应用此限制。侦听器级别限制也可以通过在配置名称前添加侦听器前缀来配置,例如
listener.name.internal.max.connections
. 代理范围的限制应根据代理容量进行配置,而侦听器限制应根据应用程序要求进行配置。如果达到侦听器或代理限制,则新连接将被阻止。即使达到代理范围的限制,也允许代理间侦听器上的连接。在这种情况下,另一个侦听器上最近最少使用的连接将被关闭。Type: int Default: 2147483647 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
max.connections.per.ip
我们允许来自每个 IP 地址的最大连接数。如果使用 max.connections.per.ip.overrides 属性配置了覆盖,则可以将其设置为 0。如果达到限制,来自该 IP 地址的新连接将被丢弃。
Type: int Default: 2147483647 Valid Values: [0,...] Importance: medium Update Mode: cluster-wide -
max.connections.per.ip.overrides
每个 IP 或主机名的逗号分隔列表将覆盖默认的最大连接数。示例值为“hostName:100,127.0.0.1:200”
Type: string Default: "" Valid Values: Importance: medium Update Mode: cluster-wide -
max.incremental.fetch.session.cache.slots
我们将维护的增量获取会话的最大数量。
Type: int Default: 1000 Valid Values: [0,...] Importance: medium Update Mode: read-only -
num.partitions
每个主题的默认日志分区数
Type: int Default: 1 Valid Values: [1,...] Importance: medium Update Mode: read-only -
password.encoder.old.secret
用于对动态配置的密码进行编码的旧秘密。仅当更新机密时才需要这样做。如果指定,所有动态编码的密码都将使用此旧密钥进行解码,并在代理启动时使用password.encoder.secret 重新编码。
Type: password Default: null Valid Values: Importance: medium Update Mode: read-only -
password.encoder.secret
用于编码该代理的动态配置密码的秘密。
Type: password Default: null Valid Values: Importance: medium Update Mode: read-only -
principal.builder.class
实现 KafkaPrincipalBuilder 接口的类的完全限定名称,用于构建授权期间使用的 KafkaPrincipal 对象。如果未定义主体构建器,则默认行为取决于所使用的安全协议。
ssl.principal.mapping.rules
对于 SSL 身份验证,将使用应用于客户端证书中的可分辨名称(如果提供了)定义的规则派生主体;否则,如果不需要客户端身份验证,则主体名称将为 ANONYMOUS。sasl.kerberos.principal.to.local.rules
对于 SASL 身份验证,如果使用 GSSAPI,将使用定义的规则派生主体,对于其他机制则使用 SASL 身份验证 ID。对于明文,主体将是匿名的。Type: class Default: org.apache.kafka.common.security.authenticator.DefaultKafkaPrincipalBuilder Valid Values: Importance: medium Update Mode: per-broker -
producer.purgatory.purge.interval.requests
生产者请求炼狱的清除间隔(以请求数为单位)
Type: int Default: 1000 Valid Values: Importance: medium Update Mode: read-only -
queued.max.request.bytes
在不再读取请求之前允许的排队字节数
Type: long Default: -1 Valid Values: Importance: medium Update Mode: read-only -
remote.log.manager.thread.pool.size
用于调度任务复制段、获取远程日志索引和清理远程日志段的线程池的大小。
Type: int Default: 10 Valid Values: [1,...] Importance: medium Update Mode: read-only -
remote.log.metadata.manager.class.name
`RemoteLogMetadataManager` 实现的完全限定类名。
Type: string Default: org.apache.kafka.server.log.remote.metadata.storage.TopicBasedRemoteLogMetadataManager Valid Values: non-empty string Importance: medium Update Mode: read-only -
remote.log.metadata.manager.class.path
`RemoteLogMetadataManager` 实现的类路径。如果指定,RemoteLogMetadataManager 实现及其依赖库将由专用类加载器加载,该类加载器在 Kafka 代理类路径之前搜索此类路径。该参数的语法与标准 Java 类路径字符串相同。
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
remote.log.metadata.manager.impl.prefix
用于传递给 RemoteLogMetadataManager 实现的属性的前缀。例如,该值可以是“rlmm.config”。
Type: string Default: rlmm.config. Valid Values: non-empty string Importance: medium Update Mode: read-only -
remote.log.metadata.manager.listener.name
如果 RemoteLogMetadataManager 实现需要,它应该连接到的本地代理的侦听器名称。
Type: string Default: null Valid Values: non-empty string Importance: medium Update Mode: read-only -
remote.log.reader.max.pending.tasks
最大远程日志读取器线程池任务队列大小。如果任务队列已满,则在处理获取请求时会出现错误。
Type: int Default: 100 Valid Values: [1,...] Importance: medium Update Mode: read-only -
remote.log.reader.threads
分配用于处理远程日志读取的线程池的大小。
Type: int Default: 10 Valid Values: [1,...] Importance: medium Update Mode: read-only -
remote.log.storage.manager.class.name
`RemoteStorageManager` 实现的完全限定类名。
Type: string Default: null Valid Values: non-empty string Importance: medium Update Mode: read-only -
remote.log.storage.manager.class.path
`RemoteStorageManager` 实现的类路径。如果指定,RemoteStorageManager 实现及其依赖库将由专用类加载器加载,该类加载器在 Kafka 代理类路径之前搜索此类路径。该参数的语法与标准 Java 类路径字符串相同。
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
remote.log.storage.manager.impl.prefix
用于传递给 RemoteStorageManager 实现的属性的前缀。例如,该值可以是“rsm.config”。
Type: string Default: rsm.config. Valid Values: non-empty string Importance: medium Update Mode: read-only -
remote.log.storage.system.enable
是否在代理中启用分层存储功能。有效值为“true”或“false”,默认值为 false。当它为 true 时,代理将启动分层存储功能所需的所有服务。
Type: boolean Default: false Valid Values: Importance: medium Update Mode: read-only -
replica.fetch.backoff.ms
发生获取分区错误时休眠的时间量。
Type: int Default: 1000 (1 second) Valid Values: [0,...] Importance: medium Update Mode: read-only -
replica.fetch.max.bytes
尝试为每个分区获取的消息字节数。这不是绝对最大值,如果提取的第一个非空分区中的第一个记录批次大于此值,仍然会返回该记录批次以确保可以取得进展。代理接受的最大记录批量大小是通过
message.max.bytes
(代理配置)或max.message.bytes
(主题配置)定义的。Type: int Default: 1048576 (1 mebibyte) Valid Values: [0,...] Importance: medium Update Mode: read-only -
replica.fetch.response.max.bytes
整个获取响应的预期最大字节数。记录是分批获取的,如果获取的第一个非空分区中的第一个记录批次大于该值,仍然会返回该记录批次以确保能够取得进展。因此,这不是绝对最大值。代理接受的最大记录批量大小是通过
message.max.bytes
(代理配置)或max.message.bytes
(主题配置)定义的。Type: int Default: 10485760 (10 mebibytes) Valid Values: [0,...] Importance: medium Update Mode: read-only -
replica.selector.class
实现 ReplicaSelector 的完全限定类名。代理使用它来查找首选只读副本。默认情况下,我们使用返回领导者的实现。
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
reserved.broker.max.id
Broker.id 可使用的最大数量
Type: int Default: 1000 Valid Values: [0,...] Importance: medium Update Mode: read-only -
sasl.client.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。
Type: class Default: null Valid Values: Importance: medium Update Mode: read-only -
sasl.enabled.mechanisms
Kafka 服务器中启用的 SASL 机制列表。该列表可以包含安全提供者可用的任何机制。默认情况下仅启用 GSSAPI。
Type: list Default: GSSAPI Valid Values: Importance: medium Update Mode: per-broker -
sasl.jaas.config
SASL 连接的 JAAS 登录上下文参数采用 JAAS 配置文件使用的格式。JAAS 配置文件格式描述如下。该值的格式为:
loginModuleClass controlFlag (optionName=optionValue)*;
。对于代理,配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,需要listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule;Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
sasl.kerberos.kinit.cmd
Kerberos kinit 命令路径。
Type: string Default: /usr/bin/kinit Valid Values: Importance: medium Update Mode: per-broker -
sasl.kerberos.min.time.before.relogin
刷新尝试之间的登录线程睡眠时间。
Type: long Default: 60000 Valid Values: Importance: medium Update Mode: per-broker -
sasl.kerberos.principal.to.local.rules
用于从主体名称映射到短名称(通常是操作系统用户名)的规则列表。规则按顺序进行评估,并且与主体名称匹配的第一条规则用于将其映射到短名称。列表中的任何后续规则都将被忽略。默认情况下,表单的主体名称
{username}/{hostname}@{REALM}
映射到{username}
. 有关格式的更多详细信息,请参阅安全授权和 acls。KafkaPrincipalBuilder
请注意,如果配置提供了 的扩展,则该配置将被忽略principal.builder.class
。Type: list Default: DEFAULT Valid Values: Importance: medium Update Mode: per-broker -
sasl.kerberos.service.name
Kafka 运行时使用的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 的配置中定义。
Type: string Default: null Valid Values: Importance: medium Update Mode: per-broker -
sasl.kerberos.ticket.renew.jitter
添加到更新时间的随机抖动的百分比。
Type: double Default: 0.05 Valid Values: Importance: medium Update Mode: per-broker -
sasl.kerberos.ticket.renew.window.factor
登录线程将休眠,直到达到从上次刷新到票证到期的指定时间窗口因子,此时它将尝试更新票证。
Type: double Default: 0.8 Valid Values: Importance: medium Update Mode: per-broker -
sasl.login.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理,登录回调处理程序配置必须以侦听器前缀和小写的 SASL 机制名称为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
Type: class Default: null Valid Values: Importance: medium Update Mode: read-only -
sasl.login.class
实现 Login 接口的类的完全限定名称。对于代理,登录配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
Type: class Default: null Valid Values: Importance: medium Update Mode: read-only -
sasl.login.refresh.buffer.seconds
刷新凭证时在凭证过期前维持的缓冲时间量(以秒为单位)。如果刷新发生的时间比缓冲秒数更接近到期,则刷新将向上移动以维持尽可能多的缓冲时间。合法值介于 0 到 3600(1 小时)之间;如果未指定值,则使用默认值 300(5 分钟)。如果该值和 sasl.login.refresh.min.period.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 300 Valid Values: Importance: medium Update Mode: per-broker -
sasl.login.refresh.min.period.seconds
登录刷新线程在刷新凭据之前等待的所需最短时间(以秒为单位)。合法值介于 0 到 900(15 分钟)之间;如果未指定值,则使用默认值 60(1 分钟)。如果该值和 sasl.login.refresh.buffer.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 60 Valid Values: Importance: medium Update Mode: per-broker -
sasl.login.refresh.window.factor
登录刷新线程将休眠,直到达到相对于凭证生命周期的指定窗口因子,此时它将尝试刷新凭证。合法值介于 0.5 (50%) 和 1.0 (100%)(含)之间;如果未指定值,则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.8 Valid Values: Importance: medium Update Mode: per-broker -
sasl.login.refresh.window.jitter
相对于添加到登录刷新线程睡眠时间的凭证生命周期的最大随机抖动量。合法值介于 0 和 0.25 (25%) 之间(含);如果未指定值,则使用默认值 0.05 (5%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.05 Valid Values: Importance: medium Update Mode: per-broker -
sasl.mechanism.inter.broker.protocol
SASL 机制用于代理间通信。默认为 GSSAPI。
Type: string Default: GSSAPI Valid Values: Importance: medium Update Mode: per-broker -
sasl.oauthbearer.jwks.endpoint.url
可以从中检索提供商的JWKS(JSON Web 密钥集)的 OAuth/OIDC 提供商 URL。URL 可以基于 HTTP(S) 或基于文件。如果 URL 基于 HTTP(S),则将通过代理启动时配置的 URL 从 OAuth/OIDC 提供程序检索 JWKS 数据。所有当时的密钥都将缓存在代理上以用于传入请求。如果收到 JWT 的身份验证请求,其中包含尚未在缓存中的“kid”标头声明值,则将根据需要再次查询 JWKS 端点。但是,代理会每隔 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒轮询一次 URL,以便在收到包含这些密钥的任何 JWT 请求之前使用任何即将到来的密钥刷新缓存。如果 URL 是基于文件的,代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含 JWKS 文件中不存在的“kid”标头值,代理将拒绝 JWT 并且身份验证将失败。
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
sasl.oauthbearer.token.endpoint.url
OAuth/OIDC 身份提供商的 URL。如果 URL 基于 HTTP(S),则它是颁发者的令牌端点 URL,将根据 sasl.jaas.config 中的配置发出登录请求。如果 URL 是基于文件的,则它指定一个包含 OAuth/OIDC 身份提供商颁发的访问令牌(JWT 序列化形式)的文件,用于授权。
Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
sasl.server.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 服务器回调处理程序类的完全限定名称。服务器回调处理程序必须以侦听器前缀和小写 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.plain.sasl.server.callback.handler.class=com.example.CustomPlainCallbackHandler。
Type: class Default: null Valid Values: Importance: medium Update Mode: read-only -
sasl.server.max.receive.size
初始 SASL 身份验证之前和期间允许的最大接收大小。默认接收大小为 512KB。GSSAPI 将请求限制为 64K,但对于自定义 SASL 机制,默认情况下我们允许最多 512KB。实际上,PLAIN、SCRAM 和 OAUTH 机制可以使用更小的限制。
Type: int Default: 524288 Valid Values: Importance: medium Update Mode: read-only -
security.inter.broker.protocol
用于经纪人之间通信的安全协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。同时设置 this 和 inter.broker.listener.name 属性是错误的。
Type: string Default: PLAINTEXT Valid Values: [PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL] Importance: medium Update Mode: read-only -
socket.connection.setup.timeout.max.ms
客户端等待建立套接字连接的最长时间。对于每个连续的连接失败,连接设置超时将呈指数增长,直至达到此最大值。为了避免连接风暴,将对超时应用 0.2 的随机化因子,从而产生比计算值低 20% 到高 20% 之间的随机范围。
Type: long Default: 30000 (30 seconds) Valid Values: Importance: medium Update Mode: read-only -
socket.connection.setup.timeout.ms
客户端等待建立套接字连接的时间。如果在超时之前未建立连接,客户端将关闭套接字通道。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: medium Update Mode: read-only -
socket.listen.backlog.size
套接字上挂起的连接的最大数量。在Linux中,您可能还需要相应配置`somaxconn`和`tcp_max_syn_backlog`内核参数才能使配置生效。
Type: int Default: 50 Valid Values: [1,...] Importance: medium Update Mode: read-only -
ssl.cipher.suites
密码套件列表。这是身份验证、加密、MAC 和密钥交换算法的命名组合,用于使用 TLS 或 SSL 网络协议协商网络连接的安全设置。默认情况下,支持所有可用的密码套件。
Type: list Default: "" Valid Values: Importance: medium Update Mode: per-broker -
ssl.client.auth
配置 kafka 代理来请求客户端身份验证。以下设置是常见的:
ssl.client.auth=required
如果设置为必需,则需要客户端身份验证。ssl.client.auth=requested
这意味着客户端身份验证是可选的。与必需的不同,如果设置了此选项,客户端可以选择不提供有关其自身的身份验证信息ssl.client.auth=none
这意味着不需要客户端身份验证。
Type: string Default: none Valid Values: [required, requested, none] Importance: medium Update Mode: per-broker -
ssl.enabled.protocols
为 SSL 连接启用的协议列表。使用 Java 11 或更高版本运行时,默认值为“TLSv1.2、TLSv1.3”,否则为“TLSv1.2”。使用 Java 11 的默认值,如果客户端和服务器都支持 TLSv1.3,则首选 TLSv1.3,否则回退到 TLSv1.2(假设两者至少支持 TLSv1.2)。对于大多数情况,此默认值应该没问题。另请参阅“ssl.protocol”的配置文档。
Type: list Default: TLSv1.2,TLSv1.3 Valid Values: Importance: medium Update Mode: per-broker -
ssl.key.password
密钥存储文件中私钥的密码或“ssl.keystore.key”中指定的 PEM 密钥的密码。
Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.keymanager.algorithm
密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。
Type: string Default: SunX509 Valid Values: Importance: medium Update Mode: per-broker -
ssl.keystore.certificate.chain
证书链采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 X.509 证书列表的 PEM 格式
Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.keystore.key
私钥采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 PKCS#8 密钥的 PEM 格式。如果密钥已加密,则必须使用“ssl.key.password”指定密钥密码
Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.keystore.location
密钥存储文件的位置。这对客户端来说是可选的,可用于客户端的双向身份验证。
Type: string Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.keystore.password
密钥存储文件的存储密码。这对于客户端来说是可选的,并且仅在配置了“ssl.keystore.location”时才需要。PEM 格式不支持密钥存储密码。
Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.keystore.type
密钥存储文件的文件格式。这对于客户来说是可选的。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium Update Mode: per-broker -
ssl.protocol
用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更高版本运行时,默认值为“TLSv1.3”,否则为“TLSv1.2”。该值对于大多数用例来说应该没问题。最新 JVM 中允许的值为“TLSv1.2”和“TLSv1.3”。较旧的 JVM 可能支持“TLS”、“TLSv1.1”、“SSL”、“SSLv2”和“SSLv3”,但由于已知的安全漏洞,不鼓励使用它们。使用此配置和“ssl.enabled.protocols”的默认值,如果服务器不支持“TLSv1.3”,客户端将降级到“TLSv1.2”。如果此配置设置为“TLSv1.2”,客户端将不会使用“TLSv1.3”,即使它是 ssl.enabled.protocols 中的值之一,并且服务器仅支持“TLSv1.3”。
Type: string Default: TLSv1.3 Valid Values: Importance: medium Update Mode: per-broker -
ssl.provider
用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
Type: string Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.trustmanager.algorithm
信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。
Type: string Default: PKIX Valid Values: Importance: medium Update Mode: per-broker -
ssl.truststore.certificates
采用“ssl.truststore.type”指定格式的受信任证书。默认 SSL 引擎工厂仅支持带有 X.509 证书的 PEM 格式。
Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.truststore.location
信任存储文件的位置。
Type: string Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.truststore.password
信任存储文件的密码。如果未设置密码,仍将使用配置的信任存储文件,但禁用完整性检查。PEM 格式不支持信任存储密码。
Type: password Default: null Valid Values: Importance: medium Update Mode: per-broker -
ssl.truststore.type
信任存储文件的文件格式。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium Update Mode: per-broker -
zookeeper.clientCnxnSocket
org.apache.zookeeper.ClientCnxnSocketNetty
通常在使用 TLS 连接到 ZooKeeper 时设置为。覆盖通过同名zookeeper.clientCnxnSocket
系统属性设置的任何显式值。Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.client.enable
设置客户端在连接到 ZooKeeper 时使用 TLS。显式值会覆盖通过
zookeeper.client.secure
系统属性设置的任何值(请注意不同的名称)。如果两者均未设置,则默认为 false;如果为 true,zookeeper.clientCnxnSocket
则必须设置(通常设置为org.apache.zookeeper.ClientCnxnSocketNetty
);要设置的其他值可能包括zookeeper.ssl.cipher.suites
,zookeeper.ssl.crl.enable
,zookeeper.ssl.enabled.protocols
,zookeeper.ssl.endpoint.identification.algorithm
,zookeeper.ssl.keystore.location
,zookeeper.ssl.keystore.password
,zookeeper.ssl.keystore.type
,zookeeper.ssl.ocsp.enable
,zookeeper.ssl.protocol
,zookeeper.ssl.truststore.location
,zookeeper.ssl.truststore.password
,zookeeper.ssl.truststore.type
Type: boolean Default: false Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.keystore.location
使用通过 TLS 连接到 ZooKeeper 的客户端证书时的密钥库位置。覆盖通过
zookeeper.ssl.keyStore.location
系统属性设置的任何显式值(注意驼峰命名法)。Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.keystore.password
使用通过 TLS 连接到 ZooKeeper 的客户端证书时的密钥库密码。覆盖通过
zookeeper.ssl.keyStore.password
系统属性设置的任何显式值(注意驼峰命名法)。请注意,ZooKeeper 不支持与 keystore 密码不同的密钥密码,因此请务必将 keystore 中的密钥密码设置为与 keystore 密码相同;否则与 Zookeeper 的连接尝试将失败。Type: password Default: null Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.keystore.type
使用通过 TLS 连接到 ZooKeeper 的客户端证书时的密钥库类型。覆盖通过
zookeeper.ssl.keyStore.type
系统属性设置的任何显式值(注意驼峰命名法)。默认值null
表示将根据密钥库的文件扩展名自动检测类型。Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.truststore.location
使用 TLS 连接到 ZooKeeper 时的信任库位置。覆盖通过
zookeeper.ssl.trustStore.location
系统属性设置的任何显式值(注意驼峰命名法)。Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.truststore.password
使用 TLS 连接到 ZooKeeper 时的信任库密码。覆盖通过
zookeeper.ssl.trustStore.password
系统属性设置的任何显式值(注意驼峰命名法)。Type: password Default: null Valid Values: Importance: medium Update Mode: read-only -
zookeeper.ssl.truststore.type
使用 TLS 连接到 ZooKeeper 时的信任库类型。覆盖通过
zookeeper.ssl.trustStore.type
系统属性设置的任何显式值(注意驼峰命名法)。默认值null
表示将根据信任库的文件扩展名自动检测类型。Type: string Default: null Valid Values: Importance: medium Update Mode: read-only -
alter.config.policy.class.name
应用于验证的更改配置策略类。该类应该实现该
org.apache.kafka.server.policy.AlterConfigPolicy
接口。Type: class Default: null Valid Values: Importance: low Update Mode: read-only -
alter.log.dirs.replication.quota.window.num
为更改日志目录复制配额而保留在内存中的样本数
Type: int Default: 11 Valid Values: [1,...] Importance: low Update Mode: read-only -
alter.log.dirs.replication.quota.window.size.seconds
alter log dirs 复制配额的每个样本的时间跨度
Type: int Default: 1 Valid Values: [1,...] Importance: low Update Mode: read-only -
authorizer.class.name
实现接口的类的完全限定名称
org.apache.kafka.server.authorizer.Authorizer
,代理使用它来进行授权。Type: string Default: "" Valid Values: non-null string Importance: low Update Mode: read-only -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low Update Mode: read-only -
client.quota.callback.class
实现 ClientQuotaCallback 接口的类的完全限定名称,用于确定应用于客户端请求的配额限制。默认情况下,应用存储在 ZooKeeper 中的 <user> 和 <client-id> 配额。对于任何给定的请求,将应用与会话的用户主体和请求的客户端 ID 匹配的最具体的配额。
Type: class Default: null Valid Values: Importance: low Update Mode: read-only -
connection.failed.authentication.delay.ms
身份验证失败时的连接关闭延迟:这是身份验证失败时连接关闭将延迟的时间(以毫秒为单位)。必须将其配置为小于connections.max.idle.ms,以防止连接超时。
Type: int Default: 100 Valid Values: [0,...] Importance: low Update Mode: read-only -
controller.quorum.retry.backoff.ms
尝试重试对给定主题分区的失败请求之前等待的时间。这避免了在某些故障场景下在紧密循环中重复发送请求。
Type: int Default: 20 Valid Values: Importance: low Update Mode: read-only -
controller.quota.window.num
控制器突变配额在内存中保留的样本数量
Type: int Default: 11 Valid Values: [1,...] Importance: low Update Mode: read-only -
controller.quota.window.size.seconds
控制器突变配额的每个样本的时间跨度
Type: int Default: 1 Valid Values: [1,...] Importance: low Update Mode: read-only -
create.topic.policy.class.name
创建应用于验证的主题策略类。该类应该实现该
org.apache.kafka.server.policy.CreateTopicPolicy
接口。Type: class Default: null Valid Values: Importance: low Update Mode: read-only -
delegation.token.expiry.check.interval.ms
扫描间隔以删除过期的委托令牌。
Type: long Default: 3600000 (1 hour) Valid Values: [1,...] Importance: low Update Mode: read-only -
kafka.metrics.polling.interval.secs
可在 kafka.metrics.reporters 实现中使用的指标轮询间隔(以秒为单位)。
Type: int Default: 10 Valid Values: [1,...] Importance: low Update Mode: read-only -
kafka.metrics.reporters
用作 Yammer 指标自定义报告器的类列表。记者要践行
kafka.metrics.KafkaMetricsReporter
特色。如果客户端想要在自定义报告器上公开 JMX 操作,则自定义报告器需要另外实现扩展特征的 MBean 特征,kafka.metrics.KafkaMetricsReporterMBean
以便注册的 MBean 符合标准 MBean 约定。Type: list Default: "" Valid Values: Importance: low Update Mode: read-only -
listener.security.protocol.map
侦听器名称和安全协议之间的映射。必须定义这一点,以便同一安全协议可在多个端口或 IP 中使用。例如,即使内部和外部流量都需要 SSL,也可以将两者分开。具体来说,用户可以定义名称为 INTERNAL 和 EXTERNAL 的侦听器,并将此属性定义为:“INTERNAL:SSL,EXTERNAL:SSL”。如图所示,键和值由冒号分隔,映射条目由逗号分隔。每个侦听器名称只能在地图中出现一次。通过向配置名称添加规范化前缀(侦听器名称小写),可以为每个侦听器配置不同的安全性(SSL 和 SASL)设置。例如,要为 INTERNAL 监听器设置不同的密钥库,
listener.name.internal.ssl.keystore.location
需要设置一个带有名称的配置。如果未设置侦听器名称的配置,该配置将回退到通用配置(即ssl.keystore.location
)。controller.listener.names
请注意,在 KRaft 中,如果未提供显式映射且未使用其他安全协议,则假定从 定义的侦听器名称到 PLAINTEXT 的默认映射。Type: string Default: PLAINTEXT:PLAINTEXT,SSL:SSL,SASL_PLAINTEXT:SASL_PLAINTEXT,SASL_SSL:SASL_SSL Valid Values: Importance: low Update Mode: per-broker -
log.message.downconversion.enable
该配置控制是否启用消息格式下转换以满足消费请求。当设置为 时
false
,代理将不会为期望旧消息格式的消费者执行向下转换。UNSUPPORTED_VERSION
对于来自此类较旧客户端的消费请求,代理会返回错误响应。此配置不适用于复制到关注者可能需要的任何消息格式转换。Type: boolean Default: true Valid Values: Importance: low Update Mode: cluster-wide -
metadata.max.idle.interval.ms
此配置控制活动控制器应将无操作记录写入元数据分区的频率。如果值为 0,则无操作记录不会附加到元数据分区。默认值为 500
Type: int Default: 500 Valid Values: [0,...] Importance: low Update Mode: read-only -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: "" Valid Values: Importance: low Update Mode: cluster-wide -
metrics.num.samples
为计算指标而维护的样本数量。
Type: int Default: 2 Valid Values: [1,...] Importance: low Update Mode: read-only -
metrics.recording.level
指标的最高记录级别。
Type: string Default: INFO Valid Values: Importance: low Update Mode: read-only -
metrics.sample.window.ms
计算指标样本的时间窗口。
Type: long Default: 30000 (30 seconds) Valid Values: [1,...] Importance: low Update Mode: read-only -
password.encoder.cipher.algorithm
用于对动态配置的密码进行编码的密码算法。
Type: string Default: AES/CBC/PKCS5Padding Valid Values: Importance: low Update Mode: read-only -
password.encoder.iterations
用于对动态配置的密码进行编码的迭代计数。
Type: int Default: 4096 Valid Values: [1024,...] Importance: low Update Mode: read-only -
password.encoder.key.length
用于对动态配置的密码进行编码的密钥长度。
Type: int Default: 128 Valid Values: [8,...] Importance: low Update Mode: read-only -
password.encoder.keyfactory.algorithm
SecretKeyFactory 算法用于对动态配置的密码进行编码。如果可用,默认值为 PBKDF2WithHmacSHA512,否则默认值为 PBKDF2WithHmacSHA1。
Type: string Default: null Valid Values: Importance: low Update Mode: read-only -
producer.id.expiration.ms
主题分区领导者在生产者 ID 过期之前等待的时间(以毫秒为单位)。当与其关联的交易仍在进行时,生产者 ID 不会过期。请注意,如果由于主题的保留设置而删除了生产者 ID 的最后一次写入,则生产者 ID 可能会更快过期。将此值设置为相同或更高
delivery.timeout.ms
可以帮助防止重试期间过期并防止消息重复,但默认值对于大多数用例来说应该是合理的。Type: int Default: 86400000 (1 day) Valid Values: [1,...] Importance: low Update Mode: cluster-wide -
quota.window.num
为客户端配额保留在内存中的样本数量
Type: int Default: 11 Valid Values: [1,...] Importance: low Update Mode: read-only -
quota.window.size.seconds
客户配额每个样本的时间跨度
Type: int Default: 1 Valid Values: [1,...] Importance: low Update Mode: read-only -
remote.log.manager.task.interval.ms
远程日志管理器运行计划任务(例如复制段和清理远程日志段)的时间间隔。
Type: long Default: 30000 (30 seconds) Valid Values: [1,...] Importance: low Update Mode: read-only -
remote.log.metadata.custom.metadata.max.bytes
代理应从远程存储插件接受的自定义元数据的最大大小(以字节为单位)。如果自定义元数据超过此限制,则不会存储更新的段元数据,将尝试删除复制的数据,并且此主题分区的远程复制任务将停止并出现错误。
Type: int Default: 128 Valid Values: [0,...] Importance: low Update Mode: read-only -
replication.quota.window.num
为了复制配额而保留在内存中的样本数量
Type: int Default: 11 Valid Values: [1,...] Importance: low Update Mode: read-only -
replication.quota.window.size.seconds
每个样本复制配额的时间跨度
Type: int Default: 1 Valid Values: [1,...] Importance: low Update Mode: read-only -
sasl.login.connect.timeout.ms
外部身份验证提供程序连接超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low Update Mode: read-only -
sasl.login.read.timeout.ms
外部身份验证提供程序读取超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low Update Mode: read-only -
sasl.login.retry.backoff.max.ms
尝试登录外部身份验证提供程序之间的最长等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low Update Mode: read-only -
sasl.login.retry.backoff.ms
尝试登录外部身份验证提供程序之间的初始等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 100 Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.clock.skew.seconds
以秒为单位的(可选)值,以允许 OAuth/OIDC 身份提供商和代理的时间之间存在差异。
Type: int Default: 30 Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.expected.audience
代理的(可选)逗号分隔设置,用于验证 JWT 是否是为预期受众之一颁发的。将检查 JWT 是否有标准 OAuth“aud”声明,如果设置了此值,代理将匹配 JWT 的“aud”声明中的值,以查看是否存在完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: list Default: null Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.expected.issuer
代理用于验证 JWT 是否由预期发行者创建的(可选)设置。将检查 JWT 是否有标准 OAuth“iss”声明,如果设置了该值,代理会将其与 JWT 的“iss”声明中的内容完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: string Default: null Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.jwks.endpoint.refresh.ms
代理在刷新其 JWKS(JSON Web 密钥集)缓存之间等待的(可选)值(以毫秒为单位),该缓存包含用于验证 JWT 签名的密钥。
Type: long Default: 3600000 (1 hour) Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms
尝试从外部身份验证提供程序检索 JWKS(JSON Web 密钥集)之间的最长等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.jwks.endpoint.retry.backoff.ms
来自外部身份验证提供程序的 JWKS(JSON Web 密钥集)检索尝试之间的初始等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 100 Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.scope.claim.name
该范围的 OAuth 声明通常被命名为“scope”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的范围提供不同的名称。
Type: string Default: scope Valid Values: Importance: low Update Mode: read-only -
sasl.oauthbearer.sub.claim.name
主题的 OAuth 声明通常命名为“sub”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的主题提供不同的名称。
Type: string Default: sub Valid Values: Importance: low Update Mode: read-only -
security.providers
可配置创建者类的列表,每个类返回一个实现安全算法的提供者。这些类应该实现该
org.apache.kafka.common.security.auth.SecurityProviderCreator
接口。Type: string Default: null Valid Values: Importance: low Update Mode: read-only -
ssl.endpoint.identification.algorithm
使用服务器证书验证服务器主机名的端点识别算法。
Type: string Default: https Valid Values: Importance: low Update Mode: per-broker -
ssl.engine.factory.class
org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory
Type: class Default: null Valid Values: Importance: low Update Mode: per-broker -
ssl.principal.mapping.rules
用于从客户端证书的专有名称映射到短名称的规则列表。规则按顺序进行评估,并且与主体名称匹配的第一条规则用于将其映射到短名称。列表中的任何后续规则都将被忽略。默认情况下,X.500 证书的专有名称将是主体。有关格式的更多详细信息,请参阅安全授权和 acls。请注意,如果配置提供了 KafkaPrincipalBuilder 的扩展,则此配置将被忽略
principal.builder.class
。Type: string Default: DEFAULT Valid Values: Importance: low Update Mode: read-only -
ssl.secure.random.implementation
用于 SSL 加密操作的 SecureRandom PRNG 实现。
Type: string Default: null Valid Values: Importance: low Update Mode: per-broker -
transaction.abort.timed.out.transaction.cleanup.interval.ms
回滚超时事务的时间间隔
Type: int Default: 10000 (10 seconds) Valid Values: [1,...] Importance: low Update Mode: read-only -
transaction.partition.verification.enable
启用验证,在将事务记录写入分区之前检查分区是否已添加到事务中
Type: boolean Default: true Valid Values: Importance: low Update Mode: cluster-wide -
transaction.remove.expired.transaction.cleanup.interval.ms
删除因过期而过期的交易的时间
transactional.id.expiration.ms
间隔Type: int Default: 3600000 (1 hour) Valid Values: [1,...] Importance: low Update Mode: read-only -
zookeeper.ssl.cipher.suites
指定要在 ZooKeeper TLS 协商 (csv) 中使用的已启用密码套件。覆盖通过系统属性设置的任何显式值
zookeeper.ssl.ciphersuites
(请注意单个词“密码套件”)。默认值null
表示启用的密码套件列表由正在使用的 Java 运行时确定。Type: list Default: null Valid Values: Importance: low Update Mode: read-only -
zookeeper.ssl.crl.enable
指定是否在 ZooKeeper TLS 协议中启用证书吊销列表。覆盖通过系统属性设置的任何显式值
zookeeper.ssl.crl
(注意较短的名称)。Type: boolean Default: false Valid Values: Importance: low Update Mode: read-only -
zookeeper.ssl.enabled.protocols
指定 ZooKeeper TLS 协商 (csv) 中启用的协议。覆盖通过
zookeeper.ssl.enabledProtocols
系统属性设置的任何显式值(注意驼峰命名法)。默认值null
表示启用的协议将是配置属性的值zookeeper.ssl.protocol
。Type: list Default: null Valid Values: Importance: low Update Mode: read-only -
zookeeper.ssl.endpoint.identification.algorithm
指定是否在 ZooKeeper TLS 协商过程中启用主机名验证,(不区分大小写)“https”表示启用 ZooKeeper 主机名验证,显式空白值表示禁用它(仅建议出于测试目的禁用它)。显式值会覆盖通过系统属性设置的任何“true”或“false”值
zookeeper.ssl.hostnameVerification
(请注意不同的名称和值;true 表示 https,false 表示空白)。Type: string Default: HTTPS Valid Values: Importance: low Update Mode: read-only -
zookeeper.ssl.ocsp.enable
指定是否在 ZooKeeper TLS 协议中启用在线证书状态协议。覆盖通过系统属性设置的任何显式值
zookeeper.ssl.ocsp
(注意较短的名称)。Type: boolean Default: false Valid Values: Importance: low Update Mode: read-only -
zookeeper.ssl.protocol
指定 ZooKeeper TLS 协商中使用的协议。显式值会覆盖通过同名
zookeeper.ssl.protocol
系统属性设置的任何值。Type: string Default: TLSv1.2 Valid Values: Importance: low Update Mode: read-only
有关代理配置的更多详细信息可以在 scala 类中找到kafka.server.KafkaConfig
。
3.1.1 更新代理配置
从 Kafka 1.1 版开始,一些代理配置可以在不重新启动代理的情况下更新。每个 Broker 配置的更新模式 请参见 Broker ConfigsDynamic Update Mode
栏目。read-only
:需要重启代理才能更新per-broker
:可能会针对每个经纪商动态更新cluster-wide
:可以作为集群范围内的默认值动态更新。也可以更新为每个经纪商的测试值。
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-name 0 --alter --add-config log.cleaner.threads=2
描述代理 ID 0 的当前动态代理配置:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-name 0 --describe
要删除配置覆盖并恢复为代理 ID 0 的静态配置或默认值(例如,日志清理器线程数):
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-name 0 --alter --delete-config log.cleaner.threads
某些配置可以配置为集群范围内的默认值,以在整个集群中保持一致的值。集群中的所有代理都会处理集群默认更新。例如,要更新所有代理上的日志清理线程:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --alter --add-config log.cleaner.threads=2
描述当前配置的动态集群范围默认配置:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers --entity-default --describe
所有可在集群级别配置的配置也可以在每个代理级别配置(例如用于测试)。如果在不同级别定义配置值,则使用以下优先顺序:
- 存储在 ZooKeeper 中的动态每个代理配置
- 存储在 ZooKeeper 中的动态集群范围默认配置
- 静态代理配置来自
server.properties
- Kafka 默认,请参阅代理配置
动态更新密码配置
动态更新的密码配置值在存储到 ZooKeeper 之前会被加密。password.encoder.secret
必须配置代理配置
server.properties
才能启用密码配置的动态更新。不同经纪商的秘密可能不同。
用于密码编码的秘密可以随着代理的滚动重启而轮换。当前在 ZooKeeper 中用于编码密码的旧密钥必须在静态代理配置中提供password.encoder.old.secret
,新密钥必须在password.encoder.secret
. 当代理启动时,ZooKeeper 中存储的所有动态密码配置都将使用新密钥重新编码。
kafka-configs.sh
在 Kafka 1.1.x 中,即使密码配置未更改,在更新配置时也必须在每个更改请求中提供所有动态更新的密码配置。此限制将在未来版本中删除。
在启动 Broker 之前更新 ZooKeeper 中的密码配置
从 Kafka 2.0.0 开始,kafka-configs.sh
在启动代理进行引导之前,可以使用 ZooKeeper 更新动态代理配置。这使得所有密码配置都能够以加密形式存储,从而避免了在server.properties
. password.encoder.secret
如果 alter 命令中包含任何密码配置,则还必须指定代理配置。还可以指定附加的加密参数。密码编码器配置不会保留在 ZooKeeper 中。例如,要存储INTERNAL
代理 0 上侦听器的 SSL 密钥密码:
> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --entity-type brokers --entity-name 0 --alter --add-config
'listener.name.internal.ssl.key.password=key-password,password.encoder.secret=secret,password.encoder.iterations=8192'
配置listener.name.internal.ssl.key.password
将使用提供的编码器配置以加密形式保存在 ZooKeeper 中。编码器秘密和迭代不会保留在 ZooKeeper 中。
更新现有侦听器的 SSL 密钥库
代理可以配置有效期较短的 SSL 密钥库,以降低证书受损的风险。密钥库可以动态更新,无需重新启动代理。配置名称必须以侦听器前缀作为前缀listener.name.{listenerName}.
,以便仅更新特定侦听器的密钥库配置。以下配置可以在每个代理级别的单个更改请求中更新:
ssl.keystore.type
ssl.keystore.location
ssl.keystore.password
ssl.key.password
更新现有侦听器的 SSL 信任库
代理信任库可以动态更新,无需重新启动代理来添加或删除证书。更新后的信任库将用于验证新的客户端连接。配置名称必须以侦听器前缀作为前缀listener.name.{listenerName}.
,以便仅更新特定侦听器的信任库配置。以下配置可以在每个代理级别的单个更改请求中更新:
ssl.truststore.type
ssl.truststore.location
ssl.truststore.password
更新默认主题配置
代理使用的默认主题配置选项可以在不重新启动代理的情况下更新。这些配置适用于没有主题配置覆盖的主题,以实现等效的每个主题配置。这些配置中的一项或多项可能会在所有代理使用的集群默认级别上被覆盖。log.segment.bytes
log.roll.ms
log.roll.hours
log.roll.jitter.ms
log.roll.jitter.hours
log.index.size.max.bytes
log.flush.interval.messages
log.flush.interval.ms
log.retention.bytes
log.retention.ms
log.retention.minutes
log.retention.hours
log.index.interval.bytes
log.cleaner.delete.retention.ms
log.cleaner.min.compaction.lag.ms
log.cleaner.max.compaction.lag.ms
log.cleaner.min.cleanable.ratio
log.cleanup.policy
log.segment.delete.delay.ms
unclean.leader.election.enable
min.insync.replicas
max.message.bytes
compression.type
log.preallocate
log.message.timestamp.type
log.message.timestamp.difference.max.ms
unclean.leader.election.enable
从 Kafka 2.0.0 版本开始,当配置动态更新
时,控制器会自动启用不干净的领导者选举
。在 Kafka 1.1.x 版本中,更改unclean.leader.election.enable
仅在选举出新控制器时才会生效。可以通过运行以下命令强制控制器重新选举:
> bin/zookeeper-shell.sh localhost
rmr /controller
更新日志清理器配置
日志清理器配置可以在所有代理使用的集群默认级别动态更新。这些更改将在下一次日志清理迭代中生效。可能会更新其中一项或多项配置:log.cleaner.threads
log.cleaner.io.max.bytes.per.second
log.cleaner.dedupe.buffer.size
log.cleaner.io.buffer.size
log.cleaner.io.buffer.load.factor
log.cleaner.backoff.ms
更新线程配置
代理使用的各种线程池的大小可以在所有代理使用的集群默认级别动态更新。更新限制在一定范围内,currentSize / 2
以currentSize * 2
确保配置更新得到妥善处理。
num.network.threads
num.io.threads
num.replica.fetchers
num.recovery.threads.per.data.dir
log.cleaner.threads
background.threads
更新 ConnectionQuota 配置
代理允许给定 IP/主机的最大连接数可以在所有代理使用的集群默认级别动态更新。这些更改将应用于新的连接创建,并且新的限制将考虑现有连接计数。max.connections.per.ip
max.connections.per.ip.overrides
添加和删除监听器
监听器可以动态添加或删除。添加新侦听器时,必须将侦听器的安全配置提供为带有侦听器前缀的侦听器配置listener.name.{listenerName}.
。如果新侦听器使用 SASL,则必须使用带有侦听器和机制前缀的 JAAS 配置属性来提供侦听器的 JAAS 配置sasl.jaas.config
。有关详细信息,请参阅Kafka 代理的 JAAS 配置。
在Kafka 1.1.x版本中,代理间监听器使用的监听器可能不会动态更新。为了将代理间侦听器更新为新侦听器,可以在所有代理上添加新侦听器,而无需重新启动代理。然后需要滚动重新启动才能更新inter.broker.listener.name
。
listeners
advertised.listeners
listener.security.protocol.map
inter.broker.listener.name
或security.inter.broker.protocol
.
3.2 主题级配置
与主题相关的配置既有服务器默认值,也有可选的每个主题覆盖。如果没有给出每个主题的配置,则使用服务器默认值。可以在主题创建时通过提供一个或多个选项来设置覆盖--config
。此示例创建一个名为my-topic 的主题,具有自定义最大消息大小和刷新率:
> bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic my-topic --partitions 1 \
--replication-factor 1 --config max.message.bytes=64000 --config flush.messages=1
也可以稍后使用 alter configs 命令更改或设置覆盖。此示例更新my-topic的最大消息大小:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name my-topic
--alter --add-config max.message.bytes=128000
要检查主题上设置的覆盖,您可以执行以下操作
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name my-topic --describe
要删除覆盖,您可以执行以下操作
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --entity-type topics --entity-name my-topic
--alter --delete-config max.message.bytes
以下是主题级别的配置。服务器对此属性的默认配置在“服务器默认属性”标题下给出。给定的服务器默认配置值仅适用于没有显式主题配置覆盖的主题。
-
cleanup.policy
此配置指定在日志段上使用的保留策略。当达到保留时间或大小限制时,“删除”策略(默认)将丢弃旧段。“compact”策略将启用日志压缩,它保留每个键的最新值。也可以在逗号分隔的列表中指定这两个策略(例如“delete,compact”)。在这种情况下,旧的段将根据保留时间和大小配置被丢弃,而保留的段将被压缩。
Type: list Default: delete Valid Values: [compact, delete] Server Default Property: log.cleanup.policy Importance: medium -
compression.type
指定给定主题的最终压缩类型。此配置接受标准压缩编解码器('gzip'、'snappy'、'lz4'、'zstd')。它还接受“未压缩”,这相当于不压缩;“生产者”表示保留生产者设置的原始压缩编解码器。
Type: string Default: producer Valid Values: [uncompressed, zstd, lz4, snappy, gzip, producer] Server Default Property: compression.type Importance: medium -
delete.retention.ms
为日志压缩主题保留删除逻辑删除标记的时间量。此设置还规定了消费者必须完成读取的时间限制(如果消费者从偏移量 0 开始),以确保他们获得最后阶段的有效快照(否则可能会在完成扫描之前收集删除逻辑删除)。
Type: long Default: 86400000 (1 day) Valid Values: [0,...] Server Default Property: log.cleaner.delete.retention.ms Importance: medium -
file.delete.delay.ms
从文件系统中删除文件之前等待的时间
Type: long Default: 60000 (1 minute) Valid Values: [0,...] Server Default Property: log.segment.delete.delay.ms Importance: medium -
flush.messages
此设置允许指定强制同步写入日志的数据的时间间隔。例如,如果将其设置为 1,我们将在每条消息之后进行 fsync;如果是 5,我们将在每 5 条消息后进行 fsync。一般来说,我们建议您不要设置此项并使用复制来实现持久性,并允许操作系统的后台刷新功能,因为它更高效。可以根据每个主题覆盖此设置(请参阅每个主题配置部分)。
Type: long Default: 9223372036854775807 Valid Values: [1,...] Server Default Property: log.flush.interval.messages Importance: medium -
flush.ms
此设置允许指定强制同步写入日志的数据的时间间隔。例如,如果将其设置为 1000,我们将在 1000 毫秒过去后进行 fsync。一般来说,我们建议您不要设置此项并使用复制来实现持久性,并允许操作系统的后台刷新功能,因为它更高效。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Server Default Property: log.flush.interval.ms Importance: medium -
follower.replication.throttled.replicas
应在从属端限制其日志复制的副本列表。该列表应以 [PartitionId]:[BrokerId],[PartitionId]:[BrokerId]:... 的形式描述一组副本,或者可以使用通配符“*”来限制该主题的所有副本。
Type: list Default: "" Valid Values: [partitionId]:[brokerId],[partitionId]:[brokerId],... Server Default Property: null Importance: medium -
index.interval.bytes
此设置控制 Kafka 将索引条目添加到其偏移索引的频率。默认设置确保我们大约每 4096 字节索引一条消息。更多索引允许读取跳转到更接近日志中的确切位置,但会使索引更大。您可能不需要更改此设置。
Type: int Default: 4096 (4 kibibytes) Valid Values: [0,...] Server Default Property: log.index.interval.bytes Importance: medium -
leader.replication.throttled.replicas
应在领导者端限制其日志复制的副本列表。该列表应以 [PartitionId]:[BrokerId],[PartitionId]:[BrokerId]:... 的形式描述一组副本,或者可以使用通配符“*”来限制该主题的所有副本。
Type: list Default: "" Valid Values: [partitionId]:[brokerId],[partitionId]:[brokerId],... Server Default Property: null Importance: medium -
local.retention.bytes
在删除旧段之前分区可以增长的本地日志段的最大大小。默认值为-2,它表示要使用的“retention.bytes”值。有效值应始终小于或等于“retention.bytes”值。
Type: long Default: -2 Valid Values: [-2,...] Server Default Property: log.local.retention.bytes Importance: medium -
local.retention.ms
本地日志段被删除之前保留的毫秒数。默认值为-2,表示要使用“retention.ms”值。有效值应始终小于或等于“retention.ms”值。
Type: long Default: -2 Valid Values: [-2,...] Server Default Property: log.local.retention.ms Importance: medium -
max.compaction.lag.ms
消息在日志中不符合压缩条件的最长时间。仅适用于正在压缩的日志。
Type: long Default: 9223372036854775807 Valid Values: [1,...] Server Default Property: log.cleaner.max.compaction.lag.ms Importance: medium -
max.message.bytes
Kafka 允许的最大记录批量大小(如果启用压缩,则在压缩后)。如果增加此值并且存在早于 0.10.2 的消费者,则消费者的获取大小也必须增加,以便他们可以获取这么大的记录批次。在最新的消息格式版本中,为了提高效率,记录总是分组为批次。在以前的消息格式版本中,未压缩的记录不会分组为批次,并且此限制仅适用于这种情况下的单个记录。
Type: int Default: 1048588 Valid Values: [0,...] Server Default Property: message.max.bytes Importance: medium -
message.format.version
[已弃用] 指定代理将用于将消息附加到日志的消息格式版本。如果“inter.broker.protocol.version”为 3.0 或更高,则此配置的值始终假定为“3.0”(忽略实际配置值)。否则,该值应该是有效的 ApiVersion。一些示例是:0.10.0、1.1、2.8、3.0。通过设置特定的消息格式版本,用户可以证明磁盘上的所有现有消息都小于或等于指定的版本。错误地设置此值将导致使用旧版本的消费者崩溃,因为他们将收到他们不理解的格式的消息。
Type: string Default: 3.0-IV1 Valid Values: [0.8.0, 0.8.1, 0.8.2, 0.9.0, 0.10.0-IV0, 0.10.0-IV1, 0.10.1-IV0, 0.10.1-IV1, 0.10.1-IV2, 0.10.2-IV0, 0.11.0-IV0, 0.11.0-IV1, 0.11.0-IV2, 1.0-IV0, 1.1-IV0, 2.0-IV0, 2.0-IV1, 2.1-IV0, 2.1-IV1, 2.1-IV2, 2.2-IV0, 2.2-IV1, 2.3-IV0, 2.3-IV1, 2.4-IV0, 2.4-IV1, 2.5-IV0, 2.6-IV0, 2.7-IV0, 2.7-IV1, 2.7-IV2, 2.8-IV0, 2.8-IV1, 3.0-IV0, 3.0-IV1, 3.1-IV0, 3.2-IV0, 3.3-IV0, 3.3-IV1, 3.3-IV2, 3.3-IV3, 3.4-IV0, 3.5-IV0, 3.5-IV1, 3.5-IV2, 3.6-IV0, 3.6-IV1, 3.6-IV2] Server Default Property: log.message.format.version Importance: medium -
message.timestamp.after.max.ms
此配置设置消息时间戳和代理时间戳之间允许的时间戳差异。消息时间戳可以晚于或等于代理的时间戳,最大允许差异由此配置中设置的值确定。如果 message.timestamp.type=CreateTime,则如果时间戳差异超过此指定阈值,消息将被拒绝。如果 message.timestamp.type=LogAppendTime,则忽略此配置。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Server Default Property: log.message.timestamp.after.max.ms Importance: medium -
message.timestamp.before.max.ms
此配置设置代理时间戳和消息时间戳之间允许的时间戳差异。消息时间戳可以早于或等于代理的时间戳,最大允许差异由此配置中设置的值确定。如果 message.timestamp.type=CreateTime,则如果时间戳差异超过此指定阈值,消息将被拒绝。如果 message.timestamp.type=LogAppendTime,则忽略此配置。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Server Default Property: log.message.timestamp.before.max.ms Importance: medium -
message.timestamp.difference.max.ms
[已弃用] 代理收到消息时的时间戳与消息中指定的时间戳之间允许的最大差异。如果message.timestamp.type=CreateTime,则如果时间戳差异超过此阈值,消息将被拒绝。如果 message.timestamp.type=LogAppendTime,则忽略此配置。
Type: long Default: 9223372036854775807 Valid Values: [0,...] Server Default Property: log.message.timestamp.difference.max.ms Importance: medium -
message.timestamp.type
定义消息中的时间戳是消息创建时间还是日志追加时间。该值应该是“CreateTime”或“LogAppendTime”
Type: string Default: CreateTime Valid Values: [CreateTime, LogAppendTime] Server Default Property: log.message.timestamp.type Importance: medium -
min.cleanable.dirty.ratio
此配置控制日志压缩器尝试清理日志的频率(假设启用了日志压缩)。默认情况下,我们将避免清理超过 50% 的日志已被压缩的日志。此比率限制了日志中因重复项而浪费的最大空间(日志的 50% 至多 50% 可能是重复项)。较高的比率意味着更少、更有效的清理,但也意味着日志中浪费的空间更多。如果还指定了 max.compaction.lag.ms 或 min.compaction.lag.ms 配置,则只要满足以下任一条件,日志压缩器就会认为日志符合压缩条件: (i) 满足脏率阈值并且日志在至少 min.compaction.lag.ms 持续时间内有脏(未压缩)记录,或者 (ii) 如果日志在最多 max.compaction.lag.ms 时间内有脏(未压缩)记录。
Type: double Default: 0.5 Valid Values: [0,...,1] Server Default Property: log.cleaner.min.cleanable.ratio Importance: medium -
min.compaction.lag.ms
消息在日志中保持未压缩状态的最短时间。仅适用于正在压缩的日志。
Type: long Default: 0 Valid Values: [0,...] Server Default Property: log.cleaner.min.compaction.lag.ms Importance: medium -
min.insync.replicas
当生产者将 acks 设置为“all”(或“-1”)时,此配置指定必须确认写入才能被视为成功的最小副本数。如果无法满足此最小值,则生产者将引发异常(NotEnoughReplicas 或 NotEnoughReplicasAfterAppend)。
一起使用时,min.insync.replicas
可以acks
让您强制执行更大的耐用性保证。典型的场景是创建一个复制因子为 3 的主题,设置min.insync.replicas
为 2,并使用acks
“all”进行生成。这将确保生产者在大多数副本未收到写入时引发异常。Type: int Default: 1 Valid Values: [1,...] Server Default Property: min.insync.replicas Importance: medium -
preallocate
如果我们在创建新日志段时应该在磁盘上预分配文件,则为 true。
Type: boolean Default: false Valid Values: Server Default Property: log.preallocate Importance: medium -
remote.storage.enable
要为主题启用分层存储,请将此配置设置为 true。一旦启用此配置,您将无法禁用它。它将在未来版本中提供。
Type: boolean Default: false Valid Values: Server Default Property: null Importance: medium -
retention.bytes
如果我们使用“删除”保留策略,此配置控制分区(由日志段组成)在我们丢弃旧日志段以释放空间之前可以增长到的最大大小。默认情况下,没有大小限制,只有时间限制。由于此限制是在分区级别强制实施的,因此将其乘以分区数即可计算主题保留时间(以字节为单位)。
Type: long Default: -1 Valid Values: Server Default Property: log.retention.bytes Importance: medium -
retention.ms
如果我们使用“删除”保留策略,此配置控制我们在丢弃旧日志段以释放空间之前保留日志的最长时间。这代表了关于消费者必须多快读取其数据的 SLA。如果设置为 -1,则不应用时间限制。
Type: long Default: 604800000 (7 days) Valid Values: [-1,...] Server Default Property: log.retention.ms Importance: medium -
segment.bytes
此配置控制日志的段文件大小。保留和清理总是一次对一个文件进行,因此较大的段大小意味着文件较少,但对保留的粒度控制较小。
Type: int Default: 1073741824 (1 gibibyte) Valid Values: [14,...] Server Default Property: log.segment.bytes Importance: medium -
segment.index.bytes
此配置控制将偏移量映射到文件位置的索引的大小。我们预先分配该索引文件,并仅在日志滚动后收缩它。您通常不需要更改此设置。
Type: int Default: 10485760 (10 mebibytes) Valid Values: [4,...] Server Default Property: log.index.size.max.bytes Importance: medium -
segment.jitter.ms
从预定的分段滚动时间中减去最大随机抖动,以避免分段滚动的雷群
Type: long Default: 0 Valid Values: [0,...] Server Default Property: log.roll.jitter.ms Importance: medium -
segment.ms
此配置控制一段时间后,即使段文件未满,Kafka也会强制日志滚动,以确保保留可以删除或压缩旧数据。
Type: long Default: 604800000 (7 days) Valid Values: [1,...] Server Default Property: log.roll.ms Importance: medium -
unclean.leader.election.enable
指示是否将不在 ISR 集中的副本作为最后手段选举为领导者,即使这样做可能会导致数据丢失。
Type: boolean Default: false Valid Values: Server Default Property: unclean.leader.election.enable Importance: medium -
message.downconversion.enable
该配置控制是否启用消息格式下转换以满足消费请求。当设置为 时
false
,代理将不会为期望旧消息格式的消费者执行向下转换。UNSUPPORTED_VERSION
对于来自此类较旧客户端的消费请求,代理会返回错误响应。此配置不适用于复制到关注者可能需要的任何消息格式转换。Type: boolean Default: true Valid Values: Server Default Property: log.message.downconversion.enable Importance: low
3.3 生产者配置
下面是生产者的配置:-
key.serializer
实现该
org.apache.kafka.common.serialization.Serializer
接口的键的序列化器类。Type: class Default: Valid Values: Importance: high -
value.serializer
实现
org.apache.kafka.common.serialization.Serializer
接口的值的序列化器类。Type: class Default: Valid Values: Importance: high -
bootstrap.servers
用于建立与 Kafka 集群的初始连接的主机/端口对列表。客户端将使用所有服务器,无论此处指定哪些服务器进行引导 - 该列表仅影响用于发现全套服务器的初始主机。该列表应采用以下形式
host1:port1,host2:port2,...
。由于这些服务器仅用于初始连接以发现完整的集群成员资格(可能会动态更改),因此此列表不需要包含完整的服务器集(不过,您可能需要多个服务器,以防服务器停机) 。Type: list Default: "" Valid Values: non-null string Importance: high -
buffer.memory
生产者可用于缓冲等待发送到服务器的记录的内存总字节数。如果记录的发送速度快于传送到服务器的速度,生产者将阻塞,
max.block.ms
然后抛出异常。此设置应大致对应于生产者将使用的总内存,但不是硬限制,因为并非生产者使用的所有内存都用于缓冲。一些额外的内存将用于压缩(如果启用压缩)以及维护正在进行的请求。
Type: long Default: 33554432 Valid Values: [0,...] Importance: high -
compression.type
生产者生成的所有数据的压缩类型。默认值为无(即不压缩)。有效值为
none
、gzip
、snappy
、lz4
或zstd
。压缩是对整批数据进行压缩,因此批处理的效果也会影响压缩率(批处理越多意味着压缩效果越好)。Type: string Default: none Valid Values: [none, gzip, snappy, lz4, zstd] Importance: high -
retries
设置大于零的值将导致客户端重新发送发送失败并可能出现暂时性错误的任何记录。请注意,此重试与客户端在收到错误后重新发送记录没有什么不同。
delivery.timeout.ms
如果在成功确认之前配置的超时时间先到期,则在重试次数用完之前,生产请求将失败。用户通常应该更愿意保留此配置未设置,而是用于delivery.timeout.ms
控制重试行为。启用幂等性要求此配置值大于 0。如果设置了冲突的配置并且未显式启用幂等性,则幂等性将被禁用。
在设置
enable.idempotence
为1false
或max.in.flight.requests.per.connection
大于 1 时允许重试可能会更改记录的顺序,因为如果将两个批次发送到单个分区,并且第一个批次失败并重试,但第二个成功,则第二个批次中的记录可能会先出现。Type: int Default: 2147483647 Valid Values: [0,...,2147483647] Importance: high -
ssl.key.password
密钥存储文件中私钥的密码或“ssl.keystore.key”中指定的 PEM 密钥的密码。
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.certificate.chain
证书链采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 X.509 证书列表的 PEM 格式
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.key
私钥采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 PKCS#8 密钥的 PEM 格式。如果密钥已加密,则必须使用“ssl.key.password”指定密钥密码
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.location
密钥存储文件的位置。这对客户端来说是可选的,可用于客户端的双向身份验证。
Type: string Default: null Valid Values: Importance: high -
ssl.keystore.password
密钥存储文件的存储密码。这对于客户端来说是可选的,并且仅在配置了“ssl.keystore.location”时才需要。PEM 格式不支持密钥存储密码。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.certificates
采用“ssl.truststore.type”指定格式的受信任证书。默认 SSL 引擎工厂仅支持带有 X.509 证书的 PEM 格式。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.location
信任存储文件的位置。
Type: string Default: null Valid Values: Importance: high -
ssl.truststore.password
信任存储文件的密码。如果未设置密码,仍将使用配置的信任存储文件,但禁用完整性检查。PEM 格式不支持信任存储密码。
Type: password Default: null Valid Values: Importance: high -
batch.size
每当多个记录发送到同一分区时,生产者将尝试将记录一起批处理为更少的请求。这有助于提高客户端和服务器的性能。此配置控制默认批量大小(以字节为单位)。
不会尝试批量记录大于此大小的记录。
发送到代理的请求将包含多个批次,每个批次对应一个可发送数据的分区。
小批量大小将使批处理不太常见,并且可能会降低吞吐量(批量大小为零将完全禁用批处理)。非常大的批处理大小可能会更加浪费内存,因为我们总是会分配指定批处理大小的缓冲区以应对额外的记录。
注意:此设置给出了要发送的批量大小的上限。如果该分区累积的字节数少于这么多,我们将“徘徊”一段时间,
linger.ms
等待更多记录显示。此linger.ms
设置默认为 0,这意味着即使累积的批量大小低于此设置,我们也会立即发送一条记录batch.size
。Type: int Default: 16384 Valid Values: [0,...] Importance: medium -
client.dns.lookup
控制客户端如何使用 DNS 查找。如果设置为
use_all_dns_ips
,则按顺序连接每个返回的 IP 地址,直到建立成功连接。断开连接后,将使用下一个 IP。一旦所有 IP 使用一次,客户端就会再次从主机名解析 IP(但是 JVM 和操作系统都会缓存 DNS 名称查找)。如果设置为resolve_canonical_bootstrap_servers_only
,则将每个引导地址解析为规范名称列表。在引导阶段之后,其行为与 相同use_all_dns_ips
。Type: string Default: use_all_dns_ips Valid Values: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only] Importance: medium -
client.id
发出请求时传递给服务器的 id 字符串。这样做的目的是通过允许在服务器端请求日志记录中包含逻辑应用程序名称,能够跟踪 IP/端口之外的请求源。
Type: string Default: "" Valid Values: Importance: medium -
connections.max.idle.ms
在该配置指定的毫秒数后关闭空闲连接。
Type: long Default: 540000 (9 minutes) Valid Values: Importance: medium -
delivery.timeout.ms
调用返回后报告成功或失败的时间上限
send()
。这限制了记录在发送之前延迟的总时间、等待代理确认的时间(如果预期)以及允许重试发送失败的时间。如果遇到不可恢复的错误、重试次数已用完或者记录被添加到达到较早交付到期期限的批次,生产者可能会报告无法发送早于此配置的记录。此配置的值应大于或等于request.timeout.ms
和的总和linger.ms
。Type: int Default: 120000 (2 minutes) Valid Values: [0,...] Importance: medium -
linger.ms
生产者将请求传输之间到达的所有记录分组到单个批处理请求中。通常,只有在负载情况下,当记录到达速度快于发送速度时,才会发生这种情况。然而,在某些情况下,即使在中等负载下,客户端也可能希望减少请求数量。此设置通过添加少量人为延迟来实现此目的 - 也就是说,生产者不会立即发送记录,而是等待给定的延迟以允许发送其他记录,以便可以将发送分批在一起。这可以被认为类似于 TCP 中的 Nagle 算法。此设置给出了批处理延迟的上限:一旦我们获得了
batch.size
分区的记录价值,无论此设置如何,它都会立即发送,但是如果我们为该分区累积的字节数少于这么多,我们将“徘徊”一段时间等待更多记录显示的指定时间。该设置默认为 0(即无延迟)。例如,设置linger.ms=5
可以减少发送的请求数量,但会在没有负载的情况下为发送的记录增加最多 5 毫秒的延迟。Type: long Default: 0 Valid Values: [0,...] Importance: medium -
max.block.ms
KafkaProducer
配置控制send()
、partitionsFor()
、initTransactions()
、sendOffsetsToTransaction()
和commitTransaction()
方法将阻塞多长时间abortTransaction()
。对于send()
此超时限制等待元数据获取和缓冲区分配的总时间(用户提供的序列化器或分区器中的阻塞不计入此超时)。对于partitionsFor()
此超时,限制了等待元数据(如果元数据不可用)所花费的时间。与事务相关的方法始终会阻塞,但如果无法发现事务协调器或在超时内未响应,则可能会超时。Type: long Default: 60000 (1 minute) Valid Values: [0,...] Importance: medium -
max.request.size
请求的最大大小(以字节为单位)。此设置将限制生产者在单个请求中发送的记录批次数量,以避免发送巨大的请求。这实际上也是最大未压缩记录批量大小的上限。请注意,服务器对记录批量大小有自己的上限(如果启用了压缩,则在压缩后),这可能与此不同。
Type: int Default: 1048576 Valid Values: [0,...] Importance: medium -
partitioner.class
确定生成记录时将记录发送到哪个分区。可用选项有:
- 如果未设置,则使用默认分区逻辑。此策略将记录发送到分区,直到至少为分区生成了batch.size字节。它适用于以下策略:
1) 如果未指定分区但存在密钥,则根据密钥的哈希值选择分区。
2) 如果不存在分区或键,则选择当至少为该分区生成batch.size 字节时更改的粘性分区。
org.apache.kafka.clients.producer.RoundRobinPartitioner
:一种分区策略,其中一系列连续记录中的每个记录都被发送到不同的分区,无论是否提供“密钥”,直到分区用完并且该过程重新开始。注意:有一个已知问题会导致创建新批次时分布不均。有关更多详细信息,请参阅 KAFKA-9965。
实现该
org.apache.kafka.clients.producer.Partitioner
接口允许您插入自定义分区器。Type: class Default: null Valid Values: Importance: medium - 如果未设置,则使用默认分区逻辑。此策略将记录发送到分区,直到至少为分区生成了batch.size字节。它适用于以下策略:
-
partitioner.ignore.keys
当设置为“true”时,生产者将不会使用记录键来选择分区。如果为“false”,则当存在密钥时,生产者将根据密钥的哈希值选择分区。注意:如果使用自定义分区程序,此设置无效。
Type: boolean Default: false Valid Values: Importance: medium -
receive.buffer.bytes
读取数据时使用的 TCP 接收缓冲区 (SO_RCVBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 32768 (32 kibibytes) Valid Values: [-1,...] Importance: medium -
request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。这应该大于
replica.lag.time.max.ms
(代理配置),以减少由于不必要的生产者重试而导致消息重复的可能性。Type: int Default: 30000 (30 seconds) Valid Values: [0,...] Importance: medium -
sasl.client.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。
Type: class Default: null Valid Values: Importance: medium -
sasl.jaas.config
SASL 连接的 JAAS 登录上下文参数采用 JAAS 配置文件使用的格式。JAAS 配置文件格式描述如下。该值的格式为:
loginModuleClass controlFlag (optionName=optionValue)*;
。对于代理,配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,需要listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule;Type: password Default: null Valid Values: Importance: medium -
sasl.kerberos.service.name
Kafka 运行时使用的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 的配置中定义。
Type: string Default: null Valid Values: Importance: medium -
sasl.login.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理,登录回调处理程序配置必须以侦听器前缀和小写的 SASL 机制名称为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
Type: class Default: null Valid Values: Importance: medium -
sasl.login.class
实现 Login 接口的类的完全限定名称。对于代理,登录配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
Type: class Default: null Valid Values: Importance: medium -
sasl.mechanism
用于客户端连接的 SASL 机制。这可以是安全提供者可用的任何机制。GSSAPI 是默认机制。
Type: string Default: GSSAPI Valid Values: Importance: medium -
sasl.oauthbearer.jwks.endpoint.url
可以从中检索提供商的JWKS(JSON Web 密钥集)的 OAuth/OIDC 提供商 URL。URL 可以基于 HTTP(S) 或基于文件。如果 URL 基于 HTTP(S),则将通过代理启动时配置的 URL 从 OAuth/OIDC 提供程序检索 JWKS 数据。所有当时的密钥都将缓存在代理上以用于传入请求。如果收到 JWT 的身份验证请求,其中包含尚未在缓存中的“kid”标头声明值,则将根据需要再次查询 JWKS 端点。但是,代理会每隔 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒轮询一次 URL,以便在收到包含这些密钥的任何 JWT 请求之前使用任何即将到来的密钥刷新缓存。如果 URL 是基于文件的,代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含 JWKS 文件中不存在的“kid”标头值,代理将拒绝 JWT 并且身份验证将失败。
Type: string Default: null Valid Values: Importance: medium -
sasl.oauthbearer.token.endpoint.url
OAuth/OIDC 身份提供商的 URL。如果 URL 基于 HTTP(S),则它是颁发者的令牌端点 URL,将根据 sasl.jaas.config 中的配置发出登录请求。如果 URL 是基于文件的,则它指定一个包含 OAuth/OIDC 身份提供商颁发的访问令牌(JWT 序列化形式)的文件,用于授权。
Type: string Default: null Valid Values: Importance: medium -
security.protocol
用于与经纪人通信的协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
Type: string Default: PLAINTEXT Valid Values: (case insensitive) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] Importance: medium -
send.buffer.bytes
发送数据时使用的 TCP 发送缓冲区 (SO_SNDBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 131072 (128 kibibytes) Valid Values: [-1,...] Importance: medium -
socket.connection.setup.timeout.max.ms
客户端等待建立套接字连接的最长时间。对于每个连续的连接失败,连接设置超时将呈指数增长,直至达到此最大值。为了避免连接风暴,将对超时应用 0.2 的随机化因子,从而产生比计算值低 20% 到高 20% 之间的随机范围。
Type: long Default: 30000 (30 seconds) Valid Values: Importance: medium -
socket.connection.setup.timeout.ms
客户端等待建立套接字连接的时间。如果在超时之前未建立连接,客户端将关闭套接字通道。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: medium -
ssl.enabled.protocols
为 SSL 连接启用的协议列表。使用 Java 11 或更高版本运行时,默认值为“TLSv1.2、TLSv1.3”,否则为“TLSv1.2”。使用 Java 11 的默认值,如果客户端和服务器都支持 TLSv1.3,则首选 TLSv1.3,否则回退到 TLSv1.2(假设两者至少支持 TLSv1.2)。对于大多数情况,此默认值应该没问题。另请参阅“ssl.protocol”的配置文档。
Type: list Default: TLSv1.2,TLSv1.3 Valid Values: Importance: medium -
ssl.keystore.type
密钥存储文件的文件格式。这对于客户来说是可选的。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
ssl.protocol
用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更高版本运行时,默认值为“TLSv1.3”,否则为“TLSv1.2”。该值对于大多数用例来说应该没问题。最新 JVM 中允许的值为“TLSv1.2”和“TLSv1.3”。较旧的 JVM 可能支持“TLS”、“TLSv1.1”、“SSL”、“SSLv2”和“SSLv3”,但由于已知的安全漏洞,不鼓励使用它们。使用此配置和“ssl.enabled.protocols”的默认值,如果服务器不支持“TLSv1.3”,客户端将降级到“TLSv1.2”。如果此配置设置为“TLSv1.2”,客户端将不会使用“TLSv1.3”,即使它是 ssl.enabled.protocols 中的值之一,并且服务器仅支持“TLSv1.3”。
Type: string Default: TLSv1.3 Valid Values: Importance: medium -
ssl.provider
用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
Type: string Default: null Valid Values: Importance: medium -
ssl.truststore.type
信任存储文件的文件格式。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
acks
生产者要求领导者在考虑请求完成之前收到的确认数量。这控制发送的记录的持久性。允许以下设置:
acks=0
如果设置为零,则生产者根本不会等待服务器的任何确认。该记录将立即添加到套接字缓冲区并被视为已发送。在这种情况下,不能保证服务器已收到记录,并且配置retries
不会生效(因为客户端通常不会知道任何失败)。为每个记录返回的偏移量将始终设置为-1
。acks=1
这意味着领导者会将记录写入其本地日志,但会在不等待所有追随者完全确认的情况下做出响应。在这种情况下,如果领导者在确认记录后但在追随者复制记录之前立即失败,那么记录将丢失。acks=all
这意味着领导者将等待完整的同步副本集确认记录。这保证了只要至少一个同步副本保持活动状态,记录就不会丢失。这是最强有力的保证。这相当于 acks=-1 设置。
请注意,启用幂等性要求此配置值为“all”。如果设置了冲突的配置并且未显式启用幂等性,则幂等性将被禁用。
Type: string Default: all Valid Values: [all, -1, 0, 1] Importance: low -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low -
enable.idempotence
当设置为“true”时,生产者将确保每条消息的一份副本准确写入流中。如果为“false”,则生产者由于代理故障等原因重试,可能会在流中写入重试消息的重复项。请注意,启用幂等性要求
max.in.flight.requests.per.connection
小于或等于 5(为任何允许的值保留消息排序)、retries
大于 0,并且acks
必须为“全部”。如果没有设置冲突的配置,则默认启用幂等性。如果设置了冲突的配置并且未显式启用幂等性,则幂等性将被禁用。如果显式启用幂等性并且设置了冲突的配置,
ConfigException
则会抛出 a 。Type: boolean Default: true Valid Values: Importance: low -
interceptor.classes
用作拦截器的类的列表。实现该
org.apache.kafka.clients.producer.ProducerInterceptor
接口允许您在将生产者收到的记录发布到 Kafka 集群之前拦截(并可能改变)这些记录。默认情况下,没有拦截器。Type: list Default: "" Valid Values: non-null string Importance: low -
max.in.flight.requests.per.connection
客户端在阻塞之前在单个连接上发送的未确认请求的最大数量。注意,如果该配置设置大于1且
enable.idempotence
设置为false,则存在因重试导致发送失败后消息重新排序的风险(即如果启用了重试);如果禁用重试或enable.idempotence
设置为 true,则将保留排序。此外,启用幂等性要求此配置的值小于或等于 5。如果设置了冲突的配置并且未显式启用幂等性,则幂等性将被禁用。Type: int Default: 5 Valid Values: [1,...] Importance: low -
metadata.max.age.ms
即使我们没有看到任何分区领导层发生变化以主动发现任何新的代理或分区,我们也会强制刷新元数据,以毫秒为单位的时间段。
Type: long Default: 300000 (5 minutes) Valid Values: [0,...] Importance: low -
metadata.max.idle.ms
控制生产者为空闲主题缓存元数据的时间。如果自上次生成主题以来经过的时间超过了元数据空闲持续时间,则该主题的元数据将被遗忘,并且下次访问该主题将强制执行元数据获取请求。
Type: long Default: 300000 (5 minutes) Valid Values: [5000,...] Importance: low -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: "" Valid Values: non-null string Importance: low -
metrics.num.samples
为计算指标而维护的样本数量。
Type: int Default: 2 Valid Values: [1,...] Importance: low -
metrics.recording.level
指标的最高记录级别。
Type: string Default: INFO Valid Values: [INFO, DEBUG, TRACE] Importance: low -
metrics.sample.window.ms
计算指标样本的时间窗口。
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
partitioner.adaptive.partitioning.enable
当设置为“true”时,生产者将尝试适应代理性能并向更快代理上托管的分区生成更多消息。如果为“false”,生产者将尝试统一分发消息。注意:如果使用自定义分区程序,此设置无效
Type: boolean Default: true Valid Values: Importance: low -
partitioner.availability.timeout.ms
如果代理在一段
partitioner.availability.timeout.ms
时间内无法处理来自分区的生产请求,则分区程序会将该分区视为不可用。如果值为 0,则禁用此逻辑。partitioner.adaptive.partitioning.enable
注意:如果使用自定义分区程序或设置为“false”,则此设置无效Type: long Default: 0 Valid Values: [0,...] Importance: low -
reconnect.backoff.max.ms
重新连接到多次连接失败的代理时等待的最长时间(以毫秒为单位)。如果提供,每个主机的退避将在每次连续连接失败时呈指数增加,直至达到此最大值。计算退避增量后,添加 20% 的随机抖动以避免连接风暴。
Type: long Default: 1000 (1 second) Valid Values: [0,...] Importance: low -
reconnect.backoff.ms
尝试重新连接到给定主机之前等待的基本时间量。这避免了在紧密循环中重复连接到主机。此退避适用于客户端与代理的所有连接尝试。
Type: long Default: 50 Valid Values: [0,...] Importance: low -
retry.backoff.ms
尝试重试对给定主题分区的失败请求之前等待的时间。这避免了在某些故障场景下在紧密循环中重复发送请求。
Type: long Default: 100 Valid Values: [0,...] Importance: low -
sasl.kerberos.kinit.cmd
Kerberos kinit 命令路径。
Type: string Default: /usr/bin/kinit Valid Values: Importance: low -
sasl.kerberos.min.time.before.relogin
刷新尝试之间的登录线程睡眠时间。
Type: long Default: 60000 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.jitter
添加到更新时间的随机抖动的百分比。
Type: double Default: 0.05 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.window.factor
登录线程将休眠,直到达到从上次刷新到票证到期的指定时间窗口因子,此时它将尝试更新票证。
Type: double Default: 0.8 Valid Values: Importance: low -
sasl.login.connect.timeout.ms
外部身份验证提供程序连接超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.read.timeout.ms
外部身份验证提供程序读取超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.refresh.buffer.seconds
刷新凭证时在凭证过期前维持的缓冲时间量(以秒为单位)。如果刷新发生的时间比缓冲秒数更接近到期,则刷新将向上移动以维持尽可能多的缓冲时间。合法值介于 0 到 3600(1 小时)之间;如果未指定值,则使用默认值 300(5 分钟)。如果该值和 sasl.login.refresh.min.period.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 300 Valid Values: [0,...,3600] Importance: low -
sasl.login.refresh.min.period.seconds
登录刷新线程在刷新凭据之前等待的所需最短时间(以秒为单位)。合法值介于 0 到 900(15 分钟)之间;如果未指定值,则使用默认值 60(1 分钟)。如果该值和 sasl.login.refresh.buffer.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 60 Valid Values: [0,...,900] Importance: low -
sasl.login.refresh.window.factor
登录刷新线程将休眠,直到达到相对于凭证生命周期的指定窗口因子,此时它将尝试刷新凭证。合法值介于 0.5 (50%) 和 1.0 (100%)(含)之间;如果未指定值,则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.8 Valid Values: [0.5,...,1.0] Importance: low -
sasl.login.refresh.window.jitter
相对于添加到登录刷新线程睡眠时间的凭证生命周期的最大随机抖动量。合法值介于 0 和 0.25 (25%) 之间(含);如果未指定值,则使用默认值 0.05 (5%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.05 Valid Values: [0.0,...,0.25] Importance: low -
sasl.login.retry.backoff.max.ms
尝试登录外部身份验证提供程序之间的最长等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.login.retry.backoff.ms
尝试登录外部身份验证提供程序之间的初始等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.clock.skew.seconds
以秒为单位的(可选)值,以允许 OAuth/OIDC 身份提供商和代理的时间之间存在差异。
Type: int Default: 30 Valid Values: Importance: low -
sasl.oauthbearer.expected.audience
代理的(可选)逗号分隔设置,用于验证 JWT 是否是为预期受众之一颁发的。将检查 JWT 是否有标准 OAuth“aud”声明,如果设置了此值,代理将匹配 JWT 的“aud”声明中的值,以查看是否存在完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: list Default: null Valid Values: Importance: low -
sasl.oauthbearer.expected.issuer
代理用于验证 JWT 是否由预期发行者创建的(可选)设置。将检查 JWT 是否有标准 OAuth“iss”声明,如果设置了该值,代理会将其与 JWT 的“iss”声明中的内容完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: string Default: null Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.refresh.ms
代理在刷新其 JWKS(JSON Web 密钥集)缓存之间等待的(可选)值(以毫秒为单位),该缓存包含用于验证 JWT 签名的密钥。
Type: long Default: 3600000 (1 hour) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms
尝试从外部身份验证提供程序检索 JWKS(JSON Web 密钥集)之间的最长等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.ms
来自外部身份验证提供程序的 JWKS(JSON Web 密钥集)检索尝试之间的初始等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.scope.claim.name
该范围的 OAuth 声明通常被命名为“scope”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的范围提供不同的名称。
Type: string Default: scope Valid Values: Importance: low -
sasl.oauthbearer.sub.claim.name
主题的 OAuth 声明通常命名为“sub”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的主题提供不同的名称。
Type: string Default: sub Valid Values: Importance: low -
security.providers
可配置创建者类的列表,每个类返回一个实现安全算法的提供者。这些类应该实现该
org.apache.kafka.common.security.auth.SecurityProviderCreator
接口。Type: string Default: null Valid Values: Importance: low -
ssl.cipher.suites
密码套件列表。这是身份验证、加密、MAC 和密钥交换算法的命名组合,用于使用 TLS 或 SSL 网络协议协商网络连接的安全设置。默认情况下,支持所有可用的密码套件。
Type: list Default: null Valid Values: Importance: low -
ssl.endpoint.identification.algorithm
使用服务器证书验证服务器主机名的端点识别算法。
Type: string Default: https Valid Values: Importance: low -
ssl.engine.factory.class
org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory
Type: class Default: null Valid Values: Importance: low -
ssl.keymanager.algorithm
密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。
Type: string Default: SunX509 Valid Values: Importance: low -
ssl.secure.random.implementation
用于 SSL 加密操作的 SecureRandom PRNG 实现。
Type: string Default: null Valid Values: Importance: low -
ssl.trustmanager.algorithm
信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。
Type: string Default: PKIX Valid Values: Importance: low -
transaction.timeout.ms
在协调器主动中止事务之前,事务保持打开状态的最长时间(以毫秒为单位)。事务的开始时间是在将第一个分区添加到其中时设置的。如果该值大于
transaction.max.timeout.ms
代理中的设置,请求将失败并出现InvalidTxnTimeoutException
错误。Type: int Default: 60000 (1 minute) Valid Values: Importance: low -
transactional.id
用于事务交付的 TransactionalId。这使得跨多个生产者会话的可靠性语义成为可能,因为它允许客户端保证使用相同 TransactionalId 的事务在开始任何新事务之前已完成。如果未提供 TransactionalId,则生产者仅限于幂等传递。如果配置了 TransactionalId,
enable.idempotence
则隐含。默认情况下没有配置TransactionId,这意味着不能使用事务。请注意,默认情况下,事务需要至少包含三个代理的集群,这是生产环境的推荐设置;对于开发,您可以通过调整代理设置来更改此设置transaction.state.log.replication.factor
。Type: string Default: null Valid Values: non-empty string Importance: low
3.4 消费者配置
以下是消费者的配置:-
key.deserializer
实现该
org.apache.kafka.common.serialization.Deserializer
接口的键的反序列化器类。Type: class Default: Valid Values: Importance: high -
value.deserializer
实现
org.apache.kafka.common.serialization.Deserializer
接口的值的反序列化器类。Type: class Default: Valid Values: Importance: high -
bootstrap.servers
用于建立与 Kafka 集群的初始连接的主机/端口对列表。客户端将使用所有服务器,无论此处指定哪些服务器进行引导 - 该列表仅影响用于发现全套服务器的初始主机。该列表应采用以下形式
host1:port1,host2:port2,...
。由于这些服务器仅用于初始连接以发现完整的集群成员资格(可能会动态更改),因此此列表不需要包含完整的服务器集(不过,您可能需要多个服务器,以防服务器停机) 。Type: list Default: "" Valid Values: non-null string Importance: high -
fetch.min.bytes
服务器应为获取请求返回的最小数据量。如果可用数据不足,请求将等待积累足够多的数据,然后再答复请求。默认设置 1 字节意味着,只要有那么多字节的数据可用,或者获取请求在等待数据到达时超时,就会立即应答获取请求。将其设置为较大的值将导致服务器等待大量数据的积累,这可以稍微提高服务器吞吐量,但会带来一些额外的延迟。
Type: int Default: 1 Valid Values: [0,...] Importance: high -
group.id
标识该消费者所属的消费者组的唯一字符串。如果消费者使用组管理功能
subscribe(topic)
或基于 Kafka 的偏移量管理策略,则需要此属性。Type: string Default: null Valid Values: Importance: high -
heartbeat.interval.ms
使用 Kafka 的组管理设施时向消费者协调器发出心跳的预期时间间隔。心跳用于确保消费者的会话保持活动状态,并在新消费者加入或离开组时促进重新平衡。该值必须设置为低于
session.timeout.ms
,但通常不应高于该值的 1/3。它可以调整得更低,以控制正常重新平衡的预期时间。Type: int Default: 3000 (3 seconds) Valid Values: Importance: high -
max.partition.fetch.bytes
服务器将返回的每个分区的最大数据量。记录由消费者批量获取。如果提取的第一个非空分区中的第一个记录批次大于此限制,该批次仍将被返回以确保消费者可以取得进展。代理接受的最大记录批量大小是通过
message.max.bytes
(代理配置)或max.message.bytes
(主题配置)定义的。请参阅 fetch.max.bytes 以限制消费者请求大小。Type: int Default: 1048576 (1 mebibyte) Valid Values: [0,...] Importance: high -
session.timeout.ms
使用 Kafka 的组管理工具时用于检测客户端故障的超时。客户端定期发送心跳以向代理表明其活跃度。如果在此会话超时到期之前代理没有收到心跳,则代理将从组中删除该客户端并启动重新平衡。请注意,该值必须在代理配置中
group.min.session.timeout.ms
和所配置的允许范围内group.max.session.timeout.ms
。Type: int Default: 45000 (45 seconds) Valid Values: Importance: high -
ssl.key.password
密钥存储文件中私钥的密码或“ssl.keystore.key”中指定的 PEM 密钥的密码。
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.certificate.chain
证书链采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 X.509 证书列表的 PEM 格式
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.key
私钥采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 PKCS#8 密钥的 PEM 格式。如果密钥已加密,则必须使用“ssl.key.password”指定密钥密码
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.location
密钥存储文件的位置。这对客户端来说是可选的,可用于客户端的双向身份验证。
Type: string Default: null Valid Values: Importance: high -
ssl.keystore.password
密钥存储文件的存储密码。这对于客户端来说是可选的,并且仅在配置了“ssl.keystore.location”时才需要。PEM 格式不支持密钥存储密码。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.certificates
采用“ssl.truststore.type”指定格式的受信任证书。默认 SSL 引擎工厂仅支持带有 X.509 证书的 PEM 格式。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.location
信任存储文件的位置。
Type: string Default: null Valid Values: Importance: high -
ssl.truststore.password
信任存储文件的密码。如果未设置密码,仍将使用配置的信任存储文件,但禁用完整性检查。PEM 格式不支持信任存储密码。
Type: password Default: null Valid Values: Importance: high -
allow.auto.create.topics
订阅或分配主题时允许在代理上自动创建主题。仅当代理允许使用“auto.create.topics.enable”代理配置时,才会自动创建订阅的主题。使用早于 0.11.0 的代理时,此配置必须设置为“false”
Type: boolean Default: true Valid Values: Importance: medium -
auto.offset.reset
当 Kafka 中没有初始偏移量或者当前偏移量在服务器上不再存在时(例如因为该数据已被删除)该怎么办:
- 最早:自动将偏移量重置为最早的偏移量
- 最新:自动将偏移量重置为最新偏移量
- none:如果没有找到消费者组的先前偏移量,则向消费者抛出异常
- 其他任何事情:向消费者抛出异常。
请注意,在将此配置设置为最新时更改分区编号可能会导致消息传递丢失,因为生产者可能会在消费者重置其偏移量之前开始将消息发送到新添加的分区(即尚不存在初始偏移量)。
Type: string Default: latest Valid Values: [latest, earliest, none] Importance: medium -
client.dns.lookup
控制客户端如何使用 DNS 查找。如果设置为
use_all_dns_ips
,则按顺序连接每个返回的 IP 地址,直到建立成功连接。断开连接后,将使用下一个 IP。一旦所有 IP 使用一次,客户端就会再次从主机名解析 IP(但是 JVM 和操作系统都会缓存 DNS 名称查找)。如果设置为resolve_canonical_bootstrap_servers_only
,则将每个引导地址解析为规范名称列表。在引导阶段之后,其行为与 相同use_all_dns_ips
。Type: string Default: use_all_dns_ips Valid Values: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only] Importance: medium -
connections.max.idle.ms
在该配置指定的毫秒数后关闭空闲连接。
Type: long Default: 540000 (9 minutes) Valid Values: Importance: medium -
default.api.timeout.ms
指定客户端 API 的超时(以毫秒为单位)。此配置用作所有未指定
timeout
参数的客户端操作的默认超时。Type: int Default: 60000 (1 minute) Valid Values: [0,...] Importance: medium -
enable.auto.commit
如果为 true,消费者的偏移量将在后台定期提交。
Type: boolean Default: true Valid Values: Importance: medium -
exclude.internal.topics
是否应从订阅中排除与订阅模式匹配的内部主题。始终可以显式订阅内部主题。
Type: boolean Default: true Valid Values: Importance: medium -
fetch.max.bytes
服务器应为获取请求返回的最大数据量。记录由消费者批量获取,如果获取的第一个非空分区中的第一个记录批次大于该值,仍然会返回该记录批次以确保消费者能够取得进展。因此,这不是绝对最大值。代理接受的最大记录批量大小是通过
message.max.bytes
(代理配置)或max.message.bytes
(主题配置)定义的。请注意,消费者并行执行多个提取。Type: int Default: 52428800 (50 mebibytes) Valid Values: [0,...] Importance: medium -
group.instance.id
最终用户提供的消费者实例的唯一标识符。只允许非空字符串。如果设置,消费者将被视为静态成员,这意味着消费者组中任何时候只允许有一个具有此 ID 的实例。这可以与较大的会话超时结合使用,以避免由于暂时不可用(例如进程重新启动)而导致的组重新平衡。如果未设置,消费者将作为动态成员加入该组,这是传统行为。
Type: string Default: null Valid Values: non-empty string Importance: medium -
isolation.level
控制如何读取以事务方式写入的消息。如果设置为
read_committed
,consumer.poll() 将仅返回已提交的事务消息。如果设置为read_uncommitted
(默认),consumer.poll() 将返回所有消息,甚至是已中止的事务消息。无论哪种模式,非事务性消息都将无条件返回。消息将始终按偏移顺序返回。因此,在
read_committed
mode 下,consumer.poll() 只会返回直到最后一个稳定偏移量 (LSO) 的消息,该偏移量小于第一个打开事务的偏移量。特别是,在属于正在进行的交易的消息之后出现的任何消息将被保留,直到相关交易完成为止。因此,read_committed
当存在飞行交易时,消费者将无法读取到高水位线。进一步,当在
read_committed
seekToEnd方法中会返回LSOType: string Default: read_uncommitted Valid Values: [read_committed, read_uncommitted] Importance: medium -
max.poll.interval.ms
使用消费者组管理时,调用 poll() 之间的最大延迟。这对消费者在获取更多记录之前可以空闲的时间设置了上限。如果在此超时到期之前未调用 poll(),则消费者将被视为失败,并且组将重新平衡,以便将分区重新分配给另一个成员。对于使用非空的消费者
group.instance.id
达到此超时,分区不会立即重新分配。相反,消费者将停止发送心跳,并且分区将在 过期后重新分配session.timeout.ms
。这反映了已关闭的静态消费者的行为。Type: int Default: 300000 (5 minutes) Valid Values: [1,...] Importance: medium -
max.poll.records
单次调用 poll() 返回的最大记录数。请注意,这
max.poll.records
不会影响底层的获取行为。消费者将缓存每个获取请求的记录,并从每次轮询中增量返回它们。Type: int Default: 500 Valid Values: [1,...] Importance: medium -
partition.assignment.strategy
按优先顺序排序的类名称或类类型列表,支持分区分配策略,当使用组管理时,客户端将使用这些策略在消费者实例之间分配分区所有权。可用选项有:
org.apache.kafka.clients.consumer.RangeAssignor
:按主题分配分区。org.apache.kafka.clients.consumer.RoundRobinAssignor
:以循环方式将分区分配给消费者。org.apache.kafka.clients.consumer.StickyAssignor
:保证分配最大程度地平衡,同时保留尽可能多的现有分区分配。org.apache.kafka.clients.consumer.CooperativeStickyAssignor
:遵循相同的 StickyAssignor 逻辑,但允许合作重新平衡。
默认分配器是 [RangeAssignor, CooperativeStickyAssignor],默认情况下将使用 RangeAssignor,但允许升级到 CooperativeStickyAssignor,只需一次滚动弹跳即可从列表中删除 RangeAssignor。
实现该
org.apache.kafka.clients.consumer.ConsumerPartitionAssignor
接口允许您插入自定义分配策略。Type: list Default: class org.apache.kafka.clients.consumer.RangeAssignor,class org.apache.kafka.clients.consumer.CooperativeStickyAssignor Valid Values: non-null string Importance: medium -
receive.buffer.bytes
读取数据时使用的 TCP 接收缓冲区 (SO_RCVBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 65536 (64 kibibytes) Valid Values: [-1,...] Importance: medium -
request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。
Type: int Default: 30000 (30 seconds) Valid Values: [0,...] Importance: medium -
sasl.client.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。
Type: class Default: null Valid Values: Importance: medium -
sasl.jaas.config
SASL 连接的 JAAS 登录上下文参数采用 JAAS 配置文件使用的格式。JAAS 配置文件格式描述如下。该值的格式为:
loginModuleClass controlFlag (optionName=optionValue)*;
。对于代理,配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,需要listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule;Type: password Default: null Valid Values: Importance: medium -
sasl.kerberos.service.name
Kafka 运行时使用的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 的配置中定义。
Type: string Default: null Valid Values: Importance: medium -
sasl.login.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理,登录回调处理程序配置必须以侦听器前缀和小写的 SASL 机制名称为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
Type: class Default: null Valid Values: Importance: medium -
sasl.login.class
实现 Login 接口的类的完全限定名称。对于代理,登录配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
Type: class Default: null Valid Values: Importance: medium -
sasl.mechanism
用于客户端连接的 SASL 机制。这可以是安全提供者可用的任何机制。GSSAPI 是默认机制。
Type: string Default: GSSAPI Valid Values: Importance: medium -
sasl.oauthbearer.jwks.endpoint.url
可以从中检索提供商的JWKS(JSON Web 密钥集)的 OAuth/OIDC 提供商 URL。URL 可以基于 HTTP(S) 或基于文件。如果 URL 基于 HTTP(S),则将通过代理启动时配置的 URL 从 OAuth/OIDC 提供程序检索 JWKS 数据。所有当时的密钥都将缓存在代理上以用于传入请求。如果收到 JWT 的身份验证请求,其中包含尚未在缓存中的“kid”标头声明值,则将根据需要再次查询 JWKS 端点。但是,代理会每隔 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒轮询一次 URL,以便在收到包含这些密钥的任何 JWT 请求之前使用任何即将到来的密钥刷新缓存。如果 URL 是基于文件的,代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含 JWKS 文件中不存在的“kid”标头值,代理将拒绝 JWT 并且身份验证将失败。
Type: string Default: null Valid Values: Importance: medium -
sasl.oauthbearer.token.endpoint.url
OAuth/OIDC 身份提供商的 URL。如果 URL 基于 HTTP(S),则它是颁发者的令牌端点 URL,将根据 sasl.jaas.config 中的配置发出登录请求。如果 URL 是基于文件的,则它指定一个包含 OAuth/OIDC 身份提供商颁发的访问令牌(JWT 序列化形式)的文件,用于授权。
Type: string Default: null Valid Values: Importance: medium -
security.protocol
用于与经纪人通信的协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
Type: string Default: PLAINTEXT Valid Values: (case insensitive) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] Importance: medium -
send.buffer.bytes
发送数据时使用的 TCP 发送缓冲区 (SO_SNDBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 131072 (128 kibibytes) Valid Values: [-1,...] Importance: medium -
socket.connection.setup.timeout.max.ms
客户端等待建立套接字连接的最长时间。对于每个连续的连接失败,连接设置超时将呈指数增长,直至达到此最大值。为了避免连接风暴,将对超时应用 0.2 的随机化因子,从而产生比计算值低 20% 到高 20% 之间的随机范围。
Type: long Default: 30000 (30 seconds) Valid Values: Importance: medium -
socket.connection.setup.timeout.ms
客户端等待建立套接字连接的时间。如果在超时之前未建立连接,客户端将关闭套接字通道。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: medium -
ssl.enabled.protocols
为 SSL 连接启用的协议列表。使用 Java 11 或更高版本运行时,默认值为“TLSv1.2、TLSv1.3”,否则为“TLSv1.2”。使用 Java 11 的默认值,如果客户端和服务器都支持 TLSv1.3,则首选 TLSv1.3,否则回退到 TLSv1.2(假设两者至少支持 TLSv1.2)。对于大多数情况,此默认值应该没问题。另请参阅“ssl.protocol”的配置文档。
Type: list Default: TLSv1.2,TLSv1.3 Valid Values: Importance: medium -
ssl.keystore.type
密钥存储文件的文件格式。这对于客户来说是可选的。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
ssl.protocol
用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更高版本运行时,默认值为“TLSv1.3”,否则为“TLSv1.2”。该值对于大多数用例来说应该没问题。最新 JVM 中允许的值为“TLSv1.2”和“TLSv1.3”。较旧的 JVM 可能支持“TLS”、“TLSv1.1”、“SSL”、“SSLv2”和“SSLv3”,但由于已知的安全漏洞,不鼓励使用它们。使用此配置和“ssl.enabled.protocols”的默认值,如果服务器不支持“TLSv1.3”,客户端将降级到“TLSv1.2”。如果此配置设置为“TLSv1.2”,客户端将不会使用“TLSv1.3”,即使它是 ssl.enabled.protocols 中的值之一,并且服务器仅支持“TLSv1.3”。
Type: string Default: TLSv1.3 Valid Values: Importance: medium -
ssl.provider
用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
Type: string Default: null Valid Values: Importance: medium -
ssl.truststore.type
信任存储文件的文件格式。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
auto.commit.interval.ms
enable.auto.commit
如果设置为,则消费者偏移量自动提交到 Kafka 的频率(以毫秒为单位)true
。Type: int Default: 5000 (5 seconds) Valid Values: [0,...] Importance: low -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low -
check.crcs
自动检查消费记录的CRC32。这可确保消息不会发生在线或磁盘损坏。此检查会增加一些开销,因此在寻求极端性能的情况下可能会禁用它。
Type: boolean Default: true Valid Values: Importance: low -
client.id
发出请求时传递给服务器的 id 字符串。这样做的目的是通过允许在服务器端请求日志记录中包含逻辑应用程序名称,能够跟踪 IP/端口之外的请求源。
Type: string Default: "" Valid Values: Importance: low -
client.rack
该客户端的机架标识符。这可以是指示该客户端物理位置的任何字符串值。它与代理配置“broker.rack”相对应
Type: string Default: "" Valid Values: Importance: low -
fetch.max.wait.ms
如果没有足够的数据来立即满足 fetch.min.bytes 给出的要求,则服务器在应答提取请求之前将阻塞的最长时间。
Type: int Default: 500 Valid Values: [0,...] Importance: low -
interceptor.classes
用作拦截器的类的列表。实现该
org.apache.kafka.clients.consumer.ConsumerInterceptor
接口允许您拦截(并可能改变)消费者收到的记录。默认情况下,没有拦截器。Type: list Default: "" Valid Values: non-null string Importance: low -
metadata.max.age.ms
即使我们没有看到任何分区领导层发生变化以主动发现任何新的代理或分区,我们也会强制刷新元数据,以毫秒为单位的时间段。
Type: long Default: 300000 (5 minutes) Valid Values: [0,...] Importance: low -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: "" Valid Values: non-null string Importance: low -
metrics.num.samples
为计算指标而维护的样本数量。
Type: int Default: 2 Valid Values: [1,...] Importance: low -
metrics.recording.level
指标的最高记录级别。
Type: string Default: INFO Valid Values: [INFO, DEBUG, TRACE] Importance: low -
metrics.sample.window.ms
计算指标样本的时间窗口。
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
reconnect.backoff.max.ms
重新连接到多次连接失败的代理时等待的最长时间(以毫秒为单位)。如果提供,每个主机的退避将在每次连续连接失败时呈指数增加,直至达到此最大值。计算退避增量后,添加 20% 的随机抖动以避免连接风暴。
Type: long Default: 1000 (1 second) Valid Values: [0,...] Importance: low -
reconnect.backoff.ms
尝试重新连接到给定主机之前等待的基本时间量。这避免了在紧密循环中重复连接到主机。此退避适用于客户端与代理的所有连接尝试。
Type: long Default: 50 Valid Values: [0,...] Importance: low -
retry.backoff.ms
尝试重试对给定主题分区的失败请求之前等待的时间。这避免了在某些故障场景下在紧密循环中重复发送请求。
Type: long Default: 100 Valid Values: [0,...] Importance: low -
sasl.kerberos.kinit.cmd
Kerberos kinit 命令路径。
Type: string Default: /usr/bin/kinit Valid Values: Importance: low -
sasl.kerberos.min.time.before.relogin
刷新尝试之间的登录线程睡眠时间。
Type: long Default: 60000 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.jitter
添加到更新时间的随机抖动的百分比。
Type: double Default: 0.05 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.window.factor
登录线程将休眠,直到达到从上次刷新到票证到期的指定时间窗口因子,此时它将尝试更新票证。
Type: double Default: 0.8 Valid Values: Importance: low -
sasl.login.connect.timeout.ms
外部身份验证提供程序连接超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.read.timeout.ms
外部身份验证提供程序读取超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.refresh.buffer.seconds
刷新凭证时在凭证过期前维持的缓冲时间量(以秒为单位)。如果刷新发生的时间比缓冲秒数更接近到期,则刷新将向上移动以维持尽可能多的缓冲时间。合法值介于 0 到 3600(1 小时)之间;如果未指定值,则使用默认值 300(5 分钟)。如果该值和 sasl.login.refresh.min.period.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 300 Valid Values: [0,...,3600] Importance: low -
sasl.login.refresh.min.period.seconds
登录刷新线程在刷新凭据之前等待的所需最短时间(以秒为单位)。合法值介于 0 到 900(15 分钟)之间;如果未指定值,则使用默认值 60(1 分钟)。如果该值和 sasl.login.refresh.buffer.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 60 Valid Values: [0,...,900] Importance: low -
sasl.login.refresh.window.factor
登录刷新线程将休眠,直到达到相对于凭证生命周期的指定窗口因子,此时它将尝试刷新凭证。合法值介于 0.5 (50%) 和 1.0 (100%)(含)之间;如果未指定值,则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.8 Valid Values: [0.5,...,1.0] Importance: low -
sasl.login.refresh.window.jitter
相对于添加到登录刷新线程睡眠时间的凭证生命周期的最大随机抖动量。合法值介于 0 和 0.25 (25%) 之间(含);如果未指定值,则使用默认值 0.05 (5%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.05 Valid Values: [0.0,...,0.25] Importance: low -
sasl.login.retry.backoff.max.ms
尝试登录外部身份验证提供程序之间的最长等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.login.retry.backoff.ms
尝试登录外部身份验证提供程序之间的初始等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.clock.skew.seconds
以秒为单位的(可选)值,以允许 OAuth/OIDC 身份提供商和代理的时间之间存在差异。
Type: int Default: 30 Valid Values: Importance: low -
sasl.oauthbearer.expected.audience
代理的(可选)逗号分隔设置,用于验证 JWT 是否是为预期受众之一颁发的。将检查 JWT 是否有标准 OAuth“aud”声明,如果设置了此值,代理将匹配 JWT 的“aud”声明中的值,以查看是否存在完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: list Default: null Valid Values: Importance: low -
sasl.oauthbearer.expected.issuer
代理用于验证 JWT 是否由预期发行者创建的(可选)设置。将检查 JWT 是否有标准 OAuth“iss”声明,如果设置了该值,代理会将其与 JWT 的“iss”声明中的内容完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: string Default: null Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.refresh.ms
代理在刷新其 JWKS(JSON Web 密钥集)缓存之间等待的(可选)值(以毫秒为单位),该缓存包含用于验证 JWT 签名的密钥。
Type: long Default: 3600000 (1 hour) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms
尝试从外部身份验证提供程序检索 JWKS(JSON Web 密钥集)之间的最长等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.ms
来自外部身份验证提供程序的 JWKS(JSON Web 密钥集)检索尝试之间的初始等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.scope.claim.name
该范围的 OAuth 声明通常被命名为“scope”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的范围提供不同的名称。
Type: string Default: scope Valid Values: Importance: low -
sasl.oauthbearer.sub.claim.name
主题的 OAuth 声明通常命名为“sub”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的主题提供不同的名称。
Type: string Default: sub Valid Values: Importance: low -
security.providers
可配置创建者类的列表,每个类返回一个实现安全算法的提供者。这些类应该实现该
org.apache.kafka.common.security.auth.SecurityProviderCreator
接口。Type: string Default: null Valid Values: Importance: low -
ssl.cipher.suites
密码套件列表。这是身份验证、加密、MAC 和密钥交换算法的命名组合,用于使用 TLS 或 SSL 网络协议协商网络连接的安全设置。默认情况下,支持所有可用的密码套件。
Type: list Default: null Valid Values: Importance: low -
ssl.endpoint.identification.algorithm
使用服务器证书验证服务器主机名的端点识别算法。
Type: string Default: https Valid Values: Importance: low -
ssl.engine.factory.class
org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory
Type: class Default: null Valid Values: Importance: low -
ssl.keymanager.algorithm
密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。
Type: string Default: SunX509 Valid Values: Importance: low -
ssl.secure.random.implementation
用于 SSL 加密操作的 SecureRandom PRNG 实现。
Type: string Default: null Valid Values: Importance: low -
ssl.trustmanager.algorithm
信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。
Type: string Default: PKIX Valid Values: Importance: low
3.5 Kafka连接配置
以下是 Kafka Connect 框架的配置。-
config.storage.topic
存储连接器配置的 Kafka 主题的名称
Type: string Default: Valid Values: Importance: high -
group.id
标识该工作线程所属的 Connect 集群组的唯一字符串。
Type: string Default: Valid Values: Importance: high -
key.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中键的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: Valid Values: Importance: high -
offset.storage.topic
存储源连接器偏移量的 Kafka 主题的名称
Type: string Default: Valid Values: Importance: high -
status.storage.topic
存储连接器和任务状态的 Kafka 主题的名称
Type: string Default: Valid Values: Importance: high -
value.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中的值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: Valid Values: Importance: high -
bootstrap.servers
用于建立与 Kafka 集群的初始连接的主机/端口对列表。客户端将使用所有服务器,无论此处指定哪些服务器进行引导 - 该列表仅影响用于发现全套服务器的初始主机。该列表应采用以下形式
host1:port1,host2:port2,...
。由于这些服务器仅用于初始连接以发现完整的集群成员资格(可能会动态更改),因此此列表不需要包含完整的服务器集(不过,您可能需要多个服务器,以防服务器停机) 。Type: list Default: localhost:9092 Valid Values: Importance: high -
exactly.once.source.support
是否通过使用事务写入源记录及其源偏移量,以及在启动新任务之前主动隔离旧任务代,来为集群中的源连接器启用一次性支持。
要在新集群上启用一次性源支持,请将此属性设置为“已启用”。要在现有集群上启用支持,请首先在集群中的每个工作线程上设置为“准备”,然后设置为“启用”。滚动升级可用于这两种更改。有关此功能的更多信息,请参阅一次性源支持文档。Type: string Default: disabled Valid Values: (case insensitive) [DISABLED, ENABLED, PREPARING] Importance: high -
heartbeat.interval.ms
使用 Kafka 的组管理工具时,向组协调器发出心跳的预期时间间隔。心跳用于确保工作人员的会话保持活动状态,并在新成员加入或离开组时促进重新平衡。该值必须设置为低于
session.timeout.ms
,但通常不应高于该值的 1/3。它可以调整得更低,以控制正常重新平衡的预期时间。Type: int Default: 3000 (3 seconds) Valid Values: Importance: high -
rebalance.timeout.ms
重新平衡开始后,每个工作人员加入该组的最大允许时间。这基本上是对所有任务刷新任何挂起数据和提交偏移量所需的时间的限制。如果超过超时,那么该worker将从组中删除,这将导致偏移量提交失败。
Type: int Default: 60000 (1 minute) Valid Values: Importance: high -
session.timeout.ms
用于检测工作器故障的超时时间。工作线程定期发送心跳以向代理表明其活跃度。如果在此会话超时到期之前代理没有收到心跳,则代理将从组中删除该工作线程并启动重新平衡。请注意,该值必须在代理配置中
group.min.session.timeout.ms
和所配置的允许范围内group.max.session.timeout.ms
。Type: int Default: 10000 (10 seconds) Valid Values: Importance: high -
ssl.key.password
密钥存储文件中私钥的密码或“ssl.keystore.key”中指定的 PEM 密钥的密码。
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.certificate.chain
证书链采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 X.509 证书列表的 PEM 格式
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.key
私钥采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 PKCS#8 密钥的 PEM 格式。如果密钥已加密,则必须使用“ssl.key.password”指定密钥密码
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.location
密钥存储文件的位置。这对客户端来说是可选的,可用于客户端的双向身份验证。
Type: string Default: null Valid Values: Importance: high -
ssl.keystore.password
密钥存储文件的存储密码。这对于客户端来说是可选的,并且仅在配置了“ssl.keystore.location”时才需要。PEM 格式不支持密钥存储密码。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.certificates
采用“ssl.truststore.type”指定格式的受信任证书。默认 SSL 引擎工厂仅支持带有 X.509 证书的 PEM 格式。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.location
信任存储文件的位置。
Type: string Default: null Valid Values: Importance: high -
ssl.truststore.password
信任存储文件的密码。如果未设置密码,仍将使用配置的信任存储文件,但禁用完整性检查。PEM 格式不支持信任存储密码。
Type: password Default: null Valid Values: Importance: high -
client.dns.lookup
控制客户端如何使用 DNS 查找。如果设置为
use_all_dns_ips
,则按顺序连接每个返回的 IP 地址,直到建立成功连接。断开连接后,将使用下一个 IP。一旦所有 IP 使用一次,客户端就会再次从主机名解析 IP(但是 JVM 和操作系统都会缓存 DNS 名称查找)。如果设置为resolve_canonical_bootstrap_servers_only
,则将每个引导地址解析为规范名称列表。在引导阶段之后,其行为与 相同use_all_dns_ips
。Type: string Default: use_all_dns_ips Valid Values: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only] Importance: medium -
connections.max.idle.ms
在该配置指定的毫秒数后关闭空闲连接。
Type: long Default: 540000 (9 minutes) Valid Values: Importance: medium -
connector.client.config.override.policy
的实现的类名或别名
ConnectorClientConfigOverridePolicy
。定义连接器可以覆盖哪些客户端配置。默认实现是“All”,这意味着连接器配置可以覆盖所有客户端属性。框架中的其他可能的策略包括“None”(禁止连接器覆盖客户端属性)和“Principal”(允许连接器仅覆盖客户端主体)。Type: string Default: All Valid Values: Importance: medium -
receive.buffer.bytes
读取数据时使用的 TCP 接收缓冲区 (SO_RCVBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 32768 (32 kibibytes) Valid Values: [-1,...] Importance: medium -
request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。
Type: int Default: 40000 (40 seconds) Valid Values: [0,...] Importance: medium -
sasl.client.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。
Type: class Default: null Valid Values: Importance: medium -
sasl.jaas.config
SASL 连接的 JAAS 登录上下文参数采用 JAAS 配置文件使用的格式。JAAS 配置文件格式描述如下。该值的格式为:
loginModuleClass controlFlag (optionName=optionValue)*;
。对于代理,配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,需要listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule;Type: password Default: null Valid Values: Importance: medium -
sasl.kerberos.service.name
Kafka 运行时使用的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 的配置中定义。
Type: string Default: null Valid Values: Importance: medium -
sasl.login.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理,登录回调处理程序配置必须以侦听器前缀和小写的 SASL 机制名称为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
Type: class Default: null Valid Values: Importance: medium -
sasl.login.class
实现 Login 接口的类的完全限定名称。对于代理,登录配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
Type: class Default: null Valid Values: Importance: medium -
sasl.mechanism
用于客户端连接的 SASL 机制。这可以是安全提供者可用的任何机制。GSSAPI 是默认机制。
Type: string Default: GSSAPI Valid Values: Importance: medium -
sasl.oauthbearer.jwks.endpoint.url
可以从中检索提供商的JWKS(JSON Web 密钥集)的 OAuth/OIDC 提供商 URL。URL 可以基于 HTTP(S) 或基于文件。如果 URL 基于 HTTP(S),则将通过代理启动时配置的 URL 从 OAuth/OIDC 提供程序检索 JWKS 数据。所有当时的密钥都将缓存在代理上以用于传入请求。如果收到 JWT 的身份验证请求,其中包含尚未在缓存中的“kid”标头声明值,则将根据需要再次查询 JWKS 端点。但是,代理会每隔 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒轮询一次 URL,以便在收到包含这些密钥的任何 JWT 请求之前使用任何即将到来的密钥刷新缓存。如果 URL 是基于文件的,代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含 JWKS 文件中不存在的“kid”标头值,代理将拒绝 JWT 并且身份验证将失败。
Type: string Default: null Valid Values: Importance: medium -
sasl.oauthbearer.token.endpoint.url
OAuth/OIDC 身份提供商的 URL。如果 URL 基于 HTTP(S),则它是颁发者的令牌端点 URL,将根据 sasl.jaas.config 中的配置发出登录请求。如果 URL 是基于文件的,则它指定一个包含 OAuth/OIDC 身份提供商颁发的访问令牌(JWT 序列化形式)的文件,用于授权。
Type: string Default: null Valid Values: Importance: medium -
security.protocol
用于与经纪人通信的协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
Type: string Default: PLAINTEXT Valid Values: (case insensitive) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] Importance: medium -
send.buffer.bytes
发送数据时使用的 TCP 发送缓冲区 (SO_SNDBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 131072 (128 kibibytes) Valid Values: [-1,...] Importance: medium -
ssl.enabled.protocols
为 SSL 连接启用的协议列表。使用 Java 11 或更高版本运行时,默认值为“TLSv1.2、TLSv1.3”,否则为“TLSv1.2”。使用 Java 11 的默认值,如果客户端和服务器都支持 TLSv1.3,则首选 TLSv1.3,否则回退到 TLSv1.2(假设两者至少支持 TLSv1.2)。对于大多数情况,此默认值应该没问题。另请参阅“ssl.protocol”的配置文档。
Type: list Default: TLSv1.2,TLSv1.3 Valid Values: Importance: medium -
ssl.keystore.type
密钥存储文件的文件格式。这对于客户来说是可选的。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
ssl.protocol
用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更高版本运行时,默认值为“TLSv1.3”,否则为“TLSv1.2”。该值对于大多数用例来说应该没问题。最新 JVM 中允许的值为“TLSv1.2”和“TLSv1.3”。较旧的 JVM 可能支持“TLS”、“TLSv1.1”、“SSL”、“SSLv2”和“SSLv3”,但由于已知的安全漏洞,不鼓励使用它们。使用此配置和“ssl.enabled.protocols”的默认值,如果服务器不支持“TLSv1.3”,客户端将降级到“TLSv1.2”。如果此配置设置为“TLSv1.2”,客户端将不会使用“TLSv1.3”,即使它是 ssl.enabled.protocols 中的值之一,并且服务器仅支持“TLSv1.3”。
Type: string Default: TLSv1.3 Valid Values: Importance: medium -
ssl.provider
用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
Type: string Default: null Valid Values: Importance: medium -
ssl.truststore.type
信任存储文件的文件格式。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
worker.sync.timeout.ms
当工作人员与其他工作人员不同步并且需要重新同步配置时,请在放弃、离开组之前等待一段时间,并在重新加入之前等待一段退避期。
Type: int Default: 3000 (3 seconds) Valid Values: Importance: medium -
worker.unsync.backoff.ms
当工作线程与其他工作线程不同步并且无法在worker.sync.timeout.ms内赶上时,请在重新加入之前离开Connect集群这么长时间。
Type: int Default: 300000 (5 minutes) Valid Values: Importance: medium -
access.control.allow.methods
通过设置 Access-Control-Allow-Methods 标头来设置跨源请求支持的方法。Access-Control-Allow-Methods 标头的默认值允许 GET、POST 和 HEAD 的跨源请求。
Type: string Default: "" Valid Values: Importance: low -
access.control.allow.origin
为 REST API 请求设置 Access-Control-Allow-Origin 标头的值。要启用跨源访问,请将其设置为应允许访问 API 的应用程序的域,或“*”以允许来自任何域的访问领域。默认值仅允许从 REST API 的域进行访问。
Type: string Default: "" Valid Values: Importance: low -
admin.listeners
管理 REST API 将侦听的以逗号分隔的 URI 列表。支持的协议是 HTTP 和 HTTPS。空字符串将禁用此功能。默认行为是使用常规侦听器(由“侦听器”属性指定)。
Type: list Default: null Valid Values: List of comma-separated URLs, ex: http://localhost:8080,https://localhost:8443. Importance: low -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low -
client.id
发出请求时传递给服务器的 id 字符串。这样做的目的是通过允许在服务器端请求日志记录中包含逻辑应用程序名称,能够跟踪 IP/端口之外的请求源。
Type: string Default: "" Valid Values: Importance: low -
config.providers
以逗号分隔的
ConfigProvider
类名称,按指定的顺序加载和使用。实现该接口ConfigProvider
允许您替换连接器配置中的变量引用,例如外部化机密。Type: list Default: "" Valid Values: Importance: low -
config.storage.replication.factor
创建配置存储主题时使用的复制因子
Type: short Default: 3 Valid Values: Positive number not larger than the number of brokers in the Kafka cluster, or -1 to use the broker's default Importance: low -
connect.protocol
Kafka Connect 协议的兼容模式
Type: string Default: sessioned Valid Values: [eager, compatible, sessioned] Importance: low -
header.converter
HeaderConverter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中标头值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。默认情况下,SimpleHeaderConverter 用于将标头值序列化为字符串,并通过推断架构来反序列化它们。
Type: class Default: org.apache.kafka.connect.storage.SimpleHeaderConverter Valid Values: Importance: low -
inter.worker.key.generation.algorithm
用于生成内部请求密钥的算法。算法“HmacSHA256”将在支持该算法的 JVM 上默认使用;在其他 JVM 上,不使用默认值,并且必须在工作配置中手动指定此属性的值。
Type: string Default: HmacSHA256 Valid Values: Any KeyGenerator algorithm supported by the worker JVM Importance: low -
inter.worker.key.size
用于签署内部请求的密钥的大小(以位为单位)。如果为空,则将使用密钥生成算法的默认密钥大小。
Type: int Default: null Valid Values: Importance: low -
inter.worker.key.ttl.ms
用于内部请求验证的生成会话密钥的 TTL(以毫秒为单位)
Type: int Default: 3600000 (1 hour) Valid Values: [0,...,2147483647] Importance: low -
inter.worker.signature.algorithm
用于签署内部请求的算法“inter.worker.signature.algorithm”算法将在支持该算法的 JVM 上默认使用;在其他 JVM 上,不使用默认值,并且必须在工作配置中手动指定此属性的值。
Type: string Default: HmacSHA256 Valid Values: Any MAC algorithm supported by the worker JVM Importance: low -
inter.worker.verification.algorithms
用于验证内部请求的允许算法列表,其中必须包括用于 inter.worker.signature.algorithm 属性的算法。算法“[HmacSHA256]”将用作提供它们的 JVM 的默认值;在其他 JVM 上,不使用默认值,并且必须在工作配置中手动指定此属性的值。
Type: list Default: HmacSHA256 Valid Values: A list of one or more MAC algorithms, each supported by the worker JVM Importance: low -
listeners
REST API 将侦听的以逗号分隔的 URI 列表。支持的协议是 HTTP 和 HTTPS。
将主机名指定为 0.0.0.0 以绑定到所有接口。
将主机名留空以绑定到默认接口。
合法侦听器列表示例:HTTP://myhost:8083、HTTPS://myhost:8084Type: list Default: http://:8083 Valid Values: List of comma-separated URLs, ex: http://localhost:8080,https://localhost:8443. Importance: low -
metadata.max.age.ms
即使我们没有看到任何分区领导层发生变化以主动发现任何新的代理或分区,我们也会强制刷新元数据,以毫秒为单位的时间段。
Type: long Default: 300000 (5 minutes) Valid Values: [0,...] Importance: low -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: "" Valid Values: Importance: low -
metrics.num.samples
为计算指标而维护的样本数量。
Type: int Default: 2 Valid Values: [1,...] Importance: low -
metrics.recording.level
指标的最高记录级别。
Type: string Default: INFO Valid Values: [INFO, DEBUG] Importance: low -
metrics.sample.window.ms
计算指标样本的时间窗口。
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
offset.flush.interval.ms
尝试提交任务偏移量的时间间隔。
Type: long Default: 60000 (1 minute) Valid Values: Importance: low -
offset.flush.timeout.ms
在取消进程并恢复要在未来尝试中提交的偏移数据之前,等待记录刷新并将分区偏移数据提交到偏移存储的最大毫秒数。此属性对于以一次性支持运行的源连接器没有影响。
Type: long Default: 5000 (5 seconds) Valid Values: Importance: low -
offset.storage.partitions
创建offset存储topic时使用的分区数量
Type: int Default: 25 Valid Values: Positive number, or -1 to use the broker's default Importance: low -
offset.storage.replication.factor
创建偏移存储主题时使用的复制因子
Type: short Default: 3 Valid Values: Positive number not larger than the number of brokers in the Kafka cluster, or -1 to use the broker's default Importance: low -
plugin.discovery
用于发现类路径和plugin.path 配置中存在的插件的方法。这可以是具有以下含义的多个值之一:
* only_scan:仅通过反射发现插件。ServiceLoader 无法发现的插件不会影响工作进程启动。
* Hybrid_warn:通过 ServiceLoader 反射性地发现插件。ServiceLoader 无法发现的插件将在工作进程启动期间打印警告。
* Hybrid_fail:通过 ServiceLoader 反思性地发现插件。ServiceLoader 无法发现的插件将导致工作进程启动失败。
* service_load:仅通过ServiceLoader发现插件。比其他模式启动更快。ServiceLoader 无法发现的插件可能无法使用。Type: string Default: hybrid_warn Valid Values: (case insensitive) [ONLY_SCAN, SERVICE_LOAD, HYBRID_WARN, HYBRID_FAIL] Importance: low -
plugin.path
由逗号 (,) 分隔的包含插件(连接器、转换器、转换)的路径列表。该列表应由顶级目录组成,其中包括以下任意组合:
a) 直接包含带有插件及其依赖项的 jar 的目录
b) 带有插件及其依赖项的 uber-jars
c) 立即包含插件类及其依赖项的包目录结构的目录依赖项
注意:将遵循符号链接来发现依赖项或插件。
示例:plugin.path=/usr/local/share/java,/usr/local/share/kafka/plugins,/opt/connectors
不要在此属性中使用配置提供程序变量,因为原始路径由工作程序的扫描仪使用在配置提供程序初始化并用于替换变量之前。Type: list Default: null Valid Values: Importance: low -
reconnect.backoff.max.ms
重新连接到多次连接失败的代理时等待的最长时间(以毫秒为单位)。如果提供,每个主机的退避将在每次连续连接失败时呈指数增加,直至达到此最大值。计算退避增量后,添加 20% 的随机抖动以避免连接风暴。
Type: long Default: 1000 (1 second) Valid Values: [0,...] Importance: low -
reconnect.backoff.ms
尝试重新连接到给定主机之前等待的基本时间量。这避免了在紧密循环中重复连接到主机。此退避适用于客户端与代理的所有连接尝试。
Type: long Default: 50 Valid Values: [0,...] Importance: low -
response.http.headers.config
REST API HTTP 响应标头的规则
Type: string Default: "" Valid Values: Comma-separated header rules, where each header rule is of the form '[action] [header name]:[header value]' and optionally surrounded by double quotes if any part of a header rule contains a comma Importance: low -
rest.advertised.host.name
如果设置了此项,则这就是将提供给其他工作人员进行连接的主机名。
Type: string Default: null Valid Values: Importance: low -
rest.advertised.listener
设置将提供给其他工作人员使用的广告侦听器(HTTP 或 HTTPS)。
Type: string Default: null Valid Values: Importance: low -
rest.advertised.port
如果设置了此端口,则该端口将提供给其他工作人员进行连接。
Type: int Default: null Valid Values: Importance: low -
rest.extension.classes
以逗号分隔的
ConnectRestExtension
类名称,按指定的顺序加载和调用。实现该接口ConnectRestExtension
允许您将用户定义的资源(例如过滤器)注入 Connect 的 REST API。通常用于添加自定义功能,例如日志记录、安全性等。Type: list Default: "" Valid Values: Importance: low -
retry.backoff.ms
尝试重试对给定主题分区的失败请求之前等待的时间。这避免了在某些故障场景下在紧密循环中重复发送请求。
Type: long Default: 100 Valid Values: [0,...] Importance: low -
sasl.kerberos.kinit.cmd
Kerberos kinit 命令路径。
Type: string Default: /usr/bin/kinit Valid Values: Importance: low -
sasl.kerberos.min.time.before.relogin
刷新尝试之间的登录线程睡眠时间。
Type: long Default: 60000 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.jitter
添加到更新时间的随机抖动的百分比。
Type: double Default: 0.05 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.window.factor
登录线程将休眠,直到达到从上次刷新到票证到期的指定时间窗口因子,此时它将尝试更新票证。
Type: double Default: 0.8 Valid Values: Importance: low -
sasl.login.connect.timeout.ms
外部身份验证提供程序连接超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.read.timeout.ms
外部身份验证提供程序读取超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.refresh.buffer.seconds
刷新凭证时在凭证过期前维持的缓冲时间量(以秒为单位)。如果刷新发生的时间比缓冲秒数更接近到期,则刷新将向上移动以维持尽可能多的缓冲时间。合法值介于 0 到 3600(1 小时)之间;如果未指定值,则使用默认值 300(5 分钟)。如果该值和 sasl.login.refresh.min.period.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 300 Valid Values: [0,...,3600] Importance: low -
sasl.login.refresh.min.period.seconds
登录刷新线程在刷新凭据之前等待的所需最短时间(以秒为单位)。合法值介于 0 到 900(15 分钟)之间;如果未指定值,则使用默认值 60(1 分钟)。如果该值和 sasl.login.refresh.buffer.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 60 Valid Values: [0,...,900] Importance: low -
sasl.login.refresh.window.factor
登录刷新线程将休眠,直到达到相对于凭证生命周期的指定窗口因子,此时它将尝试刷新凭证。合法值介于 0.5 (50%) 和 1.0 (100%)(含)之间;如果未指定值,则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.8 Valid Values: [0.5,...,1.0] Importance: low -
sasl.login.refresh.window.jitter
相对于添加到登录刷新线程睡眠时间的凭证生命周期的最大随机抖动量。合法值介于 0 和 0.25 (25%) 之间(含);如果未指定值,则使用默认值 0.05 (5%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.05 Valid Values: [0.0,...,0.25] Importance: low -
sasl.login.retry.backoff.max.ms
尝试登录外部身份验证提供程序之间的最长等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.login.retry.backoff.ms
尝试登录外部身份验证提供程序之间的初始等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.clock.skew.seconds
以秒为单位的(可选)值,以允许 OAuth/OIDC 身份提供商和代理的时间之间存在差异。
Type: int Default: 30 Valid Values: Importance: low -
sasl.oauthbearer.expected.audience
代理的(可选)逗号分隔设置,用于验证 JWT 是否是为预期受众之一颁发的。将检查 JWT 是否有标准 OAuth“aud”声明,如果设置了此值,代理将匹配 JWT 的“aud”声明中的值,以查看是否存在完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: list Default: null Valid Values: Importance: low -
sasl.oauthbearer.expected.issuer
代理用于验证 JWT 是否由预期发行者创建的(可选)设置。将检查 JWT 是否有标准 OAuth“iss”声明,如果设置了该值,代理会将其与 JWT 的“iss”声明中的内容完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: string Default: null Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.refresh.ms
代理在刷新其 JWKS(JSON Web 密钥集)缓存之间等待的(可选)值(以毫秒为单位),该缓存包含用于验证 JWT 签名的密钥。
Type: long Default: 3600000 (1 hour) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms
尝试从外部身份验证提供程序检索 JWKS(JSON Web 密钥集)之间的最长等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.ms
来自外部身份验证提供程序的 JWKS(JSON Web 密钥集)检索尝试之间的初始等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.scope.claim.name
该范围的 OAuth 声明通常被命名为“scope”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的范围提供不同的名称。
Type: string Default: scope Valid Values: Importance: low -
sasl.oauthbearer.sub.claim.name
主题的 OAuth 声明通常命名为“sub”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的主题提供不同的名称。
Type: string Default: sub Valid Values: Importance: low -
scheduled.rebalance.max.delay.ms
为等待一名或多名离职工作人员返回而安排的最大延迟,然后再重新平衡其连接器和任务并将其重新分配给组。在此期间,离职员工的连接器和任务仍未分配
Type: int Default: 300000 (5 minutes) Valid Values: [0,...,2147483647] Importance: low -
socket.connection.setup.timeout.max.ms
客户端等待建立套接字连接的最长时间。对于每个连续的连接失败,连接设置超时将呈指数增长,直至达到此最大值。为了避免连接风暴,将对超时应用 0.2 的随机化因子,从而产生比计算值低 20% 到高 20% 之间的随机范围。
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
socket.connection.setup.timeout.ms
客户端等待建立套接字连接的时间。如果在超时之前未建立连接,客户端将关闭套接字通道。
Type: long Default: 10000 (10 seconds) Valid Values: [0,...] Importance: low -
ssl.cipher.suites
密码套件列表。这是身份验证、加密、MAC 和密钥交换算法的命名组合,用于使用 TLS 或 SSL 网络协议协商网络连接的安全设置。默认情况下,支持所有可用的密码套件。
Type: list Default: null Valid Values: Importance: low -
ssl.client.auth
配置 kafka 代理来请求客户端身份验证。以下设置是常见的:
ssl.client.auth=required
如果设置为必需,则需要客户端身份验证。ssl.client.auth=requested
这意味着客户端身份验证是可选的。与必需的不同,如果设置了此选项,客户端可以选择不提供有关其自身的身份验证信息ssl.client.auth=none
这意味着不需要客户端身份验证。
Type: string Default: none Valid Values: [required, requested, none] Importance: low -
ssl.endpoint.identification.algorithm
使用服务器证书验证服务器主机名的端点识别算法。
Type: string Default: https Valid Values: Importance: low -
ssl.engine.factory.class
org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory
Type: class Default: null Valid Values: Importance: low -
ssl.keymanager.algorithm
密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。
Type: string Default: SunX509 Valid Values: Importance: low -
ssl.secure.random.implementation
用于 SSL 加密操作的 SecureRandom PRNG 实现。
Type: string Default: null Valid Values: Importance: low -
ssl.trustmanager.algorithm
信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。
Type: string Default: PKIX Valid Values: Importance: low -
status.storage.partitions
创建状态存储topic时使用的分区数量
Type: int Default: 5 Valid Values: Positive number, or -1 to use the broker's default Importance: low -
status.storage.replication.factor
创建状态存储主题时使用的复制因子
Type: short Default: 3 Valid Values: Positive number not larger than the number of brokers in the Kafka cluster, or -1 to use the broker's default Importance: low -
task.shutdown.graceful.timeout.ms
等待任务正常关闭的时间。这是总时间,而不是每个任务的时间。所有任务都已触发关闭,然后按顺序等待。
Type: long Default: 5000 (5 seconds) Valid Values: Importance: low -
topic.creation.enable
当源连接器配置了“topic.creation.”属性时,是否允许自动创建源连接器使用的主题。每个任务都将使用管理客户端来创建其主题,并且不会依赖 Kafka 代理自动创建主题。
Type: boolean Default: true Valid Values: Importance: low -
topic.tracking.allow.reset
如果设置为 true,则允许用户请求重置每个连接器的活动主题集。
Type: boolean Default: true Valid Values: Importance: low -
topic.tracking.enable
启用在运行时跟踪每个连接器的活动主题集。
Type: boolean Default: true Valid Values: Importance: low
3.5.1 源连接器配置
以下是源连接器的配置。-
name
用于此连接器的全局唯一名称。
Type: string Default: Valid Values: non-empty string without ISO control characters Importance: high -
connector.class
此连接器的类的名称或别名。必须是 org.apache.kafka.connect.connector.Connector 的子类。如果连接器是org.apache.kafka.connect.file.FileStreamSinkConnector,您可以指定这个全名,或者使用“FileStreamSink”或“FileStreamSinkConnector”使配置更短一些
Type: string Default: Valid Values: Importance: high -
tasks.max
用于此连接器的最大任务数。
Type: int Default: 1 Valid Values: [1,...] Importance: high -
key.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中键的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: null Valid Values: Importance: low -
value.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中的值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: null Valid Values: Importance: low -
header.converter
HeaderConverter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中标头值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。默认情况下,SimpleHeaderConverter 用于将标头值序列化为字符串,并通过推断架构来反序列化它们。
Type: class Default: null Valid Values: Importance: low -
config.action.reload
当外部配置提供程序的更改导致连接器的配置属性发生更改时,Connect 应对连接器执行的操作。值“none”表示 Connect 将不执行任何操作。“restart”值表示 Connect 应使用更新的配置属性重新启动/重新加载连接器。如果外部配置提供程序指示配置值将来会过期,则实际上可能会在将来安排重新启动。
Type: string Default: restart Valid Values: [none, restart] Importance: low -
transforms
应用于记录的转换的别名。
Type: list Default: "" Valid Values: non-null string, unique transformation aliases Importance: low -
predicates
转换使用的谓词的别名。
Type: list Default: "" Valid Values: non-null string, unique predicate aliases Importance: low -
errors.retry.timeout
重新尝试失败操作的最大持续时间(以毫秒为单位)。默认值为 0,这意味着不会尝试重试。使用 -1 进行无限重试。
Type: long Default: 0 Valid Values: Importance: medium -
errors.retry.delay.max.ms
连续重试之间的最大持续时间(以毫秒为单位)。一旦达到此限制,抖动就会添加到延迟中,以防止雷群问题。
Type: long Default: 60000 (1 minute) Valid Values: Importance: medium -
errors.tolerance
连接器操作期间容忍错误的行为。“none”是默认值,表示任何错误都将导致连接器任务立即失败;“all”更改行为以跳过有问题的记录。
Type: string Default: none Valid Values: [none, all] Importance: medium -
errors.log.enable
如果为 true,则将每个错误以及失败操作的详细信息和有问题的记录写入 Connect 应用程序日志。默认情况下此值为“false”,因此仅报告不能容忍的错误。
Type: boolean Default: false Valid Values: Importance: medium -
errors.log.include.messages
是否在日志中包含导致失败的连接记录。对于接收器记录,将记录主题、分区、偏移量和时间戳。对于源记录,将记录键和值(及其模式)、所有标头以及时间戳、Kafka 主题、Kafka 分区、源分区和源偏移量。默认情况下这是“false”,这将阻止记录键、值和标头写入日志文件。
Type: boolean Default: false Valid Values: Importance: medium -
topic.creation.groups
由源连接器创建的主题配置组
Type: list Default: "" Valid Values: non-null string, unique topic creation groups Importance: low -
exactly.once.support
允许的值是请求的、必需的。如果设置为“必需”,则强制对连接器进行预检,以确保它可以使用给定的配置提供一次性语义。某些连接器可能能够提供一次性语义,但不会向 Connect 发出信号表明它们支持此功能;在这种情况下,在创建连接器之前应仔细查阅连接器的文档,并且该属性的值应设置为“请求”。此外,如果该值设置为“必需”,但执行预检验证的工作线程没有为源连接器启用恰好一次支持,则创建或验证连接器的请求将失败。
Type: string Default: requested Valid Values: (case insensitive) [REQUIRED, REQUESTED] Importance: medium -
transaction.boundary
允许的值为:轮询、间隔、连接器。如果设置为“轮询”,则将为该连接器中的每个任务提供给 Connect 的每批记录启动并提交一个新的生产者事务。如果设置为“连接器”,则依赖于连接器定义的事务边界;请注意,并非所有连接器都能够定义自己的事务边界,在这种情况下,尝试使用此值实例化连接器将会失败。最后,如果设置为“interval”,则仅在用户定义的时间间隔过去后提交事务。
Type: string Default: poll Valid Values: (case insensitive) [INTERVAL, POLL, CONNECTOR] Importance: medium -
transaction.boundary.interval.ms
如果“transaction.boundary”设置为“interval”,则确定连接器任务提交生产者事务的时间间隔。如果未设置,则默认为工作线程级别“offset.flush.interval.ms”属性的值。如果指定了不同的 transaction.boundary 则没有任何影响。
Type: long Default: null Valid Values: [0,...] Importance: low -
offsets.storage.topic
用于此连接器的单独偏移主题的名称。如果为空或未指定,则将使用工作人员的全局偏移量主题名称。如果指定,如果该连接器的目标 Kafka 集群上尚不存在偏移量主题,则将创建该偏移量主题(如果连接器生产者的 bootstrap.servers 属性已被设置,则该偏移量主题可能与用于工作线程全局偏移量主题的主题不同)从工人的覆盖)。仅适用于分布式模式;在独立模式下,设置该属性将不起作用。
Type: string Default: null Valid Values: non-empty string Importance: low
3.5.2 接收器连接器配置
以下是接收器连接器的配置。-
name
用于此连接器的全局唯一名称。
Type: string Default: Valid Values: non-empty string without ISO control characters Importance: high -
connector.class
此连接器的类的名称或别名。必须是 org.apache.kafka.connect.connector.Connector 的子类。如果连接器是org.apache.kafka.connect.file.FileStreamSinkConnector,您可以指定这个全名,或者使用“FileStreamSink”或“FileStreamSinkConnector”使配置更短一些
Type: string Default: Valid Values: Importance: high -
tasks.max
用于此连接器的最大任务数。
Type: int Default: 1 Valid Values: [1,...] Importance: high -
topics
要使用的主题列表,以逗号分隔
Type: list Default: "" Valid Values: Importance: high -
topics.regex
提供要使用的主题的正则表达式。在底层,正则表达式被编译为
java.util.regex.Pattern
. 仅应指定 topic 或 topic.regex 之一。Type: string Default: "" Valid Values: valid regex Importance: high -
key.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中键的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: null Valid Values: Importance: low -
value.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中的值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: null Valid Values: Importance: low -
header.converter
HeaderConverter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中标头值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。默认情况下,SimpleHeaderConverter 用于将标头值序列化为字符串,并通过推断架构来反序列化它们。
Type: class Default: null Valid Values: Importance: low -
config.action.reload
当外部配置提供程序的更改导致连接器的配置属性发生更改时,Connect 应对连接器执行的操作。值“none”表示 Connect 将不执行任何操作。“restart”值表示 Connect 应使用更新的配置属性重新启动/重新加载连接器。如果外部配置提供程序指示配置值将来会过期,则实际上可能会在将来安排重新启动。
Type: string Default: restart Valid Values: [none, restart] Importance: low -
transforms
应用于记录的转换的别名。
Type: list Default: "" Valid Values: non-null string, unique transformation aliases Importance: low -
predicates
转换使用的谓词的别名。
Type: list Default: "" Valid Values: non-null string, unique predicate aliases Importance: low -
errors.retry.timeout
重新尝试失败操作的最大持续时间(以毫秒为单位)。默认值为 0,这意味着不会尝试重试。使用 -1 进行无限重试。
Type: long Default: 0 Valid Values: Importance: medium -
errors.retry.delay.max.ms
连续重试之间的最大持续时间(以毫秒为单位)。一旦达到此限制,抖动就会添加到延迟中,以防止雷群问题。
Type: long Default: 60000 (1 minute) Valid Values: Importance: medium -
errors.tolerance
连接器操作期间容忍错误的行为。“none”是默认值,表示任何错误都将导致连接器任务立即失败;“all”更改行为以跳过有问题的记录。
Type: string Default: none Valid Values: [none, all] Importance: medium -
errors.log.enable
如果为 true,则将每个错误以及失败操作的详细信息和有问题的记录写入 Connect 应用程序日志。默认情况下此值为“false”,因此仅报告不能容忍的错误。
Type: boolean Default: false Valid Values: Importance: medium -
errors.log.include.messages
是否在日志中包含导致失败的连接记录。对于接收器记录,将记录主题、分区、偏移量和时间戳。对于源记录,将记录键和值(及其模式)、所有标头以及时间戳、Kafka 主题、Kafka 分区、源分区和源偏移量。默认情况下这是“false”,这将阻止记录键、值和标头写入日志文件。
Type: boolean Default: false Valid Values: Importance: medium -
errors.deadletterqueue.topic.name
用作死信队列 (DLQ) 的主题名称,用于处理由此接收器连接器或其转换或转换器时导致错误的消息。默认情况下,主题名称为空,这意味着 DLQ 中不会记录任何消息。
Type: string Default: "" Valid Values: Importance: medium -
errors.deadletterqueue.topic.replication.factor
当死信队列主题尚不存在时,用于创建该主题的复制因子。
Type: short Default: 3 Valid Values: Importance: medium -
errors.deadletterqueue.context.headers.enable
如果为 true,则将包含错误上下文的标头添加到写入死信队列的消息中。为了避免与原始记录中的标头冲突,所有错误上下文标头键,所有错误上下文标头键都将以
__connect.errors.
Type: boolean Default: false Valid Values: Importance: medium
3.6 Kafka流配置
以下是 Kafka Streams 客户端库的配置。-
application.id
流处理应用程序的标识符。在 Kafka 集群中必须是唯一的。它用作 1) 默认客户端 ID 前缀,2) 用于成员资格管理的组 ID,3) 变更日志主题前缀。
Type: string Default: Valid Values: Importance: high -
bootstrap.servers
用于建立与 Kafka 集群的初始连接的主机/端口对列表。客户端将使用所有服务器,无论此处指定哪些服务器进行引导 - 该列表仅影响用于发现全套服务器的初始主机。该列表应采用以下形式
host1:port1,host2:port2,...
。由于这些服务器仅用于初始连接以发现完整的集群成员资格(可能会动态更改),因此此列表不需要包含完整的服务器集(不过,您可能需要多个服务器,以防服务器停机) 。Type: list Default: Valid Values: Importance: high -
num.standby.replicas
每个任务的备用副本数。
Type: int Default: 0 Valid Values: Importance: high -
state.dir
状态存储的目录位置。对于共享相同底层文件系统的每个流实例,此路径必须是唯一的。
Type: string Default: /var/folders/1w/r49gc42j1ml6ddw0lhlvt9pw0000gn/T//kafka-streams Valid Values: Importance: high -
acceptable.recovery.lag
客户端被视为已赶上足以接收活动任务分配的最大可接受滞后(要赶上的偏移量数量)。分配后,它仍然会在处理之前恢复变更日志的其余部分。为了避免重新平衡期间处理暂停,此配置应对应于给定工作负载的远低于一分钟的恢复时间。必须至少为 0。
Type: long Default: 10000 Valid Values: [0,...] Importance: medium -
cache.max.bytes.buffering
用于跨所有线程缓冲的最大内存字节数
Type: long Default: 10485760 Valid Values: [0,...] Importance: medium -
client.id
用于内部消费者、生产者和恢复消费者的客户端 ID 的 ID 前缀字符串,模式为
<client.id>-StreamThread-<threadSequenceNumber$gt;-<consumer|producer|restore-consumer>
。Type: string Default: "" Valid Values: Importance: medium -
default.deserialization.exception.handler
实现该
org.apache.kafka.streams.errors.DeserializationExceptionHandler
接口的异常处理类。Type: class Default: org.apache.kafka.streams.errors.LogAndFailExceptionHandler Valid Values: Importance: medium -
default.key.serde
实现
org.apache.kafka.common.serialization.Serde
接口的键的默认序列化器/反序列化器类。org.apache.kafka.common.serialization.Serde
请注意,当使用窗口化 Serde 类时,还需要通过“default.windowed.key.serde.inner”或“default.windowed.value.serde.inner”设置实现该接口的内部 serde 类Type: class Default: null Valid Values: Importance: medium -
default.list.key.serde.inner
实现接口的 key 的 list serde 的默认内部类
org.apache.kafka.common.serialization.Serde
。当且仅当default.key.serde
配置设置为org.apache.kafka.common.serialization.Serdes.ListSerde
Type: class Default: null Valid Values: Importance: medium -
default.list.key.serde.type
实现
java.util.List
接口的键的默认类。当且仅当default.key.serde
配置设置为org.apache.kafka.common.serialization.Serdes.ListSerde
Note 当使用 list serde 类时,需要设置org.apache.kafka.common.serialization.Serde
通过 'default.list.key.serde.inner' 实现接口的内部 serde 类时,才会读取此配置Type: class Default: null Valid Values: Importance: medium -
default.list.value.serde.inner
实现
org.apache.kafka.common.serialization.Serde
接口的值的列表 serde 的默认内部类。当且仅当default.value.serde
配置设置为org.apache.kafka.common.serialization.Serdes.ListSerde
Type: class Default: null Valid Values: Importance: medium -
default.list.value.serde.type
实现
java.util.List
接口的值的默认类。当且仅当default.value.serde
配置设置为org.apache.kafka.common.serialization.Serdes.ListSerde
Note 当使用 list serde 类时,需要设置org.apache.kafka.common.serialization.Serde
通过 'default.list.value.serde.inner' 实现接口的内部 serde 类时,才会读取此配置Type: class Default: null Valid Values: Importance: medium -
default.production.exception.handler
实现该
org.apache.kafka.streams.errors.ProductionExceptionHandler
接口的异常处理类。Type: class Default: org.apache.kafka.streams.errors.DefaultProductionExceptionHandler Valid Values: Importance: medium -
default.timestamp.extractor
实现该
org.apache.kafka.streams.processor.TimestampExtractor
接口的默认时间戳提取器类。Type: class Default: org.apache.kafka.streams.processor.FailOnInvalidTimestamp Valid Values: Importance: medium -
default.value.serde
实现
org.apache.kafka.common.serialization.Serde
接口的值的默认序列化器/反序列化器类。org.apache.kafka.common.serialization.Serde
请注意,当使用窗口化 Serde 类时,还需要通过“default.windowed.key.serde.inner”或“default.windowed.value.serde.inner”设置实现该接口的内部 serde 类Type: class Default: null Valid Values: Importance: medium -
max.task.idle.ms
此配置控制连接和合并是否可能产生无序结果。配置值是流任务在完全赶上某些(但不是全部)输入分区以等待生产者发送附加记录并避免潜在的无序记录处理时保持空闲状态的最长时间(以毫秒为单位)跨多个输入流。默认值(零)不等待生产者发送更多记录,但它会等待获取代理上已存在的数据。此默认值意味着对于代理上已存在的记录,Streams 将按时间戳顺序处理它们。设置为 -1 以完全禁用空闲并处理任何本地可用的数据,即使这样做可能会产生无序处理。
Type: long Default: 0 Valid Values: Importance: medium -
max.warmup.replicas
可以一次分配的最大预热副本数(超出配置的 num.standbys 的额外备用副本),以便在任务在已重新分配到的另一实例上预热时保持任务在一个实例上可用。用于限制可用于实现高可用性的额外代理流量和集群状态。必须至少为 1。注意,1 个预热副本对应一个 Stream Task。此外,请注意,每个预热副本只能在重新平衡期间提升为活动任务(通常在所谓的探测重新平衡期间,其发生频率由“probing.rebalance.interval.ms”配置指定)。这意味着活动任务可以从一个 Kafka Streams 实例迁移到另一个实例的最大速率可以通过 (`max.warmup.replicas` / `probing.rebalance.interval.ms`) 确定。
Type: int Default: 2 Valid Values: [1,...] Importance: medium -
num.stream.threads
执行流处理的线程数。
Type: int Default: 1 Valid Values: Importance: medium -
processing.guarantee
应使用的处理保证。可能的值为
at_least_once
(默认)和exactly_once_v2
(需要代理版本 2.5 或更高版本)。已弃用的选项有exactly_once
(需要代理版本 0.11.0 或更高版本)和exactly_once_beta
(需要代理版本 2.5 或更高版本)。请注意,默认情况下,一次处理需要至少三个代理的集群,推荐的生产设置是什么?对于开发,您可以通过调整代理设置transaction.state.log.replication.factor
和来更改此设置transaction.state.log.min.isr
。Type: string Default: at_least_once Valid Values: [at_least_once, exactly_once, exactly_once_beta, exactly_once_v2] Importance: medium -
rack.aware.assignment.non_overlap_cost
与从现有分配中转移任务相关的成本。此配置并
rack.aware.assignment.traffic_cost
控制优化算法是否有利于最小化跨机架流量或最小化现有分配中的任务移动。如果设置较大的值org.apache.kafka.streams.processor.internals.assignment.RackAwareTaskAssignor
将优化以维持现有分配。默认值为 null,这意味着它将在不同的分配器中使用默认的 non_overlap 成本值。Type: int Default: null Valid Values: Importance: medium -
rack.aware.assignment.strategy
我们用于机架感知分配的策略。分配任务时将考虑机架感知分配
client.rack
,以最大限度地减少跨机架流量。有效设置为:(默认),这将禁用机架感知分配;,这将计算最小跨机架流量分配。racks
TopicPartition
none
min_traffic
Type: string Default: none Valid Values: [none, min_traffic] Importance: medium -
rack.aware.assignment.tags
用于跨 Kafka Streams 实例分配备用副本的客户端标签键列表。配置后,Kafka Streams 将尽最大努力在每个客户端标签维度上分配备用任务。
Type: list Default: "" Valid Values: List containing maximum of 5 elements Importance: medium -
rack.aware.assignment.traffic_cost
与跨机架流量相关的成本。此配置并
rack.aware.assignment.non_overlap_cost
控制优化算法是否有利于最小化跨机架流量或最小化现有分配中的任务移动。如果设置较大的值,org.apache.kafka.streams.processor.internals.assignment.RackAwareTaskAssignor
将优化以最小化跨机架流量。默认值为 null,这意味着它将在不同的分配器中使用默认的流量成本值。Type: int Default: null Valid Values: Importance: medium -
replication.factor
流处理应用程序创建的更改日志主题和重新分区主题的复制因子。默认值
-1
(含义:使用代理默认复制因子)需要代理版本 2.4 或更高版本Type: int Default: -1 Valid Values: Importance: medium -
security.protocol
用于与经纪人通信的协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
Type: string Default: PLAINTEXT Valid Values: (case insensitive) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] Importance: medium -
statestore.cache.max.bytes
用于所有线程的状态存储缓存的最大内存字节数
Type: long Default: 10485760 (10 mebibytes) Valid Values: [0,...] Importance: medium -
task.timeout.ms
任务可能因内部错误而停止并重试直到出现错误的最长时间(以毫秒为单位)。对于 0 毫秒的超时,任务将针对第一个内部错误引发错误。对于任何大于 0 毫秒的超时,任务将在引发错误之前至少重试一次。
Type: long Default: 300000 (5 minutes) Valid Values: [0,...] Importance: medium -
topology.optimization
告诉 Kafka Streams 是否应该优化拓扑以及应用哪些优化的配置。可接受的值为:“+NO_OPTIMIZATION+”、“+OPTIMIZE+”或以逗号分隔的特定优化列表:(“+REUSE_KTABLE_SOURCE_TOPICS+”、“+MERGE_REPARTITION_TOPICS+”+“SINGLE_STORE_SELF_JOIN+”)。默认情况下为“NO_OPTIMIZATION”。
Type: string Default: none Valid Values: org.apache.kafka.streams.StreamsConfig$$Lambda$17/0x0000000800094840@5f341870 Importance: medium -
application.server
指向用户定义端点的主机:端口对,可用于此 KafkaStreams 实例上的状态存储发现和交互式查询。
Type: string Default: "" Valid Values: Importance: low -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low -
buffered.records.per.partition
每个分区缓冲的最大记录数。
Type: int Default: 1000 Valid Values: Importance: low -
built.in.metrics.version
要使用的内置指标的版本。
Type: string Default: latest Valid Values: [latest] Importance: low -
commit.interval.ms
提交处理进度的频率(以毫秒为单位)。对于至少一次处理,提交意味着保存处理器的位置(即偏移量)。对于exactly-once处理来说,意味着提交事务,包括保存位置以及使输出主题中提交的数据对隔离级别为read_commissed的消费者可见。(注意,如果
processing.guarantee
设置为exactly_once_v2
,exactly_once
,则默认值为100
,否则默认值为30000
。Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
connections.max.idle.ms
在该配置指定的毫秒数后关闭空闲连接。
Type: long Default: 540000 (9 minutes) Valid Values: Importance: low -
default.client.supplier
实现该
org.apache.kafka.streams.KafkaClientSupplier
接口的客户端供应商类。Type: class Default: org.apache.kafka.streams.processor.internals.DefaultKafkaClientSupplier Valid Values: Importance: low -
default.dsl.store
DSL 运营商使用的默认状态存储类型。
Type: string Default: rocksDB Valid Values: [rocksDB, in_memory] Importance: low -
metadata.max.age.ms
即使我们没有看到任何分区领导层发生变化以主动发现任何新的代理或分区,我们也会强制刷新元数据,以毫秒为单位的时间段。
Type: long Default: 300000 (5 minutes) Valid Values: [0,...] Importance: low -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: "" Valid Values: Importance: low -
metrics.num.samples
为计算指标而维护的样本数量。
Type: int Default: 2 Valid Values: [1,...] Importance: low -
metrics.recording.level
指标的最高记录级别。
Type: string Default: INFO Valid Values: [INFO, DEBUG, TRACE] Importance: low -
metrics.sample.window.ms
计算指标样本的时间窗口。
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
poll.ms
阻止等待输入的时间量(以毫秒为单位)。
Type: long Default: 100 Valid Values: Importance: low -
probing.rebalance.interval.ms
触发重新平衡以探测已完成预热并准备好激活的预热副本之前等待的最长时间(以毫秒为单位)。将继续触发探测重新平衡,直到分配平衡。必须至少 1 分钟。
Type: long Default: 600000 (10 minutes) Valid Values: [60000,...] Importance: low -
receive.buffer.bytes
读取数据时使用的 TCP 接收缓冲区 (SO_RCVBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 32768 (32 kibibytes) Valid Values: [-1,...] Importance: low -
reconnect.backoff.max.ms
重新连接到多次连接失败的代理时等待的最长时间(以毫秒为单位)。如果提供,每个主机的退避将在每次连续连接失败时呈指数增加,直至达到此最大值。计算退避增量后,添加 20% 的随机抖动以避免连接风暴。
Type: long Default: 1000 (1 second) Valid Values: [0,...] Importance: low -
reconnect.backoff.ms
尝试重新连接到给定主机之前等待的基本时间量。这避免了在紧密循环中重复连接到主机。此退避适用于客户端与代理的所有连接尝试。
Type: long Default: 50 Valid Values: [0,...] Importance: low -
repartition.purge.interval.ms
从重新分区主题中删除完全使用的记录的频率(以毫秒为单位)。自上次清除后至少会在该值之后进行清除,但可能会延迟到以后。(请注意,与 不同的是,当设置为
commit.interval.ms
时,该值的默认值保持不变)。processing.guarantee
exactly_once_v2
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。
Type: int Default: 40000 (40 seconds) Valid Values: [0,...] Importance: low -
retries
设置大于零的值将导致客户端重新发送因潜在的暂时性错误而失败的任何请求。建议将该值设置为零或“MAX_VALUE”,并使用相应的超时参数来控制客户端应重试请求的时间。
Type: int Default: 0 Valid Values: [0,...,2147483647] Importance: low -
retry.backoff.ms
尝试重试对给定主题分区的失败请求之前等待的时间。这避免了在某些故障场景下在紧密循环中重复发送请求。
Type: long Default: 100 Valid Values: [0,...] Importance: low -
rocksdb.config.setter
Rocks DB 配置设置器类或实现该
org.apache.kafka.streams.state.RocksDBConfigSetter
接口的类名Type: class Default: null Valid Values: Importance: low -
send.buffer.bytes
发送数据时使用的 TCP 发送缓冲区 (SO_SNDBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 131072 (128 kibibytes) Valid Values: [-1,...] Importance: low -
state.cleanup.delay.ms
分区迁移后删除状态之前等待的时间(以毫秒为单位)。
state.cleanup.delay.ms
仅删除至少未修改的状态目录Type: long Default: 600000 (10 minutes) Valid Values: Importance: low -
upgrade.from
允许以向后兼容的方式升级。从 [0.10.0, 1.1] 升级到 2.0+ 或从 [2.0, 2.3] 升级到 2.4+ 时需要这样做。从 3.3 升级到更新版本时,不需要指定此配置。默认为“null”。接受的值为“0.10.0”、“0.10.1”、“0.10.2”、“0.11.0”、“1.0”、“1.1”、“2.0”、“2.1”、“2.2”、“2.3” 、“2.4”、“2.5”、“2.6”、“2.7”、“2.8”、“3.0”、“3.1”、“3.2”、“3.3”、“3.4”(用于从相应的旧版本升级)。
Type: string Default: null Valid Values: [null, 0.10.0, 0.10.1, 0.10.2, 0.11.0, 1.0, 1.1, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 3.0, 3.1, 3.2, 3.3, 3.4] Importance: low -
window.size.ms
设置解串器的窗口大小以计算窗口结束时间。
Type: long Default: null Valid Values: Importance: low -
windowed.inner.class.serde
窗口记录内部类的默认序列化器/反序列化器。必须实现该
org.apache.kafka.common.serialization.Serde
接口。请注意,在 KafkaStreams 应用程序中设置此配置会导致错误,因为它只能从普通消费者客户端使用。Type: string Default: null Valid Values: Importance: low -
windowstore.changelog.additional.retention.ms
添加到 Windows MaintenanceMs 以确保数据不会过早地从日志中删除。允许时钟漂移。默认为 1 天
Type: long Default: 86400000 (1 day) Valid Values: Importance: low
3.7 管理配置
以下是 Kafka 管理客户端库的配置。-
bootstrap.servers
用于建立与 Kafka 集群的初始连接的主机/端口对列表。客户端将使用所有服务器,无论此处指定哪些服务器进行引导 - 该列表仅影响用于发现全套服务器的初始主机。该列表应采用以下形式
host1:port1,host2:port2,...
。由于这些服务器仅用于初始连接以发现完整的集群成员资格(可能会动态更改),因此此列表不需要包含完整的服务器集(不过,您可能需要多个服务器,以防服务器停机) 。Type: list Default: Valid Values: Importance: high -
ssl.key.password
密钥存储文件中私钥的密码或“ssl.keystore.key”中指定的 PEM 密钥的密码。
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.certificate.chain
证书链采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 X.509 证书列表的 PEM 格式
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.key
私钥采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 PKCS#8 密钥的 PEM 格式。如果密钥已加密,则必须使用“ssl.key.password”指定密钥密码
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.location
密钥存储文件的位置。这对客户端来说是可选的,可用于客户端的双向身份验证。
Type: string Default: null Valid Values: Importance: high -
ssl.keystore.password
密钥存储文件的存储密码。这对于客户端来说是可选的,并且仅在配置了“ssl.keystore.location”时才需要。PEM 格式不支持密钥存储密码。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.certificates
采用“ssl.truststore.type”指定格式的受信任证书。默认 SSL 引擎工厂仅支持带有 X.509 证书的 PEM 格式。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.location
信任存储文件的位置。
Type: string Default: null Valid Values: Importance: high -
ssl.truststore.password
信任存储文件的密码。如果未设置密码,仍将使用配置的信任存储文件,但禁用完整性检查。PEM 格式不支持信任存储密码。
Type: password Default: null Valid Values: Importance: high -
client.dns.lookup
控制客户端如何使用 DNS 查找。如果设置为
use_all_dns_ips
,则按顺序连接每个返回的 IP 地址,直到建立成功连接。断开连接后,将使用下一个 IP。一旦所有 IP 使用一次,客户端就会再次从主机名解析 IP(但是 JVM 和操作系统都会缓存 DNS 名称查找)。如果设置为resolve_canonical_bootstrap_servers_only
,则将每个引导地址解析为规范名称列表。在引导阶段之后,其行为与 相同use_all_dns_ips
。Type: string Default: use_all_dns_ips Valid Values: [use_all_dns_ips, resolve_canonical_bootstrap_servers_only] Importance: medium -
client.id
发出请求时传递给服务器的 id 字符串。这样做的目的是通过允许在服务器端请求日志记录中包含逻辑应用程序名称,能够跟踪 IP/端口之外的请求源。
Type: string Default: "" Valid Values: Importance: medium -
connections.max.idle.ms
在该配置指定的毫秒数后关闭空闲连接。
Type: long Default: 300000 (5 minutes) Valid Values: Importance: medium -
default.api.timeout.ms
指定客户端 API 的超时(以毫秒为单位)。此配置用作所有未指定
timeout
参数的客户端操作的默认超时。Type: int Default: 60000 (1 minute) Valid Values: [0,...] Importance: medium -
receive.buffer.bytes
读取数据时使用的 TCP 接收缓冲区 (SO_RCVBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 65536 (64 kibibytes) Valid Values: [-1,...] Importance: medium -
request.timeout.ms
该配置控制客户端等待请求响应的最长时间。如果在超时之前未收到响应,则客户端将在必要时重新发送请求,或者在重试次数耗尽时使请求失败。
Type: int Default: 30000 (30 seconds) Valid Values: [0,...] Importance: medium -
sasl.client.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。
Type: class Default: null Valid Values: Importance: medium -
sasl.jaas.config
SASL 连接的 JAAS 登录上下文参数采用 JAAS 配置文件使用的格式。JAAS 配置文件格式描述如下。该值的格式为:
loginModuleClass controlFlag (optionName=optionValue)*;
。对于代理,配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,需要listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule;Type: password Default: null Valid Values: Importance: medium -
sasl.kerberos.service.name
Kafka 运行时使用的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 的配置中定义。
Type: string Default: null Valid Values: Importance: medium -
sasl.login.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理,登录回调处理程序配置必须以侦听器前缀和小写的 SASL 机制名称为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
Type: class Default: null Valid Values: Importance: medium -
sasl.login.class
实现 Login 接口的类的完全限定名称。对于代理,登录配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
Type: class Default: null Valid Values: Importance: medium -
sasl.mechanism
用于客户端连接的 SASL 机制。这可以是安全提供者可用的任何机制。GSSAPI 是默认机制。
Type: string Default: GSSAPI Valid Values: Importance: medium -
sasl.oauthbearer.jwks.endpoint.url
可以从中检索提供商的JWKS(JSON Web 密钥集)的 OAuth/OIDC 提供商 URL。URL 可以基于 HTTP(S) 或基于文件。如果 URL 基于 HTTP(S),则将通过代理启动时配置的 URL 从 OAuth/OIDC 提供程序检索 JWKS 数据。所有当时的密钥都将缓存在代理上以用于传入请求。如果收到 JWT 的身份验证请求,其中包含尚未在缓存中的“kid”标头声明值,则将根据需要再次查询 JWKS 端点。但是,代理会每隔 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒轮询一次 URL,以便在收到包含这些密钥的任何 JWT 请求之前使用任何即将到来的密钥刷新缓存。如果 URL 是基于文件的,代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含 JWKS 文件中不存在的“kid”标头值,代理将拒绝 JWT 并且身份验证将失败。
Type: string Default: null Valid Values: Importance: medium -
sasl.oauthbearer.token.endpoint.url
OAuth/OIDC 身份提供商的 URL。如果 URL 基于 HTTP(S),则它是颁发者的令牌端点 URL,将根据 sasl.jaas.config 中的配置发出登录请求。如果 URL 是基于文件的,则它指定一个包含 OAuth/OIDC 身份提供商颁发的访问令牌(JWT 序列化形式)的文件,用于授权。
Type: string Default: null Valid Values: Importance: medium -
security.protocol
用于与经纪人通信的协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
Type: string Default: PLAINTEXT Valid Values: (case insensitive) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] Importance: medium -
send.buffer.bytes
发送数据时使用的 TCP 发送缓冲区 (SO_SNDBUF) 的大小。如果值为-1,将使用操作系统默认值。
Type: int Default: 131072 (128 kibibytes) Valid Values: [-1,...] Importance: medium -
socket.connection.setup.timeout.max.ms
客户端等待建立套接字连接的最长时间。对于每个连续的连接失败,连接设置超时将呈指数增长,直至达到此最大值。为了避免连接风暴,将对超时应用 0.2 的随机化因子,从而产生比计算值低 20% 到高 20% 之间的随机范围。
Type: long Default: 30000 (30 seconds) Valid Values: Importance: medium -
socket.connection.setup.timeout.ms
客户端等待建立套接字连接的时间。如果在超时之前未建立连接,客户端将关闭套接字通道。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: medium -
ssl.enabled.protocols
为 SSL 连接启用的协议列表。使用 Java 11 或更高版本运行时,默认值为“TLSv1.2、TLSv1.3”,否则为“TLSv1.2”。使用 Java 11 的默认值,如果客户端和服务器都支持 TLSv1.3,则首选 TLSv1.3,否则回退到 TLSv1.2(假设两者至少支持 TLSv1.2)。对于大多数情况,此默认值应该没问题。另请参阅“ssl.protocol”的配置文档。
Type: list Default: TLSv1.2,TLSv1.3 Valid Values: Importance: medium -
ssl.keystore.type
密钥存储文件的文件格式。这对于客户来说是可选的。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
ssl.protocol
用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更高版本运行时,默认值为“TLSv1.3”,否则为“TLSv1.2”。该值对于大多数用例来说应该没问题。最新 JVM 中允许的值为“TLSv1.2”和“TLSv1.3”。较旧的 JVM 可能支持“TLS”、“TLSv1.1”、“SSL”、“SSLv2”和“SSLv3”,但由于已知的安全漏洞,不鼓励使用它们。使用此配置和“ssl.enabled.protocols”的默认值,如果服务器不支持“TLSv1.3”,客户端将降级到“TLSv1.2”。如果此配置设置为“TLSv1.2”,客户端将不会使用“TLSv1.3”,即使它是 ssl.enabled.protocols 中的值之一,并且服务器仅支持“TLSv1.3”。
Type: string Default: TLSv1.3 Valid Values: Importance: medium -
ssl.provider
用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
Type: string Default: null Valid Values: Importance: medium -
ssl.truststore.type
信任存储文件的文件格式。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low -
metadata.max.age.ms
即使我们没有看到任何分区领导层发生变化以主动发现任何新的代理或分区,我们也会强制刷新元数据,以毫秒为单位的时间段。
Type: long Default: 300000 (5 minutes) Valid Values: [0,...] Importance: low -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: "" Valid Values: Importance: low -
metrics.num.samples
为计算指标而维护的样本数量。
Type: int Default: 2 Valid Values: [1,...] Importance: low -
metrics.recording.level
指标的最高记录级别。
Type: string Default: INFO Valid Values: [INFO, DEBUG, TRACE] Importance: low -
metrics.sample.window.ms
计算指标样本的时间窗口。
Type: long Default: 30000 (30 seconds) Valid Values: [0,...] Importance: low -
reconnect.backoff.max.ms
重新连接到多次连接失败的代理时等待的最长时间(以毫秒为单位)。如果提供,每个主机的退避将在每次连续连接失败时呈指数增加,直至达到此最大值。计算退避增量后,添加 20% 的随机抖动以避免连接风暴。
Type: long Default: 1000 (1 second) Valid Values: [0,...] Importance: low -
reconnect.backoff.ms
尝试重新连接到给定主机之前等待的基本时间量。这避免了在紧密循环中重复连接到主机。此退避适用于客户端与代理的所有连接尝试。
Type: long Default: 50 Valid Values: [0,...] Importance: low -
retries
设置大于零的值将导致客户端重新发送因潜在的暂时性错误而失败的任何请求。建议将该值设置为零或“MAX_VALUE”,并使用相应的超时参数来控制客户端应重试请求的时间。
Type: int Default: 2147483647 Valid Values: [0,...,2147483647] Importance: low -
retry.backoff.ms
尝试重试失败的请求之前等待的时间。这避免了在某些故障场景下在紧密循环中重复发送请求。
Type: long Default: 100 Valid Values: [0,...] Importance: low -
sasl.kerberos.kinit.cmd
Kerberos kinit 命令路径。
Type: string Default: /usr/bin/kinit Valid Values: Importance: low -
sasl.kerberos.min.time.before.relogin
刷新尝试之间的登录线程睡眠时间。
Type: long Default: 60000 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.jitter
添加到更新时间的随机抖动的百分比。
Type: double Default: 0.05 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.window.factor
登录线程将休眠,直到达到从上次刷新到票证到期的指定时间窗口因子,此时它将尝试更新票证。
Type: double Default: 0.8 Valid Values: Importance: low -
sasl.login.connect.timeout.ms
外部身份验证提供程序连接超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.read.timeout.ms
外部身份验证提供程序读取超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.refresh.buffer.seconds
刷新凭证时在凭证过期前维持的缓冲时间量(以秒为单位)。如果刷新发生的时间比缓冲秒数更接近到期,则刷新将向上移动以维持尽可能多的缓冲时间。合法值介于 0 到 3600(1 小时)之间;如果未指定值,则使用默认值 300(5 分钟)。如果该值和 sasl.login.refresh.min.period.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 300 Valid Values: [0,...,3600] Importance: low -
sasl.login.refresh.min.period.seconds
登录刷新线程在刷新凭据之前等待的所需最短时间(以秒为单位)。合法值介于 0 到 900(15 分钟)之间;如果未指定值,则使用默认值 60(1 分钟)。如果该值和 sasl.login.refresh.buffer.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 60 Valid Values: [0,...,900] Importance: low -
sasl.login.refresh.window.factor
登录刷新线程将休眠,直到达到相对于凭证生命周期的指定窗口因子,此时它将尝试刷新凭证。合法值介于 0.5 (50%) 和 1.0 (100%)(含)之间;如果未指定值,则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.8 Valid Values: [0.5,...,1.0] Importance: low -
sasl.login.refresh.window.jitter
相对于添加到登录刷新线程睡眠时间的凭证生命周期的最大随机抖动量。合法值介于 0 和 0.25 (25%) 之间(含);如果未指定值,则使用默认值 0.05 (5%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.05 Valid Values: [0.0,...,0.25] Importance: low -
sasl.login.retry.backoff.max.ms
尝试登录外部身份验证提供程序之间的最长等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.login.retry.backoff.ms
尝试登录外部身份验证提供程序之间的初始等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.clock.skew.seconds
以秒为单位的(可选)值,以允许 OAuth/OIDC 身份提供商和代理的时间之间存在差异。
Type: int Default: 30 Valid Values: Importance: low -
sasl.oauthbearer.expected.audience
代理的(可选)逗号分隔设置,用于验证 JWT 是否是为预期受众之一颁发的。将检查 JWT 是否有标准 OAuth“aud”声明,如果设置了此值,代理将匹配 JWT 的“aud”声明中的值,以查看是否存在完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: list Default: null Valid Values: Importance: low -
sasl.oauthbearer.expected.issuer
代理用于验证 JWT 是否由预期发行者创建的(可选)设置。将检查 JWT 是否有标准 OAuth“iss”声明,如果设置了该值,代理会将其与 JWT 的“iss”声明中的内容完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: string Default: null Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.refresh.ms
代理在刷新其 JWKS(JSON Web 密钥集)缓存之间等待的(可选)值(以毫秒为单位),该缓存包含用于验证 JWT 签名的密钥。
Type: long Default: 3600000 (1 hour) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms
尝试从外部身份验证提供程序检索 JWKS(JSON Web 密钥集)之间的最长等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.ms
来自外部身份验证提供程序的 JWKS(JSON Web 密钥集)检索尝试之间的初始等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.scope.claim.name
该范围的 OAuth 声明通常被命名为“scope”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的范围提供不同的名称。
Type: string Default: scope Valid Values: Importance: low -
sasl.oauthbearer.sub.claim.name
主题的 OAuth 声明通常命名为“sub”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的主题提供不同的名称。
Type: string Default: sub Valid Values: Importance: low -
security.providers
可配置创建者类的列表,每个类返回一个实现安全算法的提供者。这些类应该实现该
org.apache.kafka.common.security.auth.SecurityProviderCreator
接口。Type: string Default: null Valid Values: Importance: low -
ssl.cipher.suites
密码套件列表。这是身份验证、加密、MAC 和密钥交换算法的命名组合,用于使用 TLS 或 SSL 网络协议协商网络连接的安全设置。默认情况下,支持所有可用的密码套件。
Type: list Default: null Valid Values: Importance: low -
ssl.endpoint.identification.algorithm
使用服务器证书验证服务器主机名的端点识别算法。
Type: string Default: https Valid Values: Importance: low -
ssl.engine.factory.class
org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory
Type: class Default: null Valid Values: Importance: low -
ssl.keymanager.algorithm
密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。
Type: string Default: SunX509 Valid Values: Importance: low -
ssl.secure.random.implementation
用于 SSL 加密操作的 SecureRandom PRNG 实现。
Type: string Default: null Valid Values: Importance: low -
ssl.trustmanager.algorithm
信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。
Type: string Default: PKIX Valid Values: Importance: low
3.8 MirrorMaker 配置
以下是构成 MirrorMaker 2 的连接器的配置。3.8.1 MirrorMaker 常用配置
以下是适用于所有三个连接器的常见配置属性。-
source.cluster.alias
源集群别名
Type: string Default: Valid Values: Importance: high -
ssl.key.password
密钥存储文件中私钥的密码或“ssl.keystore.key”中指定的 PEM 密钥的密码。
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.certificate.chain
证书链采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 X.509 证书列表的 PEM 格式
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.key
私钥采用“ssl.keystore.type”指定的格式。默认 SSL 引擎工厂仅支持带有 PKCS#8 密钥的 PEM 格式。如果密钥已加密,则必须使用“ssl.key.password”指定密钥密码
Type: password Default: null Valid Values: Importance: high -
ssl.keystore.location
密钥存储文件的位置。这对客户端来说是可选的,可用于客户端的双向身份验证。
Type: string Default: null Valid Values: Importance: high -
ssl.keystore.password
密钥存储文件的存储密码。这对于客户端来说是可选的,并且仅在配置了“ssl.keystore.location”时才需要。PEM 格式不支持密钥存储密码。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.certificates
采用“ssl.truststore.type”指定格式的受信任证书。默认 SSL 引擎工厂仅支持带有 X.509 证书的 PEM 格式。
Type: password Default: null Valid Values: Importance: high -
ssl.truststore.location
信任存储文件的位置。
Type: string Default: null Valid Values: Importance: high -
ssl.truststore.password
信任存储文件的密码。如果未设置密码,仍将使用配置的信任存储文件,但禁用完整性检查。PEM 格式不支持信任存储密码。
Type: password Default: null Valid Values: Importance: high -
target.cluster.alias
目标集群的别名。用于指标报告。
Type: string Default: target Valid Values: Importance: high -
sasl.client.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 客户端回调处理程序类的完全限定名称。
Type: class Default: null Valid Values: Importance: medium -
sasl.jaas.config
SASL 连接的 JAAS 登录上下文参数采用 JAAS 配置文件使用的格式。JAAS 配置文件格式描述如下。该值的格式为:
loginModuleClass controlFlag (optionName=optionValue)*;
。对于代理,配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,需要listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=com.example.ScramLoginModule;Type: password Default: null Valid Values: Importance: medium -
sasl.kerberos.service.name
Kafka 运行时使用的 Kerberos 主体名称。这可以在 Kafka 的 JAAS 配置或 Kafka 的配置中定义。
Type: string Default: null Valid Values: Importance: medium -
sasl.login.callback.handler.class
实现 AuthenticateCallbackHandler 接口的 SASL 登录回调处理程序类的完全限定名称。对于代理,登录回调处理程序配置必须以侦听器前缀和小写的 SASL 机制名称为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.callback.handler.class=com.example.CustomScramLoginCallbackHandler
Type: class Default: null Valid Values: Importance: medium -
sasl.login.class
实现 Login 接口的类的完全限定名称。对于代理,登录配置必须以侦听器前缀和小写的 SASL 机制名称作为前缀。例如,listener.name.sasl_ssl.scram-sha-256.sasl.login.class=com.example.CustomScramLogin
Type: class Default: null Valid Values: Importance: medium -
sasl.mechanism
用于客户端连接的 SASL 机制。这可以是安全提供者可用的任何机制。GSSAPI 是默认机制。
Type: string Default: GSSAPI Valid Values: Importance: medium -
sasl.oauthbearer.jwks.endpoint.url
可以从中检索提供商的JWKS(JSON Web 密钥集)的 OAuth/OIDC 提供商 URL。URL 可以基于 HTTP(S) 或基于文件。如果 URL 基于 HTTP(S),则将通过代理启动时配置的 URL 从 OAuth/OIDC 提供程序检索 JWKS 数据。所有当时的密钥都将缓存在代理上以用于传入请求。如果收到 JWT 的身份验证请求,其中包含尚未在缓存中的“kid”标头声明值,则将根据需要再次查询 JWKS 端点。但是,代理会每隔 sasl.oauthbearer.jwks.endpoint.refresh.ms 毫秒轮询一次 URL,以便在收到包含这些密钥的任何 JWT 请求之前使用任何即将到来的密钥刷新缓存。如果 URL 是基于文件的,代理将在启动时从配置的位置加载 JWKS 文件。如果 JWT 包含 JWKS 文件中不存在的“kid”标头值,代理将拒绝 JWT 并且身份验证将失败。
Type: string Default: null Valid Values: Importance: medium -
sasl.oauthbearer.token.endpoint.url
OAuth/OIDC 身份提供商的 URL。如果 URL 基于 HTTP(S),则它是颁发者的令牌端点 URL,将根据 sasl.jaas.config 中的配置发出登录请求。如果 URL 是基于文件的,则它指定一个包含 OAuth/OIDC 身份提供商颁发的访问令牌(JWT 序列化形式)的文件,用于授权。
Type: string Default: null Valid Values: Importance: medium -
security.protocol
用于与经纪人通信的协议。有效值为:PLAINTEXT、SSL、SASL_PLAINTEXT、SASL_SSL。
Type: string Default: PLAINTEXT Valid Values: (case insensitive) [SASL_SSL, PLAINTEXT, SSL, SASL_PLAINTEXT] Importance: medium -
ssl.enabled.protocols
为 SSL 连接启用的协议列表。使用 Java 11 或更高版本运行时,默认值为“TLSv1.2、TLSv1.3”,否则为“TLSv1.2”。使用 Java 11 的默认值,如果客户端和服务器都支持 TLSv1.3,则首选 TLSv1.3,否则回退到 TLSv1.2(假设两者至少支持 TLSv1.2)。对于大多数情况,此默认值应该没问题。另请参阅“ssl.protocol”的配置文档。
Type: list Default: TLSv1.2,TLSv1.3 Valid Values: Importance: medium -
ssl.keystore.type
密钥存储文件的文件格式。这对于客户来说是可选的。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
ssl.protocol
用于生成 SSLContext 的 SSL 协议。使用 Java 11 或更高版本运行时,默认值为“TLSv1.3”,否则为“TLSv1.2”。该值对于大多数用例来说应该没问题。最新 JVM 中允许的值为“TLSv1.2”和“TLSv1.3”。较旧的 JVM 可能支持“TLS”、“TLSv1.1”、“SSL”、“SSLv2”和“SSLv3”,但由于已知的安全漏洞,不鼓励使用它们。使用此配置和“ssl.enabled.protocols”的默认值,如果服务器不支持“TLSv1.3”,客户端将降级到“TLSv1.2”。如果此配置设置为“TLSv1.2”,客户端将不会使用“TLSv1.3”,即使它是 ssl.enabled.protocols 中的值之一,并且服务器仅支持“TLSv1.3”。
Type: string Default: TLSv1.3 Valid Values: Importance: medium -
ssl.provider
用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
Type: string Default: null Valid Values: Importance: medium -
ssl.truststore.type
信任存储文件的文件格式。默认 `ssl.engine.factory.class` 当前支持的值为 [JKS、PKCS12、PEM]。
Type: string Default: JKS Valid Values: Importance: medium -
admin.timeout.ms
管理任务超时,例如检测新主题。
Type: long Default: 60000 (1 minute) Valid Values: Importance: low -
auto.include.jmx.reporter
已弃用。是否自动包含 JmxReporter,即使它没有在 中列出
metric.reporters
。此配置将在 Kafka 4.0 中删除,用户应添加org.apache.kafka.common.metrics.JmxReporter
该配置metric.reporters
以启用 JmxReporter。Type: boolean Default: true Valid Values: Importance: low -
enabled
是否复制源->目标。
Type: boolean Default: true Valid Values: Importance: low -
forwarding.admin.class
扩展 ForwardingAdmin 的类来定义自定义集群资源管理(主题、配置等)。该类必须有一个带签名的构造函数,用于配置 KafkaAdminClient,如果需要,也可用于配置外部系统的客户端。
(Map
config) Type: class Default: org.apache.kafka.clients.admin.ForwardingAdmin Valid Values: Importance: low -
metric.reporters
用作指标报告者的类的列表。实现该
org.apache.kafka.common.metrics.MetricsReporter
接口允许插入将收到新指标创建通知的类。JmxReporter 始终包含在内以注册 JMX 统计信息。Type: list Default: null Valid Values: Importance: low -
replication.policy.class
定义远程主题命名约定的类。
Type: class Default: org.apache.kafka.connect.mirror.DefaultReplicationPolicy Valid Values: Importance: low -
replication.policy.internal.topic.separator.enabled
是否使用replication.policy.separator 来控制用于检查点和偏移同步的主题名称。默认情况下,这些主题名称中使用自定义分隔符;但是,如果从不允许自定义这些主题名称的旧版本升级 MirrorMaker 2,则可能需要将此属性设置为“false”,以便继续对这些主题使用相同的名称。
Type: boolean Default: true Valid Values: Importance: low -
replication.policy.separator
远程主题命名约定中使用的分隔符。
Type: string Default: . Valid Values: Importance: low -
sasl.kerberos.kinit.cmd
Kerberos kinit 命令路径。
Type: string Default: /usr/bin/kinit Valid Values: Importance: low -
sasl.kerberos.min.time.before.relogin
刷新尝试之间的登录线程睡眠时间。
Type: long Default: 60000 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.jitter
添加到更新时间的随机抖动的百分比。
Type: double Default: 0.05 Valid Values: Importance: low -
sasl.kerberos.ticket.renew.window.factor
登录线程将休眠,直到达到从上次刷新到票证到期的指定时间窗口因子,此时它将尝试更新票证。
Type: double Default: 0.8 Valid Values: Importance: low -
sasl.login.connect.timeout.ms
外部身份验证提供程序连接超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.read.timeout.ms
外部身份验证提供程序读取超时的(可选)值(以毫秒为单位)。目前仅适用于 OAUTHBEARER。
Type: int Default: null Valid Values: Importance: low -
sasl.login.refresh.buffer.seconds
刷新凭证时在凭证过期前维持的缓冲时间量(以秒为单位)。如果刷新发生的时间比缓冲秒数更接近到期,则刷新将向上移动以维持尽可能多的缓冲时间。合法值介于 0 到 3600(1 小时)之间;如果未指定值,则使用默认值 300(5 分钟)。如果该值和 sasl.login.refresh.min.period.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 300 Valid Values: [0,...,3600] Importance: low -
sasl.login.refresh.min.period.seconds
登录刷新线程在刷新凭据之前等待的所需最短时间(以秒为单位)。合法值介于 0 到 900(15 分钟)之间;如果未指定值,则使用默认值 60(1 分钟)。如果该值和 sasl.login.refresh.buffer.seconds 的总和超过凭证的剩余生命周期,则它们都会被忽略。目前仅适用于 OAUTHBEARER。
Type: short Default: 60 Valid Values: [0,...,900] Importance: low -
sasl.login.refresh.window.factor
登录刷新线程将休眠,直到达到相对于凭证生命周期的指定窗口因子,此时它将尝试刷新凭证。合法值介于 0.5 (50%) 和 1.0 (100%)(含)之间;如果未指定值,则使用默认值 0.8 (80%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.8 Valid Values: [0.5,...,1.0] Importance: low -
sasl.login.refresh.window.jitter
相对于添加到登录刷新线程睡眠时间的凭证生命周期的最大随机抖动量。合法值介于 0 和 0.25 (25%) 之间(含);如果未指定值,则使用默认值 0.05 (5%)。目前仅适用于 OAUTHBEARER。
Type: double Default: 0.05 Valid Values: [0.0,...,0.25] Importance: low -
sasl.login.retry.backoff.max.ms
尝试登录外部身份验证提供程序之间的最长等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.login.retry.backoff.ms
尝试登录外部身份验证提供程序之间的初始等待时间(可选)值(以毫秒为单位)。Login 使用指数退避算法,初始等待基于 sasl.login.retry.backoff.ms 设置,尝试之间的等待长度将加倍,直至达到 sasl.login.retry.backoff.max 指定的最大等待长度。毫秒设置。目前仅适用于 OAUTHBEARER。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.clock.skew.seconds
以秒为单位的(可选)值,以允许 OAuth/OIDC 身份提供商和代理的时间之间存在差异。
Type: int Default: 30 Valid Values: Importance: low -
sasl.oauthbearer.expected.audience
代理的(可选)逗号分隔设置,用于验证 JWT 是否是为预期受众之一颁发的。将检查 JWT 是否有标准 OAuth“aud”声明,如果设置了此值,代理将匹配 JWT 的“aud”声明中的值,以查看是否存在完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: list Default: null Valid Values: Importance: low -
sasl.oauthbearer.expected.issuer
代理用于验证 JWT 是否由预期发行者创建的(可选)设置。将检查 JWT 是否有标准 OAuth“iss”声明,如果设置了该值,代理会将其与 JWT 的“iss”声明中的内容完全匹配。如果不匹配,代理将拒绝 JWT,身份验证将失败。
Type: string Default: null Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.refresh.ms
代理在刷新其 JWKS(JSON Web 密钥集)缓存之间等待的(可选)值(以毫秒为单位),该缓存包含用于验证 JWT 签名的密钥。
Type: long Default: 3600000 (1 hour) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms
尝试从外部身份验证提供程序检索 JWKS(JSON Web 密钥集)之间的最长等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 10000 (10 seconds) Valid Values: Importance: low -
sasl.oauthbearer.jwks.endpoint.retry.backoff.ms
来自外部身份验证提供程序的 JWKS(JSON Web 密钥集)检索尝试之间的初始等待时间(可选)值(以毫秒为单位)。JWKS 检索使用指数退避算法,并根据 sasl.oauthbearer.jwks.endpoint.retry.backoff.ms 设置进行初始等待,并且两次尝试之间的等待长度将加倍,直至达到 sasl.oauthbearer.jwks 指定的最大等待长度.endpoint.retry.backoff.max.ms 设置。
Type: long Default: 100 Valid Values: Importance: low -
sasl.oauthbearer.scope.claim.name
该范围的 OAuth 声明通常被命名为“scope”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的范围提供不同的名称。
Type: string Default: scope Valid Values: Importance: low -
sasl.oauthbearer.sub.claim.name
主题的 OAuth 声明通常命名为“sub”,但如果 OAuth/OIDC 提供程序对该声明使用不同的名称,则此(可选)设置可以为 JWT 负载声明中包含的主题提供不同的名称。
Type: string Default: sub Valid Values: Importance: low -
ssl.cipher.suites
密码套件列表。这是身份验证、加密、MAC 和密钥交换算法的命名组合,用于使用 TLS 或 SSL 网络协议协商网络连接的安全设置。默认情况下,支持所有可用的密码套件。
Type: list Default: null Valid Values: Importance: low -
ssl.endpoint.identification.algorithm
使用服务器证书验证服务器主机名的端点识别算法。
Type: string Default: https Valid Values: Importance: low -
ssl.engine.factory.class
org.apache.kafka.common.security.auth.SslEngineFactory 类型的类提供 SSLEngine 对象。默认值为 org.apache.kafka.common.security.ssl.DefaultSslEngineFactory
Type: class Default: null Valid Values: Importance: low -
ssl.keymanager.algorithm
密钥管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的密钥管理器工厂算法。
Type: string Default: SunX509 Valid Values: Importance: low -
ssl.secure.random.implementation
用于 SSL 加密操作的 SecureRandom PRNG 实现。
Type: string Default: null Valid Values: Importance: low -
ssl.trustmanager.algorithm
信任管理器工厂用于 SSL 连接的算法。默认值是为 Java 虚拟机配置的信任管理器工厂算法。
Type: string Default: PKIX Valid Values: Importance: low -
name
用于此连接器的全局唯一名称。
Type: string Default: Valid Values: non-empty string without ISO control characters Importance: high -
connector.class
此连接器的类的名称或别名。必须是 org.apache.kafka.connect.connector.Connector 的子类。如果连接器是org.apache.kafka.connect.file.FileStreamSinkConnector,您可以指定这个全名,或者使用“FileStreamSink”或“FileStreamSinkConnector”使配置更短一些
Type: string Default: Valid Values: Importance: high -
tasks.max
用于此连接器的最大任务数。
Type: int Default: 1 Valid Values: [1,...] Importance: high -
key.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中键的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: null Valid Values: Importance: low -
value.converter
Converter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中的值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。
Type: class Default: null Valid Values: Importance: low -
header.converter
HeaderConverter 类用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中标头值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。默认情况下,SimpleHeaderConverter 用于将标头值序列化为字符串,并通过推断架构来反序列化它们。
Type: class Default: null Valid Values: Importance: low -
config.action.reload
当外部配置提供程序的更改导致连接器的配置属性发生更改时,Connect 应对连接器执行的操作。值“none”表示 Connect 将不执行任何操作。“restart”值表示 Connect 应使用更新的配置属性重新启动/重新加载连接器。如果外部配置提供程序指示配置值将来会过期,则实际上可能会在将来安排重新启动。
Type: string Default: restart Valid Values: [none, restart] Importance: low -
transforms
应用于记录的转换的别名。
Type: list Default: "" Valid Values: non-null string, unique transformation aliases Importance: low -
predicates
转换使用的谓词的别名。
Type: list Default: "" Valid Values: non-null string, unique predicate aliases Importance: low -
errors.retry.timeout
重新尝试失败操作的最大持续时间(以毫秒为单位)。默认值为 0,这意味着不会尝试重试。使用 -1 进行无限重试。
Type: long Default: 0 Valid Values: Importance: medium -
errors.retry.delay.max.ms
连续重试之间的最大持续时间(以毫秒为单位)。一旦达到此限制,抖动就会添加到延迟中,以防止雷群问题。
Type: long Default: 60000 (1 minute) Valid Values: Importance: medium -
errors.tolerance
连接器操作期间容忍错误的行为。“none”是默认值,表示任何错误都将导致连接器任务立即失败;“all”更改行为以跳过有问题的记录。
Type: string Default: none Valid Values: [none, all] Importance: medium -
errors.log.enable
如果为 true,则将每个错误以及失败操作的详细信息和有问题的记录写入 Connect 应用程序日志。默认情况下此值为“false”,因此仅报告不能容忍的错误。
Type: boolean Default: false Valid Values: Importance: medium -
errors.log.include.messages
是否在日志中包含导致失败的连接记录。对于接收器记录,将记录主题、分区、偏移量和时间戳。对于源记录,将记录键和值(及其模式)、所有标头以及时间戳、Kafka 主题、Kafka 分区、源分区和源偏移量。默认情况下这是“false”,这将阻止记录键、值和标头写入日志文件。
Type: boolean Default: false Valid Values: Importance: medium
3.8.2 MirrorMaker 源配置
以下是用于复制主题的 MirrorMaker 2 源连接器的配置。-
config.properties.blacklist
已弃用。请改用 config.properties.exclude。
Type: list Default: null Valid Values: Importance: high -
config.properties.exclude
不应复制的主题配置属性。支持逗号分隔的属性名称和正则表达式。
Type: list Default: follower\.replication\.throttled\.replicas,leader\.replication\.throttled\.replicas,message\.timestamp\.difference\.max\.ms,message\.timestamp\.type,unclean\.leader\.election\.enable,min\.insync\.replicas Valid Values: Importance: high -
topics
要复制的主题。支持逗号分隔的主题名称和正则表达式。
Type: list Default: .* Valid Values: Importance: high -
topics.blacklist
已弃用。请改用topics.exclude。
Type: list Default: null Valid Values: Importance: high -
topics.exclude
排除的主题。支持逗号分隔的主题名称和正则表达式。排除优先于包含。
Type: list Default: .*[\-\.]internal,.*\.replica,__.* Valid Values: Importance: high -
add.source.alias.to.metrics
已弃用。是否使用源集群别名标记指标。指标具有目标、主题和分区标签。启用此设置后,它会添加源标签。此配置将在 Kafka 4.0 中删除,默认行为将始终具有源标签。
Type: boolean Default: false Valid Values: Importance: low -
config.property.filter.class
要使用的 ConfigPropertyFilter。选择要复制的主题配置属性。
Type: class Default: org.apache.kafka.connect.mirror.DefaultConfigPropertyFilter Valid Values: Importance: low -
consumer.poll.timeout.ms
轮询源集群时超时。
Type: long Default: 1000 (1 second) Valid Values: Importance: low -
offset-syncs.topic.location
offset-syncs 主题的位置(源/目标)。
Type: string Default: source Valid Values: [source, target] Importance: low -
offset-syncs.topic.replication.factor
偏移同步主题的复制因子。
Type: short Default: 3 Valid Values: Importance: low -
offset.lag.max
远程分区在重新同步之前可能有多不同步。
Type: long Default: 100 Valid Values: Importance: low -
refresh.topics.enabled
是否定期检查新主题和分区。
Type: boolean Default: true Valid Values: Importance: low -
refresh.topics.interval.seconds
主题刷新频率。
Type: long Default: 600 Valid Values: Importance: low -
replication.factor
新创建的远程主题的复制因子。
Type: int Default: 2 Valid Values: Importance: low -
sync.topic.acls.enabled
是否定期配置远程主题ACL以匹配其相应的上游主题。
Type: boolean Default: true Valid Values: Importance: low -
sync.topic.acls.interval.seconds
主题 ACL 同步的频率。
Type: long Default: 600 Valid Values: Importance: low -
sync.topic.configs.enabled
是否定期配置远程主题以匹配其相应的上游主题。
Type: boolean Default: true Valid Values: Importance: low -
sync.topic.configs.interval.seconds
主题配置同步的频率。
Type: long Default: 600 Valid Values: Importance: low -
topic.filter.class
要使用的主题过滤器。选择要复制的主题。
Type: class Default: org.apache.kafka.connect.mirror.DefaultTopicFilter Valid Values: Importance: low -
use.incremental.alter.configs
已弃用。使用哪个 API 来同步主题配置。有效值为“请求”、“必需”和“从不”。默认情况下,设置为“已请求”,这意味着 IncrementalAlterConfigs API 用于同步主题配置,如果任何请求从不兼容的代理收到错误,它将回退到使用已弃用的 AlterConfigs API。如果显式设置为“必需”,则在不使用回退逻辑的情况下使用 IncrementalAlterConfigs API,并且如果从不兼容的代理收到错误,连接器将失败。如果显式设置为“从不”,则始终使用 AlterConfig。此设置将被删除,并在 Kafka 4.0 中使用“required”行为,因此用户应确保目标 Broker 至少为 2.3.0
Type: string Default: requested Valid Values: [requested, required, never] Importance: low
3.8.3 MirrorMaker 检查点配置
以下是 MirrorMaker 2 检查点连接器的配置,用于发出消费者偏移检查点。-
groups
要复制的消费者群体。支持逗号分隔的组 ID 和正则表达式。
Type: list Default: .* Valid Values: Importance: high -
groups.blacklist
已弃用。请改用 groups.exclude 。
Type: list Default: null Valid Values: Importance: high -
groups.exclude
排除组。支持逗号分隔的组 ID 和正则表达式。排除优先于包含。
Type: list Default: console-consumer-.*,connect-.*,__.* Valid Values: Importance: high -
checkpoints.topic.replication.factor
检查点主题的复制因子。
Type: short Default: 3 Valid Values: Importance: low -
consumer.poll.timeout.ms
轮询源集群时超时。
Type: long Default: 1000 (1 second) Valid Values: Importance: low -
emit.checkpoints.enabled
是否将消费者偏移量复制到目标集群。
Type: boolean Default: true Valid Values: Importance: low -
emit.checkpoints.interval.seconds
检查点的频率。
Type: long Default: 60 Valid Values: Importance: low -
group.filter.class
要使用的组过滤器。选择要复制的消费者组。
Type: class Default: org.apache.kafka.connect.mirror.DefaultGroupFilter Valid Values: Importance: low -
offset-syncs.topic.location
offset-syncs 主题的位置(源/目标)。
Type: string Default: source Valid Values: [source, target] Importance: low -
refresh.groups.enabled
是否定期检查新的消费群体。
Type: boolean Default: true Valid Values: Importance: low -
refresh.groups.interval.seconds
组刷新频率。
Type: long Default: 600 Valid Values: Importance: low -
sync.group.offsets.enabled
是否定期将转换后的偏移量写入目标集群中的 __consumer_offsets 主题,只要该组中没有活动消费者连接到目标集群
Type: boolean Default: false Valid Values: Importance: low -
sync.group.offsets.interval.seconds
消费者组偏移同步的频率。
Type: long Default: 60 Valid Values: Importance: low -
topic.filter.class
要使用的主题过滤器。选择要复制的主题。
Type: class Default: org.apache.kafka.connect.mirror.DefaultTopicFilter Valid Values: Importance: low
3.8.4 MirrorMaker 心跳配置
以下是 MirrorMaker 2 心跳连接器的配置,用于检查连接器和集群之间的连接性。-
emit.heartbeats.enabled
是否向目标集群发出心跳。
Type: boolean Default: true Valid Values: Importance: low -
emit.heartbeats.interval.seconds
心跳的频率。
Type: long Default: 1 Valid Values: Importance: low -
heartbeats.topic.replication.factor
心跳主题的复制因子。
Type: short Default: 3 Valid Values: Importance: low
3.9 系统属性
Kafka 支持一些可以通过 Java 系统属性启用的配置。系统属性通常通过将 -D 标志传递给运行 Kafka 组件的 Java 虚拟机来设置。以下是支持的系统属性。-
org.apache.kafka.disallowed.login.modules
此系统属性用于禁用 SASL JAAS 配置中存在问题的登录模块使用。此属性接受以逗号分隔的登录模块名称列表。默认情况下,com.sun.security.auth.module.JndiLoginModule登录模块被禁用。
如果用户想要启用 JndiLoginModule,用户需要显式重置系统属性,如下所示。我们建议用户验证配置并仅允许可信的 JNDI 配置。有关更多详细信息CVE-2023-25194。
-Dorg.apache.kafka.disallowed.login.modules=
要禁用更多登录模块,请使用逗号分隔的登录模块名称更新系统属性。确保将JndiLoginModule模块名称显式添加到逗号分隔的列表中,如下所示。
-Dorg.apache.kafka.disallowed.login.modules=com.sun.security.auth.module.JndiLoginModule,com.ibm.security.auth.module.LdapLoginModule,com.ibm.security.auth.module.Krb5LoginModule
Since: 3.4.0 Default Value: com.sun.security.auth.module.JndiLoginModule
3.10 分层存储配置
以下是分层存储的配置属性。-
log.local.retention.bytes
在分区符合删除条件之前可以增长的本地日志段的最大大小。默认值为-2,它表示要使用的“log.retention.bytes”值。有效值应始终小于或等于“log.retention.bytes”值。
Type: long Default: -2 Valid Values: [-2,...] Importance: medium -
log.local.retention.ms
在本地日志段符合删除条件之前保留本地日志段的毫秒数。默认值为-2,它表示要使用“log.retention.ms”值。有效值应始终小于或等于“log.retention.ms”值。
Type: long Default: -2 Valid Values: [-2,...] Importance: medium -
remote.log.manager.thread.pool.size
用于调度任务复制段、获取远程日志索引和清理远程日志段的线程池的大小。
Type: int Default: 10 Valid Values: [1,...] Importance: medium -
remote.log.metadata.manager.class.name
`RemoteLogMetadataManager` 实现的完全限定类名。
Type: string Default: org.apache.kafka.server.log.remote.metadata.storage.TopicBasedRemoteLogMetadataManager Valid Values: non-empty string Importance: medium -
remote.log.metadata.manager.class.path
`RemoteLogMetadataManager` 实现的类路径。如果指定,RemoteLogMetadataManager 实现及其依赖库将由专用类加载器加载,该类加载器在 Kafka 代理类路径之前搜索此类路径。该参数的语法与标准 Java 类路径字符串相同。
Type: string Default: null Valid Values: Importance: medium -
remote.log.metadata.manager.impl.prefix
用于传递给 RemoteLogMetadataManager 实现的属性的前缀。例如,该值可以是“rlmm.config”。
Type: string Default: rlmm.config. Valid Values: non-empty string Importance: medium -
remote.log.metadata.manager.listener.name
如果 RemoteLogMetadataManager 实现需要,它应该连接到的本地代理的侦听器名称。
Type: string Default: null Valid Values: non-empty string Importance: medium -
remote.log.reader.max.pending.tasks
最大远程日志读取器线程池任务队列大小。如果任务队列已满,则在处理获取请求时会出现错误。
Type: int Default: 100 Valid Values: [1,...] Importance: medium -
remote.log.reader.threads
分配用于处理远程日志读取的线程池的大小。
Type: int Default: 10 Valid Values: [1,...] Importance: medium -
remote.log.storage.manager.class.name
`RemoteStorageManager` 实现的完全限定类名。
Type: string Default: null Valid Values: non-empty string Importance: medium -
remote.log.storage.manager.class.path
`RemoteStorageManager` 实现的类路径。如果指定,RemoteStorageManager 实现及其依赖库将由专用类加载器加载,该类加载器在 Kafka 代理类路径之前搜索此类路径。该参数的语法与标准 Java 类路径字符串相同。
Type: string Default: null Valid Values: Importance: medium -
remote.log.storage.manager.impl.prefix
用于传递给 RemoteStorageManager 实现的属性的前缀。例如,该值可以是“rsm.config”。
Type: string Default: rsm.config. Valid Values: non-empty string Importance: medium -
remote.log.storage.system.enable
是否在代理中启用分层存储功能。有效值为“true”或“false”,默认值为 false。当它为 true 时,代理将启动分层存储功能所需的所有服务。
Type: boolean Default: false Valid Values: Importance: medium -
remote.log.manager.task.interval.ms
远程日志管理器运行计划任务(例如复制段和清理远程日志段)的时间间隔。
Type: long Default: 30000 (30 seconds) Valid Values: [1,...] Importance: low -
remote.log.metadata.custom.metadata.max.bytes
代理应从远程存储插件接受的自定义元数据的最大大小(以字节为单位)。如果自定义元数据超过此限制,则不会存储更新的段元数据,将尝试删除复制的数据,并且此主题分区的远程复制任务将停止并出现错误。
Type: int Default: 128 Valid Values: [0,...] Importance: low
-
remote.log.metadata.consume.wait.ms
等待本地使用者接收已发布事件的时间(以毫秒为单位)。
Type: long Default: 120000 (2 minutes) Valid Values: [0,...] Importance: low -
remote.log.metadata.initialization.retry.interval.ms
再次重试 RemoteLogMetadataManager 资源初始化的重试间隔(以毫秒为单位)。
Type: long Default: 100 Valid Values: [0,...] Importance: low -
remote.log.metadata.initialization.retry.max.timeout.ms
重试 RemoteLogMetadataManager 资源初始化的最长时间(以毫秒为单位)。当总重试间隔达到此超时时,初始化被视为失败并且代理开始关闭。
Type: long Default: 120000 (2 minutes) Valid Values: [0,...] Importance: low -
remote.log.metadata.topic.num.partitions
远程日志元数据主题的分区数。
Type: int Default: 50 Valid Values: [1,...] Importance: low -
remote.log.metadata.topic.replication.factor
远程日志元数据主题的复制因子。
Type: short Default: 3 Valid Values: [1,...] Importance: low -
remote.log.metadata.topic.retention.ms
远程日志元数据主题的保留(以毫秒为单位)。默认值:-1,表示无限制。用户可以根据自己的用例配置该值。为了避免任何数据丢失,该值应大于集群中启用分层存储的任何主题的最大保留期。
Type: long Default: -1 Valid Values: Importance: low
4. 设计
4.1 动机
我们将 Kafka 设计为能够充当统一平台来处理大公司可能拥有的 所有实时数据源。为此,我们必须考虑相当广泛的用例。
它必须具有高吞吐量才能支持大容量事件流,例如实时日志聚合。
它需要妥善处理大量积压数据,以便能够支持离线系统的定期数据加载。
这还意味着系统必须处理低延迟交付,以处理更传统的消息传递用例。
我们希望支持这些提要的分区、分布式、实时处理,以创建新的派生提要。这激发了我们的分区和消费者模型。
最后,在将流输入其他数据系统进行服务的情况下,我们知道系统必须能够在出现机器故障时保证容错。
支持这些用途使我们设计出具有许多独特元素的设计,与传统的消息系统相比,它更类似于数据库日志。我们将在以下部分中概述设计的一些元素。
4.2 持久化
Don't fear the filesystem!
Kafka 严重依赖文件系统来存储和缓存消息。人们普遍认为“磁盘速度很慢”,这使人们怀疑持久结构能否提供有竞争力的性能。事实上,磁盘比人们预期的要慢得多,也要快得多,这取决于它们的使用方式;设计得当的磁盘结构往往可以和网络一样快。
关于磁盘性能的关键事实是,在过去十年中,硬盘驱动器的吞吐量与磁盘寻道的延迟一直存在差异。因此,在具有六个 7200rpm SATA RAID-5 阵列的JBOD 配置上,线性写入性能约为 600MB/秒,但随机写入性能仅为约 100k/秒,相差超过 6000 倍。这些线性读取和写入是所有使用模式中最可预测的,并且经过操作系统的大力优化。现代操作系统提供预读和后写技术,以大块倍数预取数据,并将较小的逻辑写入分组为较大的物理写入。有关此问题的进一步讨论可以在这篇ACM Queue 文章中找到;他们实际上发现 顺序磁盘访问在某些情况下比随机内存访问更快!
为了弥补这种性能差异,现代操作系统越来越积极地使用主内存进行磁盘缓存。现代操作系统会很乐意将所有可用内存转移到磁盘缓存,当内存被回收时,性能损失很小。所有的磁盘读写都会经过这个统一的缓存。如果不使用直接 I/O,则无法轻松关闭此功能,因此即使进程维护数据的进程内缓存,该数据也可能会在操作系统页面缓存中重复,从而有效地将所有内容存储两次。
此外,我们是在 JVM 之上构建的,任何花时间研究 Java 内存使用的人都知道两件事:
- 对象的内存开销非常高,通常会使存储的数据大小增加一倍(或更糟)。
- 随着堆内数据的增加,Java 垃圾收集变得越来越繁琐和缓慢。
由于这些因素,使用文件系统并依赖页面缓存优于维护内存中缓存或其他结构 - 我们通过自动访问所有空闲内存至少使可用缓存加倍,并且可能通过存储紧凑的内容再次加倍字节结构而不是单个对象。这样做将在 32GB 机器上产生高达 28-30GB 的缓存,而不会造成 GC 损失。此外,即使服务重新启动,此缓存也将保持热状态,而进程内缓存将需要在内存中重建(对于 10GB 缓存可能需要 10 分钟),否则它将需要以完全冷的缓存启动(这可能意味着糟糕的初始性能)。这也极大地简化了代码,因为用于维护缓存和文件系统之间一致性的所有逻辑现在都在操作系统中,这往往比一次性进程内尝试更有效、更正确。如果您的磁盘使用有利于线性读取,那么预读实际上是在每次磁盘读取时使用有用的数据预先填充此缓存。
这表明了一种非常简单的设计:我们不是在内存中保留尽可能多的内容,而是在空间不足时将其全部刷新到文件系统,而是将其反转。所有数据都会立即写入文件系统上的持久日志,而不必刷新到磁盘。实际上,这仅仅意味着它被转移到内核的页面缓存中。
这种以页面缓存为中心的设计风格在一篇关于 Varnish 设计的 文章 中进行了描述(同时还带有一定程度的傲慢)。
恒定的时间就足够了
消息传递系统中使用的持久数据结构通常是每个消费者的队列,具有关联的 BTree 或其他通用随机访问数据结构,以维护有关消息的元数据。BTree 是可用的最通用的数据结构,并且可以支持消息传递系统中的各种事务性和非事务性语义。不过,它们的成本确实相当高:Btree 操作的时间复杂度为 O(log N)。通常 O(log N) 被认为本质上等于常数时间,但对于磁盘操作来说并非如此。磁盘寻道一次弹出的时间为 10 毫秒,并且每个磁盘一次只能执行一次寻道,因此并行性受到限制。因此,即使少量的磁盘查找也会导致非常高的开销。由于存储系统将非常快的缓存操作与非常慢的物理磁盘操作混合在一起,因此随着数据随着固定缓存的增加而增加,观察到的树结构性能通常是超线性的——也就是说,数据加倍会使事情变得比两倍慢更糟糕。
直观上,持久队列可以基于简单的读取和附加到文件来构建,就像日志记录解决方案的常见情况一样。这种结构的优点是所有操作都是 O(1) 并且读取不会阻塞写入或彼此之间。这具有明显的性能优势,因为性能与数据大小完全解耦——一台服务器现在可以充分利用许多廉价、低转速的 1+TB SATA 驱动器。尽管它们的寻道性能较差,但这些驱动器对于大量读取和写入具有可接受的性能,并且价格仅为其 1/3,容量为 3 倍。
可以访问几乎无限的磁盘空间而不会造成任何性能损失,这意味着我们可以提供一些消息传递系统中通常不具备的功能。例如,在 Kafka 中,我们可以将消息保留相对较长的时间(例如一周),而不是在消息被消费后立即尝试删除它们。正如我们将要描述的,这为消费者带来了很大的灵活性。
4.3 效率
我们在效率方面投入了大量精力。我们的主要用例之一是处理 Web 活动数据,该数据量非常大:每个页面视图可能会生成数十次写入。此外,我们假设发布的每条消息都被至少一个消费者(通常是多个)阅读,因此我们努力使消费尽可能便宜。
根据构建和运行许多类似系统的经验,我们还发现,效率是有效多租户运营的关键。如果下游基础设施服务很容易因为应用程序使用量的微小变化而成为瓶颈,那么这种微小的变化通常会产生问题。通过非常快的速度,我们有助于确保应用程序在负载下先于基础设施发生翻倒。当尝试在集中式集群上运行支持数十或数百个应用程序的集中式服务时,这一点尤其重要,因为使用模式的变化几乎每天都会发生。
我们在上一节中讨论了磁盘效率。一旦消除了不良的磁盘访问模式,此类系统效率低下的常见原因有两个:太多的小型 I/O 操作和过多的字节复制。
小 I/O 问题既发生在客户端与服务器之间,也发生在服务器自身的持久操作中。
为了避免这种情况,我们的协议是围绕“消息集”抽象构建的,该抽象自然地将消息分组在一起。这允许网络请求将消息分组在一起并分摊网络往返的开销,而不是一次发送单个消息。服务器依次将消息块一次性追加到其日志中,而消费者一次获取大的线性块。
这个简单的优化产生了几个数量级的加速。批处理会导致更大的网络数据包、更大的顺序磁盘操作、连续的内存块等等,所有这些都允许 Kafka 将随机消息写入的突发流转换为流向消费者的线性写入。
另一个低效之处在于字节复制。在低消息速率下这不是问题,但在负载下影响很大。为了避免这种情况,我们采用了由生产者、代理和消费者共享的标准化二进制消息格式(因此数据块可以在它们之间传输而无需修改)。
代理维护的消息日志本身只是一个文件目录,每个文件都由一系列消息集填充,这些消息集已以生产者和消费者使用的相同格式写入磁盘。维护这种通用格式可以优化最重要的操作:持久日志块的网络传输。现代 UNIX 操作系统提供了高度优化的代码路径,用于将数据从页面缓存传输到套接字;在 Linux 中,这是通过sendfile 系统调用完成的。
要了解 sendfile 的影响,了解从文件到套接字传输数据的通用数据路径非常重要:
- 操作系统将数据从磁盘读取到内核空间的pagecache中
- 应用程序将数据从内核空间读取到用户空间缓冲区
- 应用程序将数据写回到内核空间的套接字缓冲区中
- 操作系统将数据从套接字缓冲区复制到 NIC 缓冲区,并在其中通过网络发送
这显然效率低下,有四个副本和两个系统调用。使用 sendfile,允许操作系统将数据从页面缓存直接发送到网络,从而避免这种重新复制。所以在这个优化路径中,只需要最终拷贝到NIC缓冲区即可。
我们期望一个常见的用例是一个主题的多个消费者。使用上面的零复制优化,数据被复制到页面缓存一次,并在每次使用时重复使用,而不是存储在内存中并在每次读取时复制到用户空间。这允许以接近网络连接限制的速率使用消息。
pagecache 和 sendfile 的这种组合意味着,在消费者大多陷入困境的 Kafka 集群上,您将看不到磁盘上的任何读取活动,因为它们将完全从缓存提供数据。
SSL_sendfile
TLS/SSL 库在用户空间运行( Kafka 目前不支持
内核)。由于此限制,sendfile
启用 SSL 时不使用。要启用 SSL 配置,请参阅security.protocol
和security.inter.broker.protocol
有关 Java 中的 sendfile 和零拷贝支持的更多背景信息,请参阅这篇文章。
端到端批量压缩
在某些情况下,瓶颈实际上不是 CPU 或磁盘,而是网络带宽。对于需要通过广域网在数据中心之间发送消息的数据管道来说尤其如此。当然,用户总是可以一次压缩一个消息,而不需要 Kafka 的任何支持,但这可能会导致压缩率非常差,因为大部分冗余是由于相同类型的消息之间的重复造成的(例如, JSON 或网络日志中的用户代理或常见字符串值)。有效的压缩需要将多个消息压缩在一起,而不是单独压缩每个消息。
Kafka 通过高效的批处理格式来支持这一点。一批消息可以聚集在一起压缩并以这种形式发送到服务器。这批消息将以压缩形式写入,并在日志中保持压缩状态,仅由消费者解压缩。
Kafka 支持 GZIP、Snappy、LZ4 和 ZStandard 压缩协议。有关压缩的更多详细信息可以在此处找到。
4.4 生产者
负载均衡
生产者将数据直接发送到作为分区领导者的代理,而无需任何中间路由层。为了帮助生产者做到这一点,所有 Kafka 节点都可以在任何给定时间响应有关哪些服务器处于活动状态以及主题分区的领导者所在位置的元数据请求,以允许生产者适当地引导其请求。
客户端控制将消息发布到哪个分区。这可以随机完成,实现一种随机负载平衡,也可以通过某种语义分区函数来完成。我们通过允许用户指定分区键并使用它来哈希到分区来公开语义分区的接口(如果需要,还有一个选项可以覆盖分区函数)。例如,如果选择的键是用户 ID,则给定用户的所有数据都将发送到同一分区。这反过来又将使消费者能够对其消费做出局部假设。这种分区方式明确设计为允许消费者进行局部敏感处理。
异步发送
批处理是效率的重要驱动因素之一,为了启用批处理,Kafka 生产者将尝试在内存中累积数据并在单个请求中发送更大的批次。可以将批处理配置为累积不超过固定数量的消息,并且等待时间不超过某个固定延迟限制(例如 64k 或 10 ms)。这允许累积更多要发送的字节,并且服务器上很少有较大的 I/O 操作。这种缓冲是可配置的,并提供了一种机制来权衡少量的额外延迟以获得更好的吞吐量。
有关生产者的 配置和api 的 详细信息可以在文档的其他地方找到。
4.5 消费者
Kafka 消费者的工作方式是向引导其想要使用的分区的代理发出“获取”请求。消费者在每个请求中指定其在日志中的偏移量,并接收从该位置开始的日志块。因此,消费者对该位置具有显着的控制权,并且可以在需要时将其倒回以重新使用数据。推与拉
我们考虑的最初问题是消费者是否应该从经纪人那里提取数据,或者经纪人应该将数据推送给消费者。在这方面,Kafka 遵循大多数消息传递系统所共享的更传统的设计,其中数据从生产者推送到代理并由消费者从代理中提取。一些以日志记录为中心的系统,例如Scribe和 Apache Flume,遵循非常不同的基于推送的路径,将数据推送到下游。两种方法各有利弊。然而,基于推送的系统很难处理不同的消费者,因为代理控制数据传输的速率。目标通常是让消费者能够以尽可能高的速度消费;不幸的是,在推送系统中,这意味着当消费者的消费率低于生产率时,消费者往往会不知所措(本质上是拒绝服务攻击)。基于拉动的系统具有更好的特性,即消费者可以简单地落在后面并在可以的时候赶上。这可以通过某种退避协议来缓解,消费者可以通过这种协议表明自己已经不堪重负,但是让传输速率充分利用(但绝不过度利用)消费者比看起来更棘手。之前以这种方式构建系统的尝试导致我们采用了更传统的拉模型。
基于拉动的系统的另一个优点是,它有助于将数据批量发送给消费者。基于推送的系统必须选择立即发送请求或积累更多数据然后稍后发送,而不知道下游消费者是否能够立即处理它。如果调整为低延迟,这将导致一次发送一条消息,但无论如何传输最终都会被缓冲,这是浪费的。基于拉取的设计解决了这个问题,因为消费者总是在日志中当前位置之后(或达到某个可配置的最大大小)拉取所有可用消息。因此,人们可以获得最佳的批处理,而不会引入不必要的延迟。
基于拉动的系统的缺陷在于,如果代理没有数据,消费者最终可能会在紧密的循环中进行轮询,实际上忙于等待数据到达。为了避免这种情况,我们在拉取请求中设置了参数,允许消费者请求在“长轮询”中阻塞,等待数据到达(并且可以选择等待给定数量的字节可用,以确保大的传输大小)。
您可以想象其他可能的设计,这些设计只是拉式、端到端的。生产者将在本地写入本地日志,经纪人将从其中拉取,消费者也将从中拉取。人们经常提出类似类型的“存储转发”生产者。这很有趣,但我们觉得不太适合我们拥有数千个生产者的目标用例。我们大规模运行持久数据系统的经验让我们感到,在系统中跨许多应用程序涉及数千个磁盘实际上并不会让事情变得更可靠,而且操作起来会是一场噩梦。在实践中,我们发现我们可以大规模运行具有强大 SLA 的管道,而不需要生产者持久性。
消费者定位
令人惊讶的是,跟踪已消耗的内容是消息传递系统的关键性能点之一。大多数消息传递系统都会保存有关代理上已使用的消息的元数据。也就是说,当消息被分发给消费者时,代理要么立即在本地记录该事实,要么等待消费者的确认。这是一个相当直观的选择,实际上对于单机服务器来说,并不清楚这种状态还可以去哪里。由于许多消息传递系统中用于存储的数据结构扩展性很差,这也是一个务实的选择——因为代理知道消耗了什么,所以可以立即删除它,从而保持数据大小较小。
也许不太明显的是,让经纪人和消费者就消费内容达成一致并不是一个小问题。如果代理在每次通过网络分发消息时立即将其记录为已消费,那么如果消费者无法处理该消息(例如因为崩溃或请求超时或其他原因),该消息将丢失。为了解决这个问题,许多消息系统添加了确认功能,这意味着消息在发送时仅被标记为已发送,而不是被消费;代理等待来自消费者的特定确认,以将消息记录为已消费。这种策略解决了丢失消息的问题,但也产生了新的问题。首先,如果消费者处理消息但在发送确认之前失败,那么该消息将被消费两次。第二个问题是关于性能的,现在代理必须保留每条消息的多个状态(首先锁定它,这样就不会再次发出,然后将其标记为永久消耗,以便可以将其删除)。必须处理棘手的问题,例如如何处理已发送但从未确认的消息。
Kafka对此的处理方式有所不同。我们的主题分为一组完全有序的分区,每个分区在任何给定时间都由每个订阅消费者组中的一个消费者消费。这意味着每个分区中消费者的位置只是一个整数,即要消费的下一条消息的偏移量。这使得有关已消耗内容的状态非常小,每个分区只有一个数字。可以定期检查此状态。这使得消息确认的成本非常低。
这个决定还有一个附带的好处。消费者可以故意回退到旧的偏移量并重新使用数据。这违反了队列的常见契约,但事实证明对于许多消费者来说这是一个基本功能。例如,如果消费者代码存在错误,并且在消费了一些消息后发现,则消费者可以在错误修复后重新消费这些消息。
离线数据加载
可扩展的持久性允许消费者仅定期消费,例如批量数据加载,定期将数据批量加载到离线系统(例如 Hadoop 或关系数据仓库)中。对于 Hadoop,我们通过将负载拆分到各个映射任务(每个节点/主题/分区组合一个)来并行化数据加载,从而允许加载完全并行。Hadoop 提供任务管理,失败的任务可以重新启动,而不会出现重复数据的危险——它们只是从原来的位置重新启动。
静态会员资格
静态成员资格旨在提高流应用程序、消费者组和其他构建在组再平衡协议之上的应用程序的可用性。再平衡协议依赖组协调器为组成员分配实体 ID。这些生成的 ID 是短暂的,并且会在成员重新启动和重新加入时发生变化。对于基于消费者的应用程序,这种“动态成员资格”可能会导致在管理操作(例如代码部署、配置更新和定期重新启动)期间将大部分任务重新分配给不同的实例。对于大型状态应用程序,洗牌任务在处理之前需要很长时间才能恢复其本地状态,从而导致应用程序部分或完全不可用。受此观察的启发,Kafka 的组管理协议允许组成员提供持久的实体 ID。根据这些 ID,组成员资格保持不变,因此不会触发重新平衡。如果您想使用静态成员资格,
- 将代理集群和客户端应用程序升级到 2.3 或更高版本,并确保升级后的代理也使用
inter.broker.protocol.version
2.3 或更高版本。 - 将配置设置
ConsumerConfig#GROUP_INSTANCE_ID_CONFIG
为一组下每个消费者实例的唯一值。 - 对于 Kafka Streams 应用程序,为每个 KafkaStreams 实例设置唯一的值就足够了
ConsumerConfig#GROUP_INSTANCE_ID_CONFIG
,与实例使用的线程数无关。
ConsumerConfig#GROUP_INSTANCE_ID_CONFIG
在客户端设置,则应用程序将检测代理版本,然后抛出 UnsupportedException。如果您不小心为不同的实例配置了重复的 ID,代理端的防护机制将通过触发org.apache.kafka.common.errors.FencedInstanceIdException
. 有关更多详细信息,请参阅
KIP-345
4.6 消息传递语义
现在我们对生产者和消费者的工作原理有了一些了解,让我们讨论一下 Kafka 在生产者和消费者之间提供的语义保证。显然,可以提供多种可能的消息传递保证:
- 最多一次——消息可能会丢失,但永远不会重新传送。
- 至少一次——消息永远不会丢失,但可以重新传送。
- 恰好一次——这就是人们真正想要的,每条消息都传递一次且仅一次。
许多系统声称提供“恰好一次”交付语义,但阅读细则很重要,这些声明中的大多数都是误导性的(即它们不能转化为消费者或生产者可能失败的情况,有多个的情况)消费者进程,或者写入磁盘的数据可能丢失的情况)。
Kafka的语义是直接的。当发布消息时,我们有一个消息被“提交”到日志的概念。一旦提交了已发布的消息,只要复制该消息所写入的分区的一个代理保持“活动”状态,该消息就不会丢失。已提交消息、活动分区的定义以及我们尝试处理的故障类型的描述将在下一节中更详细地描述。现在让我们假设一个完美的、无损的经纪人,并尝试理解对生产者和消费者的保证。如果生产者尝试发布消息并遇到网络错误,则无法确定此错误是在提交消息之前还是之后发生。这类似于使用自动生成的键插入数据库表的语义。
在 0.11.0.0 之前,如果生产者未能收到指示消息已提交的响应,它别无选择,只能重新发送消息。这提供了至少一次传递语义,因为如果原始请求实际上已成功,则在重新发送期间消息可能会再次写入日志。从0.11.0.0开始,Kafka生产者还支持幂等传递选项,保证重新发送不会导致日志中出现重复条目。为了实现这一点,代理为每个生产者分配一个 ID,并使用生产者随每条消息发送的序列号来删除重复的消息。同样从 0.11.0.0 开始,生产者支持使用类似事务的语义将消息发送到多个主题分区的能力:即,要么所有消息都成功写入,要么没有一条消息成功写入。其主要用例是 Kafka 主题之间的一次性处理(如下所述)。
并非所有用例都需要如此强有力的保证。对于对延迟敏感的用途,我们允许生产者指定其所需的持久性级别。如果生产者指定它想要等待消息被提交,这可能需要大约 10 毫秒。然而,生产者也可以指定它想要完全异步地执行发送,或者它只想等到领导者(但不一定是追随者)收到消息。
现在让我们从消费者的角度来描述语义。所有副本都具有完全相同的日志和相同的偏移量。消费者控制其在此日志中的位置。如果消费者从未崩溃,它可以只将该位置存储在内存中,但如果消费者失败并且我们希望该主题分区由另一个进程接管,则新进程将需要选择一个适当的位置来开始处理。假设消费者读取了一些消息——它有几个选项来处理消息并更新其位置。
- 它可以读取消息,然后将其位置保存在日志中,最后处理消息。在这种情况下,消费者进程有可能在保存其位置之后但在保存其消息处理的输出之前崩溃。在这种情况下,接管处理的进程将从保存的位置开始,即使该位置之前的一些消息尚未处理。这对应于“至多一次”语义,因为在消费者失败消息可能不会被处理的情况下。
- 它可以读取消息,处理消息,最后保存其位置。在这种情况下,消费者进程有可能在处理消息之后但在保存其位置之前崩溃。在这种情况下,当新进程接管时,它收到的前几条消息将已经被处理。这对应于消费者失败情况下的“至少一次”语义。在许多情况下,消息具有主键,因此更新是幂等的(两次接收相同的消息只会用其自身的另一个副本覆盖记录)。
那么恰好一次语义(即你真正想要的东西)又如何呢?当从 Kafka 主题消费并生产到另一个主题(如在Kafka Streams 应用程序中)时,我们可以利用上面提到的 0.11.0.0 中新的事务生产者功能。消费者的位置作为消息存储在主题中,因此我们可以在与接收处理数据的输出主题相同的事务中将偏移量写入 Kafka。如果事务中止,消费者的位置将恢复到其旧值,并且输出主题上生成的数据对其他消费者不可见,具体取决于他们的“隔离级别”。在默认的“read_uncommissed”隔离级别中,所有消息对消费者都是可见的,即使它们是中止事务的一部分,但在“read_commissed”中,消费者只会从已提交的事务中返回消息(以及不属于已提交事务的任何消息)交易的一部分)。
当写入外部系统时,限制在于需要将消费者的位置与实际存储为输出的内容相协调。实现这一目标的经典方法是在消费者位置的存储和消费者输出的存储之间引入两阶段提交。但这可以通过让消费者将其偏移量存储在与其输出相同的位置来更简单和更普遍地处理。这更好,因为消费者可能想要写入的许多输出系统不支持两阶段提交。作为一个例子,考虑一个 Kafka Connect连接器,它将数据及其读取的数据的偏移量填充到 HDFS 中,以便保证数据和偏移量要么都更新,要么都不更新。对于许多其他数据系统,我们遵循类似的模式,这些系统需要这些更强的语义,并且消息没有主键来允许重复数据删除。
因此,Kafka有效地支持Kafka Streams 中的一次性交付,并且在Kafka主题之间传输和处理数据时,通常可以使用事务性生产者/消费者来提供一次性交付。其他目标系统的一次性交付通常需要与此类系统合作,但 Kafka 提供了偏移量,使得实现这一点变得可行(另请参阅Kafka Connect)。否则,Kafka 默认保证至少一次传送,并允许用户通过在处理一批消息之前禁用生产者重试并在消费者中提交偏移量来实现最多一次传送。
4.7 复制
Kafka 在可配置数量的服务器上复制每个主题分区的日志(您可以逐个主题设置此复制因子)。当集群中的服务器发生故障时,这允许自动故障转移到这些副本,因此消息在出现故障时仍然可用。
其他消息系统提供了一些与复制相关的功能,但是,在我们(完全有偏见的)看来,这似乎是一个附加的东西,没有被大量使用,并且有很大的缺点:副本不活动,吞吐量受到严重影响,它需要繁琐的手动配置等。Kafka 默认情况下与复制一起使用 - 事实上,我们将未复制的主题实现为复制主题,其中复制因子为 1。
复制的单位是主题分区。在非故障条件下,Kafka 中的每个分区都有一个领导者和零个或多个追随者。包括领导者在内的副本总数构成了复制因子。所有写入都将发送到分区的领导者,而读取可能会发送到分区的领导者或追随者。通常,分区的数量比经纪人多得多,并且领导者均匀分布在经纪人之间。追随者上的日志与领导者的日志相同 - 都具有相同的偏移量和相同顺序的消息(当然,在任何给定时间,领导者可能在其日志末尾有一些尚未复制的消息) )。
追随者像普通 Kafka 消费者一样消费来自领导者的消息,并将其应用到自己的日志中。让追随者从领导者那里拉取有一个很好的特性,即允许追随者自然地将他们应用于其日志的日志条目分批在一起。
与大多数分布式系统一样,自动处理故障需要精确定义节点“活动”的含义。在Kafka中,一个被称为“控制器”的特殊节点负责管理集群中broker的注册。经纪商活跃度有两个条件:
- 代理必须与控制器保持活动会话,以便定期接收元数据更新。
- 作为追随者的经纪人必须复制领导者的写入,并且不能落后“太远”。
“活动会话”的含义取决于集群配置。对于 KRaft 集群,通过向控制器发送定期心跳来维护活动会话。如果控制器在配置的超时时间到期之前未能收到心跳
broker.session.timeout.ms
,则该节点被视为离线。
对于使用 Zookeeper 的集群,活动性是通过临时节点的存在来间接确定的,临时节点是由代理在其 Zookeeper 会话初始化时创建的。如果代理在 过期之前未能向 Zookeeper 发送心跳后丢失会话
zookeeper.session.timeout.ms
,则该节点将被删除。然后,控制器将通过 Zookeeper 监视注意到节点删除,并将代理标记为离线。
我们将满足这两个条件的节点称为“同步”,以避免“活动”或“失败”的模糊性。领导者跟踪一组“同步”副本,称为 ISR。如果其中任何一个条件未能满足,则经纪商将从 ISR 中删除。例如,如果跟随者死亡,那么控制器将通过其会话丢失注意到失败,并将从 ISR 中删除代理。另一方面,如果追随者落后领导者太多,但仍然有活动会话,那么领导者也可以将其从 ISR 中删除。滞后副本的确定是通过replica.lag.time.max.ms
配置控制的。在此配置设置的最大时间内无法赶上领导者日志末尾的副本将从 ISR 中删除。
在分布式系统术语中,我们只尝试处理“失败/恢复”故障模型,其中节点突然停止工作,然后恢复(可能不知道它们已经死亡)。Kafka 不处理所谓的“拜占庭”故障,即节点产生任意或恶意响应(可能是由于错误或犯规)。
现在,我们可以更精确地定义,当该分区的 ISR 中的所有副本都已将消息应用到其日志时,该消息被视为已提交。只有提交的消息才会发送给消费者。这意味着消费者不必担心如果领导者失败可能会看到可能丢失的消息。另一方面,生产者可以选择等待消息提交或不提交,具体取决于他们对延迟和持久性之间权衡的偏好。此首选项由生产者使用的 ack 设置控制。请注意,主题具有同步副本“最小数量”的设置,当生产者请求确认消息已写入完整的同步副本集时,会检查该设置。如果生产者请求不太严格的确认,则即使同步副本的数量低于最小值(例如,它可以低至只有领导者),也可以提交并消费该消息。
Kafka 提供的保证是,只要至少有一个同步副本始终处于活动状态,已提交的消息就不会丢失。
在短暂的故障转移期后,Kafka 将在出现节点故障的情况下保持可用,但在存在网络分区的情况下可能无法保持可用。
Replicated Logs: Quorums, ISRs, and State Machines (Oh my!)
Kafka 分区的核心是复制日志。复制日志是分布式数据系统中最基本的原语之一,有多种实现方法。复制日志可以被其他系统用作以状态机方式实现其他分布式系统的原语。复制日志模拟了就一系列值的顺序达成共识的过程(通常将日志条目编号为 0、1、2...)。实现这一点的方法有很多,但最简单、最快的方法是由领导者选择提供给它的值的顺序。只要领导者还活着,所有追随者只需复制领导者选择的值和命令即可。
当然,如果领导者没有失败,我们就不需要追随者!当领导者死亡时,我们需要从追随者中选择一位新的领导者。但追随者本身可能会落后或崩溃,所以我们必须确保选择一个最新的追随者。日志复制算法必须提供的基本保证是,如果我们告诉客户端一条消息已提交,并且领导者失败,那么我们选出的新领导者也必须具有该消息。这会产生一个权衡:如果领导者在宣布消息已提交之前等待更多追随者确认消息,那么将会有更多潜在的当选领导者。
如果您选择所需的确认数量和必须比较的日志数量来选举领导者,以确保存在重叠,那么这称为仲裁。
这种权衡的常见方法是对提交决策和领导者选举都使用多数票。这不是 Kafka 所做的,但无论如何我们还是要探索一下它以了解其中的权衡。假设我们有 2 f +1 个副本。如果f +1 个副本必须在领导者声明提交之前接收消息,并且如果我们通过从至少 f +1 个副本中选举具有最完整日志的追随者来选举新的领导者,那么,不超过f失败时,领导者保证拥有所有已提交的消息。这是因为在任意f +1 个副本中,必须至少有一个副本包含所有已提交的消息。该副本的日志将是最完整的,因此将被选为新的领导者。每个算法还必须处理许多剩余的细节(例如精确定义什么使日志更完整,确保领导者故障期间的日志一致性或更改副本集中的服务器集),但我们现在将忽略这些。
这种多数投票方法有一个非常好的特性:延迟仅取决于最快的服务器。也就是说,如果复制因子为 3,则延迟由较快的跟随者决定,而不是由较慢的跟随者决定。
这个家族中有各种各样的算法,包括 ZooKeeper 的 Zab、 Raft和Viewstamped Replication。据我们所知,与 Kafka 实际实现最相似的学术出版物是 Microsoft 的 PacificA 。
多数投票的缺点是,不需要多次失败就会导致没有可供选举的领导人。容忍一次故障需要三份数据,容忍两次故障需要五份数据。根据我们的经验,只有足够的冗余来容忍单个故障对于实际系统来说是不够的,但是对于大容量数据问题来说,每次写入五次,磁盘空间要求为 5 倍,吞吐量为 1/5,这不太实用。这可能就是为什么仲裁算法更常出现在共享集群配置(例如 ZooKeeper)中,但在主数据存储中却不太常见。例如,在 HDFS 中,名称节点的高可用性功能是建立在基于多数投票的日志之上的,但这种更昂贵的方法并不用于数据本身。
Kafka 采用略有不同的方法来选择仲裁集。Kafka 不是多数投票,而是动态维护一组赶上领导者的同步副本 (ISR)。只有该组的成员才有资格当选为领导者。在所有同步副本都收到写入之前,对 Kafka 分区的写入不会被视为已提交。只要该 ISR 集发生更改,它就会保留在集群元数据中。因此,ISR 中的任何副本都有资格被选举为领导者。对于 Kafka 的使用模型来说,这是一个重要因素,其中有很多分区,确保领导平衡很重要。借助此 ISR 模型和f+1 个副本,Kafka 主题可以容忍f 个故障而不会丢失已提交的消息。
对于我们希望处理的大多数用例,我们认为这种权衡是合理的。实际上,为了容忍失败,多数投票和 ISR 方法都将在提交消息之前等待相同数量的副本进行确认(例如,为了在一次失败中幸存,多数仲裁需要三个副本和一个确认,而 ISR 方法需要两个副本和一个确认)。无需最慢的服务器即可提交的能力是多数投票方法的优点。然而,我们认为通过允许客户端选择是否在消息提交时阻塞可以改善这一情况,并且由于所需的复制因子较低而带来的额外吞吐量和磁盘空间是值得的。
另一个重要的设计区别是 Kafka 不要求崩溃的节点恢复时所有数据都完好无损。该领域的复制算法依赖于“稳定存储”的存在并不少见,“稳定存储”在任何故障恢复场景中都不会丢失,而不会导致潜在的一致性违规。这个假设有两个主要问题。首先,磁盘错误是我们在持久数据系统的实际操作中观察到的最常见问题,并且它们通常不会使数据完好无损。其次,即使这不是问题,我们也不希望在每次写入时都使用 fsync 来保证一致性,因为这可能会将性能降低两到三个数量级。我们允许副本重新加入 ISR 的协议确保在重新加入之前,它必须再次完全重新同步,即使它在崩溃中丢失了未刷新的数据。
Unclean leader election: What if they all die?
请注意,Kafka 对数据丢失的保证是基于至少一个副本保持同步。如果复制分区的所有节点都死亡,则此保证不再成立。然而,当所有副本死亡时,一个实用的系统需要做一些合理的事情。如果您不幸发生这种情况,重要的是要考虑会发生什么。有两种可以实现的行为:
- 等待 ISR 中的副本恢复并选择该副本作为领导者(希望它仍然拥有所有数据)。
- 选择第一个作为领导者复活的副本(不一定在 ISR 中)。
这是可用性和一致性之间的简单权衡。如果我们在 ISR 中等待副本,那么只要这些副本关闭,我们就将保持不可用状态。如果此类副本被破坏或数据丢失,那么我们就会永久瘫痪。另一方面,如果一个非同步副本恢复正常,并且我们允许它成为领导者,那么它的日志就会成为事实来源,即使它不能保证拥有每条已提交的消息。默认情况下,从 0.11.0.0 版本开始,Kafka 选择第一种策略并倾向于等待一致的副本。可以使用配置属性 unclean.leader.election.enable 更改此行为,以支持正常运行时间优于一致性的用例。
这种困境并不是Kafka特有的。它存在于任何基于仲裁的方案中。例如,在多数投票方案中,如果大多数服务器遭受永久性故障,那么您必须选择丢失 100% 的数据,或者通过将现有服务器上剩余的数据作为新的事实来源来违反一致性。
可用性和耐用性保证
当写入 Kafka 时,生产者可以选择是否等待 0,1 或所有(-1)副本确认消息。请注意,“所有副本的确认”并不能保证所有分配的副本都已收到该消息。默认情况下,当 acks=all 时,一旦所有当前同步副本收到消息,就会立即发生确认。例如,如果某个主题仅配置了两个副本,其中一个失败(即仅保留一个同步副本),则指定 acks=all 的写入将会成功。但是,如果剩余副本也发生故障,这些写入可能会丢失。尽管这确保了分区的最大可用性,但对于某些更喜欢持久性而不是可用性的用户来说,这种行为可能是不受欢迎的。因此,我们提供了两个主题级配置,可用于优先考虑消息持久性而不是可用性:- 禁用不干净的领导者选举 - 如果所有副本都不可用,则分区将保持不可用,直到最近的领导者再次可用。这实际上更倾向于不可用而不是消息丢失的风险。请参阅上一节关于不干净的领导者选举的说明。
- 指定最小 ISR 大小 - 仅当 ISR 大小高于某个最小值时,分区才会接受写入,以防止仅写入单个副本的消息丢失,该副本随后变得不可用。仅当生产者使用 acks=all 并保证消息将被至少这么多同步副本确认时,此设置才会生效。此设置提供了一致性和可用性之间的权衡。最小 ISR 大小的较高设置可以保证更好的一致性,因为消息可以保证写入更多副本,从而降低丢失的可能性。但是,它会降低可用性,因为如果同步副本的数量低于最小阈值,则分区将无法用于写入。
副本管理
上面关于复制日志的讨论实际上只涵盖了单个日志,即一个主题分区。然而,Kafka 集群将管理数百或数千个这样的分区。我们尝试以循环方式平衡集群内的分区,以避免将大量主题的所有分区聚集在少量节点上。同样,我们尝试平衡领导力,以便每个节点都是其分区中一定比例份额的领导者。优化领导选举流程也很重要,因为这是不可用的关键窗口。领导者选举的简单实现最终会在该节点发生故障时为该节点托管的所有分区运行每个分区的选举。正如上面复制部分所讨论的,Kafka 集群有一个特殊的角色,称为“控制器”,负责管理代理的注册。如果控制器检测到代理发生故障,则它负责选举 ISR 的剩余成员之一作为新的领导者。结果是,我们能够将许多所需的领导层变更通知批处理在一起,这使得大量分区的选举过程更加便宜且更快。如果控制器本身发生故障,则将选举另一个控制器。
4.8 日志压缩
日志压缩确保 Kafka 始终至少保留单个主题分区的数据日志中每个消息键的最后一个已知值。它解决了用例和场景,例如应用程序崩溃或系统故障后恢复状态,或在操作维护期间应用程序重新启动后重新加载缓存。让我们更详细地研究这些用例,然后描述压缩的工作原理。到目前为止,我们仅描述了更简单的数据保留方法,其中旧日志数据在固定时间段后或当日志达到某个预定大小时被丢弃。这对于时间事件数据非常有效,例如记录每个记录独立的情况。然而,一类重要的数据流是对键控、可变数据的更改的日志(例如,对数据库表的更改)。
让我们讨论这样一个流的具体示例。假设我们有一个包含用户电子邮件地址的主题;每次用户更新其电子邮件地址时,我们都会使用其用户 ID 作为主键向该主题发送一条消息。现在假设我们在一段时间内为 id 为 123 的用户发送以下消息,每条消息对应于电子邮件地址的更改(其他 id 的消息被省略):
123 => bill@microsoft.com
.
.
.
123 => bill@gatesfoundation.org
.
.
.
123 => bill@gmail.com
日志压缩为我们提供了更细粒度的保留机制,以便保证我们至少保留每个主键的最后更新(例如bill@gmail.com
)。通过这样做,我们保证日志包含每个键的最终值的完整快照,而不仅仅是最近更改的键。这意味着下游消费者可以在该主题之外恢复自己的状态,而无需我们保留所有更改的完整日志。
让我们首先看一些有用的用例,然后我们将了解如何使用它。
- 数据库变更订阅。通常需要在多个数据系统中拥有一个数据集,并且通常这些系统之一是某种数据库(RDBMS 或可能是新型键值存储)。例如,您可能有一个数据库、一个缓存、一个搜索集群和一个 Hadoop 集群。对数据库的每次更改都需要反映在缓存、搜索集群中,并最终反映在 Hadoop 中。如果只处理实时更新,您只需要最近的日志。但如果您希望能够重新加载缓存或恢复失败的搜索节点,您可能需要完整的数据集。
- 事件溯源。这是一种应用程序设计风格,它将查询处理与应用程序设计放在一起,并使用更改日志作为应用程序的主要存储。
- 日志记录以实现高可用性。进行本地计算的进程可以通过注销对其本地状态所做的更改来实现容错,以便另一个进程可以重新加载这些更改并在失败时继续执行。一个具体的例子是在流查询系统中处理计数、聚合和其他类似“group by”的处理。Samza 是一个实时流处理框架, 正是利用此功能来实现此目的。
总体思路非常简单。如果我们有无限的日志保留,并且我们记录了上述情况下的每个更改,那么我们将捕获系统从第一次开始时的每个时间的状态。使用这个完整的日志,我们可以通过重放日志中的前 N 条记录来恢复到任意时间点。对于多次更新单个记录的系统来说,这种假设的完整日志不太实用,因为即使对于稳定的数据集,日志也会无限制地增长。丢弃旧更新的简单日志保留机制会限制空间,但日志不再是恢复当前状态的方法 - 现在从日志开头恢复不再重新创建当前状态,因为旧更新可能根本无法捕获。
日志压缩是一种提供更细粒度的每条记录保留的机制,而不是提供更粗粒度的基于时间的保留。这个想法是有选择地删除具有相同主键的最新更新的记录。这样可以保证日志至少具有每个键的最后状态。
可以为每个主题设置此保留策略,因此单个集群可以具有一些通过大小或时间强制保留的主题,以及通过压缩强制保留的其他主题。
此功能的灵感来自于 LinkedIn 最古老、最成功的基础设施之一——名为Databus 的数据库变更日志缓存服务。与大多数日志结构存储系统不同,Kafka 是为订阅而构建的,并组织数据以进行快速线性读取和写入。与 Databus 不同,Kafka 充当真实来源存储,因此即使在上游数据源无法重放的情况下它也很有用。
日志压缩基础知识
这是一张高级图片,显示了 Kafka 日志的逻辑结构以及每条消息的偏移量。
日志的头部与传统的 Kafka 日志相同。它具有密集、连续的偏移量并保留所有消息。日志压缩添加了处理日志尾部的选项。上图显示了一根带有压紧尾部的原木。请注意,日志尾部的消息保留首次写入时分配的原始偏移量,并且永远不会改变。另请注意,即使具有该偏移量的消息已被压缩,所有偏移量仍保留在日志中的有效位置;在这种情况下,该位置与日志中出现的下一个最高偏移量无法区分。例如,在上图中,偏移量 36、37 和 38 都是等效位置,从这些偏移量中的任何一个开始读取都将返回以 38 开头的消息集。
压缩还允许删除。带有密钥和空负载的消息将被视为从日志中删除。这样的记录有时被称为墓碑。此删除标记将导致任何具有该键的先前消息被删除(就像具有该键的任何新消息一样),但删除标记的特殊之处在于,它们本身会在一段时间后从日志中清除以释放空间。删除不再保留的时间点在上图中被标记为“删除保留点”。
压缩是通过定期重新复制日志段在后台完成的。清理不会阻止读取,并且可以限制使用不超过可配置的 I/O 吞吐量,以避免影响生产者和消费者。压缩日志段的实际过程如下所示:
日志压缩提供什么保证?
日志压缩保证以下几点:- 任何关注日志头部的消费者都会看到写入的每条消息;这些消息将具有连续的偏移量。主题
min.compaction.lag.ms
可用于保证消息写入后必须经过的最短时间长度才能被压缩。即,它提供了每条消息在(未压缩的)头部中保留多长时间的下限。主题max.compaction.lag.ms
可用于保证写入消息的时间和消息适合压缩的时间之间的最大延迟。 - 消息的顺序始终保持不变。压缩永远不会重新排序消息,只是删除一些消息。
- 消息的偏移量永远不会改变。它是日志中某个位置的永久标识符。
- 从日志开始进行的任何消费者都将至少按照写入顺序看到所有记录的最终状态。此外,如果消费者在小于主题设置的时间段内到达日志的头部
delete.retention.ms
(默认为 24 小时),则将看到已删除记录的所有删除标记。换句话说:由于删除标记的删除与读取同时发生,因此如果滞后超过 ,消费者可能会错过删除标记delete.retention.ms
。
日志压缩详细信息
日志压缩由日志清理器处理,日志清理器是一个后台线程池,用于重新复制日志段文件,删除其键出现在日志头部的记录。每个压缩器线程的工作原理如下:- 它选择具有最高日志头与日志尾比的日志
- 它为日志头部的每个键创建最后一个偏移量的简洁摘要
- 它从头到尾重新复制日志,删除日志中稍后出现的键。新的、干净的段会立即交换到日志中,因此所需的额外磁盘空间只是一个额外的日志段(而不是日志的完整副本)。
- 日志头的摘要本质上只是一个空间紧凑的哈希表。每个条目正好使用 24 个字节。因此,使用 8GB 的清理缓冲区,一次清理迭代可以清理大约 366GB 的日志头(假设有 1k 条消息)。
配置日志清理器
默认情况下启用日志清理器。这将启动清理线程池。要启用特定主题的日志清理,请添加特定于日志的属性log.cleanup.policy=compact
该log.cleanup.policy
属性是代理server.properties
文件中定义的代理配置设置;它会影响集群中没有配置覆盖的所有主题(如此处所述
)。日志清理器可以配置为保留最少量的未压实的日志“头部”。这是通过设置压缩时间延迟来启用的。
log.cleaner.min.compaction.lag.ms
这可用于防止比最小消息年龄新的消息受到压缩。如果未设置,则除最后一个段(即当前正在写入的段)之外的所有日志段都适合压缩。即使活动段的所有消息都早于最小压缩时间延迟,也不会压缩活动段。日志清理器可以配置为确保最大延迟,之后日志的未压缩“头部”就可以进行日志压缩。
log.cleaner.max.compaction.lag.ms
这可用于防止低生产率的原木在无限制的持续时间内保持不符合压缩条件。如果未设置,则不会压缩不超过 min.cleanable.dirty.ratio 的日志。请注意,这个压缩期限并不是一个硬性保证,因为它仍然受到日志清理线程的可用性和实际压缩时间的影响。您将需要监控 uncleanable-partitions-count、max-clean-time-secs 和 max-compaction-delay-secs 指标。
这里 描述了更多更清洁的配置。
4.9 配额
Kafka 集群能够对请求强制实施配额,以控制客户端使用的代理资源。Kafka 代理可以为共享配额的每组客户端强制执行两种类型的客户端配额:
- 网络带宽配额定义字节率阈值(自 0.9 起)
- 请求率配额将 CPU 利用率阈值定义为网络和 I/O 线程的百分比(自 0.11 起)
为什么需要配额?
生产者和消费者有可能产生/消耗非常大量的数据或以非常高的速率生成请求,从而垄断代理资源,导致网络饱和,并且通常会 DOS 其他客户端和代理本身。拥有配额可以防止这些问题,并且在大型多租户集群中尤为重要,其中一小部分行为不良的客户端可能会降低行为良好客户端的用户体验。事实上,当将 Kafka 作为服务运行时,这甚至可以根据商定的合同强制实施 API 限制。
客户群体
Kafka 客户端的身份是用户主体,它代表安全集群中经过身份验证的用户。在支持未经身份验证的客户端的集群中,用户主体是代理使用可配置的PrincipalBuilder
. Client-id 是客户端的逻辑分组,具有由客户端应用程序选择的有意义的名称。元组(用户、客户端 ID)定义共享用户主体和客户端 ID 的安全逻辑客户端组。
配额可以应用于(用户、客户端 ID)、用户或客户端 ID 组。对于给定连接,将应用与该连接匹配的最具体的配额。配额组的所有连接共享为该组配置的配额。例如,如果 (user="test-user", client-id="test-client") 的生产配额为 10MB/秒,则该配额将在用户“test-user”的所有生产者实例与客户端之间共享id“测试客户端”。
配额配置
可以为(用户、客户端 ID)、用户和客户端 ID 组定义配额配置。可以在需要更高(甚至更低)配额的任何配额级别覆盖默认配额。该机制类似于每个主题的日志配置覆盖。用户和(用户、客户端 ID)配额覆盖写入到 ZooKeeper 的/config/users下,客户端 ID 配额覆盖写入到/config/clients下。所有经纪商都会读取这些覆盖并立即生效。这使我们可以更改配额,而无需滚动重新启动整个集群。详细信息请参见此处。每个组的默认配额也可以使用相同的机制动态更新。
配额配置的优先顺序是:
- /config/users/<用户>/clients/<客户端 ID>
- /config/users/<用户>/clients/<默认>
- /config/users/<用户>
- /config/users/<默认>/clients/<客户端 ID>
- /config/users/<默认>/clients/<默认>
- /配置/用户/<默认>
- /config/clients/<客户端 ID>
- /config/clients/<默认>
网络带宽配额
网络带宽配额定义为共享配额的每组客户端的字节率阈值。默认情况下,每个唯一的客户端组都会收到集群配置的固定配额(以字节/秒为单位)。该配额是按每个经纪商定义的。在客户端受到限制之前,每组客户端可以在每个代理上发布/获取最大 X 字节/秒。
请求速率配额
请求速率配额定义为客户端在配额窗口内可以利用每个代理的请求处理程序 I/O 线程和网络线程的时间百分比。n%的配额表示 一个线程的n%,因此配额超出了((num.io.threads + num.network.threads) * 100)%的总容量。在受到限制之前,每组客户端可以在配额窗口中的所有 I/O 和网络线程中使用高达n%的总百分比。由于分配给 I/O 和网络线程的线程数通常基于代理主机上可用的核心数,因此请求率配额表示共享配额的每组客户端可能使用的 CPU 总百分比。
执行
默认情况下,每个唯一的客户端组都会收到集群配置的固定配额。该配额是按每个经纪商定义的。在受到限制之前,每个客户端都可以使用每个代理的此配额。我们认为为每个代理定义这些配额比为每个客户端拥有固定的集群宽带宽要好得多,因为这需要一种在所有代理之间共享客户端配额使用情况的机制。这可能比配额实施本身更难!
当经纪商检测到配额违规时如何反应?在我们的解决方案中,经纪人首先计算使违规客户端低于其配额所需的延迟量,并立即返回包含延迟的响应。如果是获取请求,响应将不包含任何数据。然后,代理将与客户端的通道静音,不再处理来自客户端的请求,直到延迟结束。在收到延迟时间非零的响应后,Kafka 客户端也将在延迟期间避免向代理发送进一步的请求。因此,来自受限制客户端的请求会被双方有效地阻止。即使使用不尊重代理延迟响应的旧客户端实现,代理通过静音其套接字通道施加的反压仍然可以处理行为不良客户端的限制。那些向受限通道发送进一步请求的客户端只有在延迟结束后才会收到响应。
字节率和线程利用率是在多个小窗口(例如 30 个窗口,每个窗口 1 秒)上测量的,以便快速检测和纠正配额违规。通常,具有较大的测量窗口(例如,10 个窗口,每个窗口 30 秒)会导致大量流量突发,然后是较长的延迟,这对于用户体验而言并不是很好。
5. 实施
5.1 网络层
网络层是一个相当简单的NIO服务器,不会详细描述。sendfile 的实现是通过为TransferableRecords
接口提供一个writeTo
方法来完成的。这允许文件支持的消息集使用更有效的transferTo
实现而不是进程内缓冲写入。线程模型是单个接受器线程和N 个处理器线程,每个线程处理固定数量的连接。该设计已在其他地方进行了相当彻底的测试,发现实施简单且速度快。该协议保持非常简单,以允许将来以其他语言实现客户端。
5.2 消息
消息由可变长度标头、可变长度不透明密钥字节数组和可变长度不透明值字节数组组成。标头的格式将在以下部分中描述。让键和值不透明是正确的决定:目前序列化库正在取得很大进展,任何特定的选择都不可能适合所有用途。不用说,使用 Kafka 的特定应用程序可能会强制使用特定的序列化类型作为其使用的一部分。该RecordBatch
接口只是一个消息迭代器,具有用于批量读取和写入 NIO 的专用方法Channel
。
5.3 消息格式
消息(又名记录)始终是批量写入的。一批消息的技术术语是记录批次,记录批次包含一条或多条记录。在退化情况下,我们可以有一个包含单个记录的记录批次。记录批次和记录有自己的标题。每个的格式如下所述。
5.3.1 记录批次
以下是 RecordBatch 的磁盘格式。
baseOffset: int64
batchLength: int32
partitionLeaderEpoch: int32
magic: int8 (current magic value is 2)
crc: uint32
attributes: int16
bit 0~2:
0: no compression
1: gzip
2: snappy
3: lz4
4: zstd
bit 3: timestampType
bit 4: isTransactional (0 means not transactional)
bit 5: isControlBatch (0 means not a control batch)
bit 6: hasDeleteHorizonMs (0 means baseTimestamp is not set as the delete horizon for compaction)
bit 7~15: unused
lastOffsetDelta: int32
baseTimestamp: int64
maxTimestamp: int64
producerId: int64
producerEpoch: int16
baseSequence: int32
records: [Record]
请注意,启用压缩后,压缩的记录数据将直接按照记录数计数进行序列化。
CRC 涵盖从属性到批次结束的数据(即CRC 后面的所有字节)。它位于魔术字节之后,这意味着客户端必须先解析魔术字节,然后才能决定如何解释批量长度和魔术字节之间的字节。分区领导纪元字段不包含在 CRC 计算中,以避免在为代理接收的每个批次分配该字段时需要重新计算 CRC。CRC-32C (Castagnoli) 多项式用于计算。
关于压缩:与旧的消息格式不同,magic v2 及更高版本在清理日志时保留原始批次的第一个和最后一个偏移量/序列号。这是为了能够在重新加载日志时恢复生产者的状态所必需的。例如,如果我们没有保留最后一个序列号,那么在分区领导者失败后,生产者可能会看到 OutOfSequence 错误。必须保留基本序列号以进行重复检查(代理通过验证传入批次的第一个和最后一个序列号是否与该生产者的最后一个序列号匹配来检查传入的 Produce 请求是否有重复)。因此,当批次中的所有记录都被清除但仍保留批次以保留生产者的最后序列号时,日志中可能会有空批次。这里的一个奇怪之处是,在压缩期间不会保留 baseTimestamp 字段,因此如果批处理中的第一个记录被压缩,它将发生变化。
如果记录批次包含具有空负载或中止事务标记的记录,则压缩还可能会修改baseTimestamp。baseTimestamp 将设置为应删除这些记录的时间戳,并设置删除范围属性位。
5.3.1.1 控制批次
控制批次包含称为控制记录的单个记录。控制记录不应传递给应用程序。相反,消费者使用它们来过滤掉中止的事务消息。
控制记录的键符合以下模式:
version: int16 (current version is 0)
type: int16 (0 indicates an abort marker, 1 indicates a commit)
控制记录值的架构取决于类型。该值对客户来说是不透明的。
5.3.2 记录
记录级标头是在 Kafka 0.11.0 中引入的。带有标头的记录的磁盘格式如下所示。
length: varint
attributes: int8
bit 0~7: unused
timestampDelta: varlong
offsetDelta: varint
keyLength: varint
key: byte[]
valueLen: varint
value: byte[]
Headers => [Header]
5.3.2.1 记录头
headerKeyLength: varint
headerKey: String
headerValueLength: varint
Value: byte[]
我们使用与 Protobuf 相同的 varint 编码。有关后者的更多信息可以在这里找到。记录中的标头计数也被编码为 varint。
5.3.3 旧消息格式
在Kafka 0.11之前,消息被传输并存储在消息集中。在消息集中,每条消息都有自己的元数据。请注意,虽然消息集表示为数组,但它们不像协议中的其他数组元素那样前面有 int32 数组大小。
消息集:MessageSet (Version: 0) => [offset message_size message]
offset => INT64
message_size => INT32
message => crc magic_byte attributes key value
crc => INT32
magic_byte => INT8
attributes => INT8
bit 0~2:
0: no compression
1: gzip
2: snappy
bit 3~7: unused
key => BYTES
value => BYTES
MessageSet (Version: 1) => [offset message_size message]
offset => INT64
message_size => INT32
message => crc magic_byte attributes timestamp key value
crc => INT32
magic_byte => INT8
attributes => INT8
bit 0~2:
0: no compression
1: gzip
2: snappy
3: lz4
bit 3: timestampType
0: create time
1: log append time
bit 4~7: unused
timestamp => INT64
key => BYTES
value => BYTES
在 Kafka 0.10 之前的版本中,唯一支持的消息格式版本(在幻值中指示)是 0。消息格式版本 1 在 0.10 版本中引入了时间戳支持。
- 与上面的版本 2 类似,属性的最低位表示压缩类型。
- 在版本 1 中,生产者应始终将时间戳类型位设置为 0。如果主题配置为使用日志附加时间(通过代理级别配置 log.message.timestamp.type = LogAppendTime 或主题级别配置 message.timestamp)。 type = LogAppendTime),broker 将覆盖时间戳类型和消息集中的时间戳。
- 属性的最高位必须设置为 0。
在消息格式版本 0 和 1 中,Kafka 支持递归消息以启用压缩。在这种情况下,必须将消息的属性设置为指示其中一种压缩类型,并且值字段将包含使用该类型压缩的消息集。我们经常将嵌套消息称为“内部消息”,将包装消息称为“外部消息”。请注意,外部消息的键应该为空,并且其偏移量将是最后一个内部消息的偏移量。
当接收到递归版本 0 消息时,代理会解压缩它们,并为每个内部消息单独分配一个偏移量。在版本 1 中,为了避免服务器端重新压缩,只会为包装器消息分配偏移量。内部消息将具有相对偏移。绝对偏移量可以使用外部消息的偏移量来计算,该偏移量对应于分配给最后一个内部消息的偏移量。
crc 字段包含后续消息字节(即从幻字节到值)的 CRC32(而非 CRC-32C)。
5.4 日志
具有两个分区的名为“my-topic”的主题的日志由两个目录(即my-topic-0
和my-topic-1
)组成,其中填充了包含该主题消息的数据文件。日志文件的格式是一系列“日志条目”;每个日志条目都是一个 4 字节整数N,存储消息长度,后跟N个消息字节。每条消息都由 64 位整数偏移量唯一标识,该偏移量给出了该消息在发送到该分区上该主题的所有消息流中开始的字节位置。下面给出了每条消息的磁盘格式。每个日志文件都以其包含的第一条消息的偏移量命名。因此,创建的第一个文件将是 00000000000000000000.log,每个附加文件将有一个与前一个文件大约S字节的整数名称,其中S是配置中给定的最大日志文件大小。
记录的确切二进制格式作为标准接口进行版本控制和维护,因此记录批次可以在生产者、代理和客户端之间传输,而无需在需要时重新复制或转换。上一节包含有关记录的磁盘格式的详细信息。
使用消息偏移量作为消息 ID 的情况并不常见。我们最初的想法是使用生产者生成的 GUID,并在每个代理上维护从 GUID 到偏移量的映射。但由于消费者必须为每台服务器维护一个 ID,因此 GUID 的全局唯一性没有任何价值。此外,维护从随机 ID 到偏移量的映射的复杂性需要一个必须与磁盘同步的重量级索引结构,本质上需要一个完全持久的随机访问数据结构。因此,为了简化查找结构,我们决定使用一个简单的每分区原子计数器,它可以与分区 id 和节点 id 结合起来唯一地标识一条消息;这使得查找结构更简单,尽管每个消费者请求仍可能进行多次查找。然而,一旦我们确定了计数器,直接使用偏移量的跳转似乎很自然——毕竟两者都是分区特有的单调递增整数。由于偏移量对消费者 API 是隐藏的,所以这个决定最终是一个实现细节,我们采用了更有效的方法。
写
日志允许串行追加,始终转到最后一个文件。当该文件达到可配置大小(例如 1GB)时,它会转存为新文件。日志采用两个配置参数:M,它给出在强制操作系统将文件刷新到磁盘之前要写入的消息数;以及S,它给出强制刷新之前的秒数。这提供了在系统崩溃时 最多丢失M条消息或S秒数据的持久性保证。
读
读取是通过给出消息的 64 位逻辑偏移量和S字节最大块大小来完成的。这将返回S字节缓冲区中包含的消息的迭代器。S旨在大于任何单个消息,但如果消息异常大,则可以重试多次读取,每次将缓冲区大小加倍,直到成功读取消息。可以指定最大消息和缓冲区大小,以使服务器拒绝大于某个大小的消息,并为客户端提供获取完整消息所需读取的最大值的限制。读取缓冲区很可能以部分消息结束,这很容易通过大小分隔来检测到。
从偏移量读取的实际过程需要首先找到存储数据的日志段文件,根据全局偏移值计算文件特定的偏移量,然后从该文件偏移量读取。搜索是作为针对每个文件维护的内存范围的简单二分搜索变体来完成的。
该日志提供了获取最近写入的消息的功能,以允许客户端“立即”开始订阅。如果消费者未能在 SLA 指定的天数内使用其数据,这也很有用。在这种情况下,当客户端尝试使用不存在的偏移量时,它会收到 OutOfRangeException 异常,并且可能会根据用例自行重置或失败。
以下是发送给消费者的结果的格式。
MessageSetSend (fetch result)
total length : 4 bytes
error code : 2 bytes
message 1 : x bytes
...
message n : x bytes
MultiMessageSetSend (multiFetch result)
total length : 4 bytes
error code : 2 bytes
messageSetSend 1
...
messageSetSend n
删除
一次删除一个日志段的数据。日志管理器应用两个指标来识别适合删除的段:时间和大小。对于基于时间的策略,会考虑记录时间戳,分段文件中最大的时间戳(记录顺序不相关)定义整个分段的保留时间。默认情况下禁用基于大小的保留。启用后,日志管理器将不断删除最旧的段文件,直到分区的总体大小再次位于配置的限制内。如果同时启用这两个策略,则由于任一策略而符合删除条件的段将被删除。为了避免锁定读取,同时仍然允许修改段列表的删除,我们使用写时复制样式的段列表实现,该实现提供一致的视图,以允许在删除进行时在日志段的不可变静态快照视图上继续进行二分搜索。
保证
日志提供了一个配置参数M,它控制在强制刷新到磁盘之前写入的最大消息数。启动时,运行日志恢复进程,迭代最新日志段中的所有消息并验证每个消息条目是否有效。如果消息条目的大小和偏移量之和小于文件的长度并且消息有效负载的 CRC32 与消息中存储的 CRC 匹配,则消息条目有效。如果检测到损坏,日志将被截断到最后一个有效偏移量。
请注意,必须处理两种类型的损坏:由于崩溃而丢失未写入块的截断,以及将无意义块添加到文件的损坏。这样做的原因是,一般来说,操作系统不保证文件 inode 和实际块数据之间的写入顺序,因此,如果 inode 更新为新大小,那么除了丢失写入数据之外,文件还可能获得无意义的数据。崩溃发生在写入包含该数据的块之前。CRC 检测到这种特殊情况,并防止其损坏日志(尽管未写入的消息当然会丢失)。
5.5 分布
消费者偏移追踪
Kafka 消费者跟踪它在每个分区中消耗的最大偏移量,并且能够提交偏移量,以便在重新启动时可以从这些偏移量恢复。Kafka 提供了将给定消费者组的所有偏移量存储在称为组协调器的指定代理(针对该组)中的选项。即,该消费者组中的任何消费者实例都应该将其偏移量提交和获取发送到该组协调器(代理)。消费者组根据组名分配给协调员。消费者可以通过向任何 Kafka 代理发出 FindCoordinatorRequest 并读取包含协调器详细信息的 FindCoordinatorResponse 来查找其协调器。然后,消费者可以继续从协调代理中提交或获取偏移量。如果协调器移动,消费者将需要重新发现协调器。偏移量提交可以由消费者实例自动或手动完成。
当组协调器收到 OffsetCommitRequest 时,它会将请求附加到名为__consumer_offsets的特殊压缩Kafka 主题。仅当偏移量主题的所有副本都收到偏移量后,代理才会向消费者发送成功的偏移量提交响应。如果偏移量未能在可配置的超时内复制,则偏移量提交将失败,并且消费者可以在退出后重试提交。代理定期压缩偏移量主题,因为它只需要维护每个分区的最新偏移量提交。协调器还将偏移量缓存在内存表中,以便快速提供偏移量获取。
当协调器收到偏移量获取请求时,它只是从偏移量缓存中返回最后提交的偏移量向量。如果协调器刚刚启动或者它刚刚成为一组新的消费者组的协调器(通过成为偏移主题分区的领导者),它可能需要将偏移主题分区加载到缓存中。在这种情况下,偏移量获取将失败并出现 CoordinatorLoadInProgressException,并且使用者可以在退出后重试 OffsetFetchRequest。
ZooKeeper 目录
下面给出了用于协调消费者和代理之间的 ZooKeeper 结构和算法。
符号
当路径中的元素被表示为 时[xyz]
,这意味着 xyz 的值不固定,并且实际上 xyz 的每个可能值都有一个 ZooKeeper znode。例如,/topics/[topic]
名为 /topics 的目录包含每个主题名称的子目录。还给出了数字范围,例如[0...5]
指示子目录 0、1、2、3、4。箭头->
用于指示 znode 的内容。例如/hello -> world
,将指示包含值“world”的 znode /hello。
经纪商节点注册表
/brokers/ids/[0...N] --> {"jmx_port":...,"timestamp":...,"endpoints":[...],"host":...,"version":...,"port":...} (ephemeral node)
这是所有现有代理节点的列表,每个节点都提供一个唯一的逻辑代理 ID,用于向消费者标识它(必须作为其配置的一部分给出)。启动时,代理节点通过在 /brokers/ids 下创建具有逻辑代理 ID 的 znode 来注册自身。逻辑broker id的目的是允许broker移动到不同的物理机器而不影响消费者。尝试注册已在使用的代理 ID(例如,因为两个服务器配置了相同的代理 ID)会导致错误。
由于代理使用临时 znode 在 ZooKeeper 中注册自身,因此这种注册是动态的,并且如果代理关闭或死亡(从而通知消费者它不再可用),该注册就会消失。
经纪商主题注册表
/brokers/topics/[topic]/partitions/[0...N]/state --> {"controller_epoch":...,"leader":...,"version":...,"leader_epoch":...,"isr":[...]} (ephemeral node)
每个代理都会在其维护的主题下注册自己,并存储该主题的分区数量。
集群 ID
集群 ID 是分配给 Kafka 集群的唯一且不可变的标识符。集群 ID 最多可以有 22 个字符,允许的字符由正则表达式 [a-zA-Z0-9_\-]+ 定义,它对应于不带填充的 URL 安全 Base64 变体使用的字符。从概念上讲,它是在集群第一次启动时自动生成的。
从实现角度来看,它是在 0.10.1 或更高版本的代理首次成功启动时生成的。代理/cluster/id
在启动期间尝试从 znode 获取集群 ID。如果 znode 不存在,broker 会生成一个新的集群 id,并使用该集群 id 创建 znode。
经纪商节点注册
代理节点基本上是独立的,因此它们只发布有关其拥有的信息。当代理加入时,它会在代理节点注册表目录下注册自己,并写入有关其主机名和端口的信息。代理还在代理主题注册表中注册现有主题及其逻辑分区的列表。新主题在代理上创建时会动态注册。
6. 运营
以下是根据 LinkedIn 的使用情况和经验实际将 Kafka 作为生产系统运行的一些信息。请将您知道的任何其他提示发送给我们。6.1 Kafka基本操作
本节将回顾您将在 Kafka 集群上执行的最常见操作。本节中回顾的所有工具都可以在bin/
Kafka 发行版的目录下找到,如果不带参数运行,每个工具都会打印所有可能的命令行选项的详细信息。
添加和删除主题
您可以选择手动添加主题,也可以在数据首次发布到不存在的主题时自动创建主题。如果主题是自动创建的,那么您可能需要调整用于自动创建主题的 默认主题配置。使用主题工具添加和修改主题:
> bin/kafka-topics.sh --bootstrap-server broker_host:port --create --topic my_topic_name \
--partitions 20 --replication-factor 3 --config x=y
复制因子控制有多少服务器将复制每条写入的消息。如果复制因子为 3,则在您失去对数据的访问权限之前最多 2 个服务器可能会发生故障。我们建议您使用 2 或 3 的复制因子,以便您可以透明地弹跳机器而不中断数据消耗。
分区计数控制主题将被分片为多少个日志。分区计数有多种影响。首先,每个分区必须完全适合一台服务器。因此,如果您有 20 个分区,则完整数据集(以及读写负载)将由不超过 20 个服务器(不包括副本)处理。最后,分区计数会影响消费者的最大并行度。概念部分对此进行了更详细的讨论。
每个分片分区日志都放置在 Kafka 日志目录下自己的文件夹中。此类文件夹的名称由主题名称、附加破折号 (-) 和分区 ID 组成。由于典型的文件夹名称长度不能超过 255 个字符,因此主题名称的长度将受到限制。我们假设分区数量永远不会超过 100,000。因此,主题名称不能超过 249 个字符。这会在文件夹名称中留下足够的空间用于短划线和可能为 5 位数长的分区 ID。
在命令行上添加的配置会覆盖服务器的默认设置,例如数据应保留的时间长度。完整的每个主题配置集记录在此处。
修改主题
您可以使用同一主题工具更改主题的配置或分区。要添加分区,您可以执行以下操作
> bin/kafka-topics.sh --bootstrap-server broker_host:port --alter --topic my_topic_name \
--partitions 40
请注意,分区的一种用例是对数据进行语义分区,并且添加分区不会更改现有数据的分区,因此如果消费者依赖该分区,这可能会干扰他们。也就是说,如果数据已分区hash(key) % number_of_partitions
,则该分区可能会通过添加分区而被打乱,但 Kafka 不会尝试以任何方式自动重新分配数据。
添加配置:
> bin/kafka-configs.sh --bootstrap-server broker_host:port --entity-type topics --entity-name my_topic_name --alter --add-config x=y
要删除配置:
> bin/kafka-configs.sh --bootstrap-server broker_host:port --entity-type topics --entity-name my_topic_name --alter --delete-config x
最后删除一个主题:
> bin/kafka-topics.sh --bootstrap-server broker_host:port --delete --topic my_topic_name
Kafka目前不支持减少主题的分区数量。
可以在此处 找到有关更改主题的复制因子的说明。
优雅关机
Kafka 集群将自动检测任何代理关闭或故障,并为该机器上的分区选举新的领导者。无论服务器发生故障还是为了维护或配置更改而故意关闭服务器,都会发生这种情况。对于后一种情况,Kafka 支持一种更优雅的机制来停止服务器,而不仅仅是杀死它。当服务器正常停止时,它将利用两个优化:- 它将所有日志同步到磁盘,以避免重新启动时需要执行任何日志恢复(即验证日志尾部所有消息的校验和)。日志恢复需要时间,因此这可以加快有意重新启动的速度。
- 它将在关闭之前将服务器作为领导者的任何分区迁移到其他副本。这将使领导权转移更快,并将每个分区不可用的时间最小化到几毫秒。
controlled.shutdown.enable=true
请注意,只有在代理上托管的所有分区都有副本(即复制因子大于 1并且这些副本中至少有一个处于活动状态)时,受控关闭才会成功。这通常是您想要的,因为关闭最后一个副本将使该主题分区不可用。
平衡领导力
每当代理停止或崩溃时,该代理的分区的领导权就会转移到其他副本。当代理重新启动时,它只会成为其所有分区的追随者,这意味着它不会用于客户端读取和写入。为了避免这种不平衡,Kafka 有一个首选副本的概念。如果分区的副本列表为 1、5、9,则节点 1 优先作为节点 5 或 9 的领导者,因为它在副本列表中较早。默认情况下,Kafka 集群将尝试恢复首选副本的领导地位。此行为配置为:
auto.leader.rebalance.enable=true
您也可以将其设置为 false,但随后您需要通过运行以下命令手动恢复已恢复副本的领导权:
> bin/kafka-leader-election.sh --bootstrap-server broker_host:port --election-type preferred --all-topic-partitions
跨机架平衡副本
机架感知功能将同一分区的副本分布在不同的机架上。这扩展了 Kafka 为代理故障提供的保证以涵盖机架故障,从而限制了机架上的所有代理同时发生故障时数据丢失的风险。该功能还可以应用于其他代理分组,例如 EC2 中的可用区域。 您可以通过向代理配置添加属性来指定代理属于特定机架: broker.rack=my-rack-id
当创建、修改主题或重新分配副本
时,将遵守机架约束,确保副本跨越尽可能多的机架(分区将跨越 min(#racks,replication-factor) 个不同的机架)。
用于将副本分配给代理的算法可确保每个代理的领导者数量保持不变,无论代理如何跨机架分布。这确保了平衡的吞吐量。
但是,如果为机架分配了不同数量的代理,则副本的分配将不均匀。具有较少代理的机架将获得更多副本,这意味着它们将使用更多存储并将更多资源用于复制。因此,每个机架配置相同数量的代理是明智的。
集群之间的数据镜像和异地复制
Kafka 管理员可以定义跨越各个 Kafka 集群、数据中心或地理区域边界的数据流。请参阅异地复制部分以获取更多信息。
检查消费者位置
有时了解消费者的立场很有用。我们有一个工具可以显示消费者组中所有消费者的位置以及它们距离日志末尾有多远。要在使用名为my-topic 的主题的名为my-group 的消费者组上运行此工具,如下所示: > bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group
TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG CONSUMER-ID HOST CLIENT-ID
my-topic 0 2 4 2 consumer-1-029af89c-873c-4751-a720-cefd41a669d6 /127.0.0.1 consumer-1
my-topic 1 2 3 1 consumer-1-029af89c-873c-4751-a720-cefd41a669d6 /127.0.0.1 consumer-1
my-topic 2 2 3 1 consumer-2-42c1abd4-e3b2-425d-a8bb-e1ea49b29bb2 /127.0.0.1 consumer-2
管理消费者群体
使用 ConsumerGroupCommand 工具,我们可以列出、描述或删除消费者组。可以手动删除消费者组,也可以在该组的最后提交的偏移量到期时自动删除该消费者组。仅当组没有任何活动成员时,手动删除才有效。例如,要列出所有主题的所有消费者组: > bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list
test-consumer-group
要查看偏移量,如前所述,我们像这样“描述”消费者组:
> bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group
TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG CONSUMER-ID HOST CLIENT-ID
topic3 0 241019 395308 154289 consumer2-e76ea8c3-5d30-4299-9005-47eb41f3d3c4 /127.0.0.1 consumer2
topic2 1 520678 803288 282610 consumer2-e76ea8c3-5d30-4299-9005-47eb41f3d3c4 /127.0.0.1 consumer2
topic3 1 241018 398817 157799 consumer2-e76ea8c3-5d30-4299-9005-47eb41f3d3c4 /127.0.0.1 consumer2
topic1 0 854144 855809 1665 consumer1-3fc8d6f1-581a-4472-bdf3-3515b4aee8c1 /127.0.0.1 consumer1
topic2 0 460537 803290 342753 consumer1-3fc8d6f1-581a-4472-bdf3-3515b4aee8c1 /127.0.0.1 consumer1
topic3 2 243655 398812 155157 consumer4-117fe4d3-c6c1-4178-8ee9-eb4a3954bee0 /127.0.0.1 consumer4
有许多附加的“描述”选项可用于提供有关消费者组的更详细信息:
- --members:此选项提供消费者组中所有活跃成员的列表。
> bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group --members CONSUMER-ID HOST CLIENT-ID #PARTITIONS consumer1-3fc8d6f1-581a-4472-bdf3-3515b4aee8c1 /127.0.0.1 consumer1 2 consumer4-117fe4d3-c6c1-4178-8ee9-eb4a3954bee0 /127.0.0.1 consumer4 1 consumer2-e76ea8c3-5d30-4299-9005-47eb41f3d3c4 /127.0.0.1 consumer2 3 consumer3-ecea43e4-1f01-479f-8349-f9130b75d8ee /127.0.0.1 consumer3 0
- --members --verbose:除了上面的“--members”选项报告的信息之外,此选项还提供分配给每个成员的分区。
> bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group --members --verbose CONSUMER-ID HOST CLIENT-ID #PARTITIONS ASSIGNMENT consumer1-3fc8d6f1-581a-4472-bdf3-3515b4aee8c1 /127.0.0.1 consumer1 2 topic1(0), topic2(0) consumer4-117fe4d3-c6c1-4178-8ee9-eb4a3954bee0 /127.0.0.1 consumer4 1 topic3(2) consumer2-e76ea8c3-5d30-4299-9005-47eb41f3d3c4 /127.0.0.1 consumer2 3 topic2(1), topic3(0,1) consumer3-ecea43e4-1f01-479f-8349-f9130b75d8ee /127.0.0.1 consumer3 0 -
- --offsets:这是默认的描述选项,提供与“--describe”选项相同的输出。
- --state:此选项提供有用的组级别信息。
> bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group --state COORDINATOR (ID) ASSIGNMENT-STRATEGY STATE #MEMBERS localhost:9092 (0) range Stable 4
> bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --delete --group my-group --group my-other-group
Deletion of requested consumer groups ('my-group', 'my-other-group') was successful.
要重置消费者组的偏移量,可以使用“--reset-offsets”选项。此选项同时支持一个消费者组。它需要定义以下范围:--all-topics 或--topic。除非您使用“--from-file”方案,否则必须选择一个范围。另外,首先确保使用者实例处于非活动状态。有关更多详细信息, 请参阅 KIP-122 。
它有 3 个执行选项:
- (默认)显示要重置的偏移量。
- --execute : 执行 --reset-offsets 进程。
- --export :将结果导出为 CSV 格式。
--reset-offsets 还有以下场景可供选择(至少必须选择一种场景):
- --to-datetime <String: datetime> :将偏移量重置为日期时间的偏移量。格式:'YYYY-MM-DDTHH:mm:SS.sss'
- --to-earliest :将偏移量重置为最早的偏移量。
- --to-latest :将偏移量重置为最新偏移量。
- --shift-by <Long: number-of-offsets> :重置偏移量,将当前偏移量移动“n”,其中“n”可以是正数或负数。
- --from-file :将偏移量重置为 CSV 文件中定义的值。
- --to-current :将偏移量重置为当前偏移量。
- --by-duration <String:uration> :将偏移量重置为从当前时间戳开始按持续时间偏移。格式:'PnDTnHnMnS'
- --to-offset :将偏移量重置为特定偏移量。
例如,将消费者组的偏移量重置为最新的偏移量:
> bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --reset-offsets --group consumergroup1 --topic topic1 --to-latest
TOPIC PARTITION NEW-OFFSET
topic1 0 0
如果您使用旧的高级使用者并将组元数据存储在 ZooKeeper 中(即offsets.storage=zookeeper
),请传递
--zookeeper
而不是--bootstrap-server
:
> bin/kafka-consumer-groups.sh --zookeeper localhost:2181 --list
扩展您的集群
将服务器添加到 Kafka 集群非常简单,只需为它们分配一个唯一的代理 ID 并在新服务器上启动 Kafka 即可。但是,这些新服务器不会自动分配任何数据分区,因此除非将分区移动到它们,否则在创建新主题之前它们不会执行任何工作。因此,通常当您向集群添加机器时,您会希望将一些现有数据迁移到这些机器。迁移数据的过程是手动启动的,但完全自动化。在幕后发生的事情是,Kafka 会将新服务器添加为它正在迁移的分区的跟随者,并允许它完全复制该分区中的现有数据。当新服务器完全复制该分区的内容并加入同步副本时,现有副本之一将删除其分区的数据。
分区重新分配工具可用于跨代理移动分区。理想的分区分布将确保所有代理的数据负载和分区大小均匀。分区重新分配工具无法自动研究 Kafka 集群中的数据分布并移动分区以获得均匀的负载分布。因此,管理员必须弄清楚应该移动哪些主题或分区。
分区重新分配工具可以在 3 种互斥的模式下运行:
- --generate:在此模式下,给定主题列表和代理列表,该工具会生成候选重新分配,以将指定主题的所有分区移动到新代理。此选项仅提供了一种在给定主题和目标代理列表的情况下生成分区重新分配计划的便捷方法。
- --execute:在此模式下,该工具根据用户提供的重新分配计划启动分区的重新分配。(使用 --reassignment-json-file 选项)。这可以是由管理员手工制作的自定义重新分配计划,也可以使用 --generate 选项提供
- --verify:在此模式下,该工具验证上次 --execute 期间列出的所有分区的重新分配状态。状态可以是成功完成、失败或正在进行
自动将数据迁移到新机器
分区重新分配工具可用于将某些主题从当前代理集中移至新添加的代理。这在扩展现有集群时通常很有用,因为将整个主题移动到一组新的代理比一次移动一个分区更容易。当用于执行此操作时,用户应提供应移动到新代理集的主题列表以及新代理的目标列表。然后,该工具将给定主题列表的所有分区均匀分布在新的代理集上。在此移动过程中,主题的复制因子保持不变。实际上,主题输入列表的所有分区的副本都从旧的代理集移动到新添加的代理。例如,以下示例将主题 foo1,foo2 的所有分区移动到新的代理集 5,6。在此移动结束时,主题 foo1 和 foo2 的所有分区将仅存在于代理 5,6 上。
由于该工具接受 json 文件形式的主题输入列表,因此您首先需要确定要移动的主题并创建 json 文件,如下所示:
> cat topics-to-move.json
{"topics": [{"topic": "foo1"},
{"topic": "foo2"}],
"version":1
}
json 文件准备好后,使用分区重新分配工具生成候选分配:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --topics-to-move-json-file topics-to-move.json --broker-list "5,6" --generate
Current partition replica assignment
{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[2,1]},
{"topic":"foo1","partition":1,"replicas":[1,3]},
{"topic":"foo1","partition":2,"replicas":[3,4]},
{"topic":"foo2","partition":0,"replicas":[4,2]},
{"topic":"foo2","partition":1,"replicas":[2,1]},
{"topic":"foo2","partition":2,"replicas":[1,3]}]
}
Proposed partition reassignment configuration
{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[6,5]},
{"topic":"foo1","partition":1,"replicas":[5,6]},
{"topic":"foo1","partition":2,"replicas":[6,5]},
{"topic":"foo2","partition":0,"replicas":[5,6]},
{"topic":"foo2","partition":1,"replicas":[6,5]},
{"topic":"foo2","partition":2,"replicas":[5,6]}]
}
该工具生成一个候选分配,将所有分区从主题 foo1,foo2 移动到代理 5,6。但请注意,此时分区移动尚未开始,它仅告诉您当前分配和建议的新分配。应保存当前分配,以防您想回滚到当前分配。新分配应保存在 json 文件中(例如 Expand-cluster-reassignment.json),以便使用 --execute 选项输入到工具中,如下所示:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file expand-cluster-reassignment.json --execute
Current partition replica assignment
{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[2,1]},
{"topic":"foo1","partition":1,"replicas":[1,3]},
{"topic":"foo1","partition":2,"replicas":[3,4]},
{"topic":"foo2","partition":0,"replicas":[4,2]},
{"topic":"foo2","partition":1,"replicas":[2,1]},
{"topic":"foo2","partition":2,"replicas":[1,3]}]
}
Save this to use as the --reassignment-json-file option during rollback
Successfully started partition reassignments for foo1-0,foo1-1,foo1-2,foo2-0,foo2-1,foo2-2
最后,--verify 选项可以与该工具一起使用来检查分区重新分配的状态。请注意,相同的 Expand-cluster-reassignment.json(与 --execute 选项一起使用)应与 --verify 选项一起使用:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file expand-cluster-reassignment.json --verify
Status of partition reassignment:
Reassignment of partition [foo1,0] is completed
Reassignment of partition [foo1,1] is still in progress
Reassignment of partition [foo1,2] is still in progress
Reassignment of partition [foo2,0] is completed
Reassignment of partition [foo2,1] is completed
Reassignment of partition [foo2,2] is completed
自定义分区分配和迁移
分区重新分配工具还可用于有选择地将分区的副本移动到一组特定的代理。当以这种方式使用时,假设用户知道重新分配计划并且不需要该工具来生成候选重新分配,从而有效地跳过 --generate 步骤并直接进入 --execute 步骤例如,以下示例将主题 foo1 的分区 0 移动到代理 5,6,将主题 foo2 的分区 1 移动到代理 2,3:
第一步是在 json 文件中手工制定自定义重新分配计划:
> cat custom-reassignment.json
{"version":1,"partitions":[{"topic":"foo1","partition":0,"replicas":[5,6]},{"topic":"foo2","partition":1,"replicas":[2,3]}]}
然后,使用带有 --execute 选项的 json 文件来启动重新分配过程:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file custom-reassignment.json --execute
Current partition replica assignment
{"version":1,
"partitions":[{"topic":"foo1","partition":0,"replicas":[1,2]},
{"topic":"foo2","partition":1,"replicas":[3,4]}]
}
Save this to use as the --reassignment-json-file option during rollback
Successfully started partition reassignments for foo1-0,foo2-1
--verify 选项可以与该工具一起使用来检查分区重新分配的状态。请注意,相同的 custom-reassignment.json (与 --execute 选项一起使用)应与 --verify 选项一起使用:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file custom-reassignment.json --verify
Status of partition reassignment:
Reassignment of partition [foo1,0] is completed
Reassignment of partition [foo2,1] is completed
退役经纪人
分区重新分配工具尚不具备为退役代理自动生成重新分配计划的能力。因此,管理员必须制定一个重新分配计划,将要停用的代理上托管的所有分区的副本移动到其余代理。这可能相对乏味,因为重新分配需要确保所有副本不会从已停用的代理仅移动到另一个代理。为了使这个过程变得轻松,我们计划在未来为退役经纪人添加工具支持。增加复制因子
增加现有分区的复制因子很容易。只需在自定义重新分配 json 文件中指定额外的副本,并将其与 --execute 选项一起使用即可增加指定分区的复制因子。例如,以下示例将主题 foo 的分区 0 的复制因子从 1 增加到 3。在增加复制因子之前,该分区的唯一副本存在于代理 5 上。作为增加复制因子的一部分,我们将在代理 5 上添加更多副本经纪人 6 和 7。
第一步是在 json 文件中手工制定自定义重新分配计划:
> cat increase-replication-factor.json
{"version":1,
"partitions":[{"topic":"foo","partition":0,"replicas":[5,6,7]}]}
然后,使用带有 --execute 选项的 json 文件来启动重新分配过程:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file increase-replication-factor.json --execute
Current partition replica assignment
{"version":1,
"partitions":[{"topic":"foo","partition":0,"replicas":[5]}]}
Save this to use as the --reassignment-json-file option during rollback
Successfully started partition reassignment for foo-0
--verify 选项可以与该工具一起使用来检查分区重新分配的状态。请注意,相同的increase-replication-factor.json(与--execute选项一起使用)应与--verify选项一起使用:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --reassignment-json-file increase-replication-factor.json --verify
Status of partition reassignment:
Reassignment of partition [foo,0] is completed
您还可以使用 kafka-topics 工具验证复制因子的增加:
> bin/kafka-topics.sh --bootstrap-server localhost:9092 --topic foo --describe
Topic:foo PartitionCount:1 ReplicationFactor:3 Configs:
Topic: foo Partition: 0 Leader: 5 Replicas: 5,6,7 Isr: 5,6,7
限制数据迁移期间的带宽使用
Kafka 允许您对复制流量进行限制,设置用于在机器之间移动副本的带宽上限。这在重新平衡集群、引导新代理或添加或删除代理时非常有用,因为它限制了这些数据密集型操作对用户产生的影响。 有两个接口可用于接合油门。最简单、最安全的方法是在调用 kafka-reassign-partitions.sh 时应用限制,但 kafka-configs.sh 也可用于直接查看和更改限制值。 例如,如果您要使用以下命令执行重新平衡,它将以不超过 50MB/s 的速度移动分区。$ bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --execute --reassignment-json-file bigger-cluster.json --throttle 50000000当您执行此脚本时,您将看到油门接合:
The inter-broker throttle limit was set to 50000000 B/s
Successfully started partition reassignment for foo1-0
如果您希望在重新平衡期间改变油门,例如增加吞吐量,以便更快地完成,您可以通过使用传递相同的重新分配 json 文件的 --additional 选项重新运行执行命令来完成此操作:
$ bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --additional --execute --reassignment-json-file bigger-cluster.json --throttle 700000000 The inter-broker throttle limit was set to 700000000 B/s
重新平衡完成后,管理员可以使用 --verify 选项检查重新平衡的状态。如果重新平衡已完成,则将通过 --verify 命令删除限制。重要的是,管理员通过运行带有 --verify 选项的命令,在重新平衡完成后及时取消限制。如果不这样做可能会导致常规复制流量受到限制。
当执行 --verify 选项并且重新分配完成时,脚本将确认限制已被删除:
> bin/kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --verify --reassignment-json-file bigger-cluster.json
Status of partition reassignment:
Reassignment of partition [my-topic,1] is completed
Reassignment of partition [my-topic,0] is completed
Clearing broker-level throttles on brokers 1,2,3
Clearing topic-level throttles on topic my-topic
管理员还可以使用 kafka-configs.sh 验证分配的配置。有两对节流配置用于管理节流过程。第一对指油门值本身。这是在代理级别使用动态属性进行配置的:
leader.replication.throttled.rate
follower.replication.throttled.rate
然后是限制副本的枚举集的配置对:
leader.replication.throttled.replicas
follower.replication.throttled.replicas
哪些是按主题配置的。
所有四个配置值均由 kafka-reassign-partitions.sh 自动分配(如下所述)。
查看油门限制配置:
> bin/kafka-configs.sh --describe --bootstrap-server localhost:9092 --entity-type brokers
Configs for brokers '2' are leader.replication.throttled.rate=700000000,follower.replication.throttled.rate=700000000
Configs for brokers '1' are leader.replication.throttled.rate=700000000,follower.replication.throttled.rate=700000000
这显示了应用于复制协议的领导者和跟随者端的限制。默认情况下,双方都分配有相同的限制吞吐量值。
要查看受限制的副本列表:
> bin/kafka-configs.sh --describe --bootstrap-server localhost:9092 --entity-type topics
Configs for topic 'my-topic' are leader.replication.throttled.replicas=1:102,0:101,
follower.replication.throttled.replicas=1:101,0:102
在这里,我们看到领导者节流应用于代理 102 上的分区 1 和代理 101 上的分区 0。同样,追随者节流应用于代理 101 上的分区 1 和代理 102 上的分区 0。
默认情况下,kafka-reassign-partitions.sh 会将领导者限制应用于重新平衡之前存在的所有副本,其中任何一个都可能是领导者。它将对所有移动目的地应用跟随油门。因此,如果代理 101,102 上有一个具有副本的分区,被重新分配给 102,103,则该分区的领导者限制将应用于 101,102,追随者限制将仅应用于 103。
如果需要,您还可以使用 kafka-configs.sh 上的 --alter 开关手动更改节流配置。
安全使用限制复制
使用限制复制时应小心。尤其:
(1) 节气门拆除:
重新分配完成后应及时移除限制(通过运行 kafka-reassign-partitions.sh --verify)。(2) 确保进展:
如果与传入写入速率相比,限制设置得太低,复制可能无法取得进展。出现这种情况时:
max(BytesInPerSec) > throttle
其中 BytesInPerSec 是监控生产者写入每个代理的吞吐量的指标。
管理员可以在重新平衡期间使用以下指标监控复制是否取得进展:
kafka.server:type=FetcherLagMetrics,name=ConsumerLag,clientId=([-.\w]+),topic=([-.\w]+),partition=([0-9]+)
复制过程中滞后应该不断减少。如果指标没有减少,管理员应如上所述增加限制吞吐量。
设置配额
配额覆盖和默认值可以在(用户、客户端 ID)、用户或客户端 ID 级别进行配置,如此处所述。默认情况下,客户端获得无限配额。可以为每个(用户、客户端 ID)、用户或客户端 ID 组设置自定义配额。配置自定义配额(user=user1,client-id=clientA):
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' --entity-type users --entity-name user1 --entity-type clients --entity-name clientA
Updated config for entity: user-principal 'user1', client-id 'clientA'.
为 user=user1 配置自定义配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' --entity-type users --entity-name user1
Updated config for entity: user-principal 'user1'.
为 client-id=clientA 配置自定义配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' --entity-type clients --entity-name clientA
Updated config for entity: client-id 'clientA'.
通过指定 --entity-default 选项而不是--entity-name ,
可以为每个(用户、客户端 ID)、用户或客户端 ID 组设置默认配额。
为 user=userA 配置默认 client-id 配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' --entity-type users --entity-name user1 --entity-type clients --entity-default
Updated config for entity: user-principal 'user1', default client-id.
为用户配置默认配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' --entity-type users --entity-default
Updated config for entity: default user-principal.
配置 client-id 的默认配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' --entity-type clients --entity-default
Updated config for entity: default client-id.
以下是描述给定(用户、客户端 ID)的配额的方法:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-name user1 --entity-type clients --entity-name clientA
Configs for user-principal 'user1', client-id 'clientA' are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
描述给定用户的配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-name user1
Configs for user-principal 'user1' are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
描述给定客户端 ID 的配额:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type clients --entity-name clientA
Configs for client-id 'clientA' are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
如果未指定实体名称,则描述指定类型的所有实体。例如,描述所有用户:
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users
Configs for user-principal 'user1' are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
Configs for default user-principal are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
类似地对于(用户,客户端):
> bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type users --entity-type clients
Configs for user-principal 'user1', default client-id are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
Configs for user-principal 'user1', client-id 'clientA' are producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200
6.2 数据中心
某些部署需要管理跨越多个数据中心的数据管道。我们推荐的方法是在每个数据中心部署一个本地 Kafka 集群,每个数据中心中的应用程序实例仅与其本地集群交互并在集群之间镜像数据(有关如何执行此操作的信息, 请参阅异地复制文档)。这种部署模式允许数据中心充当独立实体,并允许我们集中管理和调整数据中心间的复制。即使数据中心间链路不可用,这也允许每个设施独立运行:当发生这种情况时,镜像会落后,直到链路恢复,此时它会赶上。
对于需要所有数据的全局视图的应用程序,您可以使用镜像来提供具有从所有数据中心的本地集群镜像的聚合数据的集群。这些聚合集群用于由需要完整数据集的应用程序进行读取。
这不是唯一可能的部署模式。可以通过 WAN 读取或写入远程 Kafka 集群,但显然这会增加获取集群所需的延迟。
Kafka 自然地在生产者和消费者中对数据进行批处理,因此即使在高延迟连接下也能实现高吞吐量。为了实现这一点,可能需要使用socket.send.buffer.bytes
和socket.receive.buffer.bytes
配置来增加生产者、消费者和代理的 TCP 套接字缓冲区大小。此处记录了设置此值的适当方法。
通常不建议通过高延迟链路运行跨多个数据中心的单个Kafka 集群。这将导致 Kafka 写入和 ZooKeeper 写入产生非常高的复制延迟,并且如果位置之间的网络不可用,Kafka 和 ZooKeeper 都不会在所有位置保持可用。
6.3 异地复制(跨集群数据镜像)
异地复制概述
Kafka 管理员可以定义跨越各个 Kafka 集群、数据中心或地理区域边界的数据流。组织、技术或法律要求通常需要此类事件流设置。常见场景包括:
- 异地复制
- 灾难恢复
- 将边缘集群馈送到中央聚合集群
- 集群的物理隔离(例如生产与测试)
- 云迁移或混合云部署
- 法律和合规要求
管理员可以使用 Kafka 的 MirrorMaker(版本 2)设置此类集群间数据流,这是一种以流式传输方式在不同 Kafka 环境之间复制数据的工具。MirrorMaker 构建在 Kafka Connect 框架之上,支持以下功能:
- 复制主题(数据加配置)
- 复制消费者组,包括在集群之间迁移应用程序的偏移量
- 复制 ACL
- 保留分区
- 自动检测新主题和分区
- 提供广泛的指标,例如跨多个数据中心/集群的端到端复制延迟
- 容错和水平可扩展的操作
注意:使用 MirrorMaker 进行异地复制可跨 Kafka 集群复制数据。这种集群间复制与 Kafka 的集群内复制不同,后者在同一个 Kafka 集群内复制数据。
什么是复制流
借助 MirrorMaker,Kafka 管理员可以将主题、主题配置、消费者组及其偏移量以及 ACL 从一个或多个源 Kafka 集群复制到一个或多个目标 Kafka 集群,即跨集群环境。简而言之,MirrorMaker 使用连接器从源集群进行消费并生产到目标集群。
这些从源集群到目标集群的定向流称为复制流。它们是使用 MirrorMaker 配置文件中的格式定义的,{source_cluster}->{target_cluster}
如下所述。管理员可以根据这些流程创建复杂的复制拓扑。
以下是一些示例模式:
- 主动/主动高可用性部署:
A->B, B->A
- 主动/被动或主动/备用高可用性部署:
A->B
- 聚合(例如,从多个集群到一个集群):
A->K, B->K, C->K
- 扇出(例如,从一个集群到多个集群):
K->A, K->B, K->C
- 转发:
A->B, B->C, C->D
默认情况下,流会复制所有主题和使用者组(排除的主题和使用者组除外)。但是,每个复制流都可以独立配置。例如,您可以定义仅将特定主题或消费者组从源集群复制到目标集群。
以下是有关如何配置从primary
集群到secondary
集群的数据复制(主动/被动设置)的第一个示例:
# Basic settings
clusters = primary, secondary
primary.bootstrap.servers = broker3-primary:9092
secondary.bootstrap.servers = broker5-secondary:9092
# Define replication flows
primary->secondary.enabled = true
primary->secondary.topics = foobar-topic, quux-.*
配置异地复制
以下部分介绍如何配置和运行专用 MirrorMaker 集群。如果您想在现有 Kafka Connect 集群或其他支持的部署设置中运行 MirrorMaker,请参阅KIP-382:MirrorMaker 2.0,并注意配置设置的名称可能因部署模式而异。
除了以下部分中介绍的内容之外,有关配置设置的更多示例和信息可在以下位置找到:
- MirrorMakerConfig , MirrorConnectorConfig
- DefaultTopicFilter用于主题,DefaultGroupFilter用于消费者组
- connect-mirror-maker.properties中的配置设置示例,KIP-382:MirrorMaker 2.0
配置文件语法
MirrorMaker 配置文件通常命名为connect-mirror-maker.properties
. 您可以在此文件中配置各种组件:
- MirrorMaker 设置:全局设置,包括集群定义(别名)以及每个复制流的自定义设置
- Kafka Connect 和连接器设置
- Kafka 生产者、消费者和管理客户端设置
示例:定义 MirrorMaker 设置(稍后详细说明)。
# Global settings
clusters = us-west, us-east # defines cluster aliases
us-west.bootstrap.servers = broker3-west:9092
us-east.bootstrap.servers = broker5-east:9092
topics = .* # all topics to be replicated by default
# Specific replication flow settings (here: flow from us-west to us-east)
us-west->us-east.enabled = true
us-west->us.east.topics = foo.*, bar.* # override the default above
MirrorMaker 基于 Kafka Connect 框架。Kafka Connect 文档章节中描述的任何 Kafka Connect、源连接器和接收器连接器设置都可以直接在 MirrorMaker 配置中使用,而无需更改配置设置的名称或为其添加前缀。
示例:定义 MirrorMaker 使用的自定义 Kafka Connect 设置。
# Setting Kafka Connect defaults for MirrorMaker
tasks.max = 5
大多数默认的 Kafka Connect 设置对于开箱即用的 MirrorMaker 都能很好地工作,但tasks.max
. 为了在多个 MirrorMaker 进程之间均匀分配工作负载,建议根据可用硬件资源和要复制的主题分区总数
设置tasks.max
为至少(最好更高)。2
您可以进一步自定义每个源或目标集群
的 MirrorMaker 的 Kafka Connect 设置(更准确地说,您可以“每个连接器”指定 Kafka Connect 工作线程级别的配置设置)。{cluster}.{config_name}
使用MirrorMaker 配置文件中
的格式。
示例:为us-west
集群定义自定义连接器设置。
# us-west custom settings
us-west.offset.storage.topic = my-mirrormaker-offsets
MirrorMaker 内部使用 Kafka 生产者、消费者和管理客户端。通常需要为这些客户端进行自定义设置。要覆盖默认值,请在 MirrorMaker 配置文件中使用以下格式:
{source}.consumer.{consumer_config_name}
{target}.producer.{producer_config_name}
{source_or_target}.admin.{admin_config_name}
示例:定义自定义生产者、消费者、管理客户端设置。
# us-west cluster (from which to consume)
us-west.consumer.isolation.level = read_committed
us-west.admin.bootstrap.servers = broker57-primary:9092
# us-east cluster (to which to produce)
us-east.producer.compression.type = gzip
us-east.producer.buffer.memory = 32768
us-east.admin.bootstrap.servers = broker8-secondary:9092
正好一次
从版本 3.5.0 开始,专用 MirrorMaker 集群支持 Exactly-once 语义。
对于新的 MirrorMaker 集群,将该exactly.once.source.support
属性设置为启用所有应使用一次性语义写入的目标 Kafka 集群。例如,要启用对集群 us-east 的写入一次,可以使用以下配置:
us-east.exactly.once.source.support = enabled
对于现有的 MirrorMaker 集群,需要进行两步升级。不要立即将该exactly.once.source.support
属性设置为启用,而是首先preparing
在集群中的所有节点上将其设置为启用。完成此操作后,可以在第二轮重新启动时将其设置为在集群中的所有节点上启用。
无论哪种情况,都需要在 MirrorMaker 节点之间启用集群内通信,如 KIP-710中所述。为此,dedicated.mode.enable.internal.rest
必须将该属性设置为true
。此外,许多 可用于 Kafka Connect 的 REST 相关配置属性都可以在 MirrorMaker 配置中指定。例如,要在 MirrorMaker 集群中启用集群内通信,并且每个节点都侦听其本地计算机的端口 8080,应将以下内容添加到 MirrorMaker 配置文件中:
dedicated.mode.enable.internal.rest = true
listeners = http://localhost:8080
请注意,如果在生产环境中启用了集群内通信,则强烈建议保护每个 MirrorMaker 节点启动的 REST 服务器。有关如何实现此目的的信息, 请参阅Kafka Connect 的配置属性。
还建议在运行 MirrorMaker 时从复制数据中过滤掉来自已中止事务的记录。为此,请确保用于从源集群读取的使用者配置为isolation.level
set to read_committed
。如果从 cluster 复制数据us-west
,则可以通过将以下内容添加到 MirrorMaker 配置文件来对从该集群读取的所有复制流完成此操作:
us-west.consumer.isolation.level = read_committed
最后一点,在幕后,MirrorMaker 使用 Kafka Connect 源连接器来复制数据。有关此类连接器的一次性支持的更多信息,请参阅相关文档页面。
创建和启用复制流
要定义复制流,您必须首先在 MirrorMaker 配置文件中定义相应的源和目标 Kafka 集群。
clusters
(必需):以逗号分隔的 Kafka 集群“别名”列表{clusterAlias}.bootstrap.servers
(必填):特定集群的连接信息;“引导”Kafka 经纪人的逗号分隔列表
示例:定义两个集群别名primary
和secondary
,包括它们的连接信息。
clusters = primary, secondary
primary.bootstrap.servers = broker10-primary:9092,broker-11-primary:9092
secondary.bootstrap.servers = broker5-secondary:9092,broker6-secondary:9092
{source}->{target}.enabled = true
其次,您必须根据需要
显式启用各个复制流。请记住,流是定向的:如果需要双向(双向)复制,则必须启用两个方向的流。
# Enable replication from primary to secondary
primary->secondary.enabled = true
默认情况下,复制流会将除少数特殊主题和使用者组之外的所有内容从源集群复制到目标集群,并自动检测任何新创建的主题和组。目标集群中复制主题的名称将以源集群的名称为前缀(请参阅下面的进一步部分)。例如,foo
源集群中的主题将被复制到目标集群中us-west
命名的主题。
us-west.foo
us-east
后续部分解释如何根据您的需要自定义此基本设置。
配置复制流
复制流的配置是顶级默认设置(例如topics
)的组合,在其之上应用特定于流的设置(如果有)(例如us-west->us-east.topics
)。要更改顶级默认设置,请将相应的顶级设置添加到 MirrorMaker 配置文件中。要仅覆盖特定复制流的默认值,请使用语法 format {source}->{target}.{config.name}
。
最重要的设置是:
topics
:主题列表或正则表达式,定义源集群中要复制的主题(默认值topics = .*
:)topics.exclude
:主题列表或正则表达式,用于随后排除与设置匹配的主题topics
(默认值topics.exclude = .*[\-\.]internal, .*\.replica, __.*
:)groups
:主题或正则表达式列表,定义源集群中要复制的消费者组(默认值groups = .*
:)groups.exclude
:主题列表或正则表达式,用于随后排除与设置匹配的消费者组groups
(默认值groups.exclude = console-consumer-.*, connect-.*, __.*
:){source}->{target}.enable
:设置true
为启用复制流(默认值false
:)
例子:
# Custom top-level defaults that apply to all replication flows
topics = .*
groups = consumer-group1, consumer-group2
# Don't forget to enable a flow!
us-west->us-east.enabled = true
# Custom settings for specific replication flows
us-west->us-east.topics = foo.*
us-west->us-east.groups = bar.*
us-west->us-east.emit.heartbeats = false
支持其他配置设置,在大多数情况下可以保留其默认值。请参阅MirrorMaker 配置。
保护复制流
MirrorMaker 支持与 Kafka Connect 相同的安全设置,因此请参阅链接部分以获取更多信息。
示例:加密 MirrorMaker 与us-east
集群之间的通信。
us-east.security.protocol=SSL
us-east.ssl.truststore.location=/path/to/truststore.jks
us-east.ssl.truststore.password=my-secret-password
us-east.ssl.keystore.location=/path/to/keystore.jks
us-east.ssl.keystore.password=my-secret-password
us-east.ssl.key.password=my-secret-password
目标集群中复制主题的自定义命名
目标集群中的复制主题(有时称为远程主题)根据复制策略进行重命名。MirrorMaker 使用此策略来确保来自不同集群的事件(也称为记录、消息)不会写入同一主题分区。默认情况下,根据DefaultReplicationPolicy,目标集群中复制主题的名称采用以下格式{source}.{source_topic_name}
:
us-west us-east
========= =================
bar-topic
foo-topic --> us-west.foo-topic
您可以使用以下设置自定义分隔符(默认:.
)replication.policy.separator
:
# Defining a custom separator
us-west->us-east.replication.policy.separator = _
如果您需要进一步控制复制主题的命名方式,您可以在 MirrorMaker 配置中
实现自定义ReplicationPolicy
并覆盖replication.policy.class
(默认为)。DefaultReplicationPolicy
防止配置冲突
MirrorMaker 进程通过其目标 Kafka 集群共享配置。当针对同一目标集群运行的 MirrorMaker 进程之间的配置不同时,此行为可能会导致冲突。
例如,以下两个 MirrorMaker 进程将是活泼的:
# Configuration of process 1
A->B.enabled = true
A->B.topics = foo
# Configuration of process 2
A->B.enabled = true
A->B.topics = bar
在这种情况下,两个进程将通过 cluster 共享配置B
,这会导致冲突。根据两个进程中的哪一个被选举为“领导者”,结果将是主题foo
或主题bar
被复制,但不会同时复制。
因此,在同一目标集群的复制流中保持 MirrorMaker 配置一致非常重要。例如,这可以通过自动化工具或为整个组织使用单个共享的 MirrorMaker 配置文件来实现。
最佳实践:从远程消费,生产到本地
为了最大限度地减少延迟(“生产者滞后”),建议将 MirrorMaker 进程放置在尽可能靠近其目标集群(即它向其生成数据的集群)的位置。这是因为 Kafka 生产者通常比 Kafka 消费者更容易遇到不可靠或高延迟的网络连接。
First DC Second DC
========== =========================
primary --------- MirrorMaker --> secondary
(remote) (local)
要运行这样的“从远程使用,生成到本地”设置,请在靠近目标集群且最好在与目标集群相同的位置运行 MirrorMaker 进程,并在命令行参数(空白分隔列表)中显式设置这些“本地”--clusters
集群集群别名):
# Run in secondary's data center, reading from the remote `primary` cluster
$ ./bin/connect-mirror-maker.sh connect-mirror-maker.properties --clusters secondary
它--clusters secondary
告诉 MirrorMaker 进程给定的集群位于附近,并阻止其复制数据或将配置发送到其他远程位置的集群。
示例:主动/被动高可用性部署
以下示例显示了将主题从主 Kafka 环境复制到辅助 Kafka 环境的基本设置,但不从辅助 Kafka 环境复制回主环境。请注意,大多数生产设置都需要进一步配置,例如安全设置。
# Unidirectional flow (one-way) from primary to secondary cluster
primary.bootstrap.servers = broker1-primary:9092
secondary.bootstrap.servers = broker2-secondary:9092
primary->secondary.enabled = true
secondary->primary.enabled = false
primary->secondary.topics = foo.* # only replicate some topics
示例:主动/主动高可用性部署
以下示例显示了以两种方式在两个集群之间复制主题的基本设置。请注意,大多数生产设置都需要进一步配置,例如安全设置。
# Bidirectional flow (two-way) between us-west and us-east clusters
clusters = us-west, us-east
us-west.bootstrap.servers = broker1-west:9092,broker2-west:9092
Us-east.bootstrap.servers = broker3-east:9092,broker4-east:9092
us-west->us-east.enabled = true
us-east->us-west.enabled = true
关于防止复制“循环”的注意事项(其中主题最初从 A 复制到 B,然后复制的主题将再次从 B 复制到 A,依此类推):只要您在同一个 MirrorMaker 中定义上述流程配置文件中,您不需要显式添加topics.exclude
设置来防止两个集群之间的复制循环。
示例:多集群异地复制
让我们将前面部分中的所有信息放在一个更大的示例中。想象一下,有三个数据中心(西、东、北),每个数据中心有两个 Kafka 集群(例如 、west-1
)west-2
。本节中的示例显示如何配置 MirrorMaker (1) 以实现每个数据中心内的主动/主动复制,以及 (2) 跨数据中心复制 (XDCR)。
首先,在配置中定义源集群和目标集群及其复制流:
# Basic settings
clusters: west-1, west-2, east-1, east-2, north-1, north-2
west-1.bootstrap.servers = ...
west-2.bootstrap.servers = ...
east-1.bootstrap.servers = ...
east-2.bootstrap.servers = ...
north-1.bootstrap.servers = ...
north-2.bootstrap.servers = ...
# Replication flows for Active/Active in West DC
west-1->west-2.enabled = true
west-2->west-1.enabled = true
# Replication flows for Active/Active in East DC
east-1->east-2.enabled = true
east-2->east-1.enabled = true
# Replication flows for Active/Active in North DC
north-1->north-2.enabled = true
north-2->north-1.enabled = true
# Replication flows for XDCR via west-1, east-1, north-1
west-1->east-1.enabled = true
west-1->north-1.enabled = true
east-1->west-1.enabled = true
east-1->north-1.enabled = true
north-1->west-1.enabled = true
north-1->east-1.enabled = true
然后,在每个数据中心中,启动一个或多个 MirrorMaker,如下所示:
# In West DC:
$ ./bin/connect-mirror-maker.sh connect-mirror-maker.properties --clusters west-1 west-2
# In East DC:
$ ./bin/connect-mirror-maker.sh connect-mirror-maker.properties --clusters east-1 east-2
# In North DC:
$ ./bin/connect-mirror-maker.sh connect-mirror-maker.properties --clusters north-1 north-2
通过此配置,任何集群生成的记录都将在数据中心内复制,并跨到其他数据中心。通过提供--clusters
参数,我们确保每个 MirrorMaker 进程仅向附近的集群生成数据。
注意:--clusters
从技术上讲,此处不需要该参数。没有它,MirrorMaker 也能正常工作。但是,吞吐量可能会受到数据中心之间“生产者滞后”的影响,并且您可能会产生不必要的数据传输成本。
开始异地复制
您可以根据需要运行任意数量的 MirrorMaker 进程(例如:节点、服务器)。由于 MirrorMaker 基于 Kafka Connect,因此配置为复制相同 Kafka 集群的 MirrorMaker 进程在分布式设置中运行:它们将找到彼此、共享配置(请参阅下面的部分)、负载平衡其工作等等。例如,如果您想要提高复制流的吞吐量,一种选择是并行运行其他 MirrorMaker 进程。
要启动 MirrorMaker 进程,请运行以下命令:
$ ./bin/connect-mirror-maker.sh connect-mirror-maker.properties
启动后,MirrorMaker 进程可能需要几分钟时间才开始复制数据。
或者,如前所述,您可以设置参数--clusters
以确保 MirrorMaker 进程仅向附近的集群生成数据。
# Note: The cluster alias us-west must be defined in the configuration file
$ ./bin/connect-mirror-maker.sh connect-mirror-maker.properties \
--clusters us-west
测试使用者组复制时请注意:默认情况下,MirrorMaker 不会复制该 kafka-console-consumer.sh
工具创建的使用者组,您可以使用该工具在命令行上测试 MirrorMaker 设置。如果您确实也想复制这些使用者组,请groups.exclude
相应地设置配置(默认值:)groups.exclude = console-consumer-.*, connect-.*, __.*
。请记住在完成测试后再次更新配置。
停止异地复制
您可以通过使用以下命令发送 SIGTERM 信号来停止正在运行的 MirrorMaker 进程:
$ kill <MirrorMaker pid>
应用配置更改
要使配置更改生效,必须重新启动 MirrorMaker 进程。
监控异地复制
建议监控 MirrorMaker 进程,以确保所有定义的复制流程均正常启动并运行。MirrorMaker 基于 Connect 框架构建,并继承了 Connect 的所有指标,例如source-record-poll-rate
. 此外,MirrorMaker 在kafka.connect.mirror
指标组下生成自己的指标。指标带有以下属性标记:
source
:源集群的别名(例如,primary
)target
:目标集群的别名(例如,secondary
)topic
:目标集群上的复制主题partition
:正在复制的分区
跟踪每个复制主题的指标。可以从主题名称推断出源集群。例如,复制topic1
将primary->secondary
产生如下指标:
target=secondary
topic=primary.topic1
partition=1
发出以下指标:
# MBean: kafka.connect.mirror:type=MirrorSourceConnector,target=([-.w]+),topic=([-.w]+),partition=([0-9]+)
record-count # number of records replicated source -> target
record-age-ms # age of records when they are replicated
record-age-ms-min
record-age-ms-max
record-age-ms-avg
replication-latency-ms # time it takes records to propagate source->target
replication-latency-ms-min
replication-latency-ms-max
replication-latency-ms-avg
byte-rate # average number of bytes/sec in replicated records
# MBean: kafka.connect.mirror:type=MirrorCheckpointConnector,source=([-.w]+),target=([-.w]+)
checkpoint-latency-ms # time it takes to replicate consumer offsets
checkpoint-latency-ms-min
checkpoint-latency-ms-max
checkpoint-latency-ms-avg
这些指标不区分创建时间和日志追加时间戳。
6.4 多租户
多租户概述
作为一个高度可扩展的事件流平台,Kafka 被许多用户用作他们的中枢神经系统,实时连接来自不同团队和业务线的各种不同系统和应用程序。这种多租户集群环境需要适当的控制和管理,以确保这些不同需求的和平共存。本节重点介绍设置此类共享环境的功能和最佳实践,这将帮助您操作满足 SLA/OLA 的集群,并最大限度地减少“吵闹的邻居”造成的潜在附带损害。
多租户是一个多方面的主题,包括但不限于:
- 为租户创建用户空间(有时称为命名空间)
- 使用数据保留策略等配置主题
- 通过加密、身份验证和授权来保护主题和集群
- 通过配额和费率限制隔离租户
- 监控与计量
- 集群间数据共享(参见异地复制)
使用主题命名为租户创建用户空间(命名空间)
操作多租户集群的 Kafka 管理员通常需要为每个租户定义用户空间。就本节而言,“用户空间”是主题的集合,这些主题在单个实体或用户的管理下组合在一起。
在Kafka中,数据的主要单位是主题。用户可以创建并命名每个主题。他们也可以删除它们,但无法直接重命名主题。相反,要重命名主题,用户必须创建新主题,将消息从原始主题移动到新主题,然后删除原始主题。考虑到这一点,建议基于分层主题命名结构来定义逻辑空间。然后,此设置可以与安全功能(例如前缀 ACL)相结合,以隔离不同的空间和租户,同时最大限度地减少保护集群中数据的管理开销。
这些逻辑用户空间可以通过不同的方式进行分组,具体选择取决于您的组织更喜欢如何使用 Kafka 集群。最常见的分组如下。
按团队或组织单位:在这里,团队是主要的聚合者。在团队是 Kafka 基础设施主要用户的组织中,这可能是最好的分组。
主题命名结构示例:
<organization>.<team>.<dataset>.<event-name>
(例如,“acme.infosec.telemetry.logins”)
按项目或产品:在这里,一个团队管理多个项目。每个项目的凭据都不同,因此所有控件和设置将始终与项目相关。
主题命名结构示例:
<project>.<product>.<event-name>
(例如,“移动性.付款.可疑”)
某些信息通常不应放在主题名称中,例如可能随时间变化的信息(例如,目标消费者的名称)或者是其他地方可用的技术细节或元数据(例如,主题的分区)计数和其他配置设置)。
要强制实施主题命名结构,可以使用以下几个选项:
- 使用前缀 ACL(参见KIP-290)强制主题名称使用公共前缀。例如,团队 A 可能只被允许创建名称以 开头的主题
payments.teamA.
。 - 定义自定义
CreateTopicPolicy
(参见KIP-108和设置create.topic.policy.class.name)以强制执行严格的命名模式。这些策略提供了最大的灵活性,并且可以涵盖复杂的模式和规则来满足组织的需求。 - 通过使用 ACL 拒绝普通用户禁用主题创建,然后依靠外部进程代表用户创建主题(例如,脚本或您最喜欢的自动化工具包)。
auto.create.topics.enable=false
通过在代理配置中进行设置来禁用 Kafka 功能以按需自动创建主题也可能很有用。请注意,您不应仅仅依赖此选项。
配置主题:数据保留等
Kafka 的配置由于其精细的粒度而非常灵活,并且它支持大量的按主题配置设置,以帮助管理员设置多租户集群。例如,管理员通常需要定义数据保留策略,以控制数据在主题中存储的数量和/或多长时间,并使用诸如retention.bytes(大小)和retention.ms(时间)等设置。这限制了集群内的存储消耗,并有助于遵守 GDPR 等法律要求。
保护集群和主题:身份验证、授权、加密
由于该文档有专门的一章介绍适用于任何 Kafka 部署的安全性,因此本节重点介绍多租户环境的其他注意事项。
Kafka 的安全设置分为三个主要类别,这与管理员保护其他客户端-服务器数据系统(如关系数据库和传统消息系统)的方式类似。
- 对 Kafka 代理和 Kafka 客户端之间、代理之间、代理和 ZooKeeper 节点之间以及代理和其他可选工具之间传输的数据进行加密。
- 对从 Kafka 客户端和应用程序到 Kafka 代理的连接以及从 Kafka 代理到 ZooKeeper 节点的连接进行身份验证。
- 对主题的创建、删除、更改配置等客户端操作的授权;将事件写入主题或从主题读取事件;创建和删除 ACL。管理员还可以定义自定义策略以实施其他限制,例如 and
CreateTopicPolicy
(AlterConfigPolicy
请参阅KIP-108和设置create.topic.policy.class.name、alter.config.policy.class.name)。
当保护多租户 Kafka 环境时,最常见的管理任务是第三类(授权),即管理用户/客户端权限,授予或拒绝对某些主题的访问,从而授予或拒绝对集群内用户存储的数据的访问。该任务主要通过访问控制列表(ACL)的设置来执行。在这里,多租户环境的管理员特别受益于将分层主题命名结构放在适当的位置(如上一节所述),因为他们可以通过带前缀的 ACL ( ) 方便地控制对主题的访问--resource-pattern-type Prefixed
。这大大减少了多租户环境中保护主题的管理开销:管理员可以在更高的开发便利性(更宽松的权限,使用更少和更广泛的 ACL)与更严格的安全性(更严格的权限,使用更多和更广泛的 ACL)之间进行权衡。更窄的 ACL)。
在以下示例中,用户 Alice(ACME 公司 InfoSec 团队的新成员)被授予对名称以“acme.infosec.”开头的所有主题的写权限,例如“acme.infosec.telemetry.logins”和“acme.infosec.logins”。 infosec.syslogs.events”。
# Grant permissions to user Alice
$ bin/kafka-acls.sh \
--bootstrap-server broker1:9092 \
--add --allow-principal User:Alice \
--producer \
--resource-pattern-type prefixed --topic acme.infosec.
您可以类似地使用此方法来隔离同一共享集群上的不同客户。
隔离租户:配额、速率限制、限制
多租户集群通常应配置配额,以防止用户(租户)占用过多集群资源,例如当他们尝试写入或读取大量数据时,或以过高的速率向代理创建请求时。这可能会导致网络饱和、垄断代理资源并影响其他客户端——所有这些都是您希望在共享环境中避免的。
客户端配额: Kafka 支持不同类型的(每用户主体)客户端配额。由于客户端的配额与客户端写入或读取哪个主题无关,因此它们是在多租户集群中分配资源的便捷且有效的工具。例如,请求速率配额通过限制代理在该用户的请求处理路径上花费的时间来帮助限制用户对代理 CPU 使用率的影响,之后就会开始限制。在许多情况下,使用请求速率配额来隔离用户在多租户集群中,比设置传入/传出网络带宽配额的影响更大,因为处理请求时过多使用代理 CPU 会降低代理可以提供的有效带宽。此外,管理员还可以定义主题操作的配额(例如创建、删除和更改),以防止 Kafka 集群因高并发主题操作而不堪重负(请参阅KIP-599和配额类型controller_mutation_rate
)。
服务器配额: Kafka还支持不同类型的broker端配额。例如,管理员可以设置代理接受新连接的速率限制、设置每个代理的最大连接数,或设置允许来自特定 IP 地址的最大连接数。
监控与计量
监控是一个更广泛的主题,在文档的其他部分中有介绍。任何 Kafka 环境(尤其是多租户环境)的管理员都应根据这些说明设置监控。Kafka 支持广泛的指标,例如身份验证尝试失败率、请求延迟、消费者滞后、消费者组总数、上一节中描述的配额指标等等。
例如,可以将监控配置为跟踪主题分区的大小(使用 JMX 指标kafka.log.Log.Size.<TOPIC-NAME>
),从而跟踪主题中存储的数据的总大小。然后,您可以定义当共享集群上的租户即将使用过多存储空间时发出的警报。
多租户和地理复制
Kafka 允许您跨不同集群共享数据,这些集群可能位于不同的地理区域、数据中心等。除了灾难恢复等用例之外,当多租户设置需要集群间数据共享时,此功能非常有用。有关详细信息, 请参阅异地复制(跨集群数据镜像)部分。
进一步的考虑
数据契约:您可能需要使用事件模式在集群中的数据生产者和消费者之间定义数据契约。这确保写入 Kafka 的事件始终可以再次正确读取,并防止写入格式错误或损坏的事件。实现此目标的最佳方法是与集群一起部署所谓的模式注册表。(Kafka 不包含模式注册表,但有可用的第三方实现。)模式注册表管理事件模式并将模式映射到主题,以便生产者知道哪些主题正在接受哪些类型(模式)的事件,以及消费者知道如何读取和解析主题中的事件。一些注册表实现提供了更多功能,例如架构演变、存储所有架构的历史记录以及架构兼容性设置。
6.5 Kafka配置
重要的客户端配置
最重要的生产者配置是:- 确认
- 压缩
- 批量大小
所有配置都记录在配置部分中。
生产服务器配置
以下是生产服务器配置示例: # ZooKeeper
zookeeper.connect=[list of ZooKeeper servers]
# Log configuration
num.partitions=8
default.replication.factor=3
log.dir=[List of directories. Kafka should have its own dedicated disk(s) or SSD(s).]
# Other configurations
broker.id=[An integer. Start with 0 and increment by 1 for each new broker.]
listeners=[list of listeners]
auto.create.topics.enable=false
min.insync.replicas=2
queued.max.requests=[number of concurrent requests]
我们的客户端配置在不同的用例之间存在很大差异。
6.6 Java版本
支持 Java 8、Java 11 和 Java 17。请注意,自 Apache Kafka 3.0 起,Java 8 支持已被弃用,并将在 Apache Kafka 4.0 中删除。如果启用 TLS,Java 11 及更高版本的性能会显着提高,因此强烈推荐它们(它们还包括许多其他性能改进:G1GC、CRC32C、紧凑字符串、线程本地握手等)。从安全角度来看,我们推荐最新发布的补丁版本,因为旧的免费版本已披露了安全漏洞。使用基于 OpenJDK 的 Java 实现(包括 Oracle JDK)运行 Kafka 的典型参数是: -Xmx6g -Xms6g -XX:MetaspaceSize=96m -XX:+UseG1GC
-XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:G1HeapRegionSize=16M
-XX:MinMetaspaceFreeRatio=50 -XX:MaxMetaspaceFreeRatio=80 -XX:+ExplicitGCInvokesConcurrent
作为参考,以下是使用上述 Java 参数的 LinkedIn 最繁忙集群之一(高峰期)的统计数据:
- 60 名经纪人
- 50k 分区(复制因子 2)
- 800k 消息/秒
- 入站 300 MB/秒,出站 1 GB/秒以上
6.7 硬件和操作系统
我们使用具有 24GB 内存的双四核 Intel Xeon 机器。您需要足够的内存来缓冲活动的读取器和写入器。您可以通过假设您希望能够缓冲 30 秒并将内存需求计算为 write_throughput*30 来对内存需求进行粗略估计。
磁盘吞吐量很重要。我们有 8x7200 rpm SATA 驱动器。一般来说磁盘吞吐量是性能瓶颈,磁盘越多越好。根据您配置刷新行为的方式,您可能会也可能不会从更昂贵的磁盘中受益(如果您经常强制刷新,那么更高 RPM 的 SAS 驱动器可能会更好)。
操作系统
Kafka应该可以在任何unix系统上运行良好,并且已经在Linux和Solaris上进行了测试。我们发现在 Windows 上运行时存在一些问题,并且 Windows 目前不是一个得到良好支持的平台,但我们很乐意对此进行更改。
它不太可能需要太多操作系统级别的调整,但存在三个潜在重要的操作系统级别配置:
- 文件描述符限制:Kafka 使用文件描述符来表示日志段和打开的连接。如果代理托管许多分区,请考虑代理除了代理建立的连接数之外,还至少需要 (number_of_partitions)*(partition_size/segment_size) 来跟踪所有日志段。我们建议代理进程至少使用 100000 个允许的文件描述符作为起点。注意:mmap() 函数添加对与文件描述符 fildes 关联的文件的额外引用,该文件描述符上的后续 close() 不会删除该引用。当不再有到该文件的映射时,该引用将被删除。
- 最大套接字缓冲区大小:可以增加以实现数据中心之间的高性能数据传输,如此处所述。
- 进程可以拥有的内存映射区域的最大数量(也称为 vm.max_map_count)。请参阅 Linux 内核文档。在考虑代理可能拥有的最大分区数时,您应该留意这个操作系统级别的属性。默认情况下,在许多 Linux 系统上,vm.max_map_count 的值约为 65535。每个分区分配的每个日志段都需要一对索引/时间索引文件,并且每个文件消耗 1 个映射区域。换句话说,每个日志段使用2个地图区域。因此,每个分区至少需要 2 个映射区域,只要它托管单个日志段即可。也就是说,在代理上创建 50000 个分区将导致分配 100000 个映射区域,并可能在具有默认 vm.max_map_count 的系统上导致代理崩溃并出现 OutOfMemoryError(映射失败)。请记住,每个分区的日志段数根据段大小、负载强度、保留策略而变化,并且通常往往不止一个。
磁盘和文件系统
我们建议使用多个驱动器来获得良好的吞吐量,并且不要与应用程序日志或其他操作系统文件系统活动共享用于 Kafka 数据的相同驱动器,以确保良好的延迟。您可以将这些驱动器一起 RAID 到单个卷中,也可以将每个驱动器格式化并安装为其自己的目录。由于 Kafka 具有复制功能,因此 RAID 提供的冗余也可以在应用程序级别提供。这种选择有几个权衡。如果配置多个数据目录,分区将循环分配给数据目录。每个分区将完全位于一个数据目录中。如果分区之间的数据没有很好地平衡,这可能会导致磁盘之间的负载不平衡。
RAID 在平衡磁盘之间的负载方面可能会做得更好(尽管看起来并不总是如此),因为它在较低级别上平衡负载。RAID 的主要缺点是它通常会严重影响写入吞吐量并减少可用磁盘空间。
RAID 的另一个潜在好处是能够容忍磁盘故障。然而,我们的经验是,重建 RAID 阵列的 I/O 密集程度很高,以至于它会有效地禁用服务器,因此这并不能提供太多真正的可用性改进。
应用程序与操作系统刷新管理
Kafka 总是立即将所有数据写入文件系统,并支持配置刷新策略的功能,该策略控制何时使用刷新将数据强制从操作系统缓存中取出并写入磁盘。可以控制此刷新策略,以在一段时间后或在写入一定数量的消息后强制将数据写入磁盘。此配置有多种选择。Kafka 最终必须调用 fsync 才能知道数据已刷新。当从任何未知的 fsync 日志段的崩溃中恢复时,Kafka 将通过检查其 CRC 来检查每条消息的完整性,并重建随附的偏移量索引文件,作为启动时执行的恢复过程的一部分。
请注意,Kafka 中的持久性不需要将数据同步到磁盘,因为故障节点始终会从其副本中恢复。
我们建议使用默认刷新设置,完全禁用应用程序 fsync。这意味着依赖操作系统完成的后台刷新和 Kafka 自己的后台刷新。这为大多数用途提供了最好的特性:无需调节旋钮、出色的吞吐量和延迟以及完全恢复保证。我们通常认为复制提供的保证比同步到本地磁盘更强,但是偏执者可能仍然更喜欢两者,并且仍然支持应用程序级 fsync 策略。
使用应用程序级别刷新设置的缺点是,它的磁盘使用模式效率较低(它给操作系统重新排序写入的余地较小),并且可能会引入延迟,因为大多数 Linux 文件系统中的 fsync 会阻止写入文件,而后台刷新执行更细粒度的页面级锁定。
一般来说,您不需要对文件系统进行任何低级调整,但在接下来的几节中,我们将讨论其中的一些内容,以防它有用。
了解 Linux 操作系统刷新行为
在 Linux 中,写入文件系统的数据保留在页面缓存中,直到必须将其写出到磁盘(由于应用程序级 fsync 或操作系统自身的刷新策略)。数据的刷新是由一组称为 pdflush 的后台线程(或在 2.6.32 后的内核中的“flusher 线程”)完成的。Pdflush 有一个可配置的策略,可以控制缓存中可以保留多少脏数据以及必须将其写回磁盘之前的时间。此处描述了该策略。当 Pdflush 无法跟上数据写入的速率时,最终会导致写入过程阻塞,从而产生写入延迟,从而减慢数据的积累。
您可以通过以下方式查看操作系统内存使用的当前状态
> cat /proc/meminfo这些值的含义在上面的链接中有描述。
与进程内缓存相比,使用页面缓存来存储将写出到磁盘的数据有几个优点:
- I/O 调度程序会将连续的小写入批量合并为更大的物理写入,从而提高吞吐量。
- I/O 调度程序将尝试重新排序写入,以最大限度地减少磁盘头的移动,从而提高吞吐量。
- 它会自动使用机器上的所有可用内存
文件系统选择
Kafka 使用磁盘上的常规文件,因此它对特定文件系统没有硬依赖。然而,使用最多的两个文件系统是 EXT4 和 XFS。从历史上看,EXT4 的使用量较多,但最近对 XFS 文件系统的改进表明,它对于 Kafka 工作负载具有更好的性能特征,且不影响稳定性。
使用各种文件系统创建和挂载选项,在具有大量消息负载的集群上执行比较测试。Kafka 中受监控的主要指标是“请求本地时间”,表示追加操作所花费的时间。XFS 带来了更好的本地时间(对于最佳 EXT4 配置,本地时间为 160 毫秒,而 250 毫秒以上),并且平均等待时间更短。XFS 性能还显示磁盘性能的变化较小。
一般文件系统注释
对于用于数据目录的任何文件系统,在 Linux 系统上,建议在挂载时使用以下选项:- noatime:此选项禁止在读取文件时更新文件的 atime(上次访问时间)属性。这可以消除大量的文件系统写入,特别是在引导消费者的情况下。Kafka 根本不依赖 atime 属性,因此禁用它是安全的。
XFS 注释
XFS 文件系统具有大量自动调整功能,因此无论是在文件系统创建时还是在挂载时,都不需要对默认设置进行任何更改。唯一值得考虑的调整参数是:- Largeio:这会影响 stat 调用报告的首选 I/O 大小。虽然这可以在较大的磁盘写入上实现更高的性能,但实际上它对性能的影响很小或没有影响。
- nobarrier:对于具有电池支持缓存的底层设备,此选项可以通过禁用定期写入刷新来提供更高的性能。但是,如果底层设备表现良好,它将向文件系统报告它不需要刷新,并且此选项将不起作用。
EXT4注释
EXT4 是 Kafka 数据目录的一个可用的文件系统选择,但是要充分利用它的性能需要调整多个安装选项。此外,这些选项在故障情况下通常是不安全的,并且会导致更多的数据丢失和损坏。对于单个代理故障,这并不是什么大问题,因为可以擦除磁盘并从集群重建副本。在多次故障的情况下,例如断电,这可能意味着底层文件系统(以及数据)损坏且难以恢复。可以调整以下选项:- data=writeback:Ext4 默认为 data=ordered,这对某些写入设置了强顺序。Kafka 不需要这种排序,因为它对所有未刷新的日志进行非常偏执的数据恢复。此设置消除了排序限制,并且似乎显着减少了延迟。
- 禁用日志记录:日志记录是一种权衡:它使服务器崩溃后重新启动速度更快,但它引入了大量额外的锁定,从而增加了写入性能的差异。那些不关心重新启动时间并希望减少写入延迟峰值的主要来源的人可以完全关闭日志记录。
- commit=num_secs:这会调整 ext4 提交其元数据日志的频率。将其设置为较低的值可以减少崩溃期间未刷新数据的丢失。将其设置为更高的值将提高吞吐量。
- nobh:此设置控制使用 data=writeback 模式时的附加排序保证。这对于 Kafka 来说应该是安全的,因为我们不依赖于写入顺序并提高了吞吐量和延迟。
- delalloc:延迟分配意味着文件系统在物理写入发生之前避免分配任何块。这允许 ext4 分配较大的范围而不是较小的页面,并有助于确保数据按顺序写入。此功能对于吞吐量非常有用。它似乎确实涉及文件系统中的一些锁定,这增加了一些延迟差异。
更换 KRaft 控制器磁盘
当 Kafka 配置为使用 KRaft 时,控制器将集群元数据存储在metadata.log.dir
-- 或第一个日志目录(如果metadata.log.dir
未配置)中指定的目录中。metadata.log.dir
有关详细信息,请参阅文档。
如果由于硬件故障或需要更换硬件而导致集群元数据目录中的数据丢失,则在配置新的控制节点时应小心。在大多数控制器拥有所有提交的数据之前,不应格式化并启动新的控制器节点。要确定大多数控制器是否具有已提交的数据,请运行该kafka-metadata-quorum.sh
工具来描述复制状态:
> bin/kafka-metadata-quorum.sh --bootstrap-server broker_host:port describe --replication
NodeId LogEndOffset Lag LastFetchTimestamp LastCaughtUpTimestamp Status
1 25806 0 1662500992757 1662500992757 Leader
... ... ... ... ... ...
检查并等待,直到Lag
对于大多数控制器来说都很小。如果领导者的结束偏移量没有增加,则可以等到滞后为 0 时才获得多数;否则,您可以选择最新的领导者末端偏移量并等待所有副本都到达它。检查并等待,直到大多数控制器的LastFetchTimestamp
和彼此接近。LastCaughtUpTimestamp
此时,格式化控制器的元数据日志目录会更安全。这可以通过运行命令来完成kafka-storage.sh
。
> bin/kafka-storage.sh format --cluster-id uuid --config server_properties
上面的命令可能bin/kafka-storage.sh format
会失败并显示类似 的消息Log directory ... is already formatted
。当使用组合模式并且仅丢失元数据日志目录而不丢失其他目录时,可能会发生这种情况。在这种情况下并且只有在这种情况下,您才能运行kafka-storage.sh format
带有该--ignore-formatted
选项的命令。
格式化日志目录后启动 KRaft 控制器。
> /bin/kafka-server-start.sh server_properties
6.8 监控
Kafka 使用 Yammer Metrics 在服务器中进行指标报告。Java 客户端使用 Kafka Metrics,这是一个内置指标注册表,可最大程度地减少客户端应用程序中的传递依赖性。两者都通过 JMX 公开指标,并且可以配置为使用可插入统计报告器报告统计信息以连接到您的监控系统。
所有 Kafka 速率指标都有一个相应的累积计数指标,后缀为-total
。例如,
records-consumed-rate
有一个名为 的相应指标records-consumed-total
。
查看可用指标的最简单方法是启动 jconsole 并将其指向正在运行的 kafka 客户端或服务器;这将允许使用 JMX 浏览所有指标。
使用 JMX 进行远程监控的安全注意事项
Apache Kafka 默认禁用远程 JMX。JMX_PORT
您可以通过为使用 CLI启动的进程设置环境变量或标准 Java 系统属性来以编程方式启用远程 JMX,从而使用 JMX 启用远程监控
。在生产场景中启用远程 JMX 时,您必须启用安全性,以确保未经授权的用户无法监视或控制您的代理或应用程序以及它们运行的平台。KAFKA_JMX_OPTS
请注意,默认情况下,Kafka 中的 JMX 身份验证处于禁用状态,并且必须通过为使用 CLI 启动的进程设置环境变量或设置适当的 Java 系统属性来覆盖生产部署的安全配置
。
有关保护 JMX 的详细信息,
请参阅
使用 JMX 技术进行监控和管理。我们对以下指标进行绘图和警报:
描述 | Mbean 名称 | 正常值 |
---|---|---|
Message in rate | kafka.server:类型=BrokerTopicMetrics,名称=MessagesInPerSec,主题=([-.\w]+) | 每个主题的传入消息率。省略“topic=(...)”将产生全主题率。 |
Byte in rate from clients | kafka.server:类型=BrokerTopicMetrics,名称=BytesInPerSec,主题=([-.\w]+) | 每个主题的字节输入(来自客户端)速率。省略“topic=(...)”将产生全主题率。 |
Byte in rate from other brokers | kafka.server:类型=BrokerTopicMetrics,名称=ReplicationBytesInPerSec | 字节(来自其他经纪人)所有主题的利率。 |
Controller Request rate from Broker | kafka.controller:类型=ControllerChannelManager,名称=RequestRateAndQueueTimeMs,brokerId=([0-9]+) | ControllerChannelManager 从给定代理的队列中获取请求的速率(每秒请求数)。以及请求在从队列中取出之前在此队列中停留的时间。 |
Controller Event queue size | kafka.controller:类型=ControllerEventManager,名称=EventQueueSize | ControllerEventManager 队列的大小。 |
Controller Event queue time | kafka.controller:类型=ControllerEventManager,名称=EventQueueTimeMs | 任何事件(Idle 事件除外)在处理之前在 ControllerEventManager 队列中等待所花费的时间 |
Request rate | kafka.network:类型=RequestMetrics,名称=RequestsPerSec,请求={Produce|FetchConsumer|FetchFollower},版本=([0-9]+) | |
Error rate | kafka.network:类型=RequestMetrics,名称=ErrorsPerSec,请求=([-.\w]+),错误=([-.\w]+) | 每个请求类型、每个错误代码计数的响应中的错误数。如果响应包含多个错误,则所有错误都会被计算在内。error=NONE 表示响应成功。 |
Produce request rate | kafka.server:类型=BrokerTopicMetrics,名称=TotalProduceRequestsPerSec,主题=([-.\w]+) | 生成每个主题的请求率。省略“topic=(...)”将产生全主题率。 |
Fetch request rate | kafka.server:类型=BrokerTopicMetrics,名称=TotalFetchRequestsPerSec,主题=([-.\w]+) | 获取每个主题的请求(来自客户或关注者)率。省略“topic=(...)”将产生全主题率。 |
Failed produce request rate | kafka.server:类型=BrokerTopicMetrics,名称=FailedProduceRequestsPerSec,主题=([-.\w]+) | 每个主题的生成请求率失败。省略“topic=(...)”将产生全主题率。 |
Failed fetch request rate | kafka.server:类型=BrokerTopicMetrics,名称=FailedFetchRequestsPerSec,主题=([-.\w]+) | 每个主题的失败获取请求(来自客户端或关注者)率。省略“topic=(...)”将产生全主题率。 |
Request size in bytes | kafka.network:类型=RequestMetrics,名称=RequestBytes,请求=([-.\w]+) | 每种请求类型的请求大小。 |
Temporary memory size in bytes | kafka.network:type=RequestMetrics,name=TemporaryMemoryBytes,request={Produce|Fetch} | 用于消息格式转换和解压缩的临时存储器。 |
Message conversion time | kafka.network:类型=RequestMetrics,名称=MessageConversionsTimeMs,请求={生产|获取} | 消息格式转换所花费的时间(以毫秒为单位)。 |
Message conversion rate | kafka.server:type=BrokerTopicMetrics,name={Produce|Fetch}MessageConversionsPerSec,topic=([-.\w]+) | 每个主题的 Produce 或 Fetch 请求的消息格式转换率。省略“topic=(...)”将产生全主题率。 |
Request Queue Size | kafka.network:类型=RequestChannel,名称=RequestQueueSize | 请求队列的大小。 |
Byte out rate to clients | kafka.server:类型=BrokerTopicMetrics,名称=BytesOutPerSec,主题=([-.\w]+) | 每个主题的字节输出(至客户端)速率。省略“topic=(...)”将产生全主题率。 |
Byte out rate to other brokers | kafka.server:类型=BrokerTopicMetrics,名称=ReplicationBytesOutPerSec | 所有主题的字节输出(至其他经纪商)率 |
Rejected byte rate | kafka.server:类型=BrokerTopicMetrics,名称=BytesRejectedPerSec,主题=([-.\w]+) | 由于记录批量大小大于 max.message.bytes 配置,每个主题被拒绝的字节率。省略“topic=(...)”将产生全主题率。 |
Message validation failure rate due to no key specified for compacted topic | kafka.server:类型=BrokerTopicMetrics,名称=NoKeyCompactedTopicRecordsPerSec | 0 |
Message validation failure rate due to invalid magic number | kafka.server:类型=BrokerTopicMetrics,名称=InvalidMagicNumberRecordsPerSec | 0 |
Message validation failure rate due to incorrect crc checksum | kafka.server:类型=BrokerTopicMetrics,名称=InvalidMessageCrcRecordsPerSec | 0 |
Message validation failure rate due to non-continuous offset or sequence number in batch | kafka.server:类型=BrokerTopicMetrics,名称=InvalidOffsetOrSequenceRecordsPerSec | 0 |
Log flush rate and time | kafka.log:类型=LogFlushStats,名称=LogFlushRateAndTimeMs | |
# of offline log directories | kafka.log:type=LogManager,name=OfflineLogDirectoryCount | 0 |
Leader election rate | kafka.controller:类型=ControllerStats,名称=LeaderElectionRateAndTimeMs | 当代理失败时非零 |
Unclean leader election rate | kafka.controller:类型=ControllerStats,名称=UncleanLeaderElectionsPerSec | 0 |
Is controller active on broker | kafka.controller:类型=KafkaController,名称=ActiveControllerCount | 集群中只有一个代理应该有 1 |
Pending topic deletes | kafka.controller:类型=KafkaController,名称=TopicsToDeleteCount | |
Pending replica deletes | kafka.controller:类型=KafkaController,名称=ReplicasToDeleteCount | |
Ineligible pending topic deletes | kafka.controller:类型= KafkaController,名称= TopicsIneligibleToDeleteCount | |
Ineligible pending replica deletes | kafka.controller:类型= KafkaController,名称= ReplicasIneligibleToDeleteCount | |
# of under replicated partitions (|ISR| < |all replicas|) | kafka.server:类型=ReplicaManager,名称=UnderReplicatedPartitions | 0 |
# of under minIsr partitions (|ISR| < min.insync.replicas) | kafka.server:type=ReplicaManager,name=UnderMinIsrPartitionCount | 0 |
# of at minIsr partitions (|ISR| = min.insync.replicas) | kafka.server:类型=ReplicaManager,名称=AtMinIsrPartitionCount | 0 |
Producer Id counts | kafka.server:类型=ReplicaManager,名称=ProducerIdCount | 代理上每个副本中事务性和幂等生产者创建的所有生产者 ID 的计数 |
Partition counts | kafka.server:类型=ReplicaManager,名称=PartitionCount | 大多数甚至跨经纪人 |
Offline Replica counts | kafka.server:类型=ReplicaManager,名称=OfflineReplicaCount | 0 |
Leader replica counts | kafka.server:类型=ReplicaManager,名称=LeaderCount | 大多数甚至跨经纪人 |
ISR shrink rate | kafka.server:类型=ReplicaManager,名称=IsrShrinksPerSec | 如果代理出现故障,某些分区的 ISR 将缩小。当该代理再次启动时,一旦副本完全赶上,ISR 将扩展。除此之外,ISR收缩率和扩张率的预期值为0。 |
ISR expansion rate | kafka.server:类型=ReplicaManager,名称=IsrExpandsPerSec | 往上看 |
Failed ISR update rate | kafka.server:类型=ReplicaManager,名称=FailedIsrUpdatesPerSec | 0 |
Max lag in messages btw follower and leader replicas | kafka.server:类型=ReplicaFetcherManager,名称=MaxLag,clientId=副本 | 滞后应与生产请求的最大批量大小成正比。 |
Lag in messages per follower replica | kafka.server:类型=FetcherLagMetrics,名称=ConsumerLag,clientId=([-.\w]+),主题=([-.\w]+),分区=([0-9]+) | 滞后应与生产请求的最大批量大小成正比。 |
Requests waiting in the producer purgatory | kafka.server:类型=DelayedOperationPurgatory,名称=PurgatorySize,delayedOperation=生产 | 如果使用 ack=-1,则非零 |
Requests waiting in the fetch purgatory | kafka.server:类型=DelayedOperationPurgatory,名称=PurgatorySize,delayedOperation=Fetch | 大小取决于消费者中的 fetch.wait.max.ms |
Request total time | kafka.network:type=RequestMetrics,name=TotalTimeMs,request={Produce|FetchConsumer|FetchFollower} | 分为队列、本地、远程和响应发送时间 |
Time the request waits in the request queue | kafka.network:类型=RequestMetrics,名称=RequestQueueTimeMs,请求={Produce|FetchConsumer|FetchFollower} | |
Time the request is processed at the leader | kafka.network:type=RequestMetrics,name=LocalTimeMs,request={Produce|FetchConsumer|FetchFollower} | |
Time the request waits for the follower | kafka.network:type=RequestMetrics,name=RemoteTimeMs,request={Produce|FetchConsumer|FetchFollower} | 当 ack=-1 时,生产请求非零 |
Time the request waits in the response queue | kafka.network:类型=RequestMetrics,名称=ResponseQueueTimeMs,请求={Produce|FetchConsumer|FetchFollower} | |
Time to send the response | kafka.network:类型=RequestMetrics,名称=ResponseSendTimeMs,请求={Produce|FetchConsumer|FetchFollower} | |
Number of messages the consumer lags behind the producer by. Published by the consumer, not broker. | kafka.consumer:type=consumer-fetch-manager-metrics,client-id={client-id} 属性:records-lag-max | |
The average fraction of time the network processors are idle | kafka.network:类型=SocketServer,名称=NetworkProcessorAvgIdlePercent | 0 到 1 之间,理想情况下 > 0.3 |
The number of connections disconnected on a processor due to a client not re-authenticating and then using the connection beyond its expiration time for anything other than re-authentication | kafka.server:类型 = 套接字服务器指标,监听器 = [SASL_PLAINTEXT | SASL_SSL],networkProcessor = <#>,名称 = 过期连接杀死计数 | 理想情况下,启用重新身份验证时为 0,这意味着不再有任何旧的 2.2.0 之前的客户端连接到此(侦听器、处理器)组合 |
The total number of connections disconnected, across all processors, due to a client not re-authenticating and then using the connection beyond its expiration time for anything other than re-authentication | kafka.network:type=SocketServer,name=ExpiredConnectionsKilledCount | 理想情况下,启用重新身份验证时为 0,这意味着不再有任何旧的、2.2.0 之前的客户端连接到该代理 |
The average fraction of time the request handler threads are idle | kafka.server:类型=KafkaRequestHandlerPool,名称=RequestHandlerAvgIdlePercent | 0 到 1 之间,理想情况下 > 0.3 |
Bandwidth quota metrics per (user, client-id), user or client-id | kafka.server:type={Produce|Fetch},user=([-.\w]+),client-id=([-.\w]+) | 两个属性。throttle-time 表示客户端被限制的时间(以毫秒为单位)。理想情况下 = 0。字节率表示客户端的数据生产/消费速率(以字节/秒为单位)。对于(用户、客户端 ID)配额,同时指定用户和客户端 ID。如果将 per-client-id 配额应用于客户端,则不指定用户。如果应用每用户配额,则不指定 client-id。 |
Request quota metrics per (user, client-id), user or client-id | kafka.server:类型=请求,用户=([-.\w]+),客户端id=([-.\w]+) | 两个属性。throttle-time 表示客户端被限制的时间(以毫秒为单位)。理想情况下 = 0。请求时间表示代理网络和 I/O 线程处理来自客户端组的请求所花费的时间百分比。对于(用户、客户端 ID)配额,同时指定用户和客户端 ID。如果将 per-client-id 配额应用于客户端,则不指定用户。如果应用每用户配额,则不指定 client-id。 |
Requests exempt from throttling | kafka.server:type=请求 | except-throttle-time 表示代理网络和 I/O 线程处理不受限制的请求所花费的时间百分比。 |
ZooKeeper client request latency | kafka.server:类型=ZooKeeperClientMetrics,名称=ZooKeeperRequestLatencyMs | 来自代理的 ZooKeeper 请求的延迟(以毫秒为单位)。 |
ZooKeeper connection status | kafka.server:类型=SessionExpireListener,名称=SessionState | 代理的 ZooKeeper 会话的连接状态,可能是 Disconnected|SyncConnected|AuthFailed|ConnectedReadOnly|SaslAuthenticated|Expired 之一。 |
Max time to load group metadata | kafka.server:类型=组协调器指标,名称=分区加载时间最大值 | 从最近 30 秒内加载的消费者偏移分区中加载偏移量和分组元数据所花费的最长时间,以毫秒为单位(包括等待调度加载任务所花费的时间) |
Avg time to load group metadata | kafka.server:类型=组协调器指标,名称=分区加载时间平均 | 从最近 30 秒内加载的消费者偏移分区中加载偏移量和分组元数据所花费的平均时间,以毫秒为单位(包括等待调度加载任务所花费的时间) |
Max time to load transaction metadata | kafka.server:类型=事务协调器指标,名称=分区加载时间最大值 | 从最近 30 秒内加载的消费者偏移分区加载事务元数据所花费的最长时间,以毫秒为单位(包括等待调度加载任务所花费的时间) |
Avg time to load transaction metadata | kafka.server:类型=事务协调器指标,名称=分区加载时间平均 | 从最近30秒内加载的消费者偏移分区加载事务元数据所花费的平均时间,以毫秒为单位(包括等待调度加载任务所花费的时间) |
Rate of transactional verification errors | kafka.server:类型=AddPartitionsToTxnManager,名称=VerificationFailureRate | 从 AddPartitionsToTxn API 响应或通过 AddPartitionsToTxnManager 中的错误返回失败的验证率。在稳定状态 0 中,但在事务状态分区的滚动和重新分配期间预计会出现暂时性错误。 |
Time to verify a transactional request | kafka.server:类型=AddPartitionsToTxnManager,名称=VerificationTimeMs | 先前可能的请求正在进行时的排队时间加上事务协调器验证(或不验证)的往返时间 |
Consumer Group Offset Count | kafka.server:类型=GroupMetadataManager,名称=NumOffsets | 消费者组承诺抵消总数 |
Consumer Group Count | kafka.server:类型=GroupMetadataManager,名称=NumGroups | 消费者群体总数 |
Consumer Group Count, per State | kafka.server:类型= GroupMetadataManager,名称= NumGroups [准备重新平衡,完成重新平衡,空,稳定,死] | 每个状态的Consumer Group数量:PreparingRebalance、CompletingRebalance、Empty、Stable、Dead |
Number of reassigning partitions | kafka.server:类型=ReplicaManager,名称=重新分配分区 | 代理上重新分配领导者分区的数量。 |
Outgoing byte rate of reassignment traffic | kafka.server:类型=BrokerTopicMetrics,名称=ReassignmentBytesOutPerSec | 0; 当分区重新分配正在进行时非零。 |
Incoming byte rate of reassignment traffic | kafka.server:类型=BrokerTopicMetrics,名称=ReassignmentBytesInPerSec | 0; 当分区重新分配正在进行时非零。 |
Size of a partition on disk (in bytes) | kafka.log:类型=日志,名称=大小,主题=([-.\w]+),分区=([0-9]+) | 磁盘上分区的大小,以字节为单位。 |
Number of log segments in a partition | kafka.log:类型=日志,名称=NumLogSegments,主题=([-.\w]+),分区=([0-9]+) | 分区中日志段的数量。 |
First offset in a partition | kafka.log:类型=日志,名称=LogStartOffset,主题=([-.\w]+),分区=([0-9]+) | 分区中的第一个偏移量。 |
Last offset in a partition | kafka.log:类型=日志,名称=LogEndOffset,主题=([-.\w]+),分区=([0-9]+) | 分区中的最后一个偏移量。 |
分层存储监控
以下一组指标可用于监控分层存储功能:指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
Remote Fetch Bytes Per Sec | 每个主题从远程存储读取的字节速率。省略“topic=(...)”将产生全主题率 | kafka.server:类型=BrokerTopicMetrics,名称=RemoteFetchBytesPerSec,主题=([-.\w]+) |
Remote Fetch Requests Per Sec | 每个主题从远程存储读取请求的速率。省略“topic=(...)”将产生全主题率 | kafka.server:类型=BrokerTopicMetrics,名称=RemoteFetchRequestsPerSec,主题=([-.\w]+) |
Remote Fetch Errors Per Sec | 每个主题的远程存储读取错误率。省略“topic=(...)”将产生全主题率 | kafka.server:类型=BrokerTopicMetrics,名称=RemoteFetchErrorsPerSec,主题=([-.\w]+) |
Remote Copy Bytes Per Sec | 每个主题复制到远程存储的字节速率。省略“topic=(...)”将产生全主题率 | kafka.server:类型=BrokerTopicMetrics,名称=RemoteCopyBytesPerSec,主题=([-.\w]+) |
Remote Copy Requests Per Sec | 每个主题对远程存储的写入请求率。省略“topic=(...)”将产生全主题率 | kafka.server:类型=BrokerTopicMetrics,名称=RemoteCopyRequestsPerSec,主题=([-.\w]+) |
Remote Copy Errors Per Sec | 每个主题的远程存储写入错误率。省略“topic=(...)”将产生全主题率 | kafka.server:类型=BrokerTopicMetrics,名称=RemoteCopyErrorsPerSec,主题=([-.\w]+) |
RemoteLogReader Task Queue Size | 保存远程存储读取任务的队列大小 | org.apache.kafka.storage.internals.log:类型=RemoteStorageThreadPool,名称=RemoteLogReaderTaskQueueSize |
RemoteLogReader Avg Idle Percent | 用于处理远程存储读取任务的线程池平均空闲百分比 | org.apache.kafka.storage.internals.log:类型=RemoteStorageThreadPool,名称=RemoteLogReaderAvgIdlePercent |
RemoteLogManager Tasks Avg Idle Percent | 用于将数据复制到远程存储的线程池的平均空闲百分比 | kafka.log.remote:类型=RemoteLogManager,名称=RemoteLogManagerTasksAvgIdlePercent |
Kraft 监控指标
允许监控 KRaft 仲裁和元数据日志的指标集。请注意,一些公开的指标取决于节点的角色,如
process.roles
KRaft 仲裁监控指标
这些指标在 KRaft 集群中的控制器和代理上报告指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
Current State | 该成员的当前状态;可能的值为领导者、候选人、投票者、追随者、独立者、观察者。 | kafka.server:type=raft-metrics,name=当前状态 |
Current Leader | 当前仲裁组领导者的 id;-1表示未知。 | kafka.server:type=raft-metrics,name=当前领导者 |
Current Voted | 当前投票领导者的 id;-1 表示没有投票给任何人。 | kafka.server:type=raft-metrics,name=当前投票 |
Current Epoch | 当前的法定人数纪元。 | kafka.server:type=raft-metrics,name=current-epoch |
High Watermark | 该成员保持高水位线;-1(如果未知)。 | kafka.server:type=raft-metrics,name=high-watermark |
Log End Offset | 当前筏日志末端偏移。 | kafka.server:type=raft-metrics,name=log-end-offset |
Number of Unknown Voter Connections | 连接信息未缓存的未知投票者数量。该指标的值始终为 0。 | kafka.server:type=raft-metrics,name=number-unknown-voter-connections |
Average Commit Latency | 在 raft 日志中提交条目的平均时间(以毫秒为单位)。 | kafka.server:type=raft-metrics,name=commit-latency-avg |
Maximum Commit Latency | 在 raft 日志中提交条目的最长时间(以毫秒为单位)。 | kafka.server:type=raft-metrics,name=commit-latency-max |
Average Election Latency | 选举新领导者所花费的平均时间(以毫秒为单位)。 | kafka.server:type=raft-metrics,name=election-latency-avg |
Maximum Election Latency | 选举新领导者所花费的最长时间(以毫秒为单位)。 | kafka.server:type=raft-metrics,name=election-latency-max |
Fetch Records Rate | 从 raft 法定人数的领导者处获取的平均记录数。 | kafka.server:type=raft-metrics,name=fetch-records-rate |
Append Records Rate | raft 仲裁组的领导者每秒附加的平均记录数。 | kafka.server:type=raft-metrics,name=append-records-rate |
Average Poll Idle Ratio | 客户端 poll() 处于空闲状态而不是等待用户代码处理记录的平均时间比例。 | kafka.server:type=raft-metrics,name=poll-idle-ratio-avg |
Current Metadata Version | 输出当前有效元数据版本的功能级别。 | kafka.server:type=MetadataLoader,name=CurrentMetadataVersion |
Metadata Snapshot Load Count | 自进程启动以来我们加载 KRaft 快照的总次数。 | kafka.server:类型=MetadataLoader,名称=HandleLoadSnapshotCount |
Latest Metadata Snapshot Size | 节点生成的最新快照的总大小(以字节为单位)。如果尚未生成任何快照,则这是加载的最新快照的大小。如果没有生成或加载快照,则该值为 0。 | kafka.server:类型=SnapshotEmitter,名称=LatestSnapshotGenerateBytes |
Latest Metadata Snapshot Age | 自节点生成的最新快照以来的时间间隔(以毫秒为单位)。如果尚未生成任何内容,则这大约是自进程启动以来的时间增量。 | kafka.server:类型=SnapshotEmitter,名称=LatestSnapshotGenerateAgeMs |
KRaft 控制器监控指标
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
Active Controller Count | 该节点上活动控制器的数量。有效值为“0”或“1”。 | kafka.controller:类型=KafkaController,名称=ActiveControllerCount |
Event Queue Time Ms | 请求在控制器事件队列中等待的时间(以毫秒为单位)的直方图。 | kafka.controller:类型=ControllerEventManager,名称=EventQueueTimeMs |
Event Queue Processing Time Ms | 控制器事件队列中处理请求所花费的时间(以毫秒为单位)的直方图。 | kafka.controller:类型=ControllerEventManager,名称=EventQueueProcessingTimeMs |
Fenced Broker Count | 该控制器观察到的受保护经纪人的数量。 | kafka.controller:类型=KafkaController,名称=FencedBrokerCount |
Active Broker Count | 该控制器观察到的活跃经纪商数量。 | kafka.controller:类型=KafkaController,名称=ActiveBrokerCount |
Global Topic Count | 该控制器观察到的全局主题的数量。 | kafka.controller:类型=KafkaController,名称=GlobalTopicCount |
Global Partition Count | 该控制器观察到的全局分区的数量。 | kafka.controller:类型=KafkaController,名称=GlobalPartitionCount |
Offline Partition Count | 该控制器观察到的离线主题分区(非内部)的数量。 | kafka.controller:类型=KafkaController,名称=OfflinePartitionCount |
Preferred Replica Imbalance Count | 领导者不是首选领导者的主题分区的数量。 | kafka.controller:类型=KafkaController,名称=PreferredReplicaImbalanceCount |
Metadata Error Count | 该控制器节点在元数据日志处理期间遇到错误的次数。 | kafka.controller:类型=KafkaController,名称=MetadataErrorCount |
Last Applied Record Offset | 控制器应用的集群元数据分区中最后一条记录的偏移量。 | kafka.controller:类型= KafkaController,名称= LastAppliedRecordOffset |
Last Committed Record Offset | 提交给该控制器的最后一条记录的偏移量。 | kafka.controller:类型= KafkaController,名称= LastCommitedRecordOffset |
Last Applied Record Timestamp | 控制器应用的集群元数据分区的最后一条记录的时间戳。 | kafka.controller:类型= KafkaController,名称= LastAppliedRecordTimestamp |
Last Applied Record Lag Ms | 现在与控制器应用的集群元数据分区的最后一条记录的时间戳之间的差异。对于活动控制器,该滞后值始终为零。 | kafka.controller:类型= KafkaController,名称= LastAppliedRecordLagMs |
ZooKeeper Write Behind Lag | ZooKeeper 相对于元数据日志中提交的最高记录的记录滞后量。该指标仅由活动的 KRaft 控制器报告。 | kafka.controller:类型=KafkaController,名称=ZkWriteBehindLag |
ZooKeeper Metadata Snapshot Write Time | KRaft 控制器将快照协调到 ZooKeeper 中所花费的毫秒数。 | kafka.controller:类型=KafkaController,名称=ZkWriteSnapshotTimeMs |
ZooKeeper Metadata Delta Write Time | KRaft 控制器将增量写入 ZK 所用的毫秒数。 | kafka.controller:类型=KafkaController,名称=ZkWriteDeltaTimeMs |
Timed-out Broker Heartbeat Count | 自进程启动以来此控制器上超时的代理心跳数。请注意,只有活动控制器才会处理心跳,因此只有它们才会看到此指标的增加。 | kafka.controller:类型= KafkaController,名称= TimedOutBrokerHeartbeatCount |
Number Of Operations Started In Event Queue | 已启动的控制器事件队列操作的总数。这包括延期操作。 | kafka.controller:类型= KafkaController,名称= EventQueueOperationsStartedCount |
Number of Operations Timed Out In Event Queue | 在执行之前超时的控制器事件队列操作总数。 | kafka.controller:类型= KafkaController,名称= EventQueueOperationsTimedOutCount |
Number Of New Controller Elections | 计算该节点选举出新控制器的次数。这里不计算到“无领导者”状态的转变。如果与以前相同的控制器处于活动状态,则仍然有效。 | kafka.controller:类型=KafkaController,名称=NewActiveControllersCount |
KRaft 经纪商监控指标
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
Last Applied Record Offset | 代理应用的集群元数据分区中最后一条记录的偏移量 | kafka.server:type=broker-metadata-metrics,name=last-applied-record-offset |
Last Applied Record Timestamp | 代理应用的集群元数据分区的最后一条记录的时间戳。 | kafka.server:type=broker-metadata-metrics,name=last-applied-record-timestamp |
Last Applied Record Lag Ms | 现在与代理应用的集群元数据分区中最后一条记录的时间戳之间的差异 | kafka.server:type=broker-metadata-metrics,name=last-applied-record-lag-ms |
Metadata Load Error Count | BrokerMetadataListener 在加载元数据日志并根据其生成新的 MetadataDelta 时遇到的错误数。 | kafka.server:类型=代理元数据指标,名称=元数据加载错误计数 |
Metadata Apply Error Count | BrokerMetadataPublisher 在应用基于最新 MetadataDelta 的新 MetadataImage 时遇到的错误数。 | kafka.server:类型=代理元数据指标,名称=元数据应用错误计数 |
Common monitoring metrics for producer/consumer/connect/streams
以下指标可用于生产者/消费者/连接器/流实例。有关具体指标,请参阅以下部分。指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
connection-close-rate | 窗口中每秒关闭的连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
connection-close-total | 窗口中关闭的总连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
connection-creation-rate | 窗口中每秒建立的新连接。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
connection-creation-total | 窗口中建立的新连接总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
network-io-rate | 每秒所有连接上的平均网络操作(读取或写入)数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
network-io-total | 所有连接上的网络操作(读取或写入)总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
outgoing-byte-rate | 每秒发送到所有服务器的平均传出字节数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
outgoing-byte-total | 发送到所有服务器的传出字节总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
request-rate | 每秒发送的平均请求数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
request-total | 发送的请求总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
request-size-avg | 窗口中所有请求的平均大小。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
request-size-max | 窗口中发送的任何请求的最大大小。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
incoming-byte-rate | 字节/秒读取所有套接字。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
incoming-byte-total | 从所有套接字读取的总字节数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
response-rate | 每秒收到的响应数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
response-total | 收到的回复总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
select-rate | I/O 层每秒检查新 I/O 执行的次数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
select-total | I/O 层检查要执行的新 I/O 的总次数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-wait-time-ns-avg | I/O 线程等待套接字准备好进行读取或写入所花费的平均时间(以纳秒为单位)。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-wait-time-ns-total | I/O 线程等待所花费的总时间(以纳秒为单位)。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-waittime-total | *已弃用* I/O 线程等待的总时间(以纳秒为单位)。替换是io-wait-time-ns-total . |
kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-wait-ratio | I/O 线程等待的时间比例。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-time-ns-avg | 每个选择调用的 I/O 平均时间长度(以纳秒为单位)。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-time-ns-total | I/O 线程执行 I/O 所花费的总时间(以纳秒为单位)。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
iotime-total | *已弃用* I/O 线程执行 I/O 所花费的总时间(以纳秒为单位)。替换是io-time-ns-total . |
kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
io-ratio | I/O 线程执行 I/O 所花费的时间比例。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
connection-count | 当前活动连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
successful-authentication-rate | 使用 SASL 或 SSL 成功验证的每秒连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
successful-authentication-total | 使用 SASL 或 SSL 成功验证的连接总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
failed-authentication-rate | 身份验证失败的每秒连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
failed-authentication-total | 身份验证失败的连接总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
successful-reauthentication-rate | 使用 SASL 成功重新验证的每秒连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
successful-reauthentication-total | 使用 SASL 成功重新验证的连接总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
reauthentication-latency-max | 由于重新身份验证而观察到的最大延迟(以毫秒为单位)。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
reauthentication-latency-avg | 由于重新身份验证而观察到的平均延迟(以毫秒为单位)。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
failed-reauthentication-rate | 重新验证失败的每秒连接数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
failed-reauthentication-total | 重新验证失败的连接总数。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
successful-authentication-no-reauth-total | 由不支持重新身份验证的旧版 2.2.0 之前的 SASL 客户端成功身份验证的总连接数。只能是非零。 | kafka.[生产者|消费者|连接]:type=[生产者|消费者|连接]-metrics,client-id=([-.\w]+) |
Common Per-broker metrics for producer/consumer/connect/streams
以下指标可用于生产者/消费者/连接器/流实例。有关具体指标,请参阅以下部分。指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
outgoing-byte-rate | 节点每秒发送的平均传出字节数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
outgoing-byte-total | 为节点发送的传出字节总数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
request-rate | 节点每秒发送的平均请求数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
request-total | 向节点发送的请求总数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
request-size-avg | 节点窗口中所有请求的平均大小。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
request-size-max | 在节点的窗口中发送的任何请求的最大大小。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
incoming-byte-rate | 节点每秒接收的平均字节数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
incoming-byte-total | 节点接收到的总字节数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
request-latency-avg | 节点的平均请求延迟(以毫秒为单位)。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
request-latency-max | 节点的最大请求延迟(以毫秒为单位)。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
response-rate | 节点每秒收到的响应数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
response-total | 节点收到的响应总数。 | kafka.[生产者|消费者|连接]:类型=[消费者|生产者|连接]-node-metrics,client-id=([-.\w]+),node-id=([0-9]+) |
生产者监控
以下指标可用于生产者实例。指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
waiting-threads | 因等待缓冲存储器将其记录排队而阻塞的用户线程数。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
buffer-total-bytes | 客户端可以使用的最大缓冲区内存量(无论当前是否使用)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
buffer-available-bytes | 未使用的缓冲区内存总量(未分配或在空闲列表中)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
bufferpool-wait-time | 附加程序等待空间分配的时间比例。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
bufferpool-wait-time-total | *已弃用*附加程序等待空间分配的总时间(以纳秒为单位)。更换是bufferpool-wait-time-ns-total |
kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
bufferpool-wait-time-ns-total | 附加程序等待空间分配的总时间(以纳秒为单位)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
flush-time-ns-total | Producer 在 Producer.flush 中花费的总时间(以纳秒为单位)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
txn-init-time-ns-total | 生产者初始化交易所花费的总时间(以纳秒为单位)(对于 EOS)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
txn-begin-time-ns-total | 生产者在 beginTransaction 中花费的总时间(以纳秒为单位)(对于 EOS)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
txn-send-offsets-time-ns-total | 生产者向交易发送偏移量所花费的总时间(以纳秒为单位)(对于 EOS)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
txn-commit-time-ns-total | 生产者提交交易所花费的总时间(以纳秒为单位)(对于 EOS)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
txn-abort-time-ns-total | 生产者中止交易所花费的总时间(以纳秒为单位)(对于 EOS)。 | kafka.生产者:类型=生产者指标,客户端id=([-.\w]+) |
生产者发送者指标
kafka.生产者:类型=生产者指标,客户端id =“{客户端id}” | ||
属性名称 | 描述 | |
---|---|---|
批量大小平均值 | 每个分区每个请求发送的平均字节数。 | |
最大批量大小 | 每个分区每个请求发送的最大字节数。 | |
批次分割率 | 每秒平均批分割数 | |
批次-分割-总计 | 批次拆分总数 | |
平均压缩率 | 记录批次的平均压缩率,定义为压缩批次大小与未压缩大小的平均比率。 | |
元数据时代 | 当前使用的生产者元数据的寿命(以秒为单位)。 | |
生产节流时间平均 | 请求被代理限制的平均时间(以毫秒为单位) | |
生产节流时间最大 | 请求被代理限制的最长时间(以毫秒为单位) | |
记录错误率 | 导致错误的平均每秒记录发送数 | |
记录错误总数 | 导致错误的记录发送总数 | |
记录队列平均时间 | 记录批次在发送缓冲区中花费的平均时间(以毫秒为单位)。 | |
记录队列最大时间 | 记录批次在发送缓冲区中花费的最长时间(以毫秒为单位)。 | |
记录重试率 | 平均每秒重试记录发送次数 | |
记录重试总数 | 重试记录发送总数 | |
记录发送率 | 每秒发送的平均记录数。 | |
记录发送总数 | 发送的记录总数。 | |
平均记录大小 | 平均记录大小 | |
记录大小最大值 | 最大记录大小 | |
每个请求的平均记录数 | 每个请求的平均记录数。 | |
请求平均延迟 | 平均请求延迟(以毫秒为单位) | |
请求最大延迟 | 最大请求延迟(以毫秒为单位) | |
进行中的请求 | 当前等待响应的正在进行的请求数。 | |
kafka.生产者:类型=生产者主题指标,客户端ID =“{客户端ID}”,主题=“{主题}” | ||
属性名称 | 描述 | |
字节率 | 主题每秒发送的平均字节数。 | |
字节总数 | 为主题发送的总字节数。 | |
压缩率 | 主题的记录批次的平均压缩率,定义为压缩批次大小与未压缩大小的平均比率。 | |
记录错误率 | 导致主题错误的平均每秒记录发送数 | |
记录错误总数 | 导致主题错误的记录发送总数 | |
记录重试率 | 主题的平均每秒重试记录发送次数 | |
记录重试总数 | 主题的重试记录发送总数 | |
记录发送率 | 主题每秒发送的平均记录数。 | |
记录发送总数 | 为某个主题发送的记录总数。 |
消费者监控
以下指标可用于消费者实例。指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
time-between-poll-avg | poll() 调用之间的平均延迟。 | kafka.consumer:type=consumer-metrics,client-id=([-.\w]+) |
time-between-poll-max | poll() 调用之间的最大延迟。 | kafka.consumer:type=consumer-metrics,client-id=([-.\w]+) |
last-poll-seconds-ago | 自上次 poll() 调用以来的秒数。 | kafka.consumer:type=consumer-metrics,client-id=([-.\w]+) |
poll-idle-ratio-avg | 消费者的 poll() 空闲时间而不是等待用户代码处理记录的平均时间比例。 | kafka.consumer:type=consumer-metrics,client-id=([-.\w]+) |
committed-time-ns-total | 消费者花费在承诺上的总时间(以纳秒为单位)。 | kafka.consumer:type=consumer-metrics,client-id=([-.\w]+) |
commit-sync-time-ns-total | 消费者提交偏移量所花费的总时间(以纳秒为单位)(对于 AOS)。 | kafka.consumer:type=consumer-metrics,client-id=([-.\w]+) |
消费者组指标
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
commit-latency-avg | 提交请求的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
commit-latency-max | 提交请求所花费的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
commit-rate | 每秒提交调用的次数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
commit-total | 提交调用总数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
assigned-partitions | 当前分配给该消费者的分区数量 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
heartbeat-response-time-max | 接收心跳请求响应所需的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
heartbeat-rate | 每秒平均心跳次数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
heartbeat-total | 心跳总数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
join-time-avg | 群组重新加入所需的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
join-time-max | 群组重新加入所需的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
join-rate | 每秒组加入数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
join-total | 群组加入总数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
sync-time-avg | 组同步所需的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
sync-time-max | 组同步所需的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
sync-rate | 每秒组同步数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
sync-total | 组同步总数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
rebalance-latency-avg | 组重新平衡所需的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
rebalance-latency-max | 组重新平衡所需的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
rebalance-latency-total | 到目前为止组重新平衡所需的总时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
rebalance-total | 参与群组重新平衡的总数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
rebalance-rate-per-hour | 每小时参与的群组重新平衡次数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
failed-rebalance-total | 组重新平衡失败的总数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
failed-rebalance-rate-per-hour | 每小时失败的组重新平衡事件数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
last-rebalance-seconds-ago | 自上次重新平衡事件以来的秒数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
last-heartbeat-seconds-ago | 自上次控制器心跳以来的秒数 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
partitions-revoked-latency-avg | on-partitions-revoked 重新平衡侦听器回调所花费的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
partitions-revoked-latency-max | on-partitions-revoked 重新平衡侦听器回调所花费的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
partitions-assigned-latency-avg | 分区上分配的重新平衡侦听器回调所花费的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
partitions-assigned-latency-max | 分区分配的重新平衡侦听器回调所花费的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
partitions-lost-latency-avg | on-partitions-lost 重新平衡侦听器回调所花费的平均时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
partitions-lost-latency-max | on-partitions-lost 重新平衡侦听器回调所花费的最长时间 | kafka.consumer:类型=消费者协调器指标,客户端id=([-.\w]+) |
消费者获取指标
kafka.consumer:type=consumer-fetch-manager-metrics,client-id="{client-id}" | ||
属性名称 | 描述 | |
---|---|---|
字节消耗率 | 平均每秒消耗的字节数 | |
消耗总字节数 | 消耗的总字节数 | |
获取平均延迟 | 获取请求所花费的平均时间。 | |
获取延迟最大 | 任何获取请求所花费的最长时间。 | |
获取率 | 每秒的获取请求数。 | |
获取大小平均值 | 每个请求获取的平均字节数 | |
获取大小最大值 | 每个请求获取的最大字节数 | |
获取节流时间平均 | 平均节流时间(以毫秒为单位) | |
获取节流时间最大值 | 最大节流时间(以毫秒为单位) | |
获取总计 | 获取请求的总数。 | |
记录消耗率 | 平均每秒消耗的记录数 | |
消耗记录总数 | 消耗的记录总数 | |
最大记录滞后 | 此窗口中任何分区的记录数的最大滞后。注意:这是基于当前偏移量和未提交的偏移量 | |
记录-领先-分钟 | 此窗口中任何分区的记录数的最小领先量 | |
每个请求的平均记录数 | 每个请求的平均记录数 | |
kafka.consumer:type=consumer-fetch-manager-metrics,client-id="{client-id}",topic="{topic}" | ||
属性名称 | 描述 | |
字节消耗率 | 主题每秒消耗的平均字节数 | |
消耗总字节数 | 主题消耗的总字节数 | |
获取大小平均值 | 每个主题请求获取的平均字节数 | |
获取大小最大值 | 每个主题请求获取的最大字节数 | |
记录消耗率 | 某个主题每秒消耗的平均记录数 | |
消耗记录总数 | 某个主题消耗的记录总数 | |
每个请求的平均记录数 | 某个主题的每次请求的平均记录数 | |
kafka.consumer:type=consumer-fetch-manager-metrics,partition="{partition}",topic="{topic}",client-id="{client-id}" | ||
属性名称 | 描述 | |
首选只读副本 | 分区的当前只读副本,如果从领导者读取,则为 -1 | |
记录滞后 | 分区的最新滞后时间 | |
记录滞后平均 | 分区的平均滞后 | |
最大记录滞后 | 分区的最大滞后 | |
记录领先 | 分区最新线索 | |
记录领先平均 | 分区平均导程 | |
记录-领先-分钟 | 隔板最小导程 |
连接监控
Connect 工作进程包含所有生产者和消费者指标以及特定于 Connect 的指标。工作进程本身有许多指标,而每个连接器和任务都有其他指标。[2023-09-15 00:40:42,725] INFO Metrics 调度程序关闭(org.apache.kafka.common.metrics.Metrics:693) [2023-09-15 00:40:42,729] INFO Metrics 记者关闭(org.apache.kafka.common.metrics.Metrics:693) apache.kafka.common.metrics.Metrics:703)kafka.connect:type=connect-worker-metrics | ||
属性名称 | 描述 | |
---|---|---|
连接器数量 | 该工作线程中运行的连接器数量。 | |
连接器启动尝试总数 | 该工作线程尝试启动连接器的总数。 | |
连接器启动失败百分比 | 该工作线程的连接器启动失败的平均百分比。 | |
连接器启动失败总计 | 失败的连接器启动总数。 | |
连接器启动成功百分比 | 该工作人员的连接器启动成功的平均百分比。 | |
连接器启动成功总计 | 成功启动的连接器总数。 | |
任务计数 | 该工作线程中运行的任务数。 | |
任务启动尝试总数 | 该工作线程尝试启动的任务总数。 | |
任务启动失败百分比 | 该工作人员任务启动失败的平均百分比。 | |
任务启动失败总数 | 失败的任务启动总数。 | |
任务启动成功百分比 | 该工作人员的任务开始成功的平均百分比。 | |
任务启动成功总计 | 成功启动的任务总数。 | |
kafka.connect:type=connect-worker-metrics,连接器=“{连接器}” | ||
属性名称 | 描述 | |
连接器损坏的任务计数 | Worker 上连接器已销毁的任务数。 | |
连接器失败任务计数 | 工作线程上连接器失败的任务数。 | |
连接器暂停任务计数 | Worker 上连接器暂停的任务数。 | |
连接器重新启动任务计数 | Worker 上连接器的重新启动任务数。 | |
连接器运行任务计数 | Worker 上连接器正在运行的任务数。 | |
连接器总任务计数 | 连接器在工作线程上执行的任务数。 | |
连接器未分配的任务计数 | 工作线程上连接器未分配的任务数。 | |
kafka.connect:type=connect-worker-rebalance-metrics | ||
属性名称 | 描述 | |
完成再平衡总计 | 该工作人员完成的重新平衡总数。 | |
连接协议 | 该集群使用的连接协议 | |
时代 | 该工作人员的纪元或代号。 | |
领导者姓名 | 小组领导者的姓名。 | |
重新平衡平均时间毫秒 | 该工作人员重新平衡所花费的平均时间(以毫秒为单位)。 | |
重新平衡最大时间毫秒 | 该工作人员重新平衡所花费的最长时间(以毫秒为单位)。 | |
再平衡 | 该工作人员当前是否正在重新平衡。 | |
自上次重新平衡以来的时间毫秒 | 自该工作人员完成最近一次重新平衡以来的时间(以毫秒为单位)。 | |
kafka.connect:类型=连接器指标,连接器=“{连接器}” | ||
属性名称 | 描述 | |
连接器级 | 连接器类的名称。 | |
连接器型 | 连接器的类型。“源”或“汇”之一。 | |
连接器版本 | 连接器类的版本,由连接器报告。 | |
地位 | 连接器的状态。“未分配”、“正在运行”、“已暂停”、“已停止”、“失败”或“正在重新启动”之一。 | |
kafka.connect:类型=连接器任务指标,连接器=“{连接器}”,任务=“{任务}” | ||
属性名称 | 描述 | |
批量大小平均值 | 任务到目前为止已处理的批次中的平均记录数。 | |
最大批量大小 | 任务迄今为止已处理的最大批次中的记录数。 | |
偏移提交平均时间毫秒 | 该任务提交偏移量所花费的平均时间(以毫秒为单位)。 | |
偏移提交失败百分比 | 此任务的偏移提交尝试失败的平均百分比。 | |
偏移提交最大时间毫秒 | 此任务提交偏移量所花费的最长时间(以毫秒为单位)。 | |
偏移提交成功百分比 | 此任务的偏移量提交尝试成功的平均百分比。 | |
停顿比 | 该任务处于暂停状态的时间比例。 | |
运行比 | 该任务处于运行状态的时间比例。 | |
地位 | 连接器任务的状态。“未分配”、“正在运行”、“已暂停”、“失败”或“正在重新启动”之一。 | |
kafka.connect:类型=接收器任务指标,连接器=“{连接器}”,任务=“{任务}” | ||
属性名称 | 描述 | |
偏移提交完成率 | 成功完成的平均每秒偏移提交完成次数。 | |
偏移-提交-完成-总计 | 已成功完成的偏移量提交完成总数。 | |
偏移提交序列号 | 偏移量提交的当前序列号。 | |
偏移提交跳过率 | 每秒接收得太晚且被跳过/忽略的偏移提交完成的平均数量。 | |
偏移提交跳过总计 | 接收得太晚且跳过/忽略的偏移量提交完成总数。 | |
分区计数 | 分配给该任务的主题分区数,属于该工作线程中指定的接收器连接器。 | |
put-batch-avg-time-ms | 该任务放置一批接收器记录所花费的平均时间。 | |
put-batch-max-time-ms | 该任务放置一批接收器记录所花费的最长时间。 | |
接收器记录活动计数 | 已从 Kafka 读取但尚未由接收器任务完全提交/刷新/确认的记录数。 | |
接收器记录活动计数平均值 | 已从 Kafka 读取但尚未由接收器任务完全提交/刷新/确认的平均记录数。 | |
接收器记录活动计数最大值 | 已从 Kafka 读取但尚未由接收器任务完全提交/刷新/确认的最大记录数。 | |
接收记录最大滞后 | 接收器任务落后于任何主题分区的消费者位置的最大记录数延迟。 | |
接收器记录读取率 | 对于属于该工作进程中指定接收器连接器的该任务,每秒从 Kafka 读取的平均记录数。这是应用转换之前的情况。 | |
接收器记录读取总数 | 自上次重新启动该任务以来,属于该工作线程中指定接收器连接器的该任务从 Kafka 读取的记录总数。 | |
接收器记录发送率 | 从转换输出并发送/放入属于此工作线程中指定接收器连接器的此任务的平均每秒记录数。这是应用转换之后的结果,并且不包括转换过滤掉的任何记录。 | |
接收记录发送总计 | 自上次重新启动任务以来,从转换输出并发送/放入属于此工作线程中指定接收器连接器的此任务的记录总数。 | |
kafka.connect:类型=源任务指标,连接器=“{连接器}”,任务=“{任务}” | ||
属性名称 | 描述 | |
轮询批次平均时间毫秒 | 此任务轮询一批源记录所花费的平均时间(以毫秒为单位)。 | |
轮询批次最大时间毫秒 | 此任务轮询一批源记录所花费的最长时间(以毫秒为单位)。 | |
源记录活动计数 | 该任务已生成但尚未完全写入 Kafka 的记录数。 | |
源记录活动计数平均值 | 该任务已生成但尚未完全写入 Kafka 的平均记录数。 | |
源记录活动计数最大值 | 该任务已生成但尚未完全写入 Kafka 的最大记录数。 | |
源记录轮询率 | 属于该工作线程中指定源连接器的任务每秒生成/轮询(转换之前)的平均记录数。 | |
源记录民意调查总计 | 此任务生成/轮询(转换前)的记录总数,属于该工作线程中的指定源连接器。 | |
源记录写入率 | 自上次重新启动任务以来,每秒为属于此工作线程中指定源连接器的任务写入 Kafka 的平均记录数。这是应用转换之后的结果,并且不包括转换过滤掉的任何记录。 | |
源记录写入总数 | 自上次重新启动任务以来,针对属于此工作线程中指定源连接器的此任务写入 Kafka 的记录输出数。这是应用转换之后的结果,并且不包括转换过滤掉的任何记录。 | |
平均交易大小 | 任务迄今为止已提交的事务中的平均记录数。 | |
交易大小最大值 | 任务迄今为止已提交的最大事务中的记录数。 | |
最小交易大小 | 任务迄今为止已提交的最小事务中的记录数。 | |
kafka.connect:类型=任务错误指标,连接器=“{连接器}”,任务=“{任务}” | ||
属性名称 | 描述 | |
死信队列生产失败 | 写入死信队列失败的次数。 | |
死信队列产生请求 | 尝试写入死信队列的次数。 | |
最后错误时间戳 | 此任务上次遇到错误时的纪元时间戳。 | |
记录的总错误数 | 记录的错误数。 | |
总记录错误数 | 此任务中记录处理错误的数量。 | |
总记录失败数 | 此任务中记录处理失败的数量。 | |
跳过的总记录数 | 由于错误而跳过的记录数。 | |
总重试次数 | 重试操作的次数。 |
流监控
Kafka Streams 实例包含所有生产者和消费者指标以及特定于 Streams 的其他指标。这些指标具有三个记录级别:info
、debug
和trace
。
请注意,指标有 4 层层次结构。在顶层,每个启动的 Kafka Streams 客户端都有客户端级指标。每个客户端都有流线程,有自己的指标。每个流线程都有任务,有自己的指标。每个任务都有多个处理器节点,并具有自己的指标。每个任务还有许多状态存储和记录缓存,它们都有自己的指标。
使用以下配置选项指定您要收集的指标: metrics.recording.level="info"
客户指标
以下所有指标的记录级别均为info
:
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
version | Kafka Streams 客户端的版本。 | kafka.streams:type=stream-metrics,client-id=([-.\w]+) |
commit-id | Kafka Streams 客户端的版本控制提交 ID。 | kafka.streams:type=stream-metrics,client-id=([-.\w]+) |
application-id | Kafka Streams 客户端的应用程序 ID。 | kafka.streams:type=stream-metrics,client-id=([-.\w]+) |
topology-description | 在 Kafka Streams 客户端中执行的拓扑的描述。 | kafka.streams:type=stream-metrics,client-id=([-.\w]+) |
state | Kafka Streams 客户端的状态。 | kafka.streams:type=stream-metrics,client-id=([-.\w]+) |
failed-stream-threads | 自 Kafka Streams 客户端启动以来失败的流线程数。 | kafka.streams:type=stream-metrics,client-id=([-.\w]+) |
线程指标
以下所有指标的记录级别均为info
:
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
commit-latency-avg | 该线程的所有正在运行的任务的提交平均执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
commit-latency-max | 该线程的所有正在运行的任务的提交的最大执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
poll-latency-avg | 消费者轮询的平均执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
poll-latency-max | 消费者轮询的最大执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
process-latency-avg | 处理的平均执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
process-latency-max | 处理的最大执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
punctuate-latency-avg | 用于标点符号的平均执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
punctuate-latency-max | 用于标点符号的最大执行时间(以毫秒为单位)。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
commit-rate | 每秒的平均提交次数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
commit-total | 提交调用的总数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
poll-rate | 每秒消费者轮询调用的平均数量。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
poll-total | 消费者民意调查呼叫的总数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
process-rate | 每秒处理的平均记录数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
process-total | 已处理的记录总数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
punctuate-rate | 每秒平均标点调用次数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
punctuate-total | 标点调用的总数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
task-created-rate | 每秒创建的平均任务数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
task-created-total | 创建的任务总数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
task-closed-rate | 每秒关闭的平均任务数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
task-closed-total | 已关闭的任务总数。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
blocked-time-ns-total | 线程在 kafka 上阻塞的总时间。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
thread-start-time | 线程启动的时间。 | kafka.streams:type=stream-thread-metrics,thread-id=([-.\w]+) |
任务指标
以下所有指标的记录级别均为debug
,但 drop-records-* 和 active-process-ratio 指标的记录级别除外info
:
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
process-latency-avg | 处理的平均执行时间(以纳秒为单位)。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
process-latency-max | 处理的最大执行时间(以 ns 为单位)。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
process-rate | 此任务的所有源处理器节点每秒处理的平均记录数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
process-total | 此任务的所有源处理器节点上处理的记录总数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
commit-latency-avg | 提交的平均执行时间(以纳秒为单位)。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
commit-latency-max | 提交的最大执行时间(以 ns 为单位)。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
commit-rate | 每秒平均提交调用次数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
commit-total | 提交调用的总数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
record-lateness-avg | 观察到的记录的平均延迟(流时间 - 记录时间戳)。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
record-lateness-max | 观察到的记录的最大延迟时间(流时间 - 记录时间戳)。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
enforced-processing-rate | 每秒强制执行的平均处理次数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
enforced-processing-total | 强制处理的总数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
dropped-records-rate | 此任务中丢弃的平均记录数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
dropped-records-total | 此任务中删除的记录总数。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
active-process-ratio | 流线程在所有分配的活动任务中处理此任务所花费的时间比例。 | kafka.streams:type=stream-task-metrics,thread-id=([-.\w]+),task-id=([-.\w]+) |
处理器节点指标
以下指标仅适用于某些类型的节点,即 process-* 指标仅适用于源处理器节点,suppression-emit-* 指标仅适用于抑制操作节点,而 record-e2e-latency- * 指标仅适用于源处理器节点和终端节点(没有后继节点的节点)。所有指标的记录级别均为debug
,但 record-e2e-latency-* 指标的记录级别除外info
:
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
bytes-consumed-total | 源处理器节点消耗的总字节数。 | kafka.streams:类型=流主题指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([-. \w]+),主题=([-.\w]+) |
bytes-produced-total | 接收器处理器节点产生的字节总数。 | kafka.streams:类型=流主题指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([-. \w]+),主题=([-.\w]+) |
process-rate | 源处理器节点每秒处理的平均记录数。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
process-total | 源处理器节点每秒处理的记录总数。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
suppression-emit-rate | 从抑制操作节点向下游发送记录的速率。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
suppression-emit-total | 从抑制操作节点向下游发出的记录总数。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
record-e2e-latency-avg | 记录的平均端到端延迟,通过将记录时间戳与节点完全处理该记录时的系统时间进行比较来测量。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
record-e2e-latency-max | 记录的最大端到端延迟,通过将记录时间戳与节点完全处理该记录时的系统时间进行比较来测量。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
record-e2e-latency-min | 记录的最小端到端延迟,通过将记录时间戳与节点完全处理该记录时的系统时间进行比较来测量。 | kafka.streams:类型=流处理器节点指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([ -.\w]+) |
records-consumed-total | 源处理器节点消耗的记录总数。 | kafka.streams:类型=流主题指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([-. \w]+),主题=([-.\w]+) |
records-produced-total | 接收器处理器节点生成的记录总数。 | kafka.streams:类型=流主题指标,线程id=([-.\w]+),任务id=([-.\w]+),处理器节点id=([-. \w]+),主题=([-.\w]+) |
状态存储指标
以下所有指标的记录级别均为debug
,但 record-e2e-latency-* 指标的记录级别除外trace
。请注意,该store-scope
值是在StoreSupplier#metricsScope()
用户自定义状态存储中指定的;对于内置状态存储,目前我们有:
in-memory-state
in-memory-lru-state
in-memory-window-state
in-memory-suppression
(用于抑制缓冲液)rocksdb-state
(对于 RocksDB 支持的键值存储)rocksdb-window-state
(对于 RocksDB 支持的橱窗商店)rocksdb-session-state
(对于 RocksDB 支持的会话存储)
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
put-latency-avg | 平均 put 执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-latency-max | put 的最大执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-if-absent-latency-avg | put-if-absent 的平均执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-if-absent-latency-max | put-if-absent 的最大执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
get-latency-avg | 平均 get 执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
get-latency-max | 最大 get 执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
delete-latency-avg | 平均删除执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
delete-latency-max | 最大删除执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-all-latency-avg | put-all 的平均执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-all-latency-max | put-all 的最大执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
all-latency-avg | 所有操作的平均执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
all-latency-max | 所有操作的最大执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
range-latency-avg | 平均范围执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
range-latency-max | 最大范围执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
flush-latency-avg | 平均刷新执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
flush-latency-max | 最大刷新执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
restore-latency-avg | 平均恢复执行时间(以纳秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
restore-latency-max | 最大恢复执行时间(以 ns 为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-rate | 这家商店的平均成交率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-if-absent-rate | 这家商店的平均缺货率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
get-rate | 这家商店的平均获得率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
delete-rate | 该商店的平均删除率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
put-all-rate | 这家商店的平均全盘率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
all-rate | 该商店的平均所有营业率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
range-rate | 这家商店的平均范围率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
flush-rate | 这家商店的平均刷新率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
restore-rate | 该商店的平均恢复率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
suppression-buffer-size-avg | 采样窗口内缓冲数据的平均总大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),内存抑制-id=([ -.\w]+) |
suppression-buffer-size-max | 采样窗口内缓冲数据的最大总大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),内存抑制-id=([ -.\w]+) |
suppression-buffer-count-avg | 采样窗口内缓冲的平均记录数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),内存抑制-id=([ -.\w]+) |
suppression-buffer-count-max | 采样窗口内缓冲的最大记录数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),内存抑制-id=([ -.\w]+) |
record-e2e-latency-avg | 记录的平均端到端延迟,通过将记录时间戳与节点完全处理该记录时的系统时间进行比较来测量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
record-e2e-latency-max | 记录的最大端到端延迟,通过将记录时间戳与节点完全处理该记录时的系统时间进行比较来测量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
record-e2e-latency-min | 记录的最小端到端延迟,通过将记录时间戳与节点完全处理该记录时的系统时间进行比较来测量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
RocksDB 指标
RocksDB 指标分为基于统计的指标和基于属性的指标。前者是从 RocksDB 状态存储收集的统计信息中记录的,而后者是从 RocksDB 公开的属性中记录的。RocksDB 收集的统计数据提供了一段时间内的累积测量值,例如写入状态存储的字节数。RocksDB 公开的属性提供当前测量值,例如当前使用的内存量。请注意,store-scope
内置 RocksDB 状态存储当前如下:
rocksdb-state
(对于 RocksDB 支持的键值存储)rocksdb-window-state
(对于 RocksDB 支持的橱窗商店)rocksdb-session-state
(对于 RocksDB 支持的会话存储)
debug
因为在 RocksDB 中收集统计数据可能会对性能产生影响。每分钟从 RocksDB 状态存储收集基于统计数据的指标。如果状态存储由多个 RocksDB 实例组成(如 WindowStores 和 SessionStores 的情况),则每个指标都会报告状态存储的 RocksDB 实例的聚合。
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
bytes-written-rate | 每秒写入 RocksDB 状态存储的平均字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
bytes-written-total | 写入 RocksDB 状态存储的总字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
bytes-read-rate | 每秒从 RocksDB 状态存储读取的平均字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
bytes-read-total | 从 RocksDB 状态存储读取的总字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
memtable-bytes-flushed-rate | 每秒从内存表刷新到磁盘的平均字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
memtable-bytes-flushed-total | 从内存表刷新到磁盘的总字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
memtable-hit-ratio | 内存表命中相对于所有对内存表的查找的比率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
memtable-flush-time-avg | memtable 刷新到磁盘的平均持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
memtable-flush-time-min | memtable 刷新到磁盘的最短持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
memtable-flush-time-max | memtable 刷新到磁盘的最大持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
block-cache-data-hit-ratio | 数据块的块缓存命中率相对于数据块对块缓存的所有查找的比率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
block-cache-index-hit-ratio | 索引块的块缓存命中率相对于索引块对块缓存的所有查找的比率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
block-cache-filter-hit-ratio | 过滤器块的块缓存命中率相对于过滤器块对块缓存的所有查找的比率。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
write-stall-duration-avg | 写入停顿的平均持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
write-stall-duration-total | 写入停止的总持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
bytes-read-compaction-rate | 压缩期间每秒读取的平均字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
bytes-written-compaction-rate | 压缩期间每秒写入的平均字节数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
compaction-time-avg | 椎间盘压缩的平均持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
compaction-time-min | 椎间盘压缩的最短持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
compaction-time-max | 椎间盘压缩的最大持续时间(以毫秒为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
number-open-files | 当前打开的文件数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
number-file-errors-total | 发生的文件错误总数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
info
并在访问指标时进行记录。如果状态存储由多个 RocksDB 实例组成,如 WindowStores 和 SessionStores 的情况,则每个指标报告状态存储的所有 RocksDB 实例的总和,块缓存指标除外
block-cache-*
。如果每个实例都使用自己的块缓存,则块缓存指标报告所有 RocksDB 实例的总和;如果在所有实例之间共享单个块缓存,则它们仅报告一个实例的记录值。
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
num-immutable-mem-table | 尚未刷新的不可变内存表的数量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
cur-size-active-mem-table | 活动内存表的大致大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
cur-size-all-mem-tables | 活动和未刷新的不可变内存表的大致大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
size-all-mem-tables | 活动的、未刷新的不可变的和固定的不可变内存表的大致大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-entries-active-mem-table | 活动内存表中的条目数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-entries-imm-mem-tables | 未刷新的不可变内存表中的条目数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-deletes-active-mem-table | 活动内存表中删除条目的数量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-deletes-imm-mem-tables | 未刷新的不可变内存表中的删除条目数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
mem-table-flush-pending | 如果内存表刷新处于挂起状态,则该指标报告 1,否则报告 0。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-running-flushes | 当前运行的刷新次数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
compaction-pending | 如果至少有一个压缩待处理,则该指标报告 1,否则报告 0。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-running-compactions | 当前正在运行的压缩数量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
estimate-pending-compaction-bytes | 压缩需要在磁盘上重写的估计总字节数,以使所有级别降至目标大小以下(仅对级别压缩有效)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
total-sst-files-size | 所有 SST 文件的总大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
live-sst-files-size | 属于最新 LSM 树的所有 SST 文件的总大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
num-live-versions | LSM 树的实时版本数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
block-cache-capacity | 块缓存的容量(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
block-cache-usage | 驻留在块缓存中的条目的内存大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
block-cache-pinned-usage | 固定在块缓存中的条目的内存大小(以字节为单位)。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
estimate-num-keys | 活动和未刷新的不可变内存表和存储中的键的估计数量。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
estimate-table-readers-mem | 用于读取 SST 表的估计内存(以字节为单位),不包括块缓存中使用的内存。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
background-errors | 背景错误总数。 | kafka.streams:类型=流状态指标,线程id=([-.\w]+),任务id=([-.\w]+),[存储范围]-id=([ -.\w]+) |
记录缓存指标
以下所有指标的记录级别均为debug
:
指标/属性名称 | 描述 | Mbean 名称 |
---|---|---|
hit-ratio-avg | 平均缓存命中率定义为缓存读取命中数与缓存读取请求总数的比率。 | kafka.streams:类型=流记录缓存指标,线程id=([-.\w]+),任务id=([-.\w]+),记录缓存id=([ -.\w]+) |
hit-ratio-min | 最小缓存命中率。 | kafka.streams:类型=流记录缓存指标,线程id=([-.\w]+),任务id=([-.\w]+),记录缓存id=([ -.\w]+) |
hit-ratio-max | 最大缓存命中率。 | kafka.streams:类型=流记录缓存指标,线程id=([-.\w]+),任务id=([-.\w]+),记录缓存id=([ -.\w]+) |
其他的
我们建议监控 GC 时间和其他统计信息以及各种服务器统计信息,例如 CPU 利用率、I/O 服务时间等。在客户端,我们建议监控消息/字节率(全局和每个主题)、请求率/大小/时间,在消费者方面,所有分区之间消息的最大延迟和最小获取请求率。为了让消费者跟上,最大延迟需要小于阈值,最小获取率需要大于 0。6.9 动物园管理员
稳定版
当前的稳定分支是 3.5。Kafka 会定期更新以包含 3.5 系列中的最新版本。ZooKeeper 弃用
随着 Apache Kafka 3.5 的发布,Zookeeper 现已被标记为已弃用。计划在 Apache Kafka 的下一个主要版本(版本 4.0)中删除 ZooKeeper,该版本计划最早于 2024 年 4 月进行。在弃用阶段,仍然支持 ZooKeeper 进行 Kafka 集群的元数据管理,但不建议这样做用于新的部署。KRaft 中仍有一小部分功能有待实现,请参阅当前缺失的功能以获取更多信息。
移民
将现有的基于 ZooKeeper 的 Kafka 集群迁移到 KRaft 目前处于预览阶段,我们预计它可以在 3.6 版本中投入生产使用。建议用户开始计划迁移到 KRaft,并开始测试以提供反馈。有关如何执行从ZooKeeper 到 KRaft实时迁移以及当前限制的详细信息,请参阅ZooKeeper 到 KRaft 迁移。
3.x 和 ZooKeeper 支持
支持 ZooKeeper 模式的最终 3.x 小版本将在发布后 12 个月内获得关键错误修复和安全修复。
ZooKeeper 和 KRaft 时间线
有关 ZooKeeper 删除和计划的 KRaft 功能发布的暂定时间表的详细信息和更新,请参阅KIP-833。
运行 ZooKeeper
在操作上,我们为健康的 ZooKeeper 安装执行以下操作:- 物理/硬件/网络布局中的冗余:尽量不要将它们全部放在同一个机架中,体面(但不要疯狂)的硬件,尽量保留冗余电源和网络路径等。典型的 ZooKeeper 整体有 5 个或7 台服务器,分别允许 2 台和 3 台服务器宕机。如果您的部署规模较小,那么使用 3 台服务器是可以接受的,但请记住,在这种情况下您只能容忍 1 台服务器停机。
- I/O 隔离:如果您执行大量写入类型流量,您几乎肯定希望事务日志位于专用磁盘组上。对事务日志的写入是同步的(但为了性能而进行批处理),因此并发写入会显着影响性能。ZooKeeper 快照就是这样一种并发写入源,理想情况下应该写入与事务日志分开的磁盘组上。快照异步写入磁盘,因此通常可以与操作系统和消息日志文件共享。您可以通过 dataLogDir 参数将服务器配置为使用单独的磁盘组。
- 应用程序隔离:除非您真正了解要安装在同一机器上的其他应用程序的应用程序模式,否则最好单独运行 ZooKeeper(尽管这可能是与硬件功能的平衡行为)。
- 谨慎使用虚拟化:它可以工作,具体取决于您的集群布局、读/写模式和 SLA,但是虚拟化层引入的微小开销可能会累积起来并导致 ZooKeeper 失效,因为它可能对时间非常敏感
- ZooKeeper 配置:它是 java,请确保给它“足够”的堆空间(我们通常使用 3-5G 运行它们,但这主要是由于我们这里的数据集大小)。不幸的是,我们没有一个好的公式,但请记住,允许更多的 ZooKeeper 状态意味着快照可能会变得很大,而大快照会影响恢复时间。事实上,如果快照变得太大(几 GB),那么您可能需要增加 initLimit 参数,以便为服务器提供足够的时间来恢复并加入集合。
- 监控:JMX 和 4 字母单词 (4lw) 命令都非常有用,它们在某些情况下确实重叠(在这些情况下,我们更喜欢 4 字母命令,它们看起来更可预测,或者至少,它们与LI 监控基础设施)
- 不要过度构建集群:大型集群,尤其是在写入大量使用模式中,意味着大量的集群内通信(写入和后续集群成员更新的仲裁),但不要构建不足(并有淹没集群的风险)。拥有更多服务器会增加您的读取能力。
6.10 卡夫
配置
流程角色
在 KRaft 模式下,每个 Kafka 服务器都可以使用该属性配置为控制器、代理或两者process.roles
。该属性可以具有以下值:
- 如果
process.roles
设置为broker
,则服务器充当代理。 - 如果
process.roles
设置为controller
,则服务器充当控制器。 - 如果
process.roles
设置为broker,controller
,则服务器既充当代理又充当控制器。 - 如果
process.roles
根本没有设置,则假定处于 ZooKeeper 模式。
既充当代理又充当控制器的 Kafka 服务器被称为“组合”服务器。对于开发环境等小型用例,组合服务器更易于操作。主要缺点是控制器与系统其他部分的隔离程度较低。例如,无法在组合模式下与代理分开滚动或扩展控制器。在关键部署环境中不建议使用组合模式。
控制器
在KRaft模式下,选择特定的Kafka服务器作为控制器(与基于ZooKeeper的模式不同,在该模式中任何服务器都可以成为控制器)。被选为控制器的服务器将参与元数据仲裁。每个控制器都是当前活动控制器的活动控制器或热备用控制器。
Kafka 管理员通常会选择 3 或 5 个服务器来担任此角色,具体取决于成本和系统在不影响可用性的情况下应承受的并发故障数量等因素。大多数控制器必须处于活动状态才能保持可用性。3个控制器时,集群可以容忍1个控制器故障;如果有 5 个控制器,集群可以容忍 2 个控制器故障。
Kafka 集群中的所有服务器都使用该controller.quorum.voters
属性发现仲裁投票者。这标识了应使用的仲裁控制器服务器。必须枚举所有控制器。每个控制器均通过其id
、host
和port
信息进行标识。例如:
controller.quorum.voters=id1@host1:port1,id2@host2:port2,id3@host3:port3
如果一个Kafka集群有3个控制器,分别名为controller1、controller2和controller3,那么controller1可能有以下配置:
process.roles=controller
node.id=1
listeners=CONTROLLER://controller1.example.com:9093
controller.quorum.voters=1@controller1.example.com:9093,2@controller2.example.com:9093,3@controller3.example.com:9093
每个经纪人和控制器都必须设置该controller.quorum.voters
属性。属性中提供的节点 IDcontroller.quorum.voters
必须与控制器服务器上的相应 ID 匹配。例如,在controller1上,node.id必须设置为1,依此类推。每个节点 ID 在特定集群中的所有服务器中必须是唯一的。任何两个服务器都不能具有相同的节点 ID,无论其process.roles
值如何。
存储工具
该kafka-storage.sh random-uuid
命令可用于为新集群生成集群 ID。使用该命令格式化集群中的每个服务器时,必须使用此集群 ID kafka-storage.sh format
。
这与Kafka过去的运作方式不同。此前,Kafka会自动格式化空白存储目录,并自动生成新的集群ID。进行更改的原因之一是自动格式化有时会掩盖错误情况。这对于控制器和代理服务器维护的元数据日志尤其重要。如果大多数控制器能够以空日志目录启动,则可能会在丢失已提交数据的情况下选举领导者。
调试
元数据仲裁工具
该kafka-metadata-quorum
工具可用于描述集群元数据分区的运行时状态。例如,以下命令显示元数据仲裁的摘要:
> bin/kafka-metadata-quorum.sh --bootstrap-server broker_host:port describe --status
ClusterId: fMCL8kv1SWm87L_Md-I2hg
LeaderId: 3002
LeaderEpoch: 2
HighWatermark: 10
MaxFollowerLag: 0
MaxFollowerLagTimeMs: -1
CurrentVoters: [3000,3001,3002]
CurrentObservers: [0,1,2]
转储日志工具
该kafka-dump-log
工具可用于调试集群元数据目录的日志段和快照。该工具将扫描提供的文件并解码元数据记录。例如,此命令解码并打印第一个日志段中的记录:
> bin/kafka-dump-log.sh --cluster-metadata-decoder --files metadata_log_dir/__cluster_metadata-0/00000000000000000000.log
此命令解码并打印集群元数据快照中的记录:
> bin/kafka-dump-log.sh --cluster-metadata-decoder --files metadata_log_dir/__cluster_metadata-0/00000000000000000100-0000000001.checkpoint
元数据外壳
该kafka-metadata-shell
工具可用于交互式检查集群元数据分区的状态:
> bin/kafka-metadata-shell.sh --snapshot metadata_log_dir/__cluster_metadata-0/00000000000000000000.log
>> ls /
brokers local metadataQuorum topicIds topics
>> ls /topics
foo
>> cat /topics/foo/0/data
{
"partitionId" : 0,
"topicId" : "5zoAlv-xEh9xRANKXt1Lbg",
"replicas" : [ 1 ],
"isr" : [ 1 ],
"removingReplicas" : null,
"addingReplicas" : null,
"leader" : 1,
"leaderEpoch" : 0,
"partitionEpoch" : 0
}
>> exit
部署注意事项
- Kafka 服务器
process.role
应设置为其中之一broker
或controller
但不能同时设置两者。组合模式可以在开发环境中使用,但在关键部署环境中应避免使用。 - 为了实现冗余,Kafka 集群应使用 3 个控制器。在关键环境中不建议使用超过 3 个控制器。在极少数情况下,出现部分网络故障时,集群元数据仲裁可能会变得不可用。此限制将在 Kafka 的未来版本中得到解决。
- Kafka 控制器将集群的所有元数据存储在内存和磁盘上。我们认为,对于典型的 Kafka 集群,5GB 主内存和元数据日志管理器上的 5GB 磁盘空间就足够了。
缺少的功能
KRaft 模式中未完全实现以下功能:
- 支持具有多个存储目录的JBOD配置
- 修改独立 KRaft 控制器上的某些动态配置
- 委托代币
ZooKeeper 到 KRaft 迁移
ZooKeeper 到 KRaft 的迁移被视为早期访问功能,不建议用于生产集群。
ZK 到 KRaft 的迁移尚不支持以下功能:
- 迁移期间或迁移之后降级到 ZooKeeper 模式
- KRaft 尚不支持的其他功能
请使用 项目 JIRA和“kraft”组件报告 ZooKeeper 到 KRaft 迁移的问题。
术语
我们这里使用术语“迁移”来指将Kafka集群的元数据系统从ZooKeeper更改为KRaft并迁移现有元数据的过程。“升级”是指安装更新版本的 Kafka。不建议在执行元数据迁移的同时升级软件。
我们还使用术语“ZK 模式”来指代使用 ZooKeeper 作为元数据系统的 Kafka 代理。“KRaft 模式”是指使用 KRaft 控制器仲裁作为其元数据系统的 Kafka 代理。
准备迁移
在开始迁移之前,Kafka 代理必须升级到软件版本 3.5.0,并将“inter.broker.protocol.version”配置设置为“3.5”。有关升级说明,请参阅升级到 3.5.0。
建议在迁移处于活动状态时为迁移组件启用 TRACE 级别日志记录。这可以通过将以下 log4j 配置添加到每个 KRaft 控制器的“log4j.properties”文件来完成。
log4j.logger.org.apache.kafka.metadata.migration=TRACE
在迁移期间在 KRaft 控制器和 ZK 代理上启用 DEBUG 日志记录通常很有用。
配置 KRaft 控制器仲裁
在开始迁移之前需要做两件事。首先,必须配置代理以支持迁移,其次,必须部署 KRaft 控制器仲裁。KRaft 控制器应配置与现有 Kafka 集群相同的集群 ID。这可以通过检查代理数据目录中的“meta.properties”文件之一或运行以下命令来找到。
./bin/zookeeper-shell.sh localhost:2181 get /cluster/id
KRaft 控制器仲裁还应配备最新的metadata.version
. 当您使用该kafka-storage.sh
工具格式化节点时,此操作会自动完成。有关 KRaft 部署的更多说明,请参阅上述文档。
除了标准的 KRaft 配置之外,KRaft 控制器还需要启用迁移支持并提供 ZooKeeper 连接配置。
以下是准备迁移的 KRaft 控制器的示例配置:
# Sample KRaft cluster controller.properties listening on 9093 process.roles=controller node.id=3000 controller.quorum.voters=3000@localhost:9093 controller.listener.names=CONTROLLER listeners=CONTROLLER://:9093 # Enable the migration zookeeper.metadata.migration.enable=true # ZooKeeper client configuration zookeeper.connect=localhost:2181 # Other configs ...
注意:KRaft 集群node.id
值必须与任何现有的 ZK 代理不同broker.id
。在 KRaft 模式中,代理和控制器共享相同的 Node ID 命名空间。
在代理上启用迁移
一旦 KRaft 控制器仲裁启动,代理将需要重新配置并重新启动。代理可以以滚动方式重新启动,以避免影响集群可用性。每个代理都需要以下配置才能与 KRaft 控制器通信并启用迁移。
- 控制器.quorum.voters
- 控制器.监听器.名称
- 还应将controller.listener.name添加到listener.security.property.map
- Zookeeper.metadata.migration.enable
以下是准备迁移的代理的示例配置:
# Sample ZK broker server.properties listening on 9092 broker.id=0 listeners=PLAINTEXT://:9092 advertised.listeners=PLAINTEXT://localhost:9092 listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT # Set the IBP inter.broker.protocol.version=3.5 # Enable the migration zookeeper.metadata.migration.enable=true # ZooKeeper client configuration zookeeper.connect=localhost:2181 # KRaft controller quorum configuration controller.quorum.voters=3000@localhost:9093 controller.listener.names=CONTROLLER
注意:使用必要的配置重新启动最终的 ZK 代理后,迁移将自动开始。 迁移完成后,在主控上可以观察到一条INFO级别的日志:
Completed migration of metadata from Zookeeper to KRaft
将代理迁移到 KRaft
一旦 KRaft 控制器完成元数据迁移,代理仍将以 ZK 模式运行。当 KRaft 控制器处于迁移模式时,它将继续向 ZK 模式代理发送控制器 RPC。这包括 UpdateMetadata 和 LeaderAndIsr 等 RPC。
要将代理迁移到 KRaft,只需将它们重新配置为 KRaft 代理并重新启动即可。以上面的代理配置为例,我们将替换broker.id
为node.id
并添加
process.roles=broker
。代理在重新启动时保持相同的代理/节点 ID 非常重要。此时应该删除 Zookeeper 配置。
# Sample KRaft broker server.properties listening on 9092 process.roles=broker node.id=0 listeners=PLAINTEXT://:9092 advertised.listeners=PLAINTEXT://localhost:9092 listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT # Don't set the IBP, KRaft uses "metadata.version" feature flag # inter.broker.protocol.version=3.5 # Remove the migration enabled flag # zookeeper.metadata.migration.enable=true # Remove ZooKeeper client configuration # zookeeper.connect=localhost:2181 # Keep the KRaft controller quorum configuration controller.quorum.voters=3000@localhost:9093 controller.listener.names=CONTROLLER
每个代理都会使用 KRaft 配置重新启动,直到整个集群在 KRaft 模式下运行。
完成迁移
在 KRaft 模式下重新启动所有代理后,完成迁移的最后一步是使 KRaft 控制器退出迁移模式。这是通过从每个配置中删除“zookeeper.metadata.migration.enable”属性并一次重新启动它们来完成的。
# Sample KRaft cluster controller.properties listening on 9093 process.roles=controller node.id=3000 controller.quorum.voters=3000@localhost:9093 controller.listener.names=CONTROLLER listeners=CONTROLLER://:9093 # Disable the migration # zookeeper.metadata.migration.enable=true # Remove ZooKeeper client configuration # zookeeper.connect=localhost:2181 # Other configs ...
6.11 分层存储
分层存储概述
Kafka 数据主要使用尾部读取以流方式消耗。尾部读取利用操作系统的页面缓存来提供数据,而不是磁盘读取。通常从磁盘读取较旧的数据用于回填或故障恢复目的,但这种情况并不常见。
在分层存储方法中,Kafka集群配置有两层存储——本地和远程。本地层与当前的Kafka相同,使用Kafka Broker上的本地磁盘来存储日志段。新的远程层使用外部存储系统(例如 HDFS 或 S3)来存储已完成的日志段。请查看KIP-405了解更多信息。
注意:分层存储被视为早期访问功能,不建议在生产环境中使用
配置
经纪商配置
默认情况下,Kafka服务器不会启用分层存储功能。remote.log.storage.system.enable
是控制是否在代理中启用分层存储功能的属性。将其设置为“true”可启用此功能。
RemoteStorageManager
是一个提供远程日志段和索引生命周期的接口。Kafka 服务器不提供 RemoteStorageManager 的现成实现。配置remote.log.storage.manager.class.name
并remote.log.storage.manager.class.path
指定 RemoteStorageManager 的实现。
RemoteLogMetadataManager
是一个接口,提供有关远程日志段的元数据生命周期,具有强一致的语义。默认情况下,Kafka提供了以存储为内部主题的实现。remote.log.metadata.manager.class.name
可以通过配置和来更改此实现
remote.log.metadata.manager.class.path
。当采用默认的基于 kafka 内部主题的实现时,remote.log.metadata.manager.listener.name
是一个强制属性,用于指定默认 RemoteLogMetadataManager 实现创建的客户端的侦听器。
主题配置
在正确配置了分层存储功能的代理端配置后,仍然需要设置主题级别的配置。
remote.storage.enable
是决定主题是否要使用分层存储的开关。默认情况下它设置为 false。启用remote.storage.enable
属性后,接下来要考虑的是日志保留。当为主题启用分层存储时,需要设置 2 个额外的日志保留配置:
local.retention.ms
retention.ms
local.retention.bytes
retention.bytes
local
用于指定“本地”日志文件在移动到远程存储之前可以接受的时间/大小,然后被删除。如果未设置,将使用
retention.ms
和中的值。retention.bytes
快速入门示例
Apache Kafka 不提供开箱即用的 RemoteStorageManager 实现。为了预览分层存储功能, 可以使用集成测试实现的 LocalTieredStorage ,它将在本地存储中创建一个临时目录来模拟远程存储。
要采用“LocalTieredStorage”,需要在本地构建测试库
# please checkout to the specific version tag you're using before building it # ex: `git checkout 3.6.0` ./gradlew clean :storage:testJar
构建成功后,storage/build/libs 下应该有一个 kafka-storage-xxx-test.jar 文件。接下来,在broker端设置配置以启用分层存储功能。
# Sample Zookeeper/Kraft broker server.properties listening on PLAINTEXT://:9092 remote.log.storage.system.enable=true # Setting the listener for the clients in RemoteLogMetadataManager to talk to the brokers. remote.log.metadata.manager.listener.name=PLAINTEXT # Please provide the implementation info for remoteStorageManager. # This is the mandatory configuration for tiered storage. # Here, we use the `LocalTieredStorage` built above. remote.log.storage.manager.class.name=org.apache.kafka.server.log.remote.storage.LocalTieredStorage remote.log.storage.manager.class.path=/PATH/TO/kafka-storage-x.x.x-test.jar # These 2 prefix are default values, but customizable remote.log.storage.manager.impl.prefix=rsm.config. remote.log.metadata.manager.impl.prefix=rlmm.config. # Configure the directory used for `LocalTieredStorage` # Note, please make sure the brokers need to have access to this directory rsm.config.dir=/tmp/kafka-remote-storage # This needs to be changed if number of brokers in the cluster is more than 1 rlmm.config.remote.log.metadata.topic.replication.factor=1 # Try to speed up the log retention check interval for testing log.retention.check.interval.ms=1000
按照快速入门指南启动 kafka 环境。然后,创建一个通过配置启用分层存储的主题:
# remote.storage.enable=true -> enables tiered storage on the topic # local.retention.ms=1000 -> The number of milliseconds to keep the local log segment before it gets deleted. Note that a local log segment is eligible for deletion only after it gets uploaded to remote. # retention.ms=3600000 -> when segments exceed this time, the segments in remote storage will be deleted # segment.bytes=1048576 -> for test only, to speed up the log segment rolling interval # file.delete.delay.ms=10000 -> for test only, to speed up the local-log segment file delete delay bin/kafka-topics.sh --create --topic tieredTopic --bootstrap-server localhost:9092 \ --config remote.storage.enable=true --config local.retention.ms=1000 --config retention.ms=3600000 \ --config segment.bytes=1048576 --config file.delete.delay.ms=1000
尝试向“tieredTopic”主题发送消息来滚动日志段:
bin/kafka-producer-perf-test.sh --topic tieredTopic --num-records 1200 --record-size 1024 --throughput -1 --producer-props bootstrap.servers=localhost:9092
然后,在滚动活动段后,应将旧段移动到远程存储并删除。这可以通过检查上面配置的远程日志目录来验证。例如:
> ls /tmp/kafka-remote-storage/kafka-tiered-storage/tieredTopic-0-jF8s79t9SrG_PNqlwv7bAA 00000000000000000000-knnxbs3FSRyKdPcSAOQC-w.index 00000000000000000000-knnxbs3FSRyKdPcSAOQC-w.snapshot 00000000000000000000-knnxbs3FSRyKdPcSAOQC-w.leader_epoch_checkpoint 00000000000000000000-knnxbs3FSRyKdPcSAOQC-w.timeindex 00000000000000000000-knnxbs3FSRyKdPcSAOQC-w.log
最后,我们可以尝试从头开始消耗一些数据并打印偏移量号,以确保它能够成功从远程存储中获取偏移量0。
bin/kafka-console-consumer.sh --topic tieredTopic --from-beginning --max-messages 1 --bootstrap-server localhost:9092 --property print.offset=true
请注意,如果您想在集群级别禁用分层存储,您应该显式删除启用分层存储的主题。尝试在集群级别禁用分层存储而不删除使用分层存储的主题将导致启动期间出现异常。
bin/kafka-topics.sh --delete --topic tieredTopic --bootstrap-server localhost:9092
删除主题后,您可以安全地remote.log.storage.system.enable=false
在代理配置中进行设置。
局限性
虽然分层存储的早期访问版本提供了尝试此新功能的机会,但重要的是要注意以下限制:
- 不支持具有多个日志目录的集群(即JBOD功能)
- 不支持压缩主题
- 无法在主题级别禁用分层存储
- 在代理级别禁用分层存储之前,需要删除启用分层存储的主题
- 仅 3.0 及以上版本的客户端支持与分层存储功能相关的管理操作
欲了解更多信息,请查看分层存储抢先体验发行说明。
7. 安全
7.1 安全概述
在版本 0.9.0.0 中,Kafka 社区添加了许多功能,这些功能单独或一起使用可以提高 Kafka 集群的安全性。目前支持以下安全措施:- 使用 SSL 或 SASL 对客户端(生产者和消费者)、其他代理和工具与代理的连接进行身份验证。Kafka支持以下SASL机制:
- SASL/GSSAPI (Kerberos) - 从版本 0.9.0.0 开始
- SASL/PLAIN - 从版本 0.10.0.0 开始
- SASL/SCRAM-SHA-256 和 SASL/SCRAM-SHA-512 - 从版本 0.10.2.0 开始
- SASL/OAUTHBEARER - 从版本 2.0 开始
- 从代理到 ZooKeeper 的连接身份验证
- 使用 SSL 对代理和客户端之间、代理之间或代理和工具之间传输的数据进行加密(请注意,启用 SSL 时会出现性能下降,其程度取决于 CPU 类型和 JVM 实现。)
- 客户端读/写操作的授权
- 授权可插拔,支持与外部授权服务集成
7.2 监听器配置
为了保护 Kafka 集群的安全,有必要保护用于与服务器通信的通道的安全。每个服务器必须定义一组侦听器,用于接收来自客户端以及其他服务器的请求。每个监听器可以被配置为使用各种机制来验证客户端并确保服务器和客户端之间的流量被加密。本节提供侦听器配置的入门知识。
Kafka 服务器支持侦听多个端口上的连接。这是通过listeners
服务器配置中的属性进行配置的,该属性接受要启用的侦听器的逗号分隔列表。每台服务器上必须至少定义一个侦听器。中定义的每个监听器的格式listeners
如下:
{LISTENER_NAME}://{hostname}:{port}
通常LISTENER_NAME
是一个描述性名称,定义了侦听器的目的。例如,许多配置对客户端流量使用单独的侦听器,因此它们可能会引用CLIENT
配置中相应的侦听器:
listeners=CLIENT://localhost:9092
每个侦听器的安全协议在单独的配置中定义:
listener.security.protocol.map
。该值是映射到其安全协议的每个侦听器的逗号分隔列表。例如,以下值配置指定CLIENT
侦听器将使用 SSL,而
BROKER
侦听器将使用明文。
listener.security.protocol.map=CLIENT:SSL,BROKER:PLAINTEXT
下面给出了安全协议的可能选项(不区分大小写):
- 纯文本
- SSL协议
- SASL_PLAINTEXT
- SASL_SSL
明文协议不提供安全性,并且不需要任何额外的配置。在以下部分中,本文档介绍了如何配置其余协议。
如果每个所需的侦听器使用单独的安全协议,也可以使用安全协议名称作为 中的侦听器名称listeners
。使用上面的示例,我们可以使用以下定义跳过CLIENT
和侦听器的定义:BROKER
listeners=SSL://localhost:9092,PLAINTEXT://localhost:9093
但是,我们建议用户为侦听器提供明确的名称,因为这样可以使每个侦听器的预期用途更加清晰。
inter.broker.listener.name
在此列表中的侦听器中,可以通过将配置设置为侦听器的名称来声明用于代理间通信的侦听器。代理间侦听器的主要目的是分区复制。如果未定义,则代理间侦听器由 定义的安全协议确定security.inter.broker.protocol
,默认为PLAINTEXT
。
对于依赖 Zookeeper 存储集群元数据的遗留集群,可以声明一个单独的侦听器,用于从活动控制器到代理的元数据传播。这是由 定义的control.plane.listener.name
。当活动控制器需要将元数据更新推送到集群中的代理时,它将使用此侦听器。使用控制平面侦听器的好处是它使用单独的处理线程,这使得应用程序流量不太可能阻碍元数据更改(例如分区领导者和 ISR 更新)的及时传播。请注意,默认值为 null,这意味着控制器将使用由inter.broker.listener
在 KRaft 集群中,代理是任何broker
启用了角色的服务器process.roles
,控制器是任何启用了controller
角色的服务器。侦听器配置取决于角色。定义的侦听器
inter.broker.listener.name
专门用于代理之间的请求。另一方面,控制器必须使用由
controller.listener.names
配置定义的单独侦听器。不能将其设置为与代理间侦听器相同的值。
控制器接收来自其他控制器和代理的请求。因此,即使服务器没有controller
启用该角色(即它只是一个代理),它仍然必须定义控制器侦听器以及配置它所需的任何安全属性。例如,我们可以在独立代理上使用以下配置:
process.roles=broker
listeners=BROKER://localhost:9092
inter.broker.listener.name=BROKER
controller.quorum.voters=0@localhost:9093
controller.listener.names=CONTROLLER
listener.security.protocol.map=BROKER:SASL_SSL,CONTROLLER:SASL_SSL
在此示例中,控制器侦听器仍配置为使用SASL_SSL
安全协议,但它未包含在其中,listeners
因为代理不公开控制器侦听器本身。在这种情况下将使用的端口来自controller.quorum.voters
配置,它定义了控制器的完整列表。
对于同时启用代理和控制器角色的 KRaft 服务器,配置类似。唯一的区别是控制器侦听器必须包含在
listeners
:
process.roles=broker,controller
listeners=BROKER://localhost:9092,CONTROLLER://localhost:9093
inter.broker.listener.name=BROKER
controller.quorum.voters=0@localhost:9093
controller.listener.names=CONTROLLER
listener.security.protocol.map=BROKER:SASL_SSL,CONTROLLER:SASL_SSL
要求定义的端口与controller.quorum.voters
公开的控制器侦听器之一完全匹配。例如,此处
CONTROLLER
侦听器绑定到端口 9093。 定义的连接字符串controller.quorum.voters
也必须使用端口 9093,如此处所示。
控制器将接受由 定义的所有侦听器上的请求controller.listener.names
。通常只有一个控制器侦听器,但也可以有更多。例如,这提供了一种通过集群滚动(一次滚动公开新监听器,一次滚动删除旧监听器)将活动侦听器从一个端口或安全协议更改为另一个端口或安全协议的方法。当定义了多个控制器侦听器时,列表中的第一个侦听器将用于出站请求。
在 Kafka 中,通常为客户端使用单独的侦听器。这允许集群间侦听器在网络级别进行隔离。对于 KRaft 中的控制器侦听器,侦听器应该被隔离,因为客户端无论如何都不使用它。客户端应该连接到代理上配置的任何其他侦听器。任何绑定到控制器的请求都将按如下所述 转发
在以下部分中,本文档介绍如何在侦听器上启用 SSL 进行加密和身份验证。后续部分将介绍使用 SASL 的其他身份验证机制。
7.3 使用 SSL 加密和验证
Apache Kafka 允许客户端使用 SSL 进行流量加密和身份验证。默认情况下,SSL 处于禁用状态,但可以根据需要打开。以下段落详细解释了如何设置您自己的 PKI 基础设施、使用它来创建证书以及配置 Kafka 以使用这些证书。为每个 Kafka 代理生成 SSL 密钥和证书
部署一个或多个支持 SSL 的代理的第一步是为每台服务器生成公钥/私钥对。由于 Kafka 希望所有密钥和证书都存储在密钥库中,因此我们将使用 Java 的 keytool 命令来完成此任务。该工具支持两种不同的密钥库格式:Java 特定的 jks 格式(现已弃用)以及 PKCS12。从 Java 版本 9 开始,PKCS12 是默认格式,为了确保无论使用哪个 Java 版本,都使用此格式,所有以下命令都显式指定 PKCS12 格式。
上述命令中需要指定两个参数:> keytool -keystore {keystorefile} -alias localhost -validity {validity} -genkey -keyalg RSA -storetype pkcs12
- keystorefile:存储此代理的密钥(以及后来的证书)的密钥库文件。密钥库文件包含该代理的私钥和公钥,因此需要保证其安全。理想情况下,此步骤在将使用密钥的 Kafka 代理上运行,因为该密钥永远不应该传输/离开其预期的服务器。
- 有效性:密钥的有效时间(以天为单位)。请注意,这与证书的有效期不同,证书的有效期将在签署证书中确定。您可以使用相同的密钥来请求多个证书:如果您的密钥的有效期为 10 年,但您的 CA 只会签署有效期为一年的证书,那么随着时间的推移,您可以对 10 个证书使用相同的密钥。
要获取可与刚刚创建的私钥一起使用的证书,需要创建证书签名请求。此签名请求由受信任的 CA 签名后会生成实际证书,然后可以将其安装在密钥库中并用于身份验证目的。
要生成证书签名请求,请对迄今为止创建的所有服务器密钥库运行以下命令。
该命令假设您想要将主机名信息添加到证书中,如果不是这种情况,您可以省略扩展参数> keytool -keystore server.keystore.jks -alias localhost -validity {validity} -genkey -keyalg RSA -destkeystoretype pkcs12 -ext SAN=DNS:{FQDN},IP:{IPADDRESS1}
-ext SAN=DNS:{FQDN},IP:{IPADDRESS1}
。请参阅下文了解更多相关信息。主机名验证
启用后,主机名验证是根据该服务器的实际主机名或 IP 地址检查您要连接的服务器提供的证书中的属性的过程,以确保您确实连接到正确的服务器。
进行此检查的主要原因是为了防止中间人攻击。对于 Kafka,此检查已默认禁用很长一段时间,但从 Kafka 2.0.0 开始,默认为客户端连接以及代理间连接启用服务器主机名验证。可以通过设置为空字符串来
禁用服务器主机名验证。 对于动态配置的代理侦听器,可以使用以下方法禁用主机名验证:ssl.endpoint.identification.algorithm
kafka-configs.sh
> bin/kafka-configs.sh --bootstrap-server localhost:9093 --entity-type brokers --entity-name 0 --alter --add-config "listener.name.internal.ssl.endpoint.identification.algorithm="
笔记:
通常,除了“让它正常工作”的最快方法之外,没有充分的理由禁用主机名验证,然后承诺“稍后有更多时间时修复它”!
如果在正确的时间完成正确的主机名验证并不那么困难,但一旦集群启动并运行就会变得更加困难 - 帮自己一个忙,现在就做!如果启用主机名验证,客户端将根据以下两个字段之一验证服务器的完全限定域名 (FQDN) 或 IP 地址:
- 通用名(中文)
- 主题备用名称 (SAN)
虽然 Kafka 检查这两个字段,但自 2000 年以来已弃用 使用通用名称字段进行主机名验证 ,并且应尽可能避免使用。此外,SAN 字段更加灵活,允许在证书中声明多个 DNS 和 IP 条目。
另一个优点是,如果 SAN 字段用于主机名验证,则可以将公用名称设置为更有意义的值以用于授权目的。由于我们需要将 SAN 字段包含在签名证书中,因此将在生成签名请求时指定该字段。也可以在生成密钥对时指定,但这不会自动复制到签名请求中。
要添加 SAN 字段,请将以下参数附加-ext SAN=DNS:{FQDN},IP:{IPADDRESS}
到 keytool 命令:> keytool -keystore server.keystore.jks -alias localhost -validity {validity} -genkey -keyalg RSA -destkeystoretype pkcs12 -ext SAN=DNS:{FQDN},IP:{IPADDRESS1}
创建您自己的 CA
在此步骤之后,集群中的每台计算机都拥有一个可用于加密流量的公钥/私钥对和一个证书签名请求,这是创建证书的基础。要添加身份验证功能,此签名请求需要由将在此步骤中创建的受信任机构进行签名。证书颁发机构 (CA) 负责签署证书。CA 的工作方式类似于颁发护照的政府 - 政府在每本护照上盖章(签名),以使护照难以伪造。其他政府会验证印章以确保护照的真实性。类似地,CA 对证书进行签名,并且密码学保证签名的证书在计算上难以伪造。因此,只要 CA 是真正且值得信赖的权威机构,客户端就可以强有力地保证他们正在连接到真实的机器。
对于本指南,我们将成为我们自己的证书颁发机构。在企业环境中设置生产集群时,这些证书通常由整个公司信任的企业 CA 签名。请参阅生产中的常见陷阱,了解这种情况下需要考虑的一些事项。
由于OpenSSL 中的错误,x509 模块不会将请求的扩展字段从 CSR 复制到最终证书中。由于我们希望 SAN 扩展出现在我们的证书中以启用主机名验证,因此我们将使用ca模块。这需要在生成 CA 密钥对之前进行一些额外的配置。
将以下列表保存到名为 openssl-ca.cnf 的文件中,并根据需要调整有效性和通用属性的值。
然后创建数据库和序列号文件,这些文件将用于跟踪使用该 CA 签署的证书。这两个文件都是简单的文本文件,与您的 CA 密钥位于同一目录中。HOME = . RANDFILE = $ENV::HOME/.rnd #################################################################### [ ca ] default_ca = CA_default # The default ca section [ CA_default ] base_dir = . certificate = $base_dir/cacert.pem # The CA certificate private_key = $base_dir/cakey.pem # The CA private key new_certs_dir = $base_dir # Location for new certs after signing database = $base_dir/index.txt # Database index file serial = $base_dir/serial.txt # The current serial number default_days = 1000 # How long to certify for default_crl_days = 30 # How long before next CRL default_md = sha256 # Use public key default MD preserve = no # Keep passed DN ordering x509_extensions = ca_extensions # The extensions to add to the cert email_in_dn = no # Don't concat the email in the DN copy_extensions = copy # Required to copy SANs from CSR to cert #################################################################### [ req ] default_bits = 4096 default_keyfile = cakey.pem distinguished_name = ca_distinguished_name x509_extensions = ca_extensions string_mask = utf8only #################################################################### [ ca_distinguished_name ] countryName = Country Name (2 letter code) countryName_default = DE stateOrProvinceName = State or Province Name (full name) stateOrProvinceName_default = Test Province localityName = Locality Name (eg, city) localityName_default = Test Town organizationName = Organization Name (eg, company) organizationName_default = Test Company organizationalUnitName = Organizational Unit (eg, division) organizationalUnitName_default = Test Unit commonName = Common Name (e.g. server FQDN or YOUR name) commonName_default = Test Name emailAddress = Email Address emailAddress_default = test@test.com #################################################################### [ ca_extensions ] subjectKeyIdentifier = hash authorityKeyIdentifier = keyid:always, issuer basicConstraints = critical, CA:true keyUsage = keyCertSign, cRLSign #################################################################### [ signing_policy ] countryName = optional stateOrProvinceName = optional localityName = optional organizationName = optional organizationalUnitName = optional commonName = supplied emailAddress = optional #################################################################### [ signing_req ] subjectKeyIdentifier = hash authorityKeyIdentifier = keyid,issuer basicConstraints = CA:FALSE keyUsage = digitalSignature, keyEncipherment
完成这些步骤后,您现在就可以生成 CA,稍后将使用该 CA 来签署证书。> echo 01 > serial.txt > touch index.txt
CA 只是一个由自身签名的公钥/私钥对和证书,仅用于签署其他证书。> openssl req -x509 -config openssl-ca.cnf -newkey rsa:4096 -sha256 -nodes -out cacert.pem -outform PEM
该密钥对应该保持非常安全,如果有人访问它,他们可以创建并签署您的基础设施信任的证书,这意味着他们在连接到信任该 CA 的任何服务时将能够冒充任何人。
下一步是将生成的 CA 添加到 **客户端的信任库**,以便客户端可以信任此 CA:
注意: 如果您通过在 Kafka 代理配置中将 ssl.client.auth 设置为“请求”或“必需”来将 Kafka 代理配置为需要客户端身份验证,那么您还必须为 Kafka 代理提供一个信任库,并且它应该包含所有内容签署客户端密钥的 CA 证书。> keytool -keystore client.truststore.jks -alias CARoot -import -file ca-cert
与步骤 1 中存储每台计算机自己的身份的密钥库不同,客户端的信任库存储客户端应该信任的所有证书。将证书导入到信任库中还意味着信任由该证书签名的所有证书。正如上面的类比,信任政府(CA)也意味着信任其颁发的所有护照(证书)。该属性称为信任链,在大型 Kafka 集群上部署 SSL 时特别有用。您可以使用单个 CA 签署集群中的所有证书,并让所有计算机共享信任该 CA 的同一信任库。这样所有机器都可以验证所有其他机器。> keytool -keystore server.truststore.jks -alias CARoot -import -file ca-cert
签署证书
然后使用 CA 对其进行签名:
最后,您需要将 CA 的证书和签名的证书导入密钥库:> openssl ca -config openssl-ca.cnf -policy signing_policy -extensions signing_req -out {server certificate} -infiles {certificate signing request}
参数定义如下:> keytool -keystore {keystore} -alias CARoot -import -file {CA certificate} > keytool -keystore {keystore} -alias localhost -import -file cert-signed
- keystore:密钥库的位置
- CA证书:CA的证书
- 证书签名请求:使用服务器密钥创建的 csr
- 服务器证书:用于写入服务器签名证书的文件
此外,每个节点都会有一个server.keystore.jks文件,其中包含节点密钥、证书和 CA 证书,请参阅配置 Kafka 代理和配置 Kafka 客户端 以获取有关如何使用这些文件的信息。有关此主题的一些工具帮助,请查看easyRSA项目,该项目具有丰富的脚本来帮助完成这些步骤。
PEM 格式的 SSL 密钥和证书
从 2.7.0 开始,可以直接在 PEM 格式的配置中为 Kafka 代理和客户端配置 SSL 密钥和信任存储。这避免了在文件系统上存储单独文件的需要,并受益于 Kafka 配置的密码保护功能。除了 JKS 和 PKCS12 之外,PEM 还可以用作基于文件的密钥和信任存储的存储类型。要直接在代理或客户端配置中配置 PEM 密钥存储,应在 中提供 PEM 格式的私钥,ssl.keystore.key
并应在 中提供 PEM 格式的证书链ssl.keystore.certificate.chain
。要配置信任存储,应在 中提供信任证书,例如 CA 的公共证书ssl.truststore.certificates
。由于 PEM 通常存储为多行 base-64 字符串,因此配置值可以作为多行字符串包含在 Kafka 配置中,其中行以反斜杠 ('\') 结尾以继续行。存储密码配置
ssl.keystore.password
,ssl.truststore.password
不用于 PEM。如果私钥使用密码加密,则必须在 中提供密钥密码ssl.key.password
。私钥可以以未加密的形式提供,无需密码。在生产部署中,在这种情况下,应使用 Kafka 中的密码保护功能对配置进行加密或外部化。请注意,当使用 OpenSSL 等外部工具进行加密时,默认 SSL 引擎工厂对加密私钥的解密功能有限。BouncyCastle 等第三方库可以与自定义集成,SslEngineFactory
以支持更广泛的加密私钥。生产中常见的陷阱
上面的段落展示了创建您自己的 CA 并使用它为您的集群签署证书的过程。虽然对于沙箱、开发、测试和类似系统非常有用,但这通常不是在企业环境中为生产集群创建证书的正确过程。企业通常会运营自己的CA,用户可以发送CSR来与该CA签署,这样做的好处是用户无需负责保证CA的安全,并且有一个每个人都可以信任的中央权威。然而,它也剥夺了用户对证书签名过程的很多控制权。通常,运营公司 CA 的人员会对证书施加严格的限制,这在尝试将这些证书与 Kafka 一起使用时可能会导致问题。- 扩展密钥使用
证书可能包含控制证书使用目的的扩展字段。如果此字段为空,则对使用没有限制,但如果此处指定了任何使用,则有效的 SSL 实现必须强制执行这些使用。
Kafka的相关用法有:- 客户端认证
- 服务器认证
- 出于安全原因,中间证书
企业根 CA 通常保持离线状态。为了实现日常使用,创建了所谓的中间 CA,然后使用它们来签署最终证书。将由中间 CA 签名的证书导入密钥库时,有必要提供直至根 CA 的整个信任链。只需将证书文件合并到一个组合证书文件中,然后使用 keytool 导入该文件即可完成此操作。 - 无法复制扩展字段
CA 运营商通常不愿意从 CSR 复制和请求扩展字段,而是更愿意自己指定这些字段,因为这使得恶意方更难获取具有潜在误导性或欺诈性值的证书。建议仔细检查签名证书,这些证书是否包含所有请求的 SAN 字段以启用正确的主机名验证。以下命令可用于将证书详细信息打印到控制台,该详细信息应与最初请求的内容进行比较:> openssl x509 -in certificate.crt -text -noout
- 扩展密钥使用
配置 Kafka 代理
如果没有为代理间通信启用 SSL(请参阅下文了解如何启用它),则 PLAINTEXT 和 SSL 端口都是必需的。
代理端需要以下 SSL 配置listeners=PLAINTEXT://host.name:port,SSL://host.name:port
注意:ssl.truststore.password 在技术上是可选的,但强烈建议使用。如果未设置密码,仍然可以访问信任库,但完整性检查将被禁用。值得考虑的可选设置:ssl.keystore.location=/var/private/ssl/server.keystore.jks ssl.keystore.password=test1234 ssl.key.password=test1234 ssl.truststore.location=/var/private/ssl/server.truststore.jks ssl.truststore.password=test1234
- ssl.client.auth=none (“required”=> 需要客户端身份验证,“requested”=> 请求客户端身份验证,没有证书的客户端仍然可以连接。不鼓励使用“requested”,因为它提供了一种错误的感觉安全性和配置错误的客户端仍将成功连接。)
- ssl.cipher.suites(可选)。密码套件是身份验证、加密、MAC 和密钥交换算法的命名组合,用于协商使用 TLS 或 SSL 网络协议的网络连接的安全设置。(默认为空列表)
- ssl.enabled.protocols=TLSv1.2,TLSv1.1,TLSv1(列出您要从客户端接受的 SSL 协议。请注意,SSL 已被弃用,取而代之的是 TLS,并且不建议在生产中使用 SSL)
- ssl.keystore.type=JKS
- ssl.truststore.type=JKS
- ssl.secure.random.implementation=SHA1PRNG
security.inter.broker.protocol=SSL
由于某些国家/地区的进口法规,Oracle 实施限制了默认情况下可用的加密算法的强度。如果需要更强的算法(例如,具有 256 位密钥的 AES),则必须获取JCE 无限强度管辖策略文件并将其安装在 JDK/JRE 中。有关详细信息, 请参阅 JCA 提供商文档。
JRE/JDK 将有一个默认的伪随机数生成器 (PRNG),用于加密操作,因此不需要配置
启动代理后,您应该能够在 server.log 中看到ssl.secure.random.implementation
. 然而,某些实现存在性能问题(特别是,Linux 系统上默认选择的,NativePRNG
使用全局锁)。如果 SSL 连接的性能成为问题,请考虑显式设置要使用的实现。该SHA1PRNG
实现是非阻塞的,并且在重负载(50 MB/秒生成的消息,加上每个代理的复制流量)下表现出了非常好的性能特征。
要快速检查服务器密钥库和信任库是否设置正确,您可以运行以下命令with addresses: PLAINTEXT -> EndPoint(192.168.64.1,9092,PLAINTEXT),SSL -> EndPoint(192.168.64.1,9093,SSL)
(注意:TLSv1 应列在 ssl.enabled.protocols 下)> openssl s_client -debug -connect localhost:9093 -tls1
在此命令的输出中,您应该看到服务器的证书:
如果证书未显示或存在任何其他错误消息,则说明您的密钥库设置不正确。-----BEGIN CERTIFICATE----- {variable sized random bytes} -----END CERTIFICATE----- subject=/C=US/ST=CA/L=Santa Clara/O=org/OU=org/CN=Sriharsha Chintalapani issuer=/C=US/ST=CA/L=Santa Clara/O=org/OU=org/CN=kafka/emailAddress=test@test.com
配置 Kafka 客户端
仅新的 Kafka Producer 和 Consumer 支持 SSL,不支持旧的 API。SSL 配置对于生产者和消费者来说都是相同的。
如果代理中不需要客户端身份验证,则以下是最小配置示例:
注意:ssl.truststore.password 在技术上是可选的,但强烈建议使用。如果未设置密码,仍然可以访问信任库,但完整性检查将被禁用。如果需要客户端身份验证,则必须像步骤 1 中那样创建密钥库,并且还必须配置以下内容:security.protocol=SSL ssl.truststore.location=/var/private/ssl/client.truststore.jks ssl.truststore.password=test1234
根据我们的要求和代理配置,可能还需要其他配置设置:ssl.keystore.location=/var/private/ssl/client.keystore.jks ssl.keystore.password=test1234 ssl.key.password=test1234
- ssl.provider(可选)。用于 SSL 连接的安全提供程序的名称。默认值是 JVM 的默认安全提供程序。
- ssl.cipher.suites(可选)。密码套件是身份验证、加密、MAC 和密钥交换算法的命名组合,用于协商使用 TLS 或 SSL 网络协议的网络连接的安全设置。
- ssl.enabled.protocols=TLSv1.2、TLSv1.1、TLSv1。它应该至少列出代理端配置的协议之一
- ssl.truststore.type=JKS
- ssl.keystore.type=JKS
使用控制台生产者和控制台消费者的示例:> kafka-console-producer.sh --bootstrap-server localhost:9093 --topic test --producer.config client-ssl.properties > kafka-console-consumer.sh --bootstrap-server localhost:9093 --topic test --consumer.config client-ssl.properties
7.4 使用 SASL 进行身份验证
JAAS配置
Kafka 使用 Java 身份验证和授权服务 ( JAAS ) 进行 SASL 配置。
Kafka 代理的 JAAS 配置
KafkaServer是每个 KafkaServer/Broker 使用的 JAAS 文件中的部分名称。本部分为代理提供 SASL 配置选项,包括代理为代理间通信而建立的任何 SASL 客户端连接。如果将多个侦听器配置为使用 SASL,则部分名称可以以小写侦听器名称为前缀,后跟句点,例如sasl_ssl.KafkaServer。
客户端部分用于验证与 Zookeeper 的 SASL 连接。它还允许代理在 Zookeeper 节点上设置 SASL ACL,从而锁定这些节点,以便只有代理可以修改它。所有经纪商必须具有相同的主体名称。如果要使用除 Client 之外的节名称,请将系统属性Zookeeper.sasl.clientconfig设置为适当的名称(例如-Dzookeeper.sasl.clientconfig =ZkClient)。
ZooKeeper 默认使用“zookeeper”作为服务名称。如果要更改此设置,请将系统属性 Zookeeper.sasl.client.username设置为适当的名称(例如-Dzookeeper.sasl.client.username =zk)。
代理还可以使用代理配置属性来配置 JAAS
sasl.jaas.config
。属性名称必须以侦听器前缀(包括 SASL 机制)作为前缀,即listener.name.{listenerName}.{saslMechanism}.sasl.jaas.config
. 配置值中只能指定一个登录模块。如果在侦听器上配置了多个机制,则必须使用侦听器和机制前缀为每个机制提供配置。例如,
如果在不同级别定义 JAAS 配置,则使用的优先顺序为:listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \ username="admin" \ password="admin-secret"; listener.name.sasl_ssl.plain.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \ username="admin" \ password="admin-secret" \ user_admin="admin-secret" \ user_alice="alice-secret";
- 代理配置属性
listener.name.{listenerName}.{saslMechanism}.sasl.jaas.config
{listenerName}.KafkaServer
静态 JAAS 配置部分KafkaServer
静态 JAAS 配置部分
有关代理配置示例,请参阅GSSAPI (Kerberos)、 PLAIN、 SCRAM或 OAUTHBEARER 。
- 代理配置属性
Kafka 客户端的 JAAS 配置
客户端可以使用客户端配置属性 sasl.jaas.config 或使用 类似于代理的静态 JAAS 配置文件来配置 JAAS。
使用客户端配置属性的 JAAS 配置
客户端可以将 JAAS 配置指定为生产者或消费者属性,而无需创建物理配置文件。此模式还允许同一 JVM 中的不同生产者和消费者通过为每个客户端指定不同的属性来使用不同的凭据。如果同时指定了静态 JAAS 配置系统属性
java.security.auth.login.config
和客户端属性sasl.jaas.config
,则将使用客户端属性。有关示例配置,请参阅GSSAPI (Kerberos)、 PLAIN、 SCRAM或 OAUTHBEARER 。
使用静态配置文件的 JAAS 配置
要使用静态 JAAS 配置文件在客户端上配置 SASL 身份验证:- 添加一个 JAAS 配置文件,其中包含名为KafkaClient的客户端登录部分。在KafkaClient中为所选机制配置登录模块,如设置GSSAPI (Kerberos)、
PLAIN、
SCRAM或
OAUTHBEARER的示例中所述。例如,GSSAPI
凭证可以配置为:
KafkaClient { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true storeKey=true keyTab="/etc/security/keytabs/kafka_client.keytab" principal="kafka-client-1@EXAMPLE.COM"; };
- 将 JAAS 配置文件位置作为 JVM 参数传递给每个客户端 JVM。例如:
-Djava.security.auth.login.config=/etc/kafka/kafka_client_jaas.conf
- 添加一个 JAAS 配置文件,其中包含名为KafkaClient的客户端登录部分。在KafkaClient中为所选机制配置登录模块,如设置GSSAPI (Kerberos)、
PLAIN、
SCRAM或
OAUTHBEARER的示例中所述。例如,GSSAPI
凭证可以配置为:
SASL configuration
SASL 可以与 PLAINTEXT 或 SSL 一起使用,作为分别使用安全协议 SASL_PLAINTEXT 或 SASL_SSL 的传输层。如果使用SASL_SSL,则还必须配置SSL。
SASL机制
Kafka支持以下SASL机制:- GSSAPI(Kerberos)
- 清楚的
- SCRAM-SHA-256
- SCRAM-SHA-512
- 承载者
Kafka 代理的 SASL 配置
- 在 server.properties 中配置 SASL 端口,方法是将 SASL_PLAINTEXT 或 SASL_SSL 至少之一添加到listeners参数,该参数包含一个或多个逗号分隔值:
listeners=SASL_PLAINTEXT://host.name:port
security.inter.broker.protocol=SASL_PLAINTEXT (or SASL_SSL)
- 选择 要在代理中启用的一种或多种受支持的机制,并按照步骤为该机制配置 SASL。要在代理中启用多种机制,请按照此处的步骤操作 。
- 在 server.properties 中配置 SASL 端口,方法是将 SASL_PLAINTEXT 或 SASL_SSL 至少之一添加到listeners参数,该参数包含一个或多个逗号分隔值:
Kafka 客户端的 SASL 配置
仅新的 Java Kafka 生产者和消费者支持 SASL 身份验证,不支持旧的 API。
要在客户端上配置 SASL 身份验证,请选择 在代理中启用的SASL机制以进行客户端身份验证,然后按照步骤为所选机制配置 SASL。
注意:当通过 SASL 建立与代理的连接时,客户端可以对代理地址执行反向 DNS 查找。由于 JRE 实现反向 DNS 查找的方式,如果未使用完全限定的域名(对于客户端
bootstrap.servers
和代理的advertised.listeners
.
Authentication using SASL/Kerberos
先决条件
- Kerberos
如果您的组织已经使用 Kerberos 服务器(例如,通过使用 Active Directory),则无需仅为 Kafka 安装新服务器。否则,您将需要安装一个,您的 Linux 供应商可能有 Kerberos 软件包以及有关如何安装和配置它的简短指南(Ubuntu、Redhat)。请注意,如果您使用 Oracle Java,则需要下载适合您的 Java 版本的 JCE 策略文件并将其复制到 $JAVA_HOME/jre/lib/security。 - 创建 Kerberos 主体
如果您使用组织的 Kerberos 或 Active Directory 服务器,请向 Kerberos 管理员询问集群中每个 Kafka 代理以及将使用 Kerberos 身份验证(通过客户端和工具)访问 Kafka 的每个操作系统用户的主体。
如果您安装了自己的 Kerberos,则需要使用以下命令自行创建这些主体:> sudo /usr/sbin/kadmin.local -q 'addprinc -randkey kafka/{hostname}@{REALM}' > sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{keytabname}.keytab kafka/{hostname}@{REALM}"
- 确保可以使用主机名访问所有主机- Kerberos 要求所有主机都可以使用其 FQDN 进行解析。
- Kerberos
配置 Kafka 代理
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在本示例中我们将其称为 kafka_server_jaas.conf(请注意,每个代理应该有自己的密钥表):
JAAS 文件中的KafkaServer部分告诉代理要使用哪个主体以及存储该主体的密钥表的位置。它允许代理使用本节中指定的密钥表登录。有关 Zookeeper SASL 配置的更多详细信息, 请参阅注释。KafkaServer { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true storeKey=true keyTab="/etc/security/keytabs/kafka_server.keytab" principal="kafka/kafka1.hostname.com@EXAMPLE.COM"; }; // Zookeeper client authentication Client { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true storeKey=true keyTab="/etc/security/keytabs/kafka_server.keytab" principal="kafka/kafka1.hostname.com@EXAMPLE.COM"; };
- 将 JAAS 和可选的 krb5 文件位置作为 JVM 参数传递给每个 Kafka 代理(请参阅此处了解更多详细信息):
-Djava.security.krb5.conf=/etc/kafka/krb5.conf -Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf
- 确保启动 kafka 代理的操作系统用户可以读取 JAAS 文件中配置的密钥表。
- 按照此处所述在 server.properties 中配置 SASL 端口和 SASL 机制。例如:
我们还必须在 server.properties 中配置服务名称,该名称应与 kafka 代理的主体名称匹配。在上面的示例中,主体是“kafka/kafka1.hostname.com@EXAMPLE.com”,因此:listeners=SASL_PLAINTEXT://host.name:port security.inter.broker.protocol=SASL_PLAINTEXT sasl.mechanism.inter.broker.protocol=GSSAPI sasl.enabled.mechanisms=GSSAPI
sasl.kerberos.service.name=kafka
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在本示例中我们将其称为 kafka_server_jaas.conf(请注意,每个代理应该有自己的密钥表):
配置 Kafka 客户端
要在客户端上配置 SASL 身份验证:-
客户端(生产者、消费者、连接工作人员等)将使用自己的主体(通常与运行客户端的用户同名)向集群进行身份验证,因此根据需要获取或创建这些主体。然后为每个客户端配置 JAAS 配置属性。JVM 中的不同客户端可以通过指定不同的主体以不同的用户身份运行。Producer.properties 或 Consumer.properties 中的属性
sasl.jaas.config
描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是使用密钥表的客户端的示例配置(建议用于长时间运行的进程):
对于 kafka-console-consumer 或 kafka-console- Producer 等命令行实用程序, kinit 可以与“useTicketCache = true”一起使用,如下所示:sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required \ useKeyTab=true \ storeKey=true \ keyTab="/etc/security/keytabs/kafka_client.keytab" \ principal="kafka-client-1@EXAMPLE.COM";
客户端的 JAAS 配置也可以指定为类似于代理的 JVM 参数,如此处所述。客户端使用名为KafkaClient的登录部分 。此选项仅允许一名用户进行来自 JVM 的所有客户端连接。sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required \ useTicketCache=true;
- 确保启动 kafka 客户端的操作系统用户可以读取 JAAS 配置中配置的密钥表。
- (可选)将 krb5 文件位置作为 JVM 参数传递给每个客户端 JVM(请参阅此处了解更多详细信息):
-Djava.security.krb5.conf=/etc/kafka/krb5.conf
- 在 Producer.properties 或 Consumer.properties 中配置以下属性:
security.protocol=SASL_PLAINTEXT (or SASL_SSL) sasl.mechanism=GSSAPI sasl.kerberos.service.name=kafka
-
客户端(生产者、消费者、连接工作人员等)将使用自己的主体(通常与运行客户端的用户同名)向集群进行身份验证,因此根据需要获取或创建这些主体。然后为每个客户端配置 JAAS 配置属性。JVM 中的不同客户端可以通过指定不同的主体以不同的用户身份运行。Producer.properties 或 Consumer.properties 中的属性
Authentication using SASL/PLAIN
SASL/PLAIN是一种简单的用户名/密码认证机制,通常与TLS结合使用进行加密,实现安全认证。Kafka 支持 SASL/PLAIN 的默认实现,可以将其扩展到生产用途,如此处所述。
在默认实现下principal.builder.class
,用户名用作Principal
ACL 等配置的 身份验证。配置 Kafka 代理
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在此示例中我们将其称为 kafka_server_jaas.conf:
此配置定义了两个用户(admin和alice)。KafkaServer部分 中的属性用户名和密码由代理用来启动与其他代理的连接。在此示例中, admin是经纪商间通信的用户。属性集user_ userName定义连接到代理的所有用户的密码,并且代理使用这些属性验证所有客户端连接,包括来自其他代理的连接。KafkaServer { org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="admin-secret" user_admin="admin-secret" user_alice="alice-secret"; };
- 将 JAAS 配置文件位置作为 JVM 参数传递给每个 Kafka 代理:
-Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf
- 按照此处所述在 server.properties 中配置 SASL 端口和 SASL 机制。例如:
listeners=SASL_SSL://host.name:port security.inter.broker.protocol=SASL_SSL sasl.mechanism.inter.broker.protocol=PLAIN sasl.enabled.mechanisms=PLAIN
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在此示例中我们将其称为 kafka_server_jaas.conf:
配置 Kafka 客户端
要在客户端上配置 SASL 身份验证:- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是 PLAIN 机制的客户端配置示例:
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \ username="alice" \ password="alice-secret";
客户端使用用户名和密码选项来配置客户端连接的用户。在此示例中,客户端以用户alice的身份连接到代理。JVM 中的不同客户端可以通过在
sasl.jaas.config
.客户端的 JAAS 配置也可以指定为类似于代理的 JVM 参数,如此处所述。客户端使用名为KafkaClient的登录部分 。此选项仅允许一名用户进行来自 JVM 的所有客户端连接。
- 在 Producer.properties 或 Consumer.properties 中配置以下属性:
security.protocol=SASL_SSL sasl.mechanism=PLAIN
- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是 PLAIN 机制的客户端配置示例:
在生产中使用 SASL/PLAIN
- SASL/PLAIN 只能与 SSL 一起使用作为传输层,以确保明文密码不会在未经加密的情况下在线路上传输。
- Kafka 中 SASL/PLAIN 的默认实现在 JAAS 配置文件中指定用户名和密码,如下
所示。
sasl.server.callback.handler.class
从 Kafka 2.0 版本开始,您可以通过配置自己的回调处理程序来避免在磁盘上存储明文密码,这些回调处理程序使用配置选项和来从外部源获取用户名和密码sasl.client.callback.handler.class
。 - 在生产系统中,外部认证服务器可以实现密码认证。从 Kafka 2.0 版开始,您可以插入自己的回调处理程序,通过配置
sasl.server.callback.handler.class
.
Authentication using SASL/SCRAM
Salted 质询响应身份验证机制 (SCRAM) 是一系列 SASL 机制,可解决执行用户名/密码身份验证(例如 PLAIN 和 DIGEST-MD5)的传统机制的安全问题。该机制在RFC 5802中定义。Kafka支持SCRAM-SHA-256和SCRAM-SHA-512,可以与TLS结合使用来执行安全身份验证。在默认实现下
principal.builder.class
,用户名用作Principal
ACL 等配置的身份验证。Kafka 中的默认 SCRAM 实现将 SCRAM 凭证存储在 Zookeeper 中,适合在 Zookeeper 位于专用网络上的 Kafka 安装中使用。 有关更多详细信息,请参阅安全注意事项。创建 SCRAM 凭证
Kafka 中的 SCRAM 实现使用 Zookeeper 作为凭证存储。可以使用kafka-configs.sh在 Zookeeper 中创建凭证。对于启用的每个 SCRAM 机制,必须通过添加具有机制名称的配置来创建凭据。必须在启动 Kafka 代理之前创建代理间通信的凭证。可以动态创建和更新客户端凭证,并且更新的凭证将用于验证新连接。
使用密码alice-secret为用户alice创建 SCRAM 凭证:
> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --alter --add-config 'SCRAM-SHA-256=[iterations=8192,password=alice-secret],SCRAM-SHA-512=[password=alice-secret]' --entity-type users --entity-name alice
如果未指定迭代,则使用默认迭代计数 4096。创建随机盐,并将由盐、迭代、StoredKey 和 ServerKey 组成的 SCRAM 身份存储在 Zookeeper 中。有关 SCRAM 身份和各个字段的详细信息, 请参阅RFC 5802 。
以下示例还需要用户管理员进行代理间通信,可以使用以下命令创建:
> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --alter --add-config 'SCRAM-SHA-256=[password=admin-secret],SCRAM-SHA-512=[password=admin-secret]' --entity-type users --entity-name admin
可以使用--describe选项列出现有凭据:
> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --describe --entity-type users --entity-name alice
可以使用--alter --delete-config选项删除一种或多种 SCRAM 机制的凭证:
> bin/kafka-configs.sh --zookeeper localhost:2182 --zk-tls-config-file zk_tls_config.properties --alter --delete-config 'SCRAM-SHA-512' --entity-type users --entity-name alice
配置 Kafka 代理
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在此示例中我们将其称为 kafka_server_jaas.conf:
KafkaServer部分中的 属性用户名和密码由代理用来启动与其他代理的连接。在此示例中,admin是经纪商间通信的用户。KafkaServer { org.apache.kafka.common.security.scram.ScramLoginModule required username="admin" password="admin-secret"; };
- 将 JAAS 配置文件位置作为 JVM 参数传递给每个 Kafka 代理:
-Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf
- 按照此处所述在 server.properties 中配置 SASL 端口和 SASL 机制。例如:
listeners=SASL_SSL://host.name:port security.inter.broker.protocol=SASL_SSL sasl.mechanism.inter.broker.protocol=SCRAM-SHA-256 (or SCRAM-SHA-512) sasl.enabled.mechanisms=SCRAM-SHA-256 (or SCRAM-SHA-512)
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在此示例中我们将其称为 kafka_server_jaas.conf:
配置 Kafka 客户端
要在客户端上配置 SASL 身份验证:- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是 SCRAM 机制的客户端配置示例:
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \ username="alice" \ password="alice-secret";
客户端使用用户名和密码选项来配置客户端连接的用户。在此示例中,客户端以用户alice的身份连接到代理。JVM 中的不同客户端可以通过在
sasl.jaas.config
.客户端的 JAAS 配置也可以指定为类似于代理的 JVM 参数,如此处所述。客户端使用名为KafkaClient的登录部分 。此选项仅允许一名用户进行来自 JVM 的所有客户端连接。
- 在 Producer.properties 或 Consumer.properties 中配置以下属性:
security.protocol=SASL_SSL sasl.mechanism=SCRAM-SHA-256 (or SCRAM-SHA-512)
- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是 SCRAM 机制的客户端配置示例:
SASL/SCRAM 的安全注意事项
- Kafka 中 SASL/SCRAM 的默认实现将 SCRAM 凭证存储在 Zookeeper 中。这适用于 Zookeeper 安全且位于专用网络上的安装中的生产使用。
- Kafka 仅支持强哈希函数 SHA-256 和 SHA-512,最小迭代次数为 4096。强哈希函数与强密码和高迭代次数相结合,可以在 Zookeeper 安全性受到损害时防止暴力攻击。
- SCRAM 应仅与 TLS 加密一起使用,以防止 SCRAM 交换被拦截。这可以防止字典或暴力攻击,并在 Zookeeper 受到威胁时防止假冒。
sasl.server.callback.handler.class
从 Kafka 2.0 版开始,可以通过在 Zookeeper 不安全的安装中进行配置,使用自定义回调处理程序覆盖默认 SASL/SCRAM 凭证存储。- 有关安全注意事项的更多详细信息,请参阅 RFC 5802。
Authentication using SASL/OAUTHBEARER
OAuth 2 授权框架“使第三方应用程序能够代表资源所有者通过协调资源所有者和 HTTP 服务之间的批准交互,或者通过允许第三方应用程序获得对 HTTP 服务的有限访问权限。以自己的名义获得访问权限。” SASL OAUTHBEARER 机制允许在 SASL(即非 HTTP)上下文中使用该框架;它在RFC 7628中定义。Kafka 中的默认 OAUTHBEARER 实现创建并验证不安全的 JSON Web 令牌 ,并且仅适合在非生产 Kafka 安装中使用。 有关更多详细信息,请参阅安全注意事项。
在默认实现下principal.builder.class
,OAuthBearerToken的principalName用作Principal
ACL等配置的身份 验证。配置 Kafka 代理
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在此示例中我们将其称为 kafka_server_jaas.conf:
KafkaServer部分中的 属性unsecuredLoginStringClaim_sub由代理在启动与其他代理的连接时使用。在此示例中,admin将出现在主题 ( sub ) 声明中,并将成为经纪人间通信的用户。KafkaServer { org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required unsecuredLoginStringClaim_sub="admin"; };
- 将 JAAS 配置文件位置作为 JVM 参数传递给每个 Kafka 代理:
-Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf
- 按照此处所述在 server.properties 中配置 SASL 端口和 SASL 机制。例如:
listeners=SASL_SSL://host.name:port (or SASL_PLAINTEXT if non-production) security.inter.broker.protocol=SASL_SSL (or SASL_PLAINTEXT if non-production) sasl.mechanism.inter.broker.protocol=OAUTHBEARER sasl.enabled.mechanisms=OAUTHBEARER
- 将一个经过适当修改的 JAAS 文件(类似于下面的文件)添加到每个 Kafka 代理的配置目录中,在此示例中我们将其称为 kafka_server_jaas.conf:
配置 Kafka 客户端
要在客户端上配置 SASL 身份验证:- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是 OAUTHBEARER 机制的客户端配置示例:
sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \ unsecuredLoginStringClaim_sub="alice";
客户端使用选项unsecuredLoginStringClaim_sub来配置主题 ( sub ) 声明,该声明确定客户端连接的用户。在此示例中,客户端以用户alice的身份连接到代理。JVM 中的不同客户端可以通过在 中指定不同的主题 ( sub ) 声明来作为不同用户进行连接
sasl.jaas.config
。客户端的 JAAS 配置也可以指定为类似于代理的 JVM 参数,如此处所述。客户端使用名为KafkaClient的登录部分 。此选项仅允许一名用户进行来自 JVM 的所有客户端连接。
- 在 Producer.properties 或 Consumer.properties 中配置以下属性:
security.protocol=SASL_SSL (or SASL_PLAINTEXT if non-production) sasl.mechanism=OAUTHBEARER
- SASL/OAUTHBEARER 的默认实现取决于 jackson-databind 库。由于它是一个可选依赖项,因此用户必须通过其构建工具将其配置为依赖项。
- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是 OAUTHBEARER 机制的客户端配置示例:
SASL/OAUTHBEARER 的无担保令牌创建选项
- Kafka 中 SASL/OAUTHBEARER 的默认实现创建并验证不安全的 JSON Web 令牌。虽然仅适用于非生产用途,但它确实提供了在开发或测试环境中创建任意令牌的灵活性。
- 以下是客户端(以及代理端,如果 OAUTHBEARER 是代理间协议)支持的各种 JAAS 模块选项:
JAAS Module Option for Unsecured Token Creation Documentation unsecuredLoginStringClaim_<claimname>="value" Creates a String claim with the given name and value. Any valid claim name can be specified except 'iat' and 'exp' (these are automatically generated). unsecuredLoginNumberClaim_<claimname>="value" Creates a Number claim with the given name and value. Any valid claim name can be specified except 'iat' and 'exp' (these are automatically generated). unsecuredLoginListClaim_<claimname>="value" Creates a String List claim with the given name and values parsed from the given value where the first character is taken as the delimiter. For example: unsecuredLoginListClaim_fubar="|value1|value2". Any valid claim name can be specified except 'iat' and 'exp' (these are automatically generated). unsecuredLoginExtension_<extensionname>="value" Creates a String extension with the given name and value. For example: unsecuredLoginExtension_traceId="123". A valid extension name is any sequence of lowercase or uppercase alphabet characters. In addition, the "auth" extension name is reserved. A valid extension value is any combination of characters with ASCII codes 1-127. unsecuredLoginPrincipalClaimName Set to a custom claim name if you wish the name of the String claim holding the principal name to be something other than 'sub'. unsecuredLoginLifetimeSeconds Set to an integer value if the token expiration is to be set to something other than the default value of 3600 seconds (which is 1 hour). The 'exp' claim will be set to reflect the expiration time. unsecuredLoginScopeClaimName Set to a custom claim name if you wish the name of the String or String List claim holding any token scope to be something other than 'scope'.
SASL/OAUTHBEARER 的不安全令牌验证选项
- 以下是代理端用于不安全 JSON Web 令牌验证的各种受支持的 JAAS 模块选项:
JAAS Module Option for Unsecured Token Validation Documentation unsecuredValidatorPrincipalClaimName="value" Set to a non-empty value if you wish a particular String claim holding a principal name to be checked for existence; the default is to check for the existence of the 'sub' claim. unsecuredValidatorScopeClaimName="value" Set to a custom claim name if you wish the name of the String or String List claim holding any token scope to be something other than 'scope'. unsecuredValidatorRequiredScope="value" Set to a space-delimited list of scope values if you wish the String/String List claim holding the token scope to be checked to make sure it contains certain values. unsecuredValidatorAllowableClockSkewMs="value" Set to a positive integer value if you wish to allow up to some number of positive milliseconds of clock skew (the default is 0). - 可以使用自定义登录和 SASL 服务器回调处理程序来覆盖默认的不安全 SASL/OAUTHBEARER 实现(并且必须在生产环境中覆盖)。
- 有关安全注意事项的更多详细信息,请参阅RFC 6749 第 10 节。
- 以下是代理端用于不安全 JSON Web 令牌验证的各种受支持的 JAAS 模块选项:
SASL/OAUTHBEARER 的令牌刷新
Kafka 会在令牌过期之前定期刷新令牌,以便客户端可以继续与代理建立连接。影响刷新算法运行方式的参数被指定为生产者/消费者/代理配置的一部分,如下所示。有关详细信息,请参阅其他地方有关这些属性的文档。默认值通常是合理的,在这种情况下,不需要显式设置这些配置参数。Producer/Consumer/Broker Configuration Property sasl.login.refresh.window.factor sasl.login.refresh.window.jitter sasl.login.refresh.min.period.seconds sasl.login.refresh.min.buffer.seconds SASL/OAUTHBEARER 的安全/生产使用
生产用例需要编写org.apache.kafka.common.security.auth.AuthenticateCallbackHandler 的实现 ,它可以处理org.apache.kafka.common.security.oauthbearer.OAuthBearerTokenCallback的实例 ,并通过sasl.login声明它 非代理客户端的 .callback.handler.class配置选项或通过代理的listener.name.sasl_ssl.oauthbearer.sasl.login.callback.handler.class 配置选项(当 SASL/OAUTHBEARER 是代理间协议时) 。生产用例还需要编写org.apache.kafka.common.security.auth.AuthenticateCallbackHandler 的实现 ,它可以处理org.apache.kafka.common.security.oauthbearer.OAuthBearerValidatorCallback的实例 ,并通过listener.name声明它 .sasl_ssl.oauthbearer.sasl.server.callback.handler.class 代理配置选项。
SASL/OAUTHBEARER 的安全注意事项
- Kafka 中 SASL/OAUTHBEARER 的默认实现创建并验证不安全的 JSON Web 令牌。这仅适用于非生产用途。
- OAUTHBEARER 应仅在具有 TLS 加密的生产环境中使用,以防止令牌被拦截。
- 如上所述,可以使用自定义登录和 SASL 服务器回调处理程序来覆盖默认的不安全 SASL/OAUTHBEARER 实现(并且必须在生产环境中覆盖)。
- 有关 OAuth 2 一般安全注意事项的更多详细信息,请参阅RFC 6749,第 10 节。
在代理中启用多个 SASL 机制
- 在JAAS 配置文件的KafkaServer部分中指定所有启用机制的登录模块的配置。例如:
KafkaServer { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true storeKey=true keyTab="/etc/security/keytabs/kafka_server.keytab" principal="kafka/kafka1.hostname.com@EXAMPLE.COM"; org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="admin-secret" user_admin="admin-secret" user_alice="alice-secret"; };
- 在 server.properties 中启用 SASL 机制:
sasl.enabled.mechanisms=GSSAPI,PLAIN,SCRAM-SHA-256,SCRAM-SHA-512,OAUTHBEARER
- 如果需要,请在 server.properties 中指定用于代理间通信的 SASL 安全协议和机制:
security.inter.broker.protocol=SASL_PLAINTEXT (or SASL_SSL) sasl.mechanism.inter.broker.protocol=GSSAPI (or one of the other enabled mechanisms)
- 按照GSSAPI (Kerberos)、 PLAIN、 SCRAM和OAUTHBEARER中特定于机制的步骤 为启用的机制配置 SASL。
- 在JAAS 配置文件的KafkaServer部分中指定所有启用机制的登录模块的配置。例如:
修改正在运行的集群中的SASL机制
可以使用以下顺序在正在运行的集群中修改 SASL 机制:
- 通过将机制添加到每个代理的 server.properties 中的sasl.enabled.mechanisms中,启用新的 SASL 机制。更新 JAAS 配置文件以包括此处所述的两种机制。增量反弹集群节点。
- 使用新机制重新启动客户端。
- 要更改代理间通信的机制(如果需要),请将server.properties 中的sasl.mechanism.inter.broker.protocol设置为新机制,并再次增量地弹跳集群。
- 要删除旧机制(如果需要),请从server.properties 中的sasl.enabled.mechanisms中删除旧机制,并从 JAAS 配置文件中删除旧机制的条目。再次增量地反弹集群。
使用委托令牌进行身份验证
基于委托令牌的身份验证是一种轻量级身份验证机制,可补充现有的 SASL/SSL 方法。委托令牌是 kafka 经纪人和客户端之间的共享秘密。委派令牌将帮助处理框架将工作负载分配给安全环境中的可用工作人员,而无需在使用 2 向 SSL 时增加分配 Kerberos TGT/密钥表或密钥库的成本。 有关更多详细信息,请参阅KIP-48 。
在默认实现下principal.builder.class
,委托令牌的所有者用作Principal
ACL 等配置的 身份验证。使用委托令牌的典型步骤是:
- 用户通过 SASL 或 SSL 向 Kafka 集群进行身份验证,并获取委托令牌。这可以使用管理 API 或使用kafka-delegation-tokens.sh脚本来完成。
- 用户将委托令牌安全地传递给 Kafka 客户端,以便通过 Kafka 集群进行身份验证。
- 令牌所有者/更新者可以更新/过期委托令牌。
代币管理
秘密用于生成和验证委托令牌。这是使用配置选项delegate.token.secret.key提供的。必须在所有代理之间配置相同的密钥。如果将 Kafka 与 KRaft 一起使用,则还必须使用相同的配置选项使用密钥配置控制器。如果未设置密钥或将密钥设置为空字符串,委托令牌身份验证和 API 操作将失败。
将 Kafka 与 Zookeeper 结合使用时,令牌详细信息存储在 Zookeeper 中,并且委托令牌适合在 Zookeeper 位于专用网络上的 Kafka 安装中使用。当将 Kafka 与 KRaft 结合使用时,令牌详细信息与其他元数据一起存储在控制器节点上,并且当控制器位于专用网络上或代理与控制器之间的所有通信都已加密时,委派令牌适合使用。目前,此机密以纯文本形式存储在 server.properties 配置文件中。我们打算在未来的 Kafka 版本中对这些进行配置。
代币具有当前寿命和最大可再生寿命。默认情况下,令牌必须每 24 小时更新一次,最多 7 天。这些可以使用delegation.token.expiry.time.ms 和delegation.token.max.lifetime.ms配置选项进行配置。
令牌也可以显式取消。如果令牌在令牌过期时间内未更新,或者令牌超出了最大生命周期,则将从所有代理缓存以及 Zookeeper 中删除该令牌。
创建委托令牌
可以使用管理 API 或使用kafka-delegation-tokens.sh脚本创建令牌。委托令牌请求(创建/更新/过期/描述)应仅在 SASL 或 SSL 身份验证通道上发出。如果通过委托令牌完成初始身份验证,则无法请求令牌。用户也可以通过指定--owner-principal参数为该用户或其他人创建令牌。所有者/更新者可以更新或过期令牌。所有者/更新者始终可以描述自己的代币。要描述其他令牌,需要在代表令牌所有者的用户资源上添加 DESCRIBE_TOKEN 权限。 下面给出了kafka-delegation-tokens.sh脚本示例。
创建委托令牌:
> bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --create --max-life-time-period -1 --command-config client.properties --renewer-principal User:user1
为不同的所有者创建委托令牌:
> bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --create --max-life-time-period -1 --command-config client.properties --renewer-principal User:user1 --owner-principal User:owner1
更新委托令牌:
> bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --renew --renew-time-period -1 --command-config client.properties --hmac ABCDEFGHIJK
使委托令牌过期:
> bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --expire --expiry-time-period -1 --command-config client.properties --hmac ABCDEFGHIJK
可以使用 --describe 选项描述现有令牌:
> bin/kafka-delegation-tokens.sh --bootstrap-server localhost:9092 --describe --command-config client.properties --owner-principal User:user1
令牌认证
委托令牌身份验证搭载当前 SASL/SCRAM 身份验证机制。我们必须在 Kafka 集群上启用 SASL/SCRAM 机制,如此处所述。
配置 Kafka 客户端:
- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是用于令牌身份验证的客户端配置示例:
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \ username="tokenID123" \ password="lAYYSFmLs4bTjf+lTZ1LCHR/ZZFNA==" \ tokenauth="true";
客户端使用用户名和密码选项来配置令牌 id 和令牌 HMAC。tokenauth选项用于向服务器指示令牌认证。在此示例中,客户端使用令牌 id 连接到代理:tokenID123。JVM 中的不同客户端可以通过在 中指定不同的令牌详细信息来使用不同的令牌进行连接
sasl.jaas.config
。客户端的 JAAS 配置也可以指定为类似于代理的 JVM 参数,如此处所述。客户端使用名为KafkaClient的登录部分 。此选项仅允许一名用户进行来自 JVM 的所有客户端连接。
- 在 Producer.properties 或 Consumer.properties 中为每个客户端配置 JAAS 配置属性。登录模块描述了生产者和消费者等客户端如何连接到 Kafka Broker。以下是用于令牌身份验证的客户端配置示例:
手动轮换机密的过程:
当秘密需要轮换时,我们需要重新部署。在此过程中,已连接的客户端将继续工作。但是任何新的连接请求和使用旧令牌的续订/过期请求都可能会失败。步骤如下。
- 使所有现有令牌过期。
- 通过滚动升级轮换秘密,并且
- 生成新的代币
我们打算在未来的 Kafka 版本中实现自动化。
7.5 授权和 ACL
Kafka 附带了一个可插入的授权框架,该框架在服务器配置中使用authorizer.class.name属性进行配置。配置的实现必须扩展org.apache.kafka.server.authorizer.Authorizer
。Kafka 提供了将 ACL 存储在集群元数据(Zookeeper 或 KRaft 元数据日志)中的默认实现。对于基于Zookeeper的集群,提供的实现配置如下:
authorizer.class.name=kafka.security.authorizer.AclAuthorizer
对于 KRaft 集群,在所有节点(代理、控制器或组合代理/控制器节点)上使用以下配置:
authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer
Kafka ACL 的通用格式是“主体 {P} 是[允许|拒绝]来自主机 {H} 的任何与 ResourcePattern {RP} 匹配的资源 {R} 上的操作 {O}”。您可以在KIP-11中阅读有关 ACL 结构的更多信息,在KIP-290中阅读有关资源模式的更多信息。要添加、删除或列出 ACL,您可以使用 Kafka ACL CLI kafka-acls.sh
。默认情况下,如果没有 ResourcePatterns 与特定资源 R 匹配,则 R 没有关联的 ACL,因此除了超级用户之外,任何人都不允许访问 R。如果要更改该行为,可以在 server.properties 中包含以下内容。
allow.everyone.if.no.acl.found=true
还可以在 server.properties 中添加超级用户,如下所示(请注意,分隔符是分号,因为 SSL 用户名可能包含逗号)。默认的 PrimaryType 字符串“User”区分大小写。
super.users=User:Bob;User:Alice
Kraft 主要转发
在 KRaft 集群中,诸如CreateTopics
和 之类的管理请求DeleteTopics
由客户端发送到代理侦听器。然后,代理通过在 中配置的第一个侦听器将请求转发到活动控制器controller.listener.names
。这些请求的授权是在控制器节点上完成的。这是通过Envelope
打包来自客户端和客户端主体的底层请求的请求来实现的。当控制器收到Envelope
代理转发的请求时,它首先Envelope
使用经过身份验证的代理主体来授权该请求。然后它使用转发的主体授权底层请求。
所有这些都意味着 Kafka 必须了解如何序列化和反序列化客户端主体。身份验证框架允许通过覆盖
principal.builder.class
配置来定制主体。为了使自定义主体能够与 KRaft 一起使用,配置的类必须实现,org.apache.kafka.common.security.auth.KafkaPrincipalSerde
以便 Kafka 知道如何序列化和反序列化主体。默认实现org.apache.kafka.common.security.authenticator.DefaultKafkaPrincipalBuilder
使用源代码中定义的 Kafka RPC 格式:clients/src/main/resources/common/message/DefaultPrincipalData.json
。有关 KRaft 中请求转发的更多详细信息,请参阅KIP-590
自定义 SSL 用户名
默认情况下,SSL 用户名的格式为“CN=writeuser,OU=Unknown,O=Unknown,L=Unknown,ST=Unknown,C=Unknown”。人们可以通过ssl.principal.mapping.rules
在 server.properties 中设置自定义规则来更改这一点。此配置允许将 X.500 可分辨名称映射到短名称的规则列表。规则按顺序进行评估,并且与专有名称匹配的第一个规则用于将其映射到短名称。列表中的任何后续规则都将被忽略。
的格式
ssl.principal.mapping.rules
是一个列表,其中每个规则都以“RULE:”开头,并包含以下格式的表达式。默认规则将返回 X.500 证书专有名称的字符串表示形式。如果专有名称与模式匹配,则将对该名称运行替换命令。它还支持小写/大写选项,以强制翻译结果全部为小写/大写。这是通过在规则末尾添加“/L”或“/U”来完成的。
RULE:pattern/replacement/
RULE:pattern/replacement/[LU]
示例ssl.principal.mapping.rules
值是:
RULE:^CN=(.*?),OU=ServiceUsers.*$/$1/,
RULE:^CN=(.*?),OU=(.*?),O=(.*?),L=(.*?),ST=(.*?),C=(.*?)$/$1@$2/L,
RULE:^.*[Cc][Nn]=([a-zA-Z0-9.]*).*$/$1/L,
DEFAULT
上述规则将专有名称“CN=serviceuser,OU=ServiceUsers,O=Unknown,L=Unknown,ST=Unknown,C=Unknown”转换为“serviceuser”和“CN=adminUser,OU=Admin,O=Unknown,L=”未知,ST=未知,C=未知”到“adminuser@admin”。
对于高级用例,可以通过在 server.properties 中设置自定义的 PrimaryBuilder 来自定义名称,如下所示。
principal.builder.class=CustomizedPrincipalBuilderClass
自定义 SASL 用户名
默认情况下,SASL 用户名将是 Kerberos 主体的主要部分。人们可以通过sasl.kerberos.principal.to.local.rules
在 server.properties 中设置自定义规则来更改这一点。的格式是一个列表,其中每个规则的工作方式与Kerberos 配置文件 (krb5.conf)sasl.kerberos.principal.to.local.rules
中的 auth_to_local 相同。这还支持额外的小写/大写规则,以强制翻译结果全部为小写/大写。这是通过在规则末尾添加“/L”或“/U”来完成的。检查以下格式的语法。每条规则均以 RULE: 开头,并包含如下格式的表达式。有关更多详细信息,请参阅 kerberos 文档。
RULE:[n:string](regexp)s/pattern/replacement/
RULE:[n:string](regexp)s/pattern/replacement/g
RULE:[n:string](regexp)s/pattern/replacement//L
RULE:[n:string](regexp)s/pattern/replacement/g/L
RULE:[n:string](regexp)s/pattern/replacement//U
RULE:[n:string](regexp)s/pattern/replacement/g/U
添加规则以将 user@MYDOMAIN.COM 正确转换为 user 同时保留默认规则的示例如下:
sasl.kerberos.principal.to.local.rules=RULE:[1:$1@$0](.*@MYDOMAIN.COM)s/@.*//,DEFAULT
命令行界面
Kafka 授权管理 CLI 与所有其他 CLI 都可以在 bin 目录下找到。CLI 脚本称为kafka-acls.sh。以下列出了该脚本支持的所有选项:选项 | 描述 | 默认 | 选项类型 |
---|---|---|---|
--add | 向脚本指示用户正在尝试添加 acl。 | 行动 | |
--remove | 向脚本指示用户正在尝试删除 acl。 | 行动 | |
--list | 向脚本指示用户正在尝试列出 acl。 | 行动 | |
--bootstrap-server | 用于建立与 Kafka 集群的连接的主机/端口对列表。只能指定 --bootstrap-server 或 --authorizer 选项之一。 | 配置 | |
--command-config | 包含要传递给管理客户端的配置的属性文件。此选项只能与 --bootstrap-server 选项一起使用。 | 配置 | |
--cluster | 向脚本指示用户正在尝试与单一集群资源上的 acls 进行交互。 | 资源模式 | |
--topic [topic-name] | 向脚本指示用户正在尝试与主题资源模式上的 acl 进行交互。 | 资源模式 | |
--group [group-name] | 向脚本指示用户正在尝试与消费者组资源模式上的 acl 进行交互 | 资源模式 | |
--transactional-id [transactional-id] | 应添加或删除 ACL 的 transactionalId。* 值表示 ACL 应应用于所有 transactionalId。 | 资源模式 | |
--delegation-token [delegation-token] | 应添加或删除 ACL 的委托令牌。* 值表示 ACL 应应用于所有令牌。 | 资源模式 | |
--user-principal [user-principal] | 应添加或删除 ACL 的用户资源。目前,这与委托令牌有关。* 值表示 ACL 应适用于所有用户。 | 资源模式 | |
--resource-pattern-type [pattern-type] | 向脚本指示用户希望使用的资源模式类型(对于 --add)或资源模式过滤器(对于 --list 和 --remove)。 添加 acl 时,这应该是特定的模式类型,例如“文字”或“前缀”。 列出或删除 acl 时,可以使用特定模式类型过滤器从特定类型的资源模式中列出或删除 acl,或者可以使用“any”或“match”过滤器值,其中“any”将匹配任何模式类型,但将完全匹配资源名称,并且“match”将执行模式匹配以列出或删除影响所提供资源的所有 acl。 警告:“match”与“--remove”开关结合使用时,应小心使用。 |
文字 | 配置 |
--allow-principal | 主体采用“主体类型:名称”格式,将添加到具有“允许”权限的 ACL。默认的 PrimaryType 字符串“User”区分大小写。 您可以在单个命令中指定多个 --allow-principal。 |
主要的 | |
--deny-principal | 主体采用PrincipalType:名称格式,将添加到具有拒绝权限的ACL。默认的 PrimaryType 字符串“User”区分大小写。 您可以在单个命令中指定多个 --deny-principal。 |
主要的 | |
--principal | 主体采用PrincipalType:name 格式,将与--list 选项一起使用。默认的 PrimaryType 字符串“User”区分大小写。这将列出指定主体的 ACL。 您可以在单个命令中指定多个 --principal。 |
主要的 | |
--allow-host | --allow-principal 中列出的主体可以访问的 IP 地址。 | 如果指定了 --allow-principal 默认为 * ,翻译为“所有主机” | 主持人 |
--deny-host | --deny-principal 中列出的主体将被拒绝访问的 IP 地址。 | 如果指定 --deny-principal 默认为 * ,翻译为“所有主机” | 主持人 |
--operation | 将被允许或拒绝的操作。 有效值为:
|
全部 | 手术 |
--producer | 添加/删除生产者角色 ACL 的便捷选项。这将生成允许对主题进行写入、描述和创建的 acl。 | 方便 | |
--consumer | 添加/删除消费者角色 ACL 的便捷选项。这将生成允许 READ、DESCRIBE 主题和 READ 消费者组的 ACL。 | 方便 | |
--idempotent | 为生产者启用幂等性。这应该与 -- Producer 选项结合使用。 请注意,如果生产者被授权使用特定的 transactional-id,则幂等性会自动启用。 |
方便 | |
--force | 方便的选项,假设所有查询都是“是”并且不提示。 | 方便 | |
--authorizer | (已弃用:KRaft 中不支持)授权者的完全限定类名。 | kafka.security.authorizer.AclAuthorizer | 配置 |
--authorizer-properties | (已弃用:KRaft 中不支持)将传递给授权者进行初始化的 key=val 对。对于 ZK clsuters 中的默认授权者,示例值为:zookeeper.connect=localhost:2181 | 配置 | |
--zk-tls-config-file | (已弃用:KRaft 中不支持)标识定义授权者的 ZooKeeper 客户端 TLS 连接属性的文件。除以下属性(带或不带“authorizer.”前缀)之外的任何属性都将被忽略:zookeeper.clientCnxnSocket、zookeeper.ssl.cipher.suites、zookeeper.ssl.client.enable、zookeeper.ssl.crl.enable、zookeeper。 ssl.enabled.protocols、zookeeper.ssl.endpoint.identification.algorithm、zookeeper.ssl.keystore.location、zookeeper.ssl.keystore.password、zookeeper.ssl.keystore.type、zookeeper.ssl.ocsp.enable、zookeeper。 ssl.协议,zookeeper.ssl.truststore.位置,zookeeper.ssl.truststore.密码,zookeeper.ssl.truststore.type | 配置 |
例子
- 添加ACL
假设您要添加一条ACL“允许主体User:Bob 和User:Alice 对来自IP 198.51.100.0 和IP 198.51.100.1 的Topic Test-Topic 进行读写操作”。您可以通过使用以下选项执行 CLI 来做到这一点:
默认情况下,所有不具有允许访问资源操作的显式 acl 的主体都会被拒绝。在极少数情况下,定义了允许访问除某些主体之外的所有主体的允许 acl,我们将必须使用 --deny-principal 和 --deny-host 选项。例如,如果我们想要允许所有用户从 Test-topic 读取,但仅拒绝来自 IP 198.51.100.3 的 User:BadBob,我们可以使用以下命令来实现:> bin/kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:Bob --allow-principal User:Alice --allow-host 198.51.100.0 --allow-host 198.51.100.1 --operation Read --operation Write --topic Test-topic
请注意,> bin/kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:'*' --allow-host '*' --deny-principal User:BadBob --deny-host 198.51.100.3 --operation Read --topic Test-topic
--allow-host
和--deny-host
仅支持 IP 地址(不支持主机名)。上面的示例通过指定 --topic [topic-name] 作为资源模式选项将 acl 添加到主题。同样,用户可以通过指定 --cluster 将 acl 添加到集群,并通过指定 --group [group-name] 将 acl 添加到消费者组。您可以在某种类型的任何资源上添加 acl,例如,假设您想添加一个 acl“主要用户:Peter 被允许从 IP 198.51.200.0 生成任何主题”,您可以通过使用通配符资源“*”来做到这一点,例如通过使用以下选项执行 CLI:
您可以在前缀资源模式上添加 acl,例如,假设您要添加一个 acl“主要用户:Jane 被允许从任何主机生成名称以“Test-”开头的任何主题”。您可以通过使用以下选项执行 CLI 来做到这一点:> bin/kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:Peter --allow-host 198.51.200.1 --producer --topic '*'
请注意,--resource-pattern-type 默认为“literal”,它仅影响具有完全相同名称的资源,或者在通配符资源名称“*”的情况下,影响具有任何名称的资源。> bin/kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:Jane --producer --topic Test- --resource-pattern-type prefixed
- 删除 Acl
删除 acl 几乎是相同的。唯一的区别是用户必须指定 --remove 选项,而不是 --add 选项。要删除上面第一个示例添加的 acl,我们可以使用以下选项执行 CLI:
如果您想删除添加到上面的前缀资源模式中的 acl,我们可以使用以下选项执行 CLI:> bin/kafka-acls.sh --bootstrap-server localhost:9092 --remove --allow-principal User:Bob --allow-principal User:Alice --allow-host 198.51.100.0 --allow-host 198.51.100.1 --operation Read --operation Write --topic Test-topic
> bin/kafka-acls.sh --bootstrap-server localhost:9092 --remove --allow-principal User:Jane --producer --topic Test- --resource-pattern-type Prefixed
- 列出 ACL
我们可以通过为资源指定 --list 选项来列出任何资源的 ACL。要列出文字资源模式 Test-topic 上的所有 acl,我们可以使用以下选项执行 CLI:
但是,这只会返回已添加到该确切资源模式的 acl。可能存在影响对主题的访问的其他 acl,例如主题通配符“*”上的任何 acl,或前缀资源模式上的任何 acl。可以显式查询通配符资源模式上的 ACL:> bin/kafka-acls.sh --bootstrap-server localhost:9092 --list --topic Test-topic
但是,不一定可以在与 Test-topic 匹配的前缀资源模式上显式查询 acl,因为此类模式的名称可能未知。我们可以使用“--resource-pattern-type match”列出影响测试主题的 所有acl,例如> bin/kafka-acls.sh --bootstrap-server localhost:9092 --list --topic '*'
这将列出所有匹配文字、通配符和前缀资源模式的 acl。> bin/kafka-acls.sh --bootstrap-server localhost:9092 --list --topic Test-topic --resource-pattern-type match
- 添加或删除主体作为生产者或消费者
ACL 管理最常见的用例是添加/删除主体作为生产者或消费者,因此我们添加了方便的选项来处理这些情况。为了将 User:Bob 添加为 Test-topic 的生产者,我们可以执行以下命令:
类似地,要将 Alice 添加为消费者组 Group-1 的 Test-topic 消费者,我们只需传递 --consumer 选项:> bin/kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:Bob --producer --topic Test-topic
请注意,对于消费者选项,我们还必须指定消费者组。为了从生产者或消费者角色中删除主体,我们只需要传递 --remove 选项。> bin/kafka-acls.sh --bootstrap-server localhost:9092 --add --allow-principal User:Bob --consumer --topic Test-topic --group Group-1
- 基于Admin API的ACL管理 对
ClusterResource拥有Alter权限的用户可以使用Admin API进行ACL管理。kafka-acls.sh 脚本支持 AdminClient API 来管理 ACL,而无需直接与 Zookeeper/Authorizer 交互。上述所有示例都可以使用--bootstrap-server选项来执行。例如:bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config /tmp/adminclient-configs.conf --add --allow-principal User:Bob --producer --topic Test-topic bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config /tmp/adminclient-configs.conf --add --allow-principal User:Bob --consumer --topic Test-topic --group Group-1 bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config /tmp/adminclient-configs.conf --list --topic Test-topic bin/kafka-acls.sh --bootstrap-server localhost:9092 --command-config /tmp/adminclient-configs.conf --add --allow-principal User:tokenRequester --operation CreateTokens --user-principal "owner1"
授权原语
协议调用通常是对 Kafka 中的某些资源执行一些操作。需要了解操作和资源才能建立有效的保护。在本节中,我们将列出这些操作和资源,然后列出这些操作和资源与协议的组合以查看有效的场景。
Kafka中的操作
有一些操作原语可用于建立权限。这些可以与某些资源相匹配,以允许给定用户进行特定协议调用。这些都是:
- 读
- 写
- 创造
- 删除
- 改变
- 描述
- 集群动作
- 描述配置
- 更改配置
- 幂等写
- 创建代币
- 描述令牌
- 全部
Kafka中的资源
上述操作可以应用于下面描述的某些资源。
- 主题:这仅代表一个主题。所有作用于主题(例如读取、写入主题)的协议调用都需要添加相应的权限。如果主题资源存在授权错误,则会返回 TOPIC_AUTHORIZATION_FAILED(错误代码:29)。
- 组:代表经纪人中的消费者组。所有与消费者组一起使用的协议调用(例如加入组)都必须具有主题组的权限。如果未授予权限,则协议响应中将返回 GROUP_AUTHORIZATION_FAILED(错误代码:30)。
- 集群:该资源代表集群。影响整个集群的操作(例如受控关闭)受到集群资源特权的保护。如果集群资源存在授权问题,则会返回 CLUSTER_AUTHORIZATION_FAILED(错误代码:31)。
- TransactionalId:该资源表示与事务相关的操作,例如提交。如果发生任何错误,经纪商将返回 TRANSACTIONAL_ID_AUTHORIZATION_FAILED(错误代码:53)。
- DelegationToken:这代表集群中的委托令牌。诸如描述委托令牌之类的操作可以通过DelegationToken资源上的特权来保护。由于这些对象在 Kafka 中具有一些特殊行为,因此建议阅读 KIP-48和使用委托令牌进行身份验证 中的相关上游文档。
- 用户:可以将CreateToken和DescribeToken操作授予用户资源,以允许为其他用户创建和描述令牌。更多信息可以在KIP-373中找到。
协议操作和资源
在下表中,我们将列出 Kafka API 协议对资源执行的有效操作。
协议(API 密钥) | 手术 | 资源 | 笔记 |
---|---|---|---|
PRODUCE (0) | 写 | 交易ID | 具有 transactional.id 设置的事务生产者需要此特权。 |
PRODUCE (0) | 幂等写 | 簇 | 幂等生产操作需要此特权。 |
PRODUCE (0) | 写 | 话题 | 这适用于正常的生产操作。 |
FETCH (1) | 集群动作 | 簇 | 追随者必须在集群资源上具有 ClusterAction 才能获取分区数据。 |
FETCH (1) | 读 | 话题 | 常规 Kafka 消费者需要对他们正在获取的每个分区拥有 READ 权限。 |
LIST_OFFSETS (2) | 描述 | 话题 | |
METADATA (3) | 描述 | 话题 | |
METADATA (3) | 创造 | 簇 | 如果启用了主题自动创建,则代理端 API 将检查是否存在集群级别权限。如果找到,则它将允许创建主题,否则它将迭代主题级别权限(请参阅下一个)。 |
METADATA (3) | 创造 | 话题 | 如果启用,这将授权自动创建主题,但给定用户没有集群级别权限(见上文)。 |
LEADER_AND_ISR (4) | 集群动作 | 簇 | |
STOP_REPLICA (5) | 集群动作 | 簇 | |
UPDATE_METADATA (6) | 集群动作 | 簇 | |
CONTROLLED_SHUTDOWN (7) | 集群动作 | 簇 | |
OFFSET_COMMIT (8) | 读 | 团体 | 仅当偏移量被授权给给定组和主题时才能提交(见下文)。首先检查组访问,然后检查主题访问。 |
OFFSET_COMMIT (8) | 读 | 话题 | 由于偏移提交是消费进程的一部分,因此它需要读取操作的权限。 |
OFFSET_FETCH (9) | 描述 | 团体 | 与 OFFSET_COMMIT 类似,应用程序也必须拥有组和主题级别的权限才能获取。然而在这种情况下,它需要描述访问而不是读取。首先检查组访问,然后检查主题访问。 |
OFFSET_FETCH (9) | 描述 | 话题 | |
FIND_COORDINATOR (10) | 描述 | 团体 | FIND_COORDINATOR 请求可以是“Group”类型,在这种情况下,它正在寻找消费者组协调器。此权限代表组模式。 |
FIND_COORDINATOR (10) | 描述 | 交易ID | 这仅适用于事务性生产者,并在生产者尝试查找事务协调器时进行检查。 |
JOIN_GROUP (11) | 读 | 团体 | |
HEARTBEAT (12) | 读 | 团体 | |
LEAVE_GROUP (13) | 读 | 团体 | |
SYNC_GROUP (14) | 读 | 团体 | |
DESCRIBE_GROUPS (15) | 描述 | 团体 | |
LIST_GROUPS (16) | 描述 | 簇 | 当代理检查是否授权 list_groups 请求时,它首先检查此集群级别的授权。如果没有找到,则继续单独检查组。此操作不会返回 CLUSTER_AUTHORIZATION_FAILED。 |
LIST_GROUPS (16) | 描述 | 团体 | 如果没有任何组获得授权,则只会发回空响应而不是错误。此操作不会返回 CLUSTER_AUTHORIZATION_FAILED。这适用于 2.1 版本。 |
SASL_HANDSHAKE (17) | SASL 握手是身份验证过程的一部分,因此无法在此处应用任何类型的授权。 | ||
API_VERSIONS (18) | API_VERSIONS 请求是 Kafka 协议握手的一部分,发生在连接时和任何身份验证之前。因此不可能通过授权来控制它。 | ||
CREATE_TOPICS (19) | 创造 | 簇 | 如果没有集群级别授权,那么它不会返回 CLUSTER_AUTHORIZATION_FAILED 而是回退到使用主题级别,即下面的主题级别。如果出现问题就会抛出错误。 |
CREATE_TOPICS (19) | 创造 | 话题 | 这适用于 2.0 版本。 |
DELETE_TOPICS (20) | 删除 | 话题 | |
DELETE_RECORDS (21) | 删除 | 话题 | |
INIT_PRODUCER_ID (22) | 写 | 交易ID | |
INIT_PRODUCER_ID (22) | 幂等写 | 簇 | |
OFFSET_FOR_LEADER_EPOCH (23) | 集群动作 | 簇 | 如果此操作没有集群级别权限,那么它将检查主题级别一。 |
OFFSET_FOR_LEADER_EPOCH (23) | 描述 | 话题 | 这适用于 2.1 版本。 |
ADD_PARTITIONS_TO_TXN (24) | 写 | 交易ID | 该API仅适用于事务性请求。它首先检查 TransactionalId 资源上的写入操作,然后检查主题中的主题(如下)。 |
ADD_PARTITIONS_TO_TXN (24) | 写 | 话题 | |
ADD_OFFSETS_TO_TXN (25) | 写 | 交易ID | 与 ADD_PARTITIONS_TO_TXN 类似,这仅适用于事务请求。它首先检查 TransactionalId 资源上的写入操作,然后检查是否可以读取给定组(如下)。 |
ADD_OFFSETS_TO_TXN (25) | 读 | 团体 | |
END_TXN (26) | 写 | 交易ID | |
WRITE_TXN_MARKERS (27) | 集群动作 | 簇 | |
TXN_OFFSET_COMMIT (28) | 写 | 交易ID | |
TXN_OFFSET_COMMIT (28) | 读 | 团体 | |
TXN_OFFSET_COMMIT (28) | 读 | 话题 | |
DESCRIBE_ACLS (29) | 描述 | 簇 | |
CREATE_ACLS (30) | 改变 | 簇 | |
DELETE_ACLS (31) | 改变 | 簇 | |
DESCRIBE_CONFIGS (32) | 描述配置 | 簇 | 如果请求代理配置,则代理将检查集群级别权限。 |
DESCRIBE_CONFIGS (32) | 描述配置 | 话题 | 如果请求主题配置,则代理将检查主题级别权限。 |
ALTER_CONFIGS (33) | 更改配置 | 簇 | 如果代理配置发生更改,代理将检查集群级别权限。 |
ALTER_CONFIGS (33) | 更改配置 | 话题 | 如果主题配置发生更改,代理将检查主题级别权限。 |
ALTER_REPLICA_LOG_DIRS (34) | 改变 | 簇 | |
DESCRIBE_LOG_DIRS (35) | 描述 | 簇 | 授权失败时将返回空响应。 |
SASL_AUTHENTICATE (36) | SASL_AUTHENTICATE 是身份验证过程的一部分,因此无法在此处应用任何类型的授权。 | ||
CREATE_PARTITIONS (37) | 改变 | 话题 | |
CREATE_DELEGATION_TOKEN (38) | 创建委托令牌有特殊规则,为此请参阅 使用委托令牌进行身份验证部分。 | ||
CREATE_DELEGATION_TOKEN (38) | 创建代币 | 用户 | 允许为用户资源创建委托令牌。 |
RENEW_DELEGATION_TOKEN (39) | 更新委托令牌有特殊规则,为此请参阅 使用委托令牌进行身份验证部分。 | ||
EXPIRE_DELEGATION_TOKEN (40) | 过期的委托令牌有特殊规则,为此请参阅 使用委托令牌进行身份验证部分。 | ||
DESCRIBE_DELEGATION_TOKEN (41) | 描述 | 委托令牌 | 描述委托令牌有特殊规则,为此请参阅 使用委托令牌进行身份验证部分。 |
DESCRIBE_DELEGATION_TOKEN (41) | 描述令牌 | 用户 | 允许描述用户资源的委托令牌。 |
DELETE_GROUPS (42) | 删除 | 团体 | |
ELECT_PREFERRED_LEADERS (43) | 集群动作 | 簇 | |
INCREMENTAL_ALTER_CONFIGS (44) | 更改配置 | 簇 | 如果代理配置发生更改,代理将检查集群级别权限。 |
INCREMENTAL_ALTER_CONFIGS (44) | 更改配置 | 话题 | 如果主题配置发生更改,代理将检查主题级别权限。 |
ALTER_PARTITION_REASSIGNMENTS (45) | 改变 | 簇 | |
LIST_PARTITION_REASSIGNMENTS (46) | 描述 | 簇 | |
OFFSET_DELETE (47) | 删除 | 团体 | |
OFFSET_DELETE (47) | 读 | 话题 | |
DESCRIBE_CLIENT_QUOTAS (48) | 描述配置 | 簇 | |
ALTER_CLIENT_QUOTAS (49) | 更改配置 | 簇 | |
DESCRIBE_USER_SCRAM_CREDENTIALS (50) | 描述 | 簇 | |
ALTER_USER_SCRAM_CREDENTIALS (51) | 改变 | 簇 | |
VOTE (52) | 集群动作 | 簇 | |
BEGIN_QUORUM_EPOCH (53) | 集群动作 | 簇 | |
END_QUORUM_EPOCH (54) | 集群动作 | 簇 | |
DESCRIBE_QUORUM (55) | 描述 | 簇 | |
ALTER_PARTITION (56) | 集群动作 | 簇 | |
UPDATE_FEATURES (57) | 改变 | 簇 | |
ENVELOPE (58) | 集群动作 | 簇 | |
FETCH_SNAPSHOT (59) | 集群动作 | 簇 | |
DESCRIBE_CLUSTER (60) | 描述 | 簇 | |
DESCRIBE_PRODUCERS (61) | 读 | 话题 | |
BROKER_REGISTRATION (62) | 集群动作 | 簇 | |
BROKER_HEARTBEAT (63) | 集群动作 | 簇 | |
UNREGISTER_BROKER (64) | 改变 | 簇 | |
DESCRIBE_TRANSACTIONS (65) | 描述 | 交易ID | |
LIST_TRANSACTIONS (66) | 描述 | 交易ID | |
ALLOCATE_PRODUCER_IDS (67) | 集群动作 | 簇 | |
CONSUMER_GROUP_HEARTBEAT (68) | 读 | 团体 |
7.6 将安全功能纳入正在运行的集群中
您可以通过前面讨论的一种或多种受支持的协议来保护正在运行的集群。这是分阶段完成的:- 增量反弹集群节点以打开其他安全端口。
- 使用安全端口而不是 PLAINTEXT 端口重新启动客户端(假设您正在保护客户端代理连接)。
- 再次增量地反弹集群以启用代理到代理的安全性(如果需要)
- 最后增量反弹以关闭 PLAINTEXT 端口。
listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092
然后我们重新启动客户端,更改其配置以指向新打开的安全端口:
bootstrap.servers = [broker1:9092,...]
security.protocol = SSL
...etc
在第二次增量服务器反弹中,我们指示 Kafka 使用 SSL 作为代理-代理协议(将使用相同的 SSL 端口):
listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092
security.inter.broker.protocol=SSL
在最后的反弹中,我们通过关闭 PLAINTEXT 端口来保护集群:
listeners=SSL://broker1:9092
security.inter.broker.protocol=SSL
或者,我们可以选择打开多个端口,以便可以使用不同的协议进行经纪人-经纪人和经纪人-客户端通信。假设我们希望在整个过程中使用 SSL 加密(即用于代理-代理和代理-客户端通信),但我们还希望将 SASL 身份验证添加到代理-客户端连接。我们将通过在第一次反弹期间打开两个额外的端口来实现这一点:
listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092,SASL_SSL://broker1:9093
然后,我们将重新启动客户端,更改其配置以指向新打开的 SASL 和 SSL 安全端口:
bootstrap.servers = [broker1:9093,...]
security.protocol = SASL_SSL
...etc
第二次服务器反弹会将集群切换为通过我们之前在端口 9092 上打开的 SSL 端口使用加密的代理间通信:
listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092,SASL_SSL://broker1:9093
security.inter.broker.protocol=SSL
最后的反弹通过关闭 PLAINTEXT 端口来保护集群。
listeners=SSL://broker1:9092,SASL_SSL://broker1:9093
security.inter.broker.protocol=SSL
ZooKeeper 的安全可以独立于 Kafka 集群。第7.7.2节介绍了执行此操作的步骤。
7.7 ZooKeeper 认证
ZooKeeper 从 3.5.x 版本开始支持双向 TLS (mTLS) 身份验证。从 2.5 版本开始,Kafka 支持使用 SASL 和 mTLS 单独或同时向 ZooKeeper 进行身份验证。 有关更多详细信息, 请参阅 KIP-515:启用 ZK 客户端使用新的 TLS 支持的身份验证。单独使用 mTLS 时,每个代理和任何 CLI 工具(例如ZooKeeper 安全迁移工具)都应使用相同的可分辨名称 (DN) 来标识自己,因为它是经过 ACL 处理的 DN。这可以按如下所述进行更改,但它涉及编写和部署自定义 ZooKeeper 身份验证提供程序。通常,每个证书应具有相同的 DN,但具有不同的主题备用名称 (SAN),以便 ZooKeeper 对代理和任何 CLI 工具的主机名验证能够成功。
当将 SASL 身份验证与 mTLS 一起使用到 ZooKeeper 时,SASL 身份和创建 znode 的 DN(即创建代理的证书)或安全迁移工具的 DN(如果在创建 znode 后执行迁移)都将被ACL 化,并且所有代理和 CLI 工具都将获得授权,即使它们都使用不同的 DN,因为它们都将使用相同的 ACL 化 SASL 身份。仅当单独使用 mTLS 身份验证时,所有 DN 都必须匹配(并且 SAN 变得至关重要——同样,在没有编写和部署自定义 ZooKeeper 身份验证提供程序的情况下,如下所述)。
使用代理属性文件为代理设置 TLS 配置,如下所述。
使用--zk-tls-config-file <file>选项在 Zookeeper 安全迁移工具中设置 TLS 配置。kafka-acls.sh和kafka-configs.sh CLI 工具还支持--zk - tls-config-file <file>选项。
使用-zk-tls-config-file <file>选项(注意单破折号而不是双破折号)为Zookeeper-shell.sh CLI 工具设置 TLS 配置。
7.7.1 新集群
7.7.1.1 ZooKeeper SASL 身份验证
要在代理上启用 ZooKeeper SASL 身份验证,有两个必要步骤:- 创建 JAAS 登录文件并设置相应的系统属性以指向它,如上所述
- 将每个代理中的配置属性zookeeper.set.acl设置为true
7.7.1.2 ZooKeeper 相互 TLS 身份验证
ZooKeeper mTLS 身份验证可以在有或没有 SASL 身份验证的情况下启用。如上所述,单独使用 mTLS 时,每个代理和任何 CLI 工具(例如ZooKeeper 安全迁移工具)通常必须使用相同的可分辨名称 (DN) 来标识自己,因为它是经过 ACL 处理的 DN,这意味着每个证书应具有适当的主题备用名称 (SAN),以便 ZooKeeper 对代理和任何 CLI 工具的主机名验证能够成功。通过编写一个扩展org.apache.zookeeper.server.auth.X509AuthenticationProvider的类并覆盖方法 protected String getClientId(X509Certificate clientCert) , 可以使用 DN 以外的其他内容来标识 mTLS 客户端。选择一个方案名称,并将ZooKeeper 中的authProvider.[scheme]设置为自定义实现的完全限定类名称;然后设置ssl.authProvider=[scheme]来使用它。
以下是用于启用 TLS 身份验证的 ZooKeeper 配置示例(部分)。这些配置在ZooKeeper 管理指南中有描述 。secureClientPort=2182
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
authProvider.x509=org.apache.zookeeper.server.auth.X509AuthenticationProvider
ssl.keyStore.location=/path/to/zk/keystore.jks
ssl.keyStore.password=zk-ks-passwd
ssl.trustStore.location=/path/to/zk/truststore.jks
ssl.trustStore.password=zk-ts-passwd
重要提示:ZooKeeper 不支持将 ZooKeeper 服务器密钥库中的密钥密码设置为与密钥库密码本身不同的值。请务必将密钥密码设置为与密钥库密码相同。
以下是使用 mTLS 身份验证连接到 ZooKeeper 的 Kafka Broker 配置示例(部分)。这些配置在上面的Broker Configs中有描述。
# connect to the ZooKeeper port configured for TLS
zookeeper.connect=zk1:2182,zk2:2182,zk3:2182
# required to use TLS to ZooKeeper (default is false)
zookeeper.ssl.client.enable=true
# required to use TLS to ZooKeeper
zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
# define key/trust stores to use TLS to ZooKeeper; ignored unless zookeeper.ssl.client.enable=true
zookeeper.ssl.keystore.location=/path/to/kafka/keystore.jks
zookeeper.ssl.keystore.password=kafka-ks-passwd
zookeeper.ssl.truststore.location=/path/to/kafka/truststore.jks
zookeeper.ssl.truststore.password=kafka-ts-passwd
# tell broker to create ACLs on znodes
zookeeper.set.acl=true
重要提示:ZooKeeper 不支持将 ZooKeeper 客户端(即代理)密钥库中的密钥密码设置为与密钥库密码本身不同的值。请务必将密钥密码设置为与密钥库密码相同。
7.7.2 迁移集群
如果您运行的 Kafka 版本不支持安全性或只是禁用了安全性,并且希望确保集群安全,那么您需要执行以下步骤来启用 ZooKeeper 身份验证,同时将对您的操作造成的干扰降至最低:- 在 ZooKeeper 上启用 SASL 和/或 mTLS 身份验证。如果启用 mTLS,您现在将同时拥有非 TLS 端口和 TLS 端口,如下所示:
clientPort=2181 secureClientPort=2182 serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory authProvider.x509=org.apache.zookeeper.server.auth.X509AuthenticationProvider ssl.keyStore.location=/path/to/zk/keystore.jks ssl.keyStore.password=zk-ks-passwd ssl.trustStore.location=/path/to/zk/truststore.jks ssl.trustStore.password=zk-ts-passwd
- 根据需要执行代理的滚动重启,设置 JAAS 登录文件和/或定义 ZooKeeper 双向 TLS 配置(包括连接到启用 TLS 的 ZooKeeper 端口),这使代理能够向 ZooKeeper 进行身份验证。在滚动重启结束时,代理能够使用严格的 ACL 操作 znode,但它们不会使用这些 ACL 创建 znode
- 如果启用了 mTLS,请在 ZooKeeper 中禁用非 TLS 端口
- 对代理执行第二次滚动重启,这次将配置参数zookeeper.set.acl设置为true,这样可以在创建znode时使用安全ACL
- 执行 ZkSecurityMigrator 工具。要执行该工具,有以下脚本:bin/zookeeper-security-migration.sh,其中zookeeper.acl设置为secure。该工具遍历相应的子树,更改 znode 的 ACL。
--zk-tls-config-file <file>
如果启用 mTLS,请使用该选项。
还可以关闭安全集群中的身份验证。为此,请按照下列步骤操作:
- 对代理执行滚动重启,设置 JAAS 登录文件和/或定义 ZooKeeper 双向 TLS 配置,这使代理能够进行身份验证,但将Zookeeper.set.acl设置为 false。在滚动重启结束时,代理停止使用安全 ACL 创建 znode,但仍然能够验证和操作所有 znode
- 执行 ZkSecurityMigrator 工具。要执行该工具,请运行此脚本bin/zookeeper-security-migration.sh,并将Zookeeper.acl设置为不安全。该工具遍历相应的子树,更改 znode 的 ACL。
--zk-tls-config-file <file>
如果需要设置 TLS 配置,请使用该选项。 - 如果要禁用 mTLS,请在 ZooKeeper 中启用非 TLS 端口
- 对代理执行第二次滚动重启,这次省略设置 JAAS 登录文件的系统属性和/或根据需要删除 ZooKeeper 双向 TLS 配置(包括连接到未启用 TLS 的 ZooKeeper 端口)
- 如果要禁用 mTLS,请在 ZooKeeper 中禁用 TLS 端口
> bin/zookeeper-security-migration.sh --zookeeper.acl=secure --zookeeper.connect=localhost:2181
运行此命令以查看完整的参数列表:
> bin/zookeeper-security-migration.sh --help
7.7.3 迁移 ZooKeeper 整体
还需要在 ZooKeeper 整体上启用 SASL 和/或 mTLS 身份验证。为此,我们需要执行服务器的滚动重新启动并设置一些属性。有关 mTLS 信息,请参阅上文。更多详细信息请参考 ZooKeeper 文档:7.7.4 ZooKeeper 仲裁相互 TLS 认证
可以在 ZooKeeper 服务器本身之间启用 mTLS 身份验证。请参阅ZooKeeper 文档以获取更多详细信息。7.8 ZooKeeper加密
使用双向 TLS 的 ZooKeeper 连接是加密的。从 ZooKeeper 3.5.7 版(Kafka 2.5 版附带的版本)开始,ZooKeeper 支持服务器端配置 ssl.clientAuth(不区分大小写:want / need / none是有效选项,默认为need),并设置此ZooKeeper 中的值为none允许客户端通过 TLS 加密连接进行连接,而无需提供自己的证书。以下是仅使用 TLS 加密连接到 ZooKeeper 的 Kafka Broker 配置示例(部分)。这些配置在上面的Broker Configs中有描述。# connect to the ZooKeeper port configured for TLS
zookeeper.connect=zk1:2182,zk2:2182,zk3:2182
# required to use TLS to ZooKeeper (default is false)
zookeeper.ssl.client.enable=true
# required to use TLS to ZooKeeper
zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty
# define trust stores to use TLS to ZooKeeper; ignored unless zookeeper.ssl.client.enable=true
# no need to set keystore information assuming ssl.clientAuth=none on ZooKeeper
zookeeper.ssl.truststore.location=/path/to/kafka/truststore.jks
zookeeper.ssl.truststore.password=kafka-ts-passwd
# tell broker to create ACLs on znodes (if using SASL authentication, otherwise do not set this)
zookeeper.set.acl=true
8.Kafka连接
8.1 概述
Kafka Connect 是一种在 Apache Kafka 和其他系统之间可扩展且可靠地传输数据的工具。它使得快速定义将大量数据移入和移出 Kafka 的连接器变得简单。Kafka Connect 可以摄取整个数据库或将所有应用程序服务器的指标收集到 Kafka 主题中,从而使数据可用于低延迟的流处理。导出作业可以将 Kafka 主题中的数据传输到辅助存储和查询系统或批处理系统中以进行离线分析。
Kafka连接功能包括:
- Kafka 连接器的通用框架- Kafka Connect 标准化了其他数据系统与 Kafka 的集成,简化了连接器的开发、部署和管理
- 分布式和独立模式- 扩展到支持整个组织的大型集中管理服务,或缩小到开发、测试和小型生产部署
- REST 接口- 通过易于使用的 REST API 提交和管理到 Kafka Connect 集群的连接器
- 自动偏移管理- 只需来自连接器的少量信息,Kafka Connect 就可以自动管理偏移提交过程,因此连接器开发人员无需担心连接器开发中这个容易出错的部分
- 默认情况下是分布式且可扩展的- Kafka Connect 构建在现有的组管理协议之上。可以添加更多工作人员来扩展 Kafka Connect 集群。
- 流/批集成——利用 Kafka 的现有功能,Kafka Connect 是桥接流和批数据系统的理想解决方案
8.2 用户指南
该快速入门提供了如何运行独立版本的 Kafka Connect 的简短示例。本节更详细地介绍如何配置、运行和管理 Kafka Connect。
Running Kafka Connect
Kafka Connect目前支持两种执行模式:独立(单进程)和分布式。
在独立模式下,所有工作都在单个进程中执行。此配置更易于设置和上手,并且在只有一个工作人员有意义的情况下可能很有用(例如收集日志文件),但它无法从 Kafka Connect 的某些功能(例如容错)中受益。您可以使用以下命令启动独立进程:
> bin/connect-standalone.sh config/connect-standalone.properties [connector1.properties connector2.properties ...]
第一个参数是工作线程的配置。这包括 Kafka 连接参数、序列化格式以及提交偏移量的频率等设置。提供的示例应该适用于使用 提供的默认配置运行的本地集群config/server.properties
。需要进行调整才能与不同的配置或生产部署一起使用。所有工作人员(独立的和分布式的)都需要一些配置:
bootstrap.servers
- 用于引导与 Kafka 的连接的 Kafka 服务器列表key.converter
- 转换器类,用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中键的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。value.converter
- 转换器类,用于在 Kafka Connect 格式和写入 Kafka 的序列化形式之间进行转换。这控制写入 Kafka 或从 Kafka 读取的消息中的值的格式,并且由于它独立于连接器,因此允许任何连接器使用任何序列化格式。常见格式的示例包括 JSON 和 Avro。plugin.path
(默认empty
) - 包含 Connect 插件(连接器、转换器、转换)的路径列表。在运行快速启动之前,用户必须添加包含打包在 中的示例 FileStreamSourceConnector 和 FileStreamSinkConnector 的绝对路径connect-file-"version".jar
,因为默认情况下这些连接器不包含在Connect Worker 中(请参阅CLASSPATH
plugin.path属性以获取示例)。plugin.path
独立模式特有的重要配置选项是:
offset.storage.file.filename
- 存储源连接器偏移的文件
此处配置的参数适用于 Kafka Connect 使用的生产者和消费者来访问配置、偏移量和状态主题。配置Kafka Source任务使用的生产者和Kafka Sink任务使用的消费者,可以使用相同的参数,但需要分别加上producer.
和前缀consumer.
。从工作配置中继承的唯一不带前缀的 Kafka 客户端参数是bootstrap.servers
,在大多数情况下这就足够了,因为同一个集群通常用于所有目的。一个值得注意的例外是安全集群,它需要额外的参数来允许连接。这些参数需要在工作配置中设置最多三次,一次用于管理访问,一次用于 Kafka 源,一次用于 Kafka 接收器。
从 2.3.0 开始,可以分别使用 Kafka 源或 Kafka 接收器的前缀producer.override.
和为每个连接器单独配置客户端配置覆盖。consumer.override.
这些覆盖包含在连接器的其余配置属性中。
其余参数是连接器配置文件。您可以包含任意数量的内容,但所有内容都将在同一进程中(在不同的线程上)执行。您还可以选择不在命令行上指定任何连接器配置文件,而是使用 REST API 在独立工作线程启动后在运行时创建连接器。
分布式模式处理工作的自动平衡,允许您动态扩展(或缩小),并在活动任务以及配置和偏移提交数据中提供容错能力。执行与独立模式非常相似:
> bin/connect-distributed.sh config/connect-distributed.properties
区别在于启动的类和配置参数,它们改变了 Kafka Connect 进程决定在哪里存储配置、如何分配工作以及在哪里存储偏移量和任务状态的方式。在分布式模式下,Kafka Connect 将偏移量、配置和任务状态存储在 Kafka 主题中。建议手动创建偏移量、配置和状态的主题,以获得所需的分区数量和复制因子。如果启动 Kafka Connect 时尚未创建主题,则会使用默认的分区数和复制因子自动创建主题,这可能不太适合其使用。
特别是,除了上面提到的常见设置之外,在启动集群之前设置以下配置参数也很重要:
group.id
(默认connect-cluster
)- 集群的唯一名称,用于形成 Connect 集群组;请注意,这不能与消费者组 ID冲突config.storage.topic
(默认connect-configs
)- 用于存储连接器和任务配置的主题;请注意,这应该是单个分区、高度复制、压缩的主题。您可能需要手动创建主题以确保正确配置,因为自动创建的主题可能有多个分区或自动配置为删除而不是压缩offset.storage.topic
(默认connect-offsets
)- 用于存储偏移量的主题;该主题应该有许多分区,可以复制,并配置为压缩status.storage.topic
(默认connect-status
)- 用于存储状态的主题;该主题可以有多个分区,并且应该复制并配置为压缩
请注意,在分布式模式下,连接器配置不会在命令行上传递。相反,请使用下面描述的 REST API 来创建、修改和销毁连接器。
Configuring Connectors
连接器配置是简单的键值映射。在独立模式和分布式模式下,它们都包含在创建(或修改)连接器的 REST 请求的 JSON 有效负载中。在独立模式下,这些也可以在属性文件中定义并传递到命令行上的 Connect 进程。
大多数配置都依赖于连接器,因此此处无法概述。但是,有一些常见的选项:
name
- 连接器的唯一名称。尝试使用相同名称再次注册将会失败。connector.class
- 连接器的 Java 类tasks.max
- 应为此连接器创建的最大任务数。如果连接器无法实现这种并行级别,它可能会创建更少的任务。key.converter
-(可选)覆盖工作人员设置的默认密钥转换器。value.converter
-(可选)覆盖工作人员设置的默认值转换器。
该connector.class
配置支持多种格式:该连接器的类的全名或别名。如果连接器是 org.apache.kafka.connect.file.FileStreamSinkConnector,您可以指定此全名,也可以使用 FileStreamSink 或 FileStreamSinkConnector 使配置更短一些。
接收器连接器还有一些附加选项来控制其输入。每个接收器连接器必须设置以下其中一项:
topics
- 用作此连接器输入的以逗号分隔的主题列表topics.regex
- 用作此连接器输入的主题的 Java 正则表达式
对于任何其他选项,您应该查阅连接器的文档。
Transformations
连接器可以配置转换以进行轻量级的一次消息修改。它们可以方便地进行数据处理和事件路由。
可以在连接器配置中指定转换链。
transforms
- 转换的别名列表,指定转换的应用顺序。transforms.$alias.type
- 转换的完全限定类名称。transforms.$alias.$transformationSpecificConfig
转换的配置属性
例如,让我们采用内置文件源连接器并使用转换来添加静态字段。
在整个示例中,我们将使用无模式 JSON 数据格式。为了使用无模式格式,我们将以下两行connect-standalone.properties
从 true 更改为 false:
key.converter.schemas.enable value.converter.schemas.enable
文件源连接器将每一行读取为字符串。我们将把每一行包装在一个 Map 中,然后添加第二个字段来标识事件的起源。为此,我们使用两种转换:
- HoistField将输入线放置在地图内
- InsertField添加静态字段。在此示例中,我们将指示记录来自文件连接器
添加转换后,connect-file-source.properties
文件如下所示:
name=local-file-source connector.class=FileStreamSource tasks.max=1 file=test.txt topic=connect-test transforms=MakeMap, InsertSource transforms.MakeMap.type=org.apache.kafka.connect.transforms.HoistField$Value transforms.MakeMap.field=line transforms.InsertSource.type=org.apache.kafka.connect.transforms.InsertField$Value transforms.InsertSource.static.field=data_source transforms.InsertSource.static.value=test-file-source
所有以 开头的行transforms
都是为了转换而添加的。您可以看到我们创建的两个转换:“InsertSource”和“MakeMap”是我们选择提供转换的别名。转换类型基于您可以在下面看到的内置转换列表。每个转换类型都有附加配置:HoistField 需要一个名为“field”的配置,它是映射中包含文件中原始字符串的字段的名称。InsertField 转换让我们指定字段名称和要添加的值。
当我们在不进行转换的情况下在示例文件上运行文件源连接器,然后使用 读取它们时kafka-console-consumer.sh
,结果是:
"foo" "bar" "hello world"
然后,我们在将转换添加到配置文件之后创建一个新的文件连接器。这次,结果将是:
{"line":"foo","data_source":"test-file-source"} {"line":"bar","data_source":"test-file-source"} {"line":"hello world","data_source":"test-file-source"}
您可以看到我们读取的行现在是 JSON 映射的一部分,并且有一个带有我们指定的静态值的额外字段。这只是您可以使用转换执行的操作的示例之一。
包含的转换
Kafka Connect 包含多种广泛适用的数据和路由转换:
- InsertField - 使用静态数据或记录元数据添加字段
- ReplaceField - 过滤或重命名字段
- MaskField - 将字段替换为类型的有效空值(0、空字符串等)或自定义替换(仅限非空字符串或数值)
- ValueToKey - 将记录键替换为由记录值中的字段子集形成的新键
- HoistField - 将整个事件包装为结构或映射中的单个字段
- ExtractField - 从 Struct 和 Map 中提取特定字段并在结果中仅包含该字段
- SetSchemaMetadata - 修改模式名称或版本
- TimestampRouter - 根据原始主题和时间戳修改记录的主题。当使用需要根据时间戳写入不同表或索引的接收器时很有用
- RegexRouter - 根据原始主题、替换字符串和正则表达式修改记录的主题
- 过滤器 - 从所有进一步处理中删除消息。这与谓词一起使用来选择性地过滤某些消息。
- InsertHeader - 使用静态数据添加标题
- HeadersFrom - 将键或值中的字段复制或移动到记录标题
- DropHeaders - 按名称删除标头
下面列出了如何配置每个转换的详细信息:
org.apache.kafka.connect.transforms.InsertField
使用记录元数据中的属性或配置的静态值插入字段。使用为记录键 ( org.apache.kafka.connect.transforms.InsertField$Key
) 或值 ( org.apache.kafka.connect.transforms.InsertField$Value
) 设计的具体转换类型。
-
偏移量字段
Kafka 偏移量的字段名称 - 仅适用于接收器连接器。
后缀 with!
使其成为必填字段,或?
使其保持可选(默认)。Type: string Default: null Valid Values: Importance: medium -
分区字段
Kafka 分区的字段名称。后缀 with
!
使其成为必填字段,或?
使其保持可选(默认)。Type: string Default: null Valid Values: Importance: medium -
静态场
静态数据字段的字段名称。后缀 with
!
使其成为必填字段,或?
使其保持可选(默认)。Type: string Default: null Valid Values: Importance: medium -
静态值
静态字段值(如果配置了字段名称)。
Type: string Default: null Valid Values: Importance: medium -
时间戳字段
记录时间戳的字段名称。后缀 with
!
使其成为必填字段,或?
使其保持可选(默认)。Type: string Default: null Valid Values: Importance: medium -
主题.字段
Kafka 主题的字段名称。后缀 with
!
使其成为必填字段,或?
使其保持可选(默认)。Type: string Default: null Valid Values: Importance: medium
org.apache.kafka.connect.transforms.ReplaceField
过滤或重命名字段。使用为记录键 ( org.apache.kafka.connect.transforms.ReplaceField$Key
) 或值 ( org.apache.kafka.connect.transforms.ReplaceField$Value
) 设计的具体转换类型。
-
排除
要排除的字段。这优先于要包含的字段。
Type: list Default: "" Valid Values: Importance: medium -
包括
要包含的字段。如果指定,则仅使用这些字段。
Type: list Default: "" Valid Values: Importance: medium -
重命名
字段重命名映射。
Type: list Default: "" Valid Values: list of colon-delimited pairs, e.g. foo:bar,abc:xyz
Importance: medium -
黑名单
已弃用。请改用排除。
Type: list Default: null Valid Values: Importance: low -
白名单
已弃用。使用包含代替。
Type: list Default: null Valid Values: Importance: low
org.apache.kafka.connect.transforms.MaskField
使用字段类型的有效空值(即 0、false、空字符串等)屏蔽指定字段。对于数字和字符串字段,可以指定转换为正确类型的可选替换值。
使用为记录键 ( org.apache.kafka.connect.transforms.MaskField$Key
) 或值 ( org.apache.kafka.connect.transforms.MaskField$Value
) 设计的具体转换类型。
org.apache.kafka.connect.transforms.ValueToKey
将记录键替换为由记录值中的字段子集形成的新键。
-
领域
要提取作为记录键的记录值上的字段名称。
Type: list Default: Valid Values: non-empty list Importance: high
org.apache.kafka.connect.transforms.HoistField
如果存在架构,则使用结构中指定的字段名称包装数据;如果存在无架构数据,则使用映射包装数据。使用为记录键 ( org.apache.kafka.connect.transforms.HoistField$Key
) 或值 ( org.apache.kafka.connect.transforms.HoistField$Value
) 设计的具体转换类型。
-
场地
将在生成的结构或映射中创建的单个字段的字段名称。
Type: string Default: Valid Values: Importance: medium
org.apache.kafka.connect.transforms.ExtractField
如果存在模式,则从结构中提取指定字段;如果存在无模式数据,则从映射中提取指定字段。任何空值都会不加修改地传递。使用为记录键 ( org.apache.kafka.connect.transforms.ExtractField$Key
) 或值 ( org.apache.kafka.connect.transforms.ExtractField$Value
) 设计的具体转换类型。
-
场地
要提取的字段名称。
Type: string Default: Valid Values: Importance: medium
org.apache.kafka.connect.transforms.SetSchemaMetadata
org.apache.kafka.connect.transforms.SetSchemaMetadata$Key
在记录的键 ( ) 或值 ( org.apache.kafka.connect.transforms.SetSchemaMetadata$Value
) 架构
上设置架构名称、版本或两者。
org.apache.kafka.connect.transforms.TimestampRouter
根据原始主题值和记录时间戳更新记录的主题字段。这主要对接收器连接器有用,因为主题字段通常用于确定目标系统中的等效实体名称(例如数据库表或搜索索引名称)。
org.apache.kafka.connect.transforms.RegexRouter
使用配置的正则表达式和替换字符串更新记录主题。在底层,正则表达式被编译为java.util.regex.Pattern
. 如果模式与输入主题匹配,java.util.regex.Matcher#replaceFirst()
则与替换字符串一起使用来获取新主题。
org.apache.kafka.connect.transforms.Flatten
展平嵌套数据结构,通过将每个级别的字段名称与可配置的分隔符连接来生成每个字段的名称。当模式存在时适用于结构,或者在无模式数据的情况下适用于映射。数组字段及其内容不会被修改。默认分隔符是“.”。使用为记录键 ( org.apache.kafka.connect.transforms.Flatten$Key
) 或值 ( org.apache.kafka.connect.transforms.Flatten$Value
) 设计的具体转换类型。
-
分隔符
为输出记录生成字段名称时在输入记录的字段名称之间插入的分隔符
Type: string Default: . Valid Values: Importance: medium
org.apache.kafka.connect.transforms.Cast
将字段或整个键或值转换为特定类型,例如强制整数字段具有较小的宽度。从整数、浮点数、布尔值和字符串转换为任何其他类型,并将二进制转换为字符串(base64 编码)。使用为记录键 ( org.apache.kafka.connect.transforms.Cast$Key
) 或值 ( org.apache.kafka.connect.transforms.Cast$Value
) 设计的具体转换类型。
-
规格
字段列表以及将其转换为 form field1:type,field2:type 的类型以转换映射或结构的字段。用于转换整个值的单一类型。有效类型包括 int8、int16、int32、int64、float32、float64、boolean 和 string。请注意,二进制字段只能转换为字符串。
Type: list Default: Valid Values: list of colon-delimited pairs, e.g. foo:bar,abc:xyz
Importance: high
org.apache.kafka.connect.transforms.TimestampConverter
在不同格式(例如 Unix 纪元、字符串和连接日期/时间戳类型)之间转换时间戳。适用于单个字段或整个值。使用为记录键 ( org.apache.kafka.connect.transforms.TimestampConverter$Key
) 或值 ( org.apache.kafka.connect.transforms.TimestampConverter$Value
) 设计的具体转换类型。
-
目标类型
所需的时间戳表示形式:字符串、unix、日期、时间或时间戳
Type: string Default: Valid Values: [string, unix, Date, Time, Timestamp] Importance: high -
场地
包含时间戳的字段,如果整个值是时间戳,则为空
Type: string Default: "" Valid Values: Importance: high -
格式
与 SimpleDateFormat 兼容的时间戳格式。当 type=string 时用于生成输出,或者如果输入是字符串则用于解析输入。
Type: string Default: "" Valid Values: Importance: medium -
unix.精度
时间戳所需的 Unix 精度:秒、毫秒、微秒或纳秒。用于在 type=unix 时生成输出,或用于在输入为 Long 时解析输入。注意:此 SMT 将在与具有亚毫秒分量的值进行转换期间导致精度损失。
Type: string Default: milliseconds Valid Values: [nanoseconds, microseconds, milliseconds, seconds] Importance: low
org.apache.kafka.connect.transforms.DropHeaders
从每条记录中删除一个或多个标头。
-
标头
要删除的标头的名称。
Type: list Default: Valid Values: non-empty list Importance: high
org.apache.kafka.connect.transforms.HeaderFrom
将记录的键/值中的字段移动或复制到该记录的标题中。fields
和 的相应元素headers
一起标识字段以及应将其移动或复制到的标题。使用为记录键 ( org.apache.kafka.connect.transforms.HeaderFrom$Key
) 或值 ( org.apache.kafka.connect.transforms.HeaderFrom$Value
) 设计的具体转换类型。
谓词
可以使用谓词配置转换,以便转换仅应用于满足某些条件的消息。特别是,当与过滤器转换谓词结合使用时,可用于有选择地过滤掉某些消息。
谓词在连接器配置中指定。
predicates
- 应用于某些转换的谓词的别名集。predicates.$alias.type
- 谓词的完全限定类名。predicates.$alias.$predicateSpecificConfig
- 谓词的配置属性。
所有转换都具有隐式配置属性predicate
和negate
. 通过将转换的配置设置predicate
为谓词的别名,谓词谓词与转换相关联。可以使用配置属性反转谓词的值negate
。
例如,假设您有一个源连接器,它向许多不同的主题生成消息,并且您希望:
- 完全过滤掉“foo”主题中的消息
- 将字段名称为“other_field”的 ExtractField 转换应用于除主题“bar”之外的所有主题中的记录
为此,我们首先需要过滤掉以主题“foo”为目的地的记录。过滤器转换会从进一步处理中删除记录,并且可以使用 TopicNameMatches 谓词将转换仅应用于主题中与特定正则表达式匹配的记录。TopicNameMatches 唯一的配置属性是pattern
which,它是一个用于匹配主题名称的Java 正则表达式。配置如下所示:
transforms=Filter transforms.Filter.type=org.apache.kafka.connect.transforms.Filter transforms.Filter.predicate=IsFoo predicates=IsFoo predicates.IsFoo.type=org.apache.kafka.connect.transforms.predicates.TopicNameMatches predicates.IsFoo.pattern=foo
接下来,仅当记录的主题名称不是“bar”时,我们才需要应用ExtractField。我们不能直接使用 TopicNameMatches,因为这会将转换应用于匹配的主题名称,而不是不匹配的主题名称。转换的隐式negate
配置属性允许我们反转谓词匹配的记录集。将其配置添加到前面的示例中,我们得到:
transforms=Filter,Extract transforms.Filter.type=org.apache.kafka.connect.transforms.Filter transforms.Filter.predicate=IsFoo transforms.Extract.type=org.apache.kafka.connect.transforms.ExtractField$Key transforms.Extract.field=other_field transforms.Extract.predicate=IsBar transforms.Extract.negate=true predicates=IsFoo,IsBar predicates.IsFoo.type=org.apache.kafka.connect.transforms.predicates.TopicNameMatches predicates.IsFoo.pattern=foo predicates.IsBar.type=org.apache.kafka.connect.transforms.predicates.TopicNameMatches predicates.IsBar.pattern=bar
Kafka Connect 包括以下谓词:
TopicNameMatches
- 匹配主题中名称与特定 Java 正则表达式匹配的记录。HasHeaderKey
- 匹配具有给定键的标头的记录。RecordIsTombstone
- 匹配墓碑记录,即具有空值的记录。
下面列出了如何配置每个谓词的详细信息:
org.apache.kafka.connect.transforms.predicates.HasHeaderKey
一个谓词,对于至少具有一个具有配置名称的标头的记录为真。
-
姓名
标头名称。
Type: string Default: Valid Values: non-empty string Importance: medium
org.apache.kafka.connect.transforms.predicates.TopicNameMatches
对于主题名称与配置的正则表达式匹配的记录为 true 的谓词。
-
图案
用于匹配记录主题名称的 Java 正则表达式。
Type: string Default: Valid Values: non-empty string, valid regex Importance: medium
REST API
由于 Kafka Connect 旨在作为服务运行,因此它还提供了用于管理连接器的 REST API。此 REST API 可在独立模式和分布式模式下使用。可以使用配置选项配置 REST API 服务器listeners
。该字段应包含以下格式的侦听器列表:protocol://host:port,protocol2://host2:port2
。目前支持的协议有http
和https
。例如:
listeners=http://localhost:8080,https://localhost:8443
默认情况下,如果未listeners
指定,REST 服务器使用 HTTP 协议在端口 8083 上运行。使用 HTTPS 时,配置必须包含 SSL 配置。默认情况下,它将使用这些ssl.*
设置。如果需要对 REST API 使用与连接 Kafka 代理不同的配置,则字段可以以listeners.https
. 使用前缀时,仅使用带前缀的选项,ssl.*
不带前缀的选项将被忽略。以下字段可用于为 REST API 配置 HTTPS:
ssl.keystore.location
ssl.keystore.password
ssl.keystore.type
ssl.key.password
ssl.truststore.location
ssl.truststore.password
ssl.truststore.type
ssl.enabled.protocols
ssl.provider
ssl.protocol
ssl.cipher.suites
ssl.keymanager.algorithm
ssl.secure.random.implementation
ssl.trustmanager.algorithm
ssl.endpoint.identification.algorithm
ssl.client.auth
REST API 不仅供用户用来监控/管理 Kafka Connect。在分布式模式下,它还用于Kafka Connect跨集群通信。从属节点 REST API 上收到的一些请求将转发到领导节点 REST API。如果给定主机可访问的 URI 与其侦听的 URI 不同,则配置选项rest.advertised.host.name
和rest.advertised.port
可rest.advertised.listener
用于更改跟随者节点用于与领导者连接的 URI。当同时使用 HTTP 和 HTTPS 侦听器时,该rest.advertised.listener
选项还可用于定义将使用哪个侦听器进行跨集群通信。当使用 HTTPS 在节点之间进行通信时,将使用相同的ssl.*
或选项来配置 HTTPS 客户端。listeners.https
以下是当前支持的 REST API 端点:
GET /connectors
- 返回活动连接器的列表POST /connectors
- 创建一个新的连接器;请求正文应该是一个 JSON 对象,其中包含字符串name
字段和config
带有连接器配置参数的对象字段GET /connectors/{name}
- 获取有关特定连接器的信息GET /connectors/{name}/config
- 获取特定连接器的配置参数PUT /connectors/{name}/config
- 更新特定连接器的配置参数GET /connectors/{name}/status
- 获取连接器的当前状态,包括它是否正在运行、失败、暂停等,它被分配给哪个工作线程,失败时的错误信息,以及它的所有任务的状态GET /connectors/{name}/tasks
- 获取连接器当前运行的任务列表GET /connectors/{name}/tasks/{taskid}/status
- 获取任务的当前状态,包括它是否正在运行、失败、暂停等,它被分配给哪个worker,以及失败时的错误信息PUT /connectors/{name}/pause
- 暂停连接器及其任务,这会停止消息处理,直到连接器恢复为止。其任务占用的任何资源都会保留分配状态,这使得连接器可以在恢复后快速开始处理数据。PUT /connectors/{name}/stop
- 停止连接器并关闭其任务,取消分配其任务占用的任何资源。从资源使用的角度来看,这比暂停连接器更有效,但可能会导致连接器恢复后需要更长时间才能开始处理数据。请注意,如果连接器处于停止状态,则只能通过偏移量管理端点修改连接器的偏移量PUT /connectors/{name}/resume
- 恢复暂停或停止的连接器(或者如果连接器未暂停或停止则不执行任何操作)POST /connectors/{name}/restart?includeTasks=<true|false>&onlyFailed=<true|false>
- 重新启动连接器及其任务实例。- “includeTasks”参数指定是否重新启动连接器实例和任务实例(“includeTasks=true”)或仅重新启动连接器实例(“includeTasks=false”),默认值(“false”)保留与早期版本相同的行为。
- “onlyFailed”参数指定是仅重新启动具有 FAILED 状态的实例(“onlyFailed=true”)还是重新启动所有实例(“onlyFailed=false”),默认值(“false”)保留与早期版本相同的行为。
POST /connectors/{name}/tasks/{taskId}/restart
- 重新启动单个任务(通常是因为它失败了)DELETE /connectors/{name}
- 删除连接器,停止所有任务并删除其配置GET /connectors/{name}/topics
- 获取自创建连接器或发出重置其活动主题集的请求以来特定连接器正在使用的主题集PUT /connectors/{name}/topics/reset
- 发送请求以清空连接器的活动主题集- 偏移管理端点(有关更多详细信息,
请参阅KIP-875 ):
GET /connectors/{name}/offsets
- 获取连接器的当前偏移量DELETE /connectors/{name}/offsets
- 重置连接器的偏移。连接器必须存在并且必须处于停止状态(请参阅PUT /connectors/{name}/stop
)PATCH /connectors/{name}/offsets
- 改变连接器的偏移。连接器必须存在并且必须处于停止状态(请参阅PUT /connectors/{name}/stop
)。请求正文应该是包含 JSON 数组字段的 JSON 对象offsets
,类似于GET /connectors/{name}/offsets
端点的响应正文
请求正文示例
FileStreamSourceConnector
:
请求正文示例{ "offsets": [ { "partition": { "filename": "test.txt" }, "offset": { "position": 30 } } ] }
FileStreamSinkConnector
:
“offset”字段可以为空,以重置特定分区的偏移量(适用于源连接器和接收器连接器)。请注意,在源连接器的情况下,请求正文格式取决于连接器实现,而所有接收器连接器都有通用格式。{ "offsets": [ { "partition": { "kafka_topic": "test", "kafka_partition": 0 }, "offset": { "kafka_offset": 5 } }, { "partition": { "kafka_topic": "test", "kafka_partition": 1 }, "offset": null } ] }
Kafka Connect 还提供了一个 REST API,用于获取有关连接器插件的信息:
GET /connector-plugins
- 返回 Kafka Connect 集群中安装的连接器插件列表。请注意,API 仅检查处理请求的工作线程上的连接器,这意味着您可能会看到不一致的结果,尤其是在滚动升级期间,如果您添加新的连接器 jarGET /connector-plugins/{plugin-type}/config
- 获取指定插件的配置定义。PUT /connector-plugins/{connector-type}/config/validate
- 根据配置定义验证提供的配置值。此 API 执行每个配置验证,在验证期间返回建议值和错误消息。
以下是顶级(根)端点支持的 REST 请求:
GET /
- 返回有关 Kafka Connect 集群的基本信息,例如服务 REST 请求的 Connect Worker 的版本(包括源代码的 git commit ID)以及连接到的 Kafka 集群 ID。
该admin.listeners
配置可用于在 Kafka Connect 的 REST API 服务器上配置管理 REST API。与配置类似listeners
,该字段应包含以下格式的侦听器列表:protocol://host:port,protocol2://host2:port2
。目前支持的协议有http
和https
。例如:
admin.listeners=http://localhost:8080,https://localhost:8443
默认情况下,如果admin.listeners
未配置,管理 REST API 将在常规侦听器上可用。
以下是当前支持的管理 REST API 端点:
GET /admin/loggers
- 列出明确设置级别的当前记录器及其日志级别GET /admin/loggers/{name}
- 获取指定记录器的日志级别PUT /admin/loggers/{name}
- 设置指定记录器的日志级别
有关管理记录器 REST API 的更多详细信息,请参阅KIP-495 。
有关 Kafka Connect REST API 的完整规范,请参阅OpenAPI 文档
Error Reporting in Connect
Kafka Connect 提供错误报告来处理各个处理阶段遇到的错误。默认情况下,转换期间或转换中遇到的任何错误都会导致连接器失败。每个连接器配置还可以通过跳过此类错误、选择性地将每个错误以及失败操作的详细信息和有问题的记录(具有各种详细级别)写入 Connect 应用程序日志来容忍此类错误。当接收器连接器处理从其 Kafka 主题消耗的消息时,这些机制还会捕获错误,并且所有错误都可以写入可配置的“死信队列”(DLQ) Kafka 主题。
要将连接器的转换器、转换或接收器连接器本身内的错误报告到日志,请errors.log.enable=true
在连接器配置中设置以记录每个错误和问题记录的主题、分区和偏移量的详细信息。出于其他调试目的,设置errors.log.include.messages=true
为还将问题记录键、值和标头记录到日志中(请注意,这可能会记录敏感信息)。
要将连接器的转换器、转换或接收器连接器本身内的错误报告给死信队列主题,请设置errors.deadletterqueue.topic.name
和(可选)errors.deadletterqueue.context.headers.enable=true
。
默认情况下,连接器在出现错误或异常时立即表现出“快速失败”行为。这相当于将以下配置属性及其默认值添加到连接器配置中:
# disable retries on failure errors.retry.timeout=0 # do not log the error and their contexts errors.log.enable=false # do not record errors in a dead letter queue topic errors.deadletterqueue.topic.name= # Fail on first error errors.tolerance=none
可以更改这些和其他相关的连接器配置属性以提供不同的行为。例如,可以将以下配置属性添加到连接器配置中,以通过多次重试设置错误处理、记录到应用程序日志和 Kafka 主题my-connector-errors
,并通过报告错误而不是使连接器任务失败来容忍所有错误:
# retry for at most 10 minutes times waiting up to 30 seconds between consecutive failures errors.retry.timeout=600000 errors.retry.delay.max.ms=30000 # log error context along with application logs, but do not include configs and messages errors.log.enable=true errors.log.include.messages=false # produce error context into the Kafka topic errors.deadletterqueue.topic.name=my-connector-errors # Tolerate all errors. errors.tolerance=all
Exactly-once support
Kafka Connect 能够为接收器连接器(从版本 0.11.0 开始)和源连接器(从版本 3.3.0 开始)提供一次性语义。请注意,对一次语义的支持高度依赖于您运行的连接器类型。即使您在集群中每个节点的配置中设置了所有正确的工作线程属性,如果连接器未设计为或无法利用 Kafka Connect 框架的功能,则可能无法实现精确一次。
水槽连接器
如果接收器连接器支持精确一次语义,要在 Connect 工作线程级别启用精确一次,您必须确保其使用者组配置为忽略中止事务中的记录。您可以通过将工作程序属性设置consumer.isolation.level
为来实现此read_committed
目的,或者,如果运行支持它的 Kafka Connect 版本,则使用连接器客户端配置覆盖策略,允许在各个连接器配置中consumer.override.isolation.level
将该属性设置为。read_committed
没有额外的 ACL 要求。
源连接器
如果源连接器支持一次性语义,则必须配置 Connect 集群以启用对一次性源连接器的框架级支持。如果针对安全的 Kafka 集群运行,可能需要额外的 ACL。请注意,对源连接器的一次性支持目前仅在分布式模式下可用;独立的 Connect 工作线程无法提供一次性语义。
工作人员配置
对于新的 Connect 集群,请在集群中每个节点的工作程序配置中将该exactly.once.source.support
属性设置为。enabled
对于现有集群,需要进行两次滚动升级。在第一次升级期间,该exactly.once.source.support
属性应设置为preparing
,在第二次升级期间,应设置为enabled
。
ACL要求
启用一次性源支持后,每个 Connect 工作线程的主体将需要以下 ACL:
手术 | 资源类型 | 资源名称 | 笔记 |
---|---|---|---|
Write | 交易ID | connect-cluster-${groupId} ,其中${groupId} 是group.id 簇的 |
|
Describe | 交易ID | connect-cluster-${groupId} ,其中${groupId} 是group.id 簇的 |
|
IdempotentWrite | 簇 | 托管worker配置主题的Kafka集群的ID | IdempotWrite ACL 自 2.8 起已被弃用,仅对于在 2.8 之前的 Kafka 集群上运行的 Connect 集群是必需的 |
每个连接器的主体将需要以下 ACL:
手术 | 资源类型 | 资源名称 | 笔记 |
---|---|---|---|
Write | 交易ID | ${groupId}-${connector}-${taskId} ,对于连接器将创建的每个任务,其中${groupId} 是group.id Connect 集群的 ,${connector} 是连接器的名称,${taskId} 是任务的 ID(从零开始) |
${groupId}-${connector}* 如果不存在与其他事务 ID 冲突的风险或者用户可以接受冲突,则可以使用通配符前缀以方便起见。 |
Describe | 交易ID | ${groupId}-${connector}-${taskId} ,对于连接器将创建的每个任务,其中${groupId} 是group.id Connect 集群的 ,${connector} 是连接器的名称,${taskId} 是任务的 ID(从零开始) |
${groupId}-${connector}* 如果不存在与其他事务 ID 冲突的风险或者用户可以接受冲突,则可以使用通配符前缀以方便起见。 |
Write | 话题 | offsets.storage.topic 连接器使用的偏移主题,它是连接器配置中的属性值(如果提供)或offsets.storage.topic 工作线程配置中的属性值(如果未提供)。 |
|
Read | 话题 | offsets.storage.topic 连接器使用的偏移主题,它是连接器配置中的属性值(如果提供)或offsets.storage.topic 工作线程配置中的属性值(如果未提供)。 |
|
Describe | 话题 | offsets.storage.topic 连接器使用的偏移主题,它是连接器配置中的属性值(如果提供)或offsets.storage.topic 工作线程配置中的属性值(如果未提供)。 |
|
Create | 话题 | offsets.storage.topic 连接器使用的偏移主题,它是连接器配置中的属性值(如果提供)或offsets.storage.topic 工作线程配置中的属性值(如果未提供)。 |
仅当连接器的偏移主题尚不存在时才需要 |
IdempotentWrite | 簇 | 源连接器写入的Kafka集群ID | IdempotWrite ACL 自 2.8 起已被弃用,仅对于在 2.8 之前的 Kafka 集群上运行的 Connect 集群是必需的 |
Plugin Discovery
插件发现是 Connect Worker 用于查找插件类并使它们可在连接器中配置和运行的策略的名称。这是由plugin.discovery工作器配置控制的,并且对工作器启动时间有重大影响。service_load
是最快的策略,但在将此配置设置为 之前应注意验证插件是否兼容service_load
。
在 3.6 版本之前,此策略是不可配置的,其行为类似于only_scan
与所有插件兼容的模式。对于 3.6 及更高版本,此模式默认hybrid_warn
也与所有插件兼容,但会记录与service_load
. 如果检测到不兼容的插件,该hybrid_fail
策略会停止工作程序并发出错误,断言所有插件都是兼容的。service_load
最后,该service_load
策略禁用所有其他模式中使用的缓慢的传统扫描机制,而是使用更快的ServiceLoader
机制。与该机制不兼容的插件可能无法使用。
验证插件兼容性
要验证您的所有插件是否与 兼容service_load
,请首先确保您使用的是 Kafka Connect 3.6 或更高版本。然后您可以执行以下检查之一:
- 使用默认
hybrid_warn
策略启动工作程序,并为org.apache.kafka.connect
包启用 WARN 日志。应至少plugin.discovery
打印一条提及配置的 WARN 日志消息。此日志消息将明确说明所有插件都是兼容的,或列出不兼容的插件。 - 在测试环境中启动您的工作程序
hybrid_fail
。如果所有插件都兼容,启动就会成功。如果至少有一个插件不兼容,则工作器将无法启动,并且所有不兼容的插件将在异常中列出。
如果验证步骤成功,则您当前安装的一组插件是兼容的,并且可以安全地将配置更改plugin.discovery
为service_load
. 如果验证失败,则无法使用service_load
策略,并应记下不兼容插件列表。在使用该策略之前必须解决所有插件的问题service_load
。建议在安装或更改插件版本后执行此验证,并且该验证可以在持续集成环境中自动完成。
运营商:工件迁移
作为 Connect 的运营者,如果您发现不兼容的插件,有多种方法可以解决不兼容问题。下面按最优选到最不优选的顺序列出了它们。
- 检查插件提供商的最新版本,如果兼容,请升级。
- 请联系您的插件提供商并请求他们按照源迁移说明将插件迁移为兼容版本,然后升级到兼容版本。
- 使用附带的迁移脚本自行迁移插件工件。
迁移脚本位于您的 Kafka 安装bin/connect-plugin-path.sh
中。该脚本可以通过添加或修改 JAR 或资源文件来bin\windows\connect-plugin-path.bat
迁移已安装在 Connect Worker 上的不兼容插件工件。plugin.path
这不适合使用代码签名的环境,因为这可能会更改工件,导致签名验证失败。查看内置帮助--help
。
要执行迁移,首先使用list
子命令获取脚本可用插件的概述。您必须告诉脚本在哪里可以找到插件,这可以使用可重复的--worker-config
、--plugin-path
和--plugin-location
参数来完成。该脚本将忽略类路径上的插件,因此类路径上的任何自定义插件都应移动到插件路径,以便与此迁移脚本一起使用,或手动迁移。请务必将 的输出list
与工作程序启动警告或错误消息进行比较,以确保脚本找到所有受影响的插件。
一旦您看到所有不兼容的插件都包含在列表中,您就可以继续使用sync-manifests --dry-run
. 这将执行迁移的所有部分,除了将迁移结果写入磁盘之外。请注意,该sync-manifests
命令要求所有指定的路径都是可写的,并且可能会更改目录的内容。在指定路径中备份您的插件,或将它们复制到可写目录。
在删除标志并实际运行迁移之前,请确保您有插件的备份并且--dry-run
试运行成功。如果迁移失败且没有该--dry-run
标志,则应丢弃部分迁移的工件。迁移是幂等的,因此在已迁移的插件上多次运行它是安全的。脚本完成后,您应该验证迁移是否完成。迁移脚本适合在持续集成环境中使用,实现自动迁移。
开发者:源迁移
为了使插件与 兼容service_load
,需要将ServiceLoader清单添加到源代码中,然后将其打包到发布工件中。清单是META-INF/services/
以其超类类型命名的资源文件,并包含完全限定的子类名称列表,每行一个。
为了使插件兼容,它必须在清单中显示为与其扩展的插件超类相对应的一行。如果单个插件实现多个插件接口,那么它应该出现在它实现的每个接口的清单中。如果您没有某种类型插件的类,则不需要包含该类型的清单文件。如果您有不应作为插件可见的类,则应将它们标记为抽象。以下类型预计有清单:
org.apache.kafka.connect.sink.SinkConnector
org.apache.kafka.connect.source.SourceConnector
org.apache.kafka.connect.storage.Converter
org.apache.kafka.connect.storage.HeaderConverter
org.apache.kafka.connect.transforms.Transformation
org.apache.kafka.connect.transforms.predicates.Predicate
org.apache.kafka.common.config.provider.ConfigProvider
org.apache.kafka.connect.rest.ConnectRestExtension
org.apache.kafka.connect.connector.policy.ConnectorClientConfigOverridePolicy
例如,如果您只有一个具有完全限定名称的连接器com.example.MySinkConnector
,则只需将一个清单文件添加到 中的资源中META-INF/services/org.apache.kafka.connect.sink.SinkConnector
,并且内容应类似于以下内容:
# license header or comment com.example.MySinkConnector
然后,您应该通过使用预发布工件的验证步骤来验证您的清单是否正确。如果验证成功,则可以正常发布插件,运营商也可以升级到兼容版本。
8.3 连接器开发指南
本指南介绍了开发人员如何为 Kafka Connect 编写新的连接器以在 Kafka 和其他系统之间移动数据。它简要回顾了一些关键概念,然后描述了如何创建简单的连接器。
Core Concepts and APIs
连接器和任务
要在 Kafka 和另一个系统之间复制数据,用户需要Connector
为他们想要从中提取数据或向其中推送数据的系统创建一个 Kafka 系统。连接器有两种类型:SourceConnectors
从另一个系统导入数据(例如JDBCSourceConnector
将关系数据库导入到 Kafka)和SinkConnectors
导出数据(例如HDFSSinkConnector
将 Kafka 主题的内容导出到 HDFS 文件)。
Connectors
自己不执行任何数据复制:它们的配置描述了要复制的数据,并且Connector
负责将该作业分解为一组Tasks
可以分发给工作人员的数据。它们Tasks
也有两种相应的风格:SourceTask
和SinkTask
。
完成任务后,每个人都Task
必须将其数据子集复制到 Kafka 或从 Kafka 复制数据。在 Kafka Connect 中,应该始终可以将这些分配构建为一组输入和输出流,其中包含具有一致模式的记录。有时这种映射是显而易见的:一组日志文件中的每个文件都可以被视为一个流,其中每个解析的行使用相同的模式形成一条记录,并将偏移量存储为文件中的字节偏移量。在其他情况下,映射到此模型可能需要更多工作:JDBC 连接器可以将每个表映射到流,但偏移量不太清楚。一种可能的映射使用时间戳列来生成增量返回新数据的查询,并且最后查询的时间戳可以用作偏移量。
流和记录
每个流应该是一系列键值记录。键和值都可以具有复杂的结构——提供了许多基本类型,但也可以表示数组、对象和嵌套数据结构。运行时数据格式不采用任何特定的序列化格式;这种转换由框架内部处理。
除了键和值之外,记录(由源生成的记录和传送到接收器的记录)还具有关联的流 ID 和偏移量。框架使用它们定期提交已处理的数据的偏移量,以便在发生故障时,可以从上次提交的偏移量恢复处理,从而避免不必要的重新处理和重复事件。
动态连接器
并非所有作业都是静态的,因此Connector
实现还负责监视外部系统是否有任何可能需要重新配置的更改。例如,在该JDBCSourceConnector
示例中,Connector
可能会为每个Task
. 创建新表时,它必须发现这一点,以便可以通过更新其配置将新表分配给其中之一Tasks
。当它注意到需要重新配置的更改(或 数量的更改Tasks
)时,它会通知框架,框架会更新任何相应的Tasks
.
Developing a Simple Connector
开发连接器只需要实现两个接口:Connector
和Task
。包中的 Kafka 源代码中包含一个简单的示例file
。该连接器适用于独立模式,并具有SourceConnector
/的实现SourceTask
,用于读取文件的每一行并将其作为记录发出,以及SinkConnector
/SinkTask
将每个记录写入文件。
本节的其余部分将逐步介绍一些代码来演示创建连接器的关键步骤,但开发人员还应该参考完整的示例源代码,因为为了简洁起见,省略了许多细节。
连接器示例
我们将作为一个简单的例子进行介绍SourceConnector
。SinkConnector
实现非常相似。选择一个包和类名,这些示例将使用FileStreamSourceConnector
但在适当的情况下替换您自己的类名。为了使插件在运行时可发现,请将 ServiceLoader 清单添加到您的资源中,META-INF/services/org.apache.kafka.connect.source.SourceConnector
并在一行中包含完全限定的类名:
com.example.FileStreamSourceConnector
创建一个继承SourceConnector
并添加一个字段的类,该字段将存储要传播到任务的配置信息(要发送数据的主题,以及可选的 - 要读取的文件名和最大批量大小):
package com.example; public class FileStreamSourceConnector extends SourceConnector { private Map<String, String> props;
最简单的填写方法是taskClass()
,它定义了应该在工作进程中实例化以实际读取数据的类:
@Override public Class<? extends Task> taskClass() { return FileStreamSourceTask.class; }
我们将FileStreamSourceTask
在下面定义该类。接下来,我们添加一些标准生命周期方法,start()
并且stop()
:
@Override public void start(Map<String, String> props) { // Initialization logic and setting up of resources can take place in this method. // This connector doesn't need to do any of that, but we do log a helpful message to the user. this.props = props; AbstractConfig config = new AbstractConfig(CONFIG_DEF, props); String filename = config.getString(FILE_CONFIG); filename = (filename == null || filename.isEmpty()) ? "standard input" : config.getString(FILE_CONFIG); log.info("Starting file source connector reading from {}", filename); } @Override public void stop() { // Nothing to do since no background monitoring is required. }
最后,实现的真正核心是在taskConfigs()
. 在这种情况下,我们只处理单个文件,因此即使我们可能被允许根据参数生成更多任务
maxTasks
,我们也会返回一个只有一个条目的列表:
@Override public List<Map<String, String>> taskConfigs(int maxTasks) { // Note that the task configs could contain configs additional to or different from the connector configs if needed. For instance, // if different tasks have different responsibilities, or if different tasks are meant to process different subsets of the source data stream). ArrayList<Map<String, String>> configs = new ArrayList<>(); // Only one input stream makes sense. configs.add(props); return configs; }
即使有多个任务,此方法的实现通常也非常简单。它只需要确定输入任务的数量,这可能需要联系从中提取数据的远程服务,然后将它们分开。由于一些在任务之间分配工作的模式非常常见,因此提供了一些实用程序ConnectorUtils
来简化这些情况。
请注意,这个简单的示例不包括动态输入。有关如何触发任务配置更新的信息,请参阅下一节中的讨论。
任务示例 - 源任务
接下来我们将描述相应的实现SourceTask
。实现很短,但太长,无法在本指南中完全涵盖。我们将使用伪代码来描述大部分实现,但您可以参考完整示例的源代码。
就像连接器一样,我们需要创建一个从适当的基类继承的类Task
。它还有一些标准的生命周期方法:
public class FileStreamSourceTask extends SourceTask { private String filename; private InputStream stream; private String topic; private int batchSize; @Override public void start(Map<String, String> props) { filename = props.get(FileStreamSourceConnector.FILE_CONFIG); stream = openOrThrowError(filename); topic = props.get(FileStreamSourceConnector.TOPIC_CONFIG); batchSize = props.get(FileStreamSourceConnector.TASK_BATCH_SIZE_CONFIG); } @Override public synchronized void stop() { stream.close(); }
这些是稍微简化的版本,但表明这些方法应该相对简单,并且它们应该执行的唯一工作是分配或释放资源。这个实现有两点需要注意。首先,该start()
方法尚未处理从先前偏移量恢复的问题,这将在后面的部分中解决。其次,stop()
方法是同步的。这是必要的,因为SourceTasks
有一个专用线程,它们可以无限期地阻塞,因此需要通过来自 Worker 中不同线程的调用来停止它们。
接下来,我们实现任务的主要功能,即poll()
从输入系统获取事件并返回 a 的方法List<SourceRecord>
:
@Override public List<SourceRecord> poll() throws InterruptedException { try { ArrayList<SourceRecord> records = new ArrayList<>(); while (streamValid(stream) && records.isEmpty()) { LineAndOffset line = readToNextLine(stream); if (line != null) { Map<String, Object> sourcePartition = Collections.singletonMap("filename", filename); Map<String, Object> sourceOffset = Collections.singletonMap("position", streamOffset); records.add(new SourceRecord(sourcePartition, sourceOffset, topic, Schema.STRING_SCHEMA, line)); if (records.size() >= batchSize) { return records; } } else { Thread.sleep(1); } } return records; } catch (IOException e) { // Underlying stream was killed, probably as a result of calling stop. Allow to return // null, and driving thread will handle any shutdown if necessary. } return null; }
同样,我们省略了一些细节,但我们可以看到重要的步骤:该poll()
方法将被重复调用,并且对于每次调用,它将循环尝试从文件中读取记录。对于它读取的每一行,它还会跟踪文件偏移量。它使用此信息创建一个包含SourceRecord
四部分信息的输出:源分区(只有一个,正在读取的单个文件)、源偏移量(文件中的字节偏移量)、输出主题名称和输出值(行,并且我们包含一个模式,指示该值始终是一个字符串)。构造函数的其他变体SourceRecord
还可以包括特定的输出分区、键和标头。
请注意,此实现使用普通的 JavaInputStream
接口,如果数据不可用,则可能会休眠。这是可以接受的,因为 Kafka Connect 为每个任务提供了专用线程。虽然任务实现必须符合基本poll()
接口,但它们在实现方式上具有很大的灵活性。在这种情况下,基于 NIO 的实现会更高效,但这种简单的方法有效,实现速度快,并且与旧版本的 Java 兼容。
虽然示例中没有使用,但SourceTask
还提供了两个 API 来提交源系统中的偏移量:commit
和commitRecord
。API 是为具有消息确认机制的源系统提供的。重写这些方法允许源连接器在将消息写入 Kafka 后,批量或单独地确认源系统中的消息。APIcommit
将偏移量存储在源系统中,直到 . 返回的偏移量为止poll
。此 API 的实现应阻塞,直到提交完成。API将每个写入 Kafka 后的commitRecord
偏移量保存在源系统中。SourceRecord
由于Kafka Connect会自动记录偏移量,SourceTask
因此不需要实现它们。如果连接器确实需要确认源系统中的消息,通常只需要其中一个 API。
接收器任务
上一节描述了如何实现一个简单的SourceTask
. SourceConnector
与和不同SinkConnector
,SourceTask
和SinkTask
具有非常不同的接口,因为SourceTask
使用拉接口和SinkTask
使用推接口。两者共享共同的生命周期方法,但SinkTask
接口却截然不同:
public abstract class SinkTask implements Task { public void initialize(SinkTaskContext context) { this.context = context; } public abstract void put(Collection<SinkRecord> records); public void flush(Map<TopicPartition, OffsetAndMetadata> currentOffsets) { }
该SinkTask
文档包含完整的详细信息,但该界面几乎与SourceTask
. 该put()
方法应该包含大部分实现,接受 的集合SinkRecords
,执行任何所需的转换,并将它们存储在目标系统中。此方法在返回之前不需要确保数据已完全写入目标系统。事实上,在许多情况下,内部缓冲很有用,因此可以一次发送整批记录,从而减少将事件插入下游数据存储的开销。它们包含与 Kafka 主题、分区、偏移量、事件键和值以及可选标头SinkRecords
基本相同的信息。SourceRecords
该flush()
方法在偏移提交过程中使用,允许任务从故障中恢复并从安全点恢复,从而不会错过任何事件。该方法应将任何未完成的数据推送到目标系统,然后阻塞,直到写入被确认。该offsets
参数通常可以被忽略,但在某些情况下很有用,其中实现希望将偏移量信息存储在目标存储中以提供一次性交付。例如,HDFS 连接器可以执行此操作并使用原子移动操作来确保该flush()
操作以原子方式将数据和偏移量提交到 HDFS 中的最终位置。
错误记录报告者
当为连接器启用错误报告ErrantRecordReporter
时,连接器可以使用来报告发送到接收器连接器的各个记录的问题。以下示例显示了当未启用 DLQ 或连接器安装在不具有此报告器功能的旧版 Connect 运行时中时,连接器的SinkTask
子类如何获取并使用 、安全地处理空报告器:ErrantRecordReporter
private ErrantRecordReporter reporter; @Override public void start(Map<String, String> props) { ... try { reporter = context.errantRecordReporter(); // may be null if DLQ not enabled } catch (NoSuchMethodException | NoClassDefFoundError e) { // Will occur in Connect runtimes earlier than 2.6 reporter = null; } } @Override public void put(Collection<SinkRecord> records) { for (SinkRecord record: records) { try { // attempt to process and send record to data sink process(record); } catch(Exception e) { if (reporter != null) { // Send errant record to error reporter reporter.report(record, e); } else { // There's no error reporter, so fail throw new ConnectException("Failed on record", e); } } } }
从之前的偏移量恢复
该SourceTask
实现包括每个记录的流 ID(输入文件名)和偏移量(文件中的位置)。框架使用它定期提交偏移量,以便在发生故障的情况下,任务可以恢复并最小化重新处理和可能重复的事件数量(或者如果 Kafka Connect 正常停止,则从最近的偏移量恢复,例如在独立模式下或由于作业重新配置)。此提交过程完全由框架自动化,但只有连接器知道如何返回输入流中的正确位置以从该位置恢复。
为了在启动时正确恢复,任务可以使用SourceContext
传递到其initialize()
方法中的数据来访问偏移数据。在 中initialize()
,我们将添加更多代码来读取偏移量(如果存在)并寻找该位置:
stream = new FileInputStream(filename); Map<String, Object> offset = context.offsetStorageReader().offset(Collections.singletonMap(FILENAME_FIELD, filename)); if (offset != null) { Long lastRecordedOffset = (Long) offset.get("position"); if (lastRecordedOffset != null) seekToOffset(stream, lastRecordedOffset); }
当然,您可能需要读取每个输入流的许多键。该OffsetStorageReader
接口还允许您发出批量读取以有效加载所有偏移量,然后通过将每个输入流查找到适当的位置来应用它们。
一次性源连接器
支持恰好一次
随着KIP-618的通过,Kafka Connect 从 3.3.0 版本开始支持一次性源连接器。为了使源连接器能够利用此支持,它必须能够为其发出的每个记录提供有意义的源偏移量,并在与任何这些偏移量相对应的确切位置处恢复从外部系统的消耗,而不会丢失或重复消息。
定义事务边界
默认情况下,Kafka Connect 框架将为源任务从其方法返回的每批记录创建并提交一个新的 Kafka 事务poll
。但是,连接器还可以定义自己的事务边界,用户可以通过在连接器的配置中设置属性来启用该边界transaction.boundary
。connector
TransactionContext
如果启用,连接器的任务将可以从其访问 a SourceTaskContext
,它们可以使用它来控制事务何时中止和提交。
例如,至少每十条记录提交一个事务:
private int recordsSent; @Override public void start(Map<String, String> props) { this.recordsSent = 0; } @Override public List<SourceRecord> poll() { List<SourceRecord> records = fetchRecords(); boolean shouldCommit = false; for (SourceRecord record : records) { if (++this.recordsSent >= 10) { shouldCommit = true; } } if (shouldCommit) { this.recordsSent = 0; this.context.transactionContext().commitTransaction(); } return records; }
或者为每十条记录提交一个事务:
private int recordsSent; @Override public void start(Map<String, String> props) { this.recordsSent = 0; } @Override public List<SourceRecord> poll() { List<SourceRecord> records = fetchRecords(); for (SourceRecord record : records) { if (++this.recordsSent % 10 == 0) { this.context.transactionContext().commitTransaction(record); } } return records; }
大多数连接器不需要定义自己的事务边界。但是,如果源系统中的文件或对象被分解为多个源记录,但应以原子方式传递,则它可能会很有用。此外,如果不可能为每个源记录提供唯一的源偏移量,并且具有给定偏移量的每个记录都在单个事务中传递,则它可能会很有用。
请注意,如果用户未在连接器配置中启用连接器定义的事务边界,则TransactionContext
返回的context.transactionContext()
将为null
。
验证API
源连接器开发人员可以实现一些额外的预检验证 API。
某些用户可能需要来自连接器的一次性语义。在这种情况下,他们可以在连接器的配置中设置该exactly.once.support
属性。required
发生这种情况时,Kafka Connect 框架将询问连接器是否可以使用指定的配置提供一次性语义。这是通过调用exactlyOnceSupport
连接器上的方法来完成的。
如果连接器不支持精确一次语义,它仍然应该实现此方法,以让用户确定它无法提供精确一次语义:
@Override public ExactlyOnceSupport exactlyOnceSupport(Map<String, String> props) { // This connector cannot provide exactly-once semantics under any conditions return ExactlyOnceSupport.UNSUPPORTED; }
否则,连接器应该检查配置,并返回ExactlyOnceSupport.SUPPORTED
它是否可以提供一次性语义:
@Override public ExactlyOnceSupport exactlyOnceSupport(Map<String, String> props) { // This connector can always provide exactly-once semantics return ExactlyOnceSupport.SUPPORTED; }
此外,如果用户已将连接器配置为定义自己的事务边界,Kafka Connect 框架将询问连接器是否可以使用指定的配置定义自己的事务边界,使用以下方法canDefineTransactionBoundaries
:
@Override public ConnectorTransactionBoundaries canDefineTransactionBoundaries(Map<String, String> props) { // This connector can always define its own transaction boundaries return ConnectorTransactionBoundaries.SUPPORTED; }
此方法仅适用于在某些情况下可以定义自己的事务边界的连接器。如果连接器永远无法定义自己的事务边界,则它不需要实现此方法。
Dynamic Input/Output Streams
Kafka Connect 旨在定义批量数据复制作业,例如复制整个数据库,而不是创建许多作业来单独复制每个表。这种设计的一个结果是连接器的一组输入或输出流可能会随着时间的推移而变化。
源连接器需要监视源系统的更改,例如数据库中的表添加/删除。当他们接受更改时,他们应该通过ConnectorContext
对象通知框架需要重新配置。例如,在SourceConnector
:
if (inputsChanged()) this.context.requestTaskReconfiguration();
该框架将立即请求新的配置信息并更新任务,允许它们在重新配置之前优雅地提交进度。请注意,此SourceConnector
监视当前由连接器实现。如果需要额外的线程来执行此监视,则连接器必须自行分配它。
理想情况下,用于监视更改的代码将与任务隔离,Connector
并且任务不需要担心它们。然而,更改也会影响任务,最常见的是当任务的输入流之一在输入系统中被破坏时,例如,如果从数据库中删除表。如果Task
遇到之前的问题(如果需要轮询更改,Connector
这很常见),则需要处理后续错误。值得庆幸的是,这通常可以通过捕获并处理适当的异常来简单地处理。Connector
Task
SinkConnectors
通常只需要处理流的添加,这可能会转换为输出中的新条目(例如,新的数据库表)。该框架管理 Kafka 输入的任何更改,例如当输入主题集因正则表达式订阅而更改时。SinkTasks
应该期待新的输入流,这可能需要在下游系统中创建新资源,例如数据库中的新表。在这些情况下要处理的最棘手的情况可能是多个人SinkTasks
第一次看到新的输入流并同时尝试创建新资源之间的冲突。SinkConnectors
另一方面,通常不需要特殊代码来处理动态流集。
Configuration Validation
Kafka Connect 允许您在提交要执行的连接器之前验证连接器配置,并可以提供有关错误和建议值的反馈。为了利用这一点,连接器开发人员需要提供一个实现,config()
以将配置定义公开给框架。
以下代码FileStreamSourceConnector
定义了配置并将其公开给框架。
static final ConfigDef CONFIG_DEF = new ConfigDef() .define(FILE_CONFIG, Type.STRING, null, Importance.HIGH, "Source filename. If not specified, the standard input will be used") .define(TOPIC_CONFIG, Type.STRING, ConfigDef.NO_DEFAULT_VALUE, new ConfigDef.NonEmptyString(), Importance.HIGH, "The topic to publish data to") .define(TASK_BATCH_SIZE_CONFIG, Type.INT, DEFAULT_TASK_BATCH_SIZE, Importance.LOW, "The maximum number of records the source task can read from the file each time it is polled"); public ConfigDef config() { return CONFIG_DEF; }
ConfigDef
类用于指定一组预期的配置。对于每个配置,您可以指定名称、类型、默认值、文档、组信息、组中的顺序、配置值的宽度以及适合在 UI 中显示的名称。另外,您可以通过覆盖该类来提供用于单个配置验证的特殊验证逻辑Validator
。此外,由于配置之间可能存在依赖关系,例如,一个配置的有效值和可见性可能会根据其他配置的值而改变。为了处理这个问题,ConfigDef
允许您指定配置的依赖项,并提供一个实现来Recommender
获取有效值并在给定当前配置值的情况下设置配置的可见性。
此外,validate()
中的方法Connector
提供了默认验证实现,该实现返回允许的配置列表以及配置错误和每个配置的推荐值。但是,它不使用建议值进行配置验证。您可以为自定义配置验证提供默认实现的覆盖,这可能会使用推荐值。
Working with Schemas
FileStream 连接器是很好的例子,因为它们很简单,但它们也有简单的结构化数据——每一行只是一个字符串。几乎所有实用的连接器都需要具有更复杂数据格式的模式。
要创建更复杂的数据,您需要使用 Kafka Connect data
API。大多数结构化记录除了基本类型之外还需要与两个类交互:Schema
和Struct
。
API 文档提供了完整的参考,但这里是一个创建Schema
and的简单示例Struct
:
Schema schema = SchemaBuilder.struct().name(NAME) .field("name", Schema.STRING_SCHEMA) .field("age", Schema.INT_SCHEMA) .field("admin", SchemaBuilder.bool().defaultValue(false).build()) .build(); Struct struct = new Struct(schema) .put("name", "Barbara Liskov") .put("age", 75);
如果您正在实现源连接器,则需要决定何时以及如何创建架构。如果可能,您应该尽可能避免重新计算它们。例如,如果您的连接器保证具有固定架构,请静态创建它并重用单个实例。
然而,许多连接器将具有动态模式。一个简单的例子是数据库连接器。即使只考虑单个表,也不会为整个连接器预定义架构(因为它因表而异)。但它也可能无法在连接器的生命周期内针对单个表进行修复,因为用户可能会执行命令ALTER TABLE
。连接器必须能够检测这些变化并做出适当的反应。
接收器连接器通常更简单,因为它们正在消耗数据,因此不需要创建模式。然而,他们应该同样小心地验证他们收到的模式是否具有预期的格式。当架构不匹配时(通常表明上游生产者正在生成无法正确转换到目标系统的无效数据),接收器连接器应抛出异常以向系统指示此错误。
8.4 管理
Kafka Connect 的REST 层提供了一组 API 来支持集群管理。这包括用于查看连接器配置及其任务状态以及更改其当前行为(例如更改配置和重新启动任务)的 API。
当连接器首次提交到集群时,会在连接工作线程之间触发重新平衡,以分配由新连接器的任务组成的负载。当连接器增加或减少其所需的任务数量、更改连接器的配置时,或者作为 Connect 集群有意升级的一部分或由于以下原因在组中添加或删除工作线程时,也会使用相同的重新平衡过程:失败。
在 2.3.0 之前的版本中,Connect Worker 会重新平衡集群中的全套连接器及其任务,这是一种简单的方法,可确保每个 Worker 的工作量大致相同。仍然可以通过设置来启用此行为connect.protocol=eager
。
从 2.3.0 开始,Kafka Connect 默认使用一种执行 增量协作重新平衡的 协议,该协议可以增量平衡 Connect 工作线程之间的连接器和任务,仅影响新任务、要删除的任务或需要从一个工作线程移至另一个工作线程的任务。其他。在重新平衡期间,其他任务不会像旧协议那样停止和重新启动。
scheduled.rebalance.max.delay.ms
如果 Connect 工作线程故意或由于故障而离开组,Connect 会在触发重新平衡之前
等待。此延迟默认为五分钟 ( 300000ms
),以容忍工作人员故障或升级,而无需立即重新分配离职工作人员的负载。如果该工作人员在配置的延迟内返回,它将获得之前分配的完整任务。但是,这意味着任务将保持未分配状态,直到指定的时间过去scheduled.rebalance.max.delay.ms
。如果工作人员未在该时间限制内返回,Connect 将在 Connect 集群中的剩余工作人员之间重新分配这些任务。
当构成 Connect 集群的所有工作线程都配置了 时,就会启用新的 Connect 协议connect.protocol=compatible
,这也是缺少此属性时的默认值。因此,当所有工作人员升级到 2.3.0 时,会自动升级到新的 Connect 协议。当最后一个工作线程加入版本 2.3.0 时,Connect 集群的滚动升级将激活增量协作重新平衡。
您可以使用 REST API 查看连接器及其任务的当前状态,包括每个连接器分配到的工作线程的 ID。例如,GET /connectors/file-source/status
请求显示名为 的连接器的状态file-source
:
{ "name": "file-source", "connector": { "state": "RUNNING", "worker_id": "192.168.1.208:8083" }, "tasks": [ { "id": 0, "state": "RUNNING", "worker_id": "192.168.1.209:8083" } ] }
status.storage.topic
连接器及其任务将状态更新发布到集群中所有工作线程都监控的
共享主题(配置为)。由于工作人员异步使用此主题,因此在通过状态 API 看到状态更改之前通常会有(短暂的)延迟。连接器或其任务之一可能处于以下状态:
- 未分配:连接器/任务尚未分配给工作人员。
- 正在运行:连接器/任务正在运行。
- 已暂停:连接器/任务已被管理暂停。
- STOPPED:连接器已停止。请注意,此状态不适用于任务,因为已停止连接器的任务已关闭并且在状态 API 中不可见。
- FAILED:连接器/任务失败(通常通过引发异常,在状态输出中报告)。
- 正在重新启动:连接器/任务正在主动重新启动或预计很快会重新启动
在大多数情况下,连接器和任务状态将匹配,但在发生更改或任务失败时,它们可能会在短时间内有所不同。例如,当连接器首次启动时,在连接器及其任务全部转换为 RUNNING 状态之前可能会有明显的延迟。当任务失败时,状态也会出现分歧,因为 Connect 不会自动重新启动失败的任务。要手动重新启动连接器/任务,您可以使用上面列出的重新启动 API。请注意,如果您在重新平衡期间尝试重新启动任务,Connect 将返回 409(冲突)状态代码。您可以在重新平衡完成后重试,但这可能没有必要,因为重新平衡会有效地重新启动集群中的所有连接器和任务。
从 2.5.0 开始,Kafka Connectstatus.storage.topic
还使用 来存储与每个连接器正在使用的主题相关的信息。GET /connectors/{name}/topics
Connect Workers 使用这些每个连接器主题状态更新,通过返回连接器正在使用的主题名称集来响应对 REST 端点的请求。对 REST 端点的请求PUT /connectors/{name}/topics/reset
会重置连接器的活动主题集,并允许根据连接器的最新主题使用模式填充新的主题集。连接器删除后,连接器的活动主题集也会被删除。主题跟踪默认启用,但可以通过设置禁用topic.tracking.enable=false
。如果要禁止在运行时期间重置连接器活动主题的请求,请设置 Worker 属性topic.tracking.allow.reset=false
。
有时,暂时停止连接器的消息处理很有用。例如,如果远程系统正在进行维护,源连接器最好停止轮询新数据,而不是用异常垃圾邮件填充日志。对于此用例,Connect 提供了暂停/恢复 API。当源连接器暂停时,Connect 将停止轮询它以获取其他记录。当接收器连接器暂停时,Connect 将停止向其推送新消息。暂停状态是持久的,因此即使您重新启动集群,连接器也不会再次开始消息处理,直到任务恢复为止。请注意,在连接器的所有任务转换到 PAUSED 状态之前可能会有延迟,因为它们可能需要一些时间才能完成暂停时正在进行的任何处理。此外,失败的任务在重新启动之前不会转换为 PAUSED 状态。
在 3.5.0 中,Connect 引入了一个停止 API,该 API 可以完全关闭连接器的任务并释放它们占用的任何资源。这与暂停连接器不同,在连接器中,任务处于闲置状态,并且它们占用的任何资源都处于分配状态(这允许连接器在恢复后快速开始处理数据)。从资源使用的角度来看,停止连接器比暂停连接器更有效,但可能会导致连接器恢复后需要更长时间才能开始处理数据。请注意,如果连接器处于停止状态,则只能通过偏移管理端点修改连接器的偏移。
9.Kafka流
Kafka Streams 是一个用于处理和分析 Kafka 中存储的数据的客户端库。它建立在重要的流处理概念之上,例如正确区分事件时间和处理时间、窗口支持、一次性处理语义以及简单而高效的应用程序状态管理。
Kafka Streams 的进入门槛较低:您可以在单台机器上快速编写并运行小规模的概念验证;您只需在多台计算机上运行应用程序的其他实例即可扩展到大批量生产工作负载。Kafka Streams 利用 Kafka 的并行模型透明地处理同一应用程序的多个实例的负载平衡。
了解有关 Kafka Streams 的更多信息,请阅读本节。