Skip to content

fix(DOC-1940): clarify rpk topic consume keeps connection open #1612

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mfernest wants to merge 9 commits into
base: main
Choose a base branch
from
+7 −4
Open

fix(DOC-1940): clarify rpk topic consume keeps connection open #1612

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1128095
fix(DOC-1940): clarify rpk topic consume keeps connection open
mfernest Mar 17, 2026
9b69e8b
Merge remote-tracking branch 'origin/main' into fix/doc-1940-rpk-topi…
mfernest Mar 19, 2026
0230f08
fix(DOC-1940): polish rpk topic consume prose
mfernest Mar 19, 2026
96af7bc
Merge remote-tracking branch 'origin/main' into fix/doc-1940-rpk-topi…
mfernest Mar 24, 2026
2fd337c
fix(DOC-1940): move connection behavior note to manual section below …
mfernest Mar 24, 2026
531103e
Merge remote-tracking branch 'origin/main' into fix/doc-1940-rpk-topi…
mfernest Mar 26, 2026
f872e90
Merge branch 'main' into fix/doc-1940-rpk-topic-consume-connection
Feediver1 Mar 31, 2026
801b759
Merge branch 'main' into fix/doc-1940-rpk-topic-consume-connection
Feediver1 Mar 31, 2026
1354df5
Merge branch 'main' into fix/doc-1940-rpk-topic-consume-connection
Feediver1 Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ Consuming records reads from any amount of input topics, formats each record
according to `--format`, and prints them to `STDOUT`. The output formatter
understands a wide variety of formats.

By default, `rpk topic consume` opens a persistent connection and waits
indefinitely for new records to arrive. It does not exit after consuming
existing records. To stop consuming, press `Ctrl+C`, or use `--num` to exit
after a fixed number of records, or specify an end offset with `--offset`
(for example, `-o start:end`).
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for offset examples using start:end pattern
rg -n "start:end" --type=adoc

# Search for other offset range examples without timestamps
rg -n "\\-o\s+(start|end|:[^@]|\d+:)" --type=adoc -A2 -B2

Repository: redpanda-data/docs

Length of output: 119

🏁 Script executed:

#!/bin/bash
# Search for start:end pattern without type filter
rg "start:end" --glob="*.adoc"

# Also search for offset examples in AsciiDoc files
rg "\-o\s+" --glob="*.adoc" -A2 -B2 | head -100

Repository: redpanda-data/docs

Length of output: 6857

🏁 Script executed:

#!/bin/bash
# Read the specific file to check offset documentation
wc -l modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc

# Read the offset table section mentioned (lines 120-137)
sed -n '120,137p' modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc

# Read the examples section (lines 173-178)
sed -n '173,180p' modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc

Repository: redpanda-data/docs

Length of output: 949

Consider using more explicit documented examples for the offset specification.

The example -o start:end is not explicitly documented in the offset table (lines 120-137) or examples section (lines 173-178). While end can be used as an ending offset in ranges (as shown by -o @-1m:end in the examples), the specific pattern start:end doesn't appear elsewhere in the documentation and lacks clear definition.

Use more explicit, documented alternatives such as -o :end (line 126: "Consume until the current end") or model after existing examples like -o @-1m:end. This improves clarity since the offset table shows end as a standalone type meaning "Consume from the end," which could confuse readers about its different meaning when used in range syntax.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc` around lines 10
- 14, The doc text for rpk topic consume should clarify the range offset pattern
and either replace or augment `-o start:end` with explicit, documented examples
and a note about `end`'s meaning in ranges: update the sentence referencing
`--offset`/`-o` to show a clear example like `-o :end` (consume until current
end) and/or `-o `@-1m`:end` (consume from one minute ago to current end), and add
a short parenthetical explaining that `end` inside a range denotes the current
end offset (different from using `end` alone); edit the offset table and
examples section to include this explicit `:end`/`@-1m:end` pattern and the
clarifying note so readers aren’t confused by the standalone `end` meaning.

Copy link
Copy Markdown
Contributor

@daisukebe daisukebe Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-o start:end

-o :end is enough.

Copy link
Copy Markdown
Contributor Author

@mfernest mfernest Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call — fixed to -o :end. Also took the opportunity to clean up a few other prose issues on the page (kbd macro for Ctrl+C, simplify the --format json sentence, fix a tense issue, and a grammatical error).


The default output format `--format json` is a special format that outputs each
record as JSON.

Expand Down
Loading