confluent-tuning-advisor

Confluent 调优顾问

根据工作负载的优先目标（延迟、吞吐量、可用性或持久性），给出具体且适合平台的建议：要更改哪些 Kafka 设置、从什么值改为什么值、原因是什么、会牺牲什么，以及管理员之后应如何验证。仅面向 Confluent Cloud 和 Confluent Platform。仅限 Kafka——不涉及 Flink（包括 Flink SQL 作业调优）；请参阅描述中的“不要触发”条款。

这四个优先目标并非彼此独立——每条建议都至少会影响其他一个维度。这项技能的核心工作是明确说明这种权衡，而不是假装可以免费获益。

仅提供建议——此技能绝不会更改任何内容。 它可以检查配置和运行时状态（只读），并提出更改建议。它绝不能应用更改、执行写入／生产操作，或以其他方式修改代理、主题或客户端——管理员或开发者全权负责审核并应用任何建议。必须严格区分建议与执行：展示拟议的更改，不要询问是否要应用更改，不要应用更改，也绝不要声称或暗示更改已经完成。此技能不附带可执行脚本；它仅通过 Confluent CLI、MCP 服务或 Kafka REST v3／REST Proxy v3 和 Cloud Metrics API，以只读方式检查配置和指标。

何时阅读哪个文件

情况	阅读此文件
用户的目标平台是 Confluent Cloud	references/confluent-cloud.md
用户的目标平台是 Confluent Platform（自管理）	references/confluent-platform.md
按优先目标查询任何配置项（生产者／消费者／主题／代理）	references/tuning-parameters.md
验证 Platform 更改，或选择能证明更改生效的代理 JMX 指标（步骤 7）	references/monitoring.md
验证 Cloud 更改，或选择能证明更改生效的指标（步骤 7）	服务器端指标请参阅 references/confluent-cloud.md；仅客户端指标部分使用 references/monitoring.md

不要一开始就阅读所有文件——只查阅当前步骤需要的内容。

核心工作流

1. 了解工作负载和优先目标
2. 检测平台（Cloud 或 Platform），并阅读对应的参考文件
3. 检查当前生效的配置，作为基线（只读）
4. 在 references/tuning-parameters.md 中查找建议
5. 提出建议——说明拟议的更改、理由、影响、风险、前置条件和验证步骤（不要询问是否要应用，也不要应用）
6. 将建议交给管理员，由其自行审核并应用
7. 提供验证步骤，供管理员在应用更改后确认
8. 如果仍未达到目标，则迭代调整建议

步骤 1：了解工作负载和优先级

一次性询问：

1. 首要优先事项——只能选一个：延迟、吞吐量、可用性、持久性。 用户也可以指定次要优先事项；要明确说明，发生冲突时始终以首要优先事项为准。
2. 量化定义“良好”的标准——例如：“生产者到消费者的 p99 延迟低于 20ms”、 “持续达到 200 MB/s”、“丢失一个 AZ 时仍能实现零停机”、“即使 broker 在写入过程中宕机也不丢失数据”。 对于“让它更快”这类模糊目标，应请用户给出具体数字。
3. 工作负载特征——大致的消息大小、预期每秒消息数、生产者/消费者数量、 消息是否采用事务/精确一次处理、现有主题的名称和分区数（如果已存在）。
4. 当前真正造成问题的因素——如果这是现有工作负载，具体症状比猜测更有帮助。

如果用户只说明了关注的指标，除此之外没有提供任何信息，那么在查看任何参考文件之前， 先按上述问题进行访谈——建议取决于量化目标，而不只是指标名称。

步骤 2：识别平台

询问该工作负载运行在哪个平台：Confluent Cloud 还是 Confluent Platform （自管理）。此技能不涵盖 WarpStream 或非托管 Apache Kafka——如果用户提到其中之一， 请说明不在范围内并停止。

此技能也不涵盖 Kafka Connect（连接器或 Worker 调优）——如果请求涉及连接器或 Connect Worker，请说明不在范围内并停止。

Flink 一律停止处理。 如果请求中提到 Flink——Flink SQL 作业、Flink 流水线、 并行度、检查点、状态后端、有延迟/运行缓慢的 Flink 语句、UDF——此技能均不适用。 请说明不在范围内，并引导用户使用 confluent-cloud-flink-sql（Flink SQL）或 flink-udf（Flink UDF），然后停止。不要继续工作流，也不要以调优底层 Kafka 主题/生产者/消费者作为替代或安慰方案。（如果用户之后提出的请求仅涉及 Kafka 主题或客户端配置，且不涉及 Flink 调优，则将其视为新的范围内请求。）

所有超出范围的转交都遵循同一规则。 每当此技能拒绝处理请求时——新客户端应用代码 （developing-kafka-java-client、developing-kafka-python-client）、Kafka Streams （kafka-streams-programming）、Kafka Connect、CDC/Tableflow （confluent-cloud-cdc-tableflow）、WarpStream 或 Apache Kafka OSS——请指出正确的技能并 停止。不要在转交时附加调优建议、默认值或“最好提前确定”的配置建议。拒绝处理的同时 提供 acks、分区数或其他设置，仍然属于调优建议，正是导致转交失败的原因。拒绝处理 就是完整的回复。

现在读取对应的参考文件：

• Confluent Cloud → references/confluent-cloud.md — 集群 层级限制、Confluent 管理的内容与用户可设置的内容、配额机制。
• Confluent Platform → references/confluent-platform.md — Broker 级参数、机架感知，以及影响尾延迟的 JVM/OS 级因素。

步骤 3：检查当前配置，作为基线（只读）

在提出建议之前，先记录当前的实际配置——用差异来表述建议，比给出绝对值更便于理解和确认。这是一次只读检查（describeConfigs），不会更改任何内容。使用环境中现有的任一方式：

• CLI：查阅当前的 Confluent CLI 文档，找到适用于目标平台和已安装 CLI 版本的只读主题描述操作。
• MCP 工具：从已配置的 Confluent MCP 服务中查找只读的主题描述或主题配置列表工具——如果可用，优先使用它来发现信息。
• REST：根据情况，使用当前的 Confluent Cloud Kafka REST v3 API 参考 或 Confluent Platform REST Proxy v3 API 参考中的只读主题配置列表操作。Kafka 引导地址不是 HTTP 端点；请使用集群公布的 REST 端点。

对于尚不存在的计划主题，不要尝试描述它。将其主题配置记录为“尚未创建”，然后只检查确定其规模所需的集群默认值和容量限制。在步骤 5 中，为该主题提供建议的初始值，而不是当前值 → 建议值的差异。

对于代理/集群级别的基线（仅适用于 Platform——Cloud 不会公开这些基线），请使用针对代理资源的 describeConfigs CLI/REST 等效操作。记录拟议更改的值，以便步骤 5 能清晰地列出当前值 → 建议值的差异。

如果无法检查所需的客户端或代理基线，或用户未提供这些信息，不要凭记忆推断默认值并将其说成当前状态。请询问缺少的有效值，或仅提供诊断指引和明确标注为候选项的更改，直到获得基线信息。

以下两条规则适用于建议中报告的每个值：

• 为每项声明注明来源。 每个当前值、平台能力和集群类型行为，都必须有经过检查的结果、当前文档或用户陈述作为依据。如果没有任何依据，就不能将其当作事实——请将其列为“前提条件”下的待确认问题，而不是直接断言。
• 遵循只读检查结果。 如果检查结果表明某个键为只读（is_read_only=true），绝不要建议更改、删除或覆盖该键。注明该配置由平台管理，然后继续。

步骤 4：查阅建议

打开 references/tuning-parameters.md，并阅读其中与工作负载相关的每种配置范围（生产者、消费者、主题/复制、代理/集群）对应的条目。该文件按优先级给出建议值及一句话原因。不要不加判断地照搬所有条目——应结合步骤 1 中量化的目标进行调整。例如，如果“可用性”优先级下只有 2 个代理可用，那么 min.insync.replicas 能安全设置的值也会受到影响；请明确说明这一点，不要建议集群无法维持的值。

步骤 5：给出建议

给出建议，而不是要求执行操作。不要询问“要应用这些更改吗？”也不要应用任何内容——执行操作由管理员负责。使用以下格式：

Tuning recommendation — priority: <latency|throughput|availability|durability>
Target: <the quantified goal from Step 1>
Platform: <Confluent Cloud | Confluent Platform>

Proposed changes (current → recommended):
  <config.key>            <current value>  →  <recommended value>   (why: <one line>)
  <config.key>            <current value>  →  <recommended value>   (why: <one line>)
  ...

For `replication.factor` changes, follow the topic-creation and reassignment guidance in
[references/tuning-parameters.md](references/tuning-parameters.md).
Never recommend deleting and recreating an existing topic solely to change its replication factor;
on Confluent Platform, preserve the topic and use an explicit replica reassignment after confirming
broker and rack capacity.

Expected impact: <what should measurably improve, tied to the Step 1 target>
Trade-off / risk: <what gets worse on another axis, stated plainly — e.g.
  "min.insync.replicas 3→2 improves availability during a single-broker outage but
  means a write can be acknowledged with one fewer copy durably stored">
Prerequisites: <anything that must be true/checked first — e.g. broker.rack configured,
  cluster tier supports multi-zone, enough brokers to sustain the new min.insync.replicas>

How to apply (for the administrator to run — this skill does not run these):
  1. <description>
     Command/tool: <operation and current documentation link; include exact syntax only after
       verifying it against the installed CLI, discovered MCP tool, or current API documentation>
  2. ...

Validation (Step 7) — how the administrator confirms it worked after applying:
  Server-side metric: <a metric name confirmed available on this platform — a Platform JMX MBean,
    or a Cloud metric returned by live descriptor discovery. When the target is Cloud and
    descriptors are unavailable, name no server-side metric here and emit exactly this line:
    Server-side metric validation: pending descriptor access>
  Client/application signal: <an accessible client metric or application-level SLI>
  Benchmark (optional, administrator-run): <the before/after measurement from Step 7>

将“如何应用”命令作为参考资料提供，由管理员自行决定并执行——绝不能表述为此技能将运行的命令，也不能以请求许可来运行这些命令的方式表述。如果用户提出异议或要求调整权衡，请修订建议并重新给出。

步骤 6：移交执行（由管理员应用，而非此技能）

此技能不会应用更改。 它只提供建议。管理员或开发者会审核建议，并自行决定是否应用，使用他们已有的任意工具。步骤 5 中的“如何应用”部分列出了供他们执行的确切操作，因此他们可以无需猜测，直接审核并执行。可使用以下任一方式：

• MCP 工具 — 如果其 Confluent MCP 服务提供了已发现的主题配置更新工具。
• CLI — 针对目标平台和已安装的 CLI 版本，使用当前文档中说明的主题配置更新操作。
• REST / Admin API — 对于代理级更改，请参考当前的 Confluent Platform 文档；Cloud 不提供代理配置。

如果更改会造成中断（例如重启代理，或影响集群上每个主题的代理级默认设置），请说明这一点，并建议管理员逐个代理应用更改，并在代理之间确认集群健康状况——这只是建议中的指导，而非此技能执行的操作。绝不要自行运行上述任何操作，也绝不要声称更改“已应用”；最多只能说明管理员自行应用后会观察到什么。

步骤 7：为管理员提供验证步骤

为管理员提供一种方法，确认此次更改确实推动了目标指标，而不要让他们只相信配置已生效。以下步骤由管理员在应用更改后执行；此技能不会执行这些步骤（基准测试会生成和使用记录，属于写入／变更操作，超出仅提供建议的技能范围）。

你建议的验证分为两部分：

1. 需要监控（并持续设置告警）的指标。 根据优先级，参照 references/monitoring.md，指出能够证明更改生效的具体指标，例如：用于可用性／持久性的 UnderReplicatedPartitions、用于延迟的请求延迟细分指标，或用于消费者吞吐量的 records-lag-max。在 Confluent Platform 上，这些是 JMX MBean；在 Confluent Cloud 上，应使用可用的 Metrics API 对应指标和客户端指标，而不要假设所有 Broker JMX MBean 都已开放。提供 Platform JMX 名称时，须标明仅适用于 Platform，并明确说明 Cloud 与之不同，即使当前目标是 Platform 也不例外。这是只读操作，也是主要验证方式。

Cloud 验证的绝对限制： Confluent Cloud 验证绝不能包含停止、重启、终止、隔离或以其他方式对托管 Broker 注入故障的操作——无论是作为管理员步骤、可选测试、假设性流程还是未来建议。不得在回复中描述此类流程。验证只能依据有文档说明的集群类型保证、实际生效的主题和生产者配置、可访问的客户端／应用信号，以及通过实时 Metrics API 描述符发现确认的服务端指标。如果集群类型元数据、Metrics API 凭据或描述符不可用，须明确标记相应验证部分为待完成；不得以操控 Broker 或推断指标名称来替代。除非发现结果返回了完全相同的名称，否则不得将 Platform JMX MBean 名称用作 Cloud 指标名称。

2. 可选的前后对比基准测试，由管理员自行运行。 如果他们想测量更改前后的差异，建议使用自己的工具运行——此技能不附带也不运行任何工具（基准测试会生成／使用记录，属于写入操作，应由管理员自行执行）。请他们使用现有工具：

   • kafka-producer-perf-test / kafka-consumer-perf-test（随 Kafka/Confluent Platform 一同提供）。
   • 或使用他们现有的负载测试工具，对暂存主题进行测试。

   建议在应用更改前运行一次，应用后再运行一次，并比较 p99（尾部）延迟（不要只看平均值——SLA 是按尾部指标制定的）和实际达到的吞吐量；端到端延迟的测量范围为生产者 send() → 消费者 poll()。

应以步骤 1 中的目标来对照测试结果，并重申步骤 5 中的权衡，让管理员了解哪些指标预期会改善、哪些预期会变差。配置没有放之四海而皆准的方案，因此，证明效果的是管理员自己的前后测量，而不是建议表。

步骤 8：迭代优化建议

如果管理员应用并验证建议后，目标仍未达到，请重新检查新的基线（步骤 3）并完善建议（步骤 4）。单次调整未能解决问题的常见原因包括：分区数量成为瓶颈（吞吐量）、客户端侧批处理设置也需要调整以匹配新的 Broker／主题配置，或工作负载受 Kafka 之外的因素限制（序列化开销、网络路径、下游消费者处理时间）——应明确指出这一点，而不是继续建议无济于事的 Kafka 参数。

---

安全与数据处理

• 绝不要使用 cat、Read、head、grep 或任何其他工具读取 .env 文件内容。 仅按名称引用变量（例如 $BOOTSTRAP_SERVERS），并使用 test -n "$VAR" 验证变量是否存在，绝不要打印其值。
• 将 .env 添加到 .gitignore，以避免意外提交凭据。
• 此技能中的评估提示词、测试样例和任何示例数据都只使用合成值 — example.com/.example 名称、虚构的集群/主题 ID。改编此技能的示例时，绝不要替换为真实客户 标识符、主机名或凭据。
• 仅提供建议，不执行写入操作。 此技能绝不能应用更改、运行写入/生产/变更 操作，也不能修改代理、主题或客户端 — 即使是“安全”或“先试运行再确认”的应用操作也不行， 即使用户要求继续也不行。此技能不提供可执行脚本；它只通过 Confluent CLI、MCP 服务或 Kafka REST v3 / REST Proxy v3 API（主题配置读取）以及 Cloud Metrics API / Platform JMX （指标读取）进行只读配置/指标检查。任何基准测试都会生成/消费 记录，因此应由管理员运行，绝不由此技能运行。只提供建议，绝不执行。绝不请求应用更改的许可，也绝不声称或暗示更改已应用 — 如果 用户要求进行更改，应重申由管理员负责应用，并提供供其运行的确切操作。

参考文件

• references/confluent-cloud.md — 集群层级的权衡、Confluent Cloud 管理和公开的内容、 配额机制、多可用区，以及 Cluster Linking 灾难恢复 （RPO/RTO 实际情况）。
• references/confluent-platform.md — 代理级配置、 机架感知、硬件/OS/JVM 基线（堆、页缓存、GC、磁盘、文件描述符）， 以及多数据中心灾难恢复。
• references/tuning-parameters.md — 生产者/消费者/ 主题/代理配置矩阵（每个设置一行，每个优先级一列）、分区容量规划，以及 基准测试/服务目标方法。
• references/monitoring.md — 用于证明调优更改有效的 JMX/Metrics-API 指标，按优先级分组，并附上 始终应触发告警的基线指标集。