Skip to content

Fix a claim in the ring buffer blueprint: the trace file does say how many #70

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

Merged
tamnd merged 1 commit into from
Sep 6, 2026
Merged

Fix a claim in the ring buffer blueprint: the trace file does say how many #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
52 changes: 33 additions & 19 deletions blueprints/assets/trace-ring-buffer-overrun.diagram.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@

ALT = (
"A picture in four parts, about how a full trace buffer loses events without saying so. "
"Across the top, a ring of four boxes labelled sub buffer 0 to sub buffer 3, joined "
"left to right by arrows with a dashed arrow wrapping from the last one back to the first. "
"The first box is also labelled head, the oldest, the third is labelled tail, writing here "
"now, and a separate box sits outside the ring labelled reader page, off the ring, with a "
"note that the writer will never touch it. Underneath on the left, a column headed what one "
"writer does, with three boxes reading down: read the tail page, read the two timestamps, and "
"add my length to the write index with one atomic add. That last box forks. The left branch "
"is labelled it fits and holds one box reading write the data and commit. The right branch is "
"Across the top, a ring of four boxes labelled sub buffer 0 to sub buffer 3, joined left to "
"right by arrows with a dashed arrow wrapping from the last one back to the first. The first "
"box is also labelled head, the oldest, the third is labelled tail, writing here now, and a "
"separate box sits outside the ring labelled reader page, off the ring, with a note that the "
"writer will never touch it. Underneath on the left, a column headed what one writer does, "
"with three boxes reading down: read the tail page, read the two timestamps, and add my "
"length to the write index with one atomic add. That last box forks. The left branch is "
"labelled it fits and holds one box reading write the data and commit. The right branch is "
"labelled it does not fit and holds three boxes in a red style reading the next page is the "
"head, throw that whole page away and add its events to overrun, and move the tail onto it. A "
"note beside the red branch says nothing waits, nothing fails, and no caller is told. On the "
Expand All @@ -32,14 +32,16 @@
"consuming read, take overrun minus last overrun, and print CPU:0 LOST 44002 EVENTS. The "
"right column, the trace file, has boxes reading iterator read, ask for the iterator's missed "
"events flag, and a red box reading the writer never sets that bit on an ordinary buffer, so "
"the flag is zero and nothing prints. Across the bottom is a red band reading a quiet trace "
"file is not evidence that nothing was lost, and under it a line saying the stats file under "
"per_cpu is the only place that tells you."
"nothing marks the body. An arrow leads from that red box to a wide box holding the header "
"line of the trace file, entries-in-buffer slash entries-written 273 slash 44275. Across the "
"bottom is a red band reading each way of reading a trace tells you half of what was lost, "
"and under it a line saying trace_pipe says where and prints no header, while the trace file "
"says how many, once, in a header a reader skips, and marks nothing in the body."
)


def scene() -> Scene:
s = Scene("How a full ring buffer loses events", width=1240, height=1112)
s = Scene("How a full ring buffer loses events", width=1240, height=1180)

s.note(40, 44, "How a full ring buffer loses events", font_size=20)
s.note(
Expand Down Expand Up @@ -172,7 +174,7 @@ def scene() -> Scene:
882,
210,
60,
"the writer never sets that bit,\nso the flag is zero",
"the writer never sets that bit,\nso nothing marks the body",
style="warn",
font_size=12,
)
Expand All @@ -182,23 +184,35 @@ def scene() -> Scene:
s.arrow(t1, t2)
s.arrow(t2, t3)

header = s.box(
760,
954,
440,
56,
"the header of the trace file: entries-in-buffer/entries-written 273/44275",
style="accent",
font_size=12,
mono=True,
)
s.arrow(t3, header, sides=("bottom", "top"))

# -- the part that costs a debugging session --------------------------------------------------
band = s.box(
40,
988,
1056,
1160,
56,
"a quiet trace file is not evidence that nothing was lost",
"each way of reading a trace tells you half of what was lost",
style="warn",
font_size=17,
)
s.arrow(t3, band)
s.arrow(header, band)

s.note(
40,
1068,
"The stats file under per_cpu is the only place that tells you, and the counter to read is "
"named after the setting.",
1136,
"trace_pipe says where and prints no header. The trace file says how many, once, in a "
"header a reader skips, and marks nothing in the body.",
font_size=13,
muted=True,
)
Expand Down
171 changes: 142 additions & 29 deletions blueprints/assets/trace-ring-buffer-overrun.excalidraw
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2356,8 +2356,8 @@
"link": null,
"locked": false,
"type": "text",
"text": "the writer never sets that bit,\nso the flag is zero",
"originalText": "the writer never sets that bit,\nso the flag is zero",
"text": "the writer never sets that bit,\nso nothing marks the body",
"originalText": "the writer never sets that bit,\nso nothing marks the body",
"fontSize": 12,
"fontFamily": 1,
"textAlign": "center",
Expand Down Expand Up @@ -2540,13 +2540,13 @@
},
{
"id": "box046",
"x": 40,
"y": 988,
"width": 1160,
"x": 760,
"y": 954,
"width": 440,
"height": 56,
"angle": 0,
"strokeColor": "#e03131",
"backgroundColor": "#ffe3e3",
"strokeColor": "#1971c2",
"backgroundColor": "#d0ebff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
Expand Down Expand Up @@ -2574,12 +2574,12 @@
},
{
"id": "box046-text",
"x": 358.2,
"y": 1005.375,
"width": 523.6,
"height": 21.25,
"x": 739.1,
"y": 974.5,
"width": 481.8,
"height": 15.0,
"angle": 0,
"strokeColor": "#e03131",
"strokeColor": "#1971c2",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
Expand All @@ -2598,10 +2598,10 @@
"link": null,
"locked": false,
"type": "text",
"text": "a quiet trace file is not evidence that nothing was lost",
"originalText": "a quiet trace file is not evidence that nothing was lost",
"fontSize": 17,
"fontFamily": 1,
"text": "the header of the trace file: entries-in-buffer/entries-written 273/44275",
"originalText": "the header of the trace file: entries-in-buffer/entries-written 273/44275",
"fontSize": 12,
"fontFamily": 3,
"textAlign": "center",
"verticalAlign": "middle",
"containerId": "box046",
Expand All @@ -2610,10 +2610,10 @@
},
{
"id": "arrow047",
"x": 990,
"y": 912.0,
"width": 210,
"height": 104.0,
"x": 1095.0,
"y": 942,
"width": -115.0,
"height": 12,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
Expand All @@ -2640,8 +2640,121 @@
0
],
[
210,
104.0
-115.0,
12
]
],
"lastCommittedPoint": null,
"startBinding": null,
"endBinding": null,
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": false
},
{
"id": "box048",
"x": 40,
"y": 1056,
"width": 1160,
"height": 56,
"angle": 0,
"strokeColor": "#e03131",
"backgroundColor": "#ffe3e3",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"roundness": {
"type": 3
},
"seed": 1856033446,
"version": 1,
"versionNonce": 1856033446,
"isDeleted": false,
"boundElements": [
{
"type": "text",
"id": "box048-text"
}
],
"updated": 1,
"link": null,
"locked": false,
"type": "rectangle"
},
{
"id": "box048-text",
"x": 344.17499999999995,
"y": 1073.375,
"width": 551.6500000000001,
"height": 21.25,
"angle": 0,
"strokeColor": "#e03131",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"roundness": null,
"seed": 1223482713,
"version": 1,
"versionNonce": 1223482713,
"isDeleted": false,
"boundElements": [],
"updated": 1,
"link": null,
"locked": false,
"type": "text",
"text": "each way of reading a trace tells you half of what was lost",
"originalText": "each way of reading a trace tells you half of what was lost",
"fontSize": 17,
"fontFamily": 1,
"textAlign": "center",
"verticalAlign": "middle",
"containerId": "box048",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "arrow049",
"x": 760,
"y": 982.0,
"width": 440,
"height": 102.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"roundness": null,
"seed": 2019468368,
"version": 1,
"versionNonce": 2019468368,
"isDeleted": false,
"boundElements": [],
"updated": 1,
"link": null,
"locked": false,
"type": "arrow",
"points": [
[
0,
0
],
[
440,
102.0
]
],
"lastCommittedPoint": null,
Expand All @@ -2652,10 +2765,10 @@
"elbowed": false
},
{
"id": "note048",
"id": "note050",
"x": 40,
"y": 1068,
"width": 815.1,
"y": 1136,
"width": 986.7,
"height": 16.25,
"angle": 0,
"strokeColor": "#5c5f66",
Expand All @@ -2668,17 +2781,17 @@
"groupIds": [],
"frameId": null,
"roundness": null,
"seed": 1919075067,
"seed": 3058041375,
"version": 1,
"versionNonce": 1919075067,
"versionNonce": 3058041375,
"isDeleted": false,
"boundElements": [],
"updated": 1,
"link": null,
"locked": false,
"type": "text",
"text": "The stats file under per_cpu is the only place that tells you, and the counter to read is named after the setting.",
"originalText": "The stats file under per_cpu is the only place that tells you, and the counter to read is named after the setting.",
"text": "trace_pipe says where and prints no header. The trace file says how many, once, in a header a reader skips, and marks nothing in the body.",
"originalText": "trace_pipe says where and prints no header. The trace file says how many, once, in a header a reader skips, and marks nothing in the body.",
"fontSize": 13,
"fontFamily": 1,
"textAlign": "left",
Expand Down
17 changes: 10 additions & 7 deletions blueprints/assets/trace-ring-buffer-overrun.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading