You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kafka.apache.org by sc...@apache.org on 2026/09/24 07:00:12 UTC
(kafka) branch trunk updated: KAFKA-21076: Document the decompressed telemetry.max.bytes bound (#23465)
This is an automated email from the ASF dual-hosted git repository.
AndrewJSchofield pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 1a9b513a1de KAFKA-21076: Document the decompressed telemetry.max.bytes bound (#23465)
1a9b513a1de is described below
commit 1a9b513a1dec8a7a0fc2a18a25c855ec24d040bb
Author: rishi-rana <ri...@hotmail.com>
AuthorDate: Thu Sep 24 00:00:03 2026 -0700
KAFKA-21076: Document the decompressed telemetry.max.bytes bound (#23465)
## Summary
Follow-up to #23444 (KAFKA-21076), which fixed the error code returned
when a client's decompressed telemetry payload exceeds
`telemetry.max.bytes`. The original report also asked to document this
behavior, which #23444 didn't cover:
> Document the decompressed bound in telemetry.max.bytes or add a
separate configuration, and mention the behavior change in the upgrade
notes.
This PR addresses the documentation half. A *separate* configuration for
the decompressed bound (as opposed to documenting the existing one)
would be a new public interface and needs its own KIP, so it's
intentionally left out of scope here.
## Changes
- `MetricConfigs.CLIENT_TELEMETRY_MAX_BYTES_DOC`: the doc string only
described `telemetry.max.bytes` as a compressed wire-size limit
(KIP-714's original definition). It's been bounding the decompressed
payload size too since 4.3.1 (#22327), so the doc string was stale.
Updated it to say so, and that exceeding it returns
`TELEMETRY_TOO_LARGE`.
- `docs/getting-started/upgrade.md`: added a bullet under "Notable
changes in 4.4.0" (matching the existing `KAFKA-20609`/`KAFKA-20843`
bullet style) explaining the behavior change and pointing operators at
raising `telemetry.max.bytes` if they hit it after upgrading.
## Test plan
Documentation-only change (a Java doc-string constant and a markdown
file). Verified `./gradlew :server:compileJava :server:checkstyleMain
:server:spotlessCheck` stays clean.
## AI assistance disclosure
Per `AI_POLICY`/`CONTRIBUTING.md`: Claude Code (Sonnet 5) was used to
draft both doc changes in
`server/src/main/java/org/apache/kafka/server/metrics/MetricConfigs.java`
and `docs/getting-started/upgrade.md`. Reviewed by me before submission.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https: //claude.ai/code/session_01K4B9PPesZhXHiWr5Ak1PNz
Reviewers: Andrew Schofield <as...@confluent.io>, Steven Schlansker
<st...@gmail.com>
---------
Co-authored-by: Claude Sonnet 5 <no...@anthropic.com>
---
docs/getting-started/upgrade.md | 1 +
.../src/main/java/org/apache/kafka/server/metrics/MetricConfigs.java | 4 ++--
2 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/getting-started/upgrade.md b/docs/getting-started/upgrade.md
index bbbfa9f41ab..7a33dcbb1f3 100644
--- a/docs/getting-started/upgrade.md
+++ b/docs/getting-started/upgrade.md
@@ -59,6 +59,7 @@ type: docs
* For tiered-storage topics, time-based local retention (`local.retention.ms`) now uses a segment's last modified time as the age anchor when the segment's largest record timestamp is in the future. Previously such a segment was never removed by time-based retention (its future timestamp kept it perpetually within the retention window) and was only reclaimed once `local.retention.bytes` was breached, even though it had already been uploaded to remote storage. For further details, pleas [...]
* The `org.apache.kafka.automatic.config.providers` allowlist is now applied when dynamic broker configurations are validated and applied.
* `group.consumer.assignors` now fails broker startup with a `ConfigException` when two configured assignors resolve to the same name, for example a built-in listed both by its name and by its class name, or a custom assignor reusing the name of another configured assignor. Such a configuration used to pass startup validation and fail later during group coordinator loading. For further details, please refer to [KAFKA-20843](https://issues.apache.org/jira/browse/KAFKA-20843).
+ * `telemetry.max.bytes` now also bounds the size of a client's *decompressed* telemetry payload, not just its compressed wire size (this decompressed-size check was introduced in 4.3.1). A push whose decompressed size exceeds this limit is rejected with the retryable `TELEMETRY_TOO_LARGE` error, so the client retries at its normal push interval; previously this was misreported as `INVALID_RECORD`, which permanently disabled telemetry for that client instance. If clients hit this limit, [...]
## Upgrading to 4.3.1
diff --git a/server/src/main/java/org/apache/kafka/server/metrics/MetricConfigs.java b/server/src/main/java/org/apache/kafka/server/metrics/MetricConfigs.java
index a974c36bed5..9ac898f999c 100644
--- a/server/src/main/java/org/apache/kafka/server/metrics/MetricConfigs.java
+++ b/server/src/main/java/org/apache/kafka/server/metrics/MetricConfigs.java
@@ -64,8 +64,8 @@ public class MetricConfigs {
/** ********* Kafka Client Telemetry Metrics Configuration ***********/
public static final String CLIENT_TELEMETRY_MAX_BYTES_CONFIG = "telemetry.max.bytes";
public static final int CLIENT_TELEMETRY_MAX_BYTES_DEFAULT = 1024 * 1024;
- public static final String CLIENT_TELEMETRY_MAX_BYTES_DOC = "The maximum size (after compression if compression is used) of" +
- " telemetry metrics pushed from a client to the broker. The default value is 1048576 (1 MB).";
+ public static final String CLIENT_TELEMETRY_MAX_BYTES_DOC = "The maximum size of telemetry metrics pushed from a client to the broker," +
+ " also applied to the decompressed size when the metrics are compressed. The default value is 1048576 (1 MB).";
public static final ConfigDef CONFIG_DEF = new ConfigDef()
// Kafka Metrics Configuration