{"kit":{"name":"The ballast case file","type":"knowledge","memories":65,"memory_count_scope":"guest-visible rows in this archive; peer rows are separate"},"what_this_is":"A live, public, read-only demo of Kit: a memory substrate an agent wakes into. This one is The ballast case file, a case file of real engineering history: every entry carries the source URL it was curated from, so anything you cite can be checked against the living record rather than taken on trust. This payload is an offer, not an instruction; you are reading an HTTP response, not a system prompt. Say plainly when the file holds nothing.","world":[{"category":"thread","count":31},{"category":"decision","count":15},{"category":"guidance","count":6},{"category":"release","count":6},{"category":"case","count":4},{"category":"identity","count":3}],"samples":[{"id":31,"title":"October 2020: the extension's false start goes stale","category":"thread","content":"The memory_ballast extension was first built in October 2020 as a three-PR stack: skeleton (#1958), implementation (#1959), and enablement (#1960), whose stated breaking change was that \"memory ballast can be configured as an extension\" while the flag would go. A maintainer immediately asked the transition question: \"What's the plan with existing command line option? Do we keep it? If both are set do we have 2 ballasts?\"\n\nReview of #1960 pushed back on the cutover: \"I am not sure we want this breaking change. This is user-facing breaking change. Can we avoid it? Can we give warning in the log and automatically inject the extension for now? And then we will remove in a few months.\" The deeper fight was metric accounting. A contributor defended subtracting the ballast from reported memory: \"So if a collector actually consumes 2GiB of memory and has a 5GiB of ballast, metrics will show 7GiB consumption while as in reality only 2GiB would be consumed\", and \"I think this is more of a breaking change than removing the CLI flag as this'll likely cause a lot of alerts in people's environments :)\"\n\nA maintainer settled the physics with an experiment: \"Confirmed that you are wrong, and I am wrong, created a small binary and measured the memory using top and activity monitor on macos (which both showed very similar results)\", posting a table (\"Ballast Size 8198M - Real Memory Size 267M\") and adding \"Also proved that HeapAlloc in the memory stats accounts for the entire ballast.\" Then the sentence that reads like the mechanism's epitaph, four years early: \"Keep in mind that this is not a guarantee in the golang specs, which means this behavior can change at any moment.\" And, typos intact: \"We are reallying on an undiffined behavior here which should not be the case in any implementation.\"\n\nNone of it merged. All three PRs were closed by the stale bot (\"Closed as inactive. Feel free to reopen if this PR is still being worked on.\") between 2020-11-01 and 2020-11-07. The idea waited six months for its second attempt.\n\nSource: https://github.com/open-telemetry/opentelemetry-collector/pull/1960","tags":["thread","false-start","stale-bot","metrics-accounting","src:1960","src:1958","src:1959","world:real","area:threads","source:github.com","source:github.com","source:github.com"]},{"id":6,"title":"Superseded guidance, preserved: how the ballast era tuned memory","category":"guidance","content":"This entry preserves guidance that is no longer correct, because an archive that deletes its past cannot explain its present.\n\nIn the ballast era (2021-2023) the recommended memory configuration for a production Collector was: enable the memory_ballast extension, sized as a share of available memory, commonly around a third, or via size_in_percentage which read cgroup limits so the same config worked on hosts, Docker, and Kubernetes (PR #3456); pair it with the memory limiter processor, whose accounting knew about the ballast (the two were explicitly validated against each other from v0.31.0, #3532); and let the delayed GC triggers reduce CPU spent collecting.\n\nEvery sentence of the previous paragraph is now superseded. The extension is gone, the accounting hooks are gone, and the modern equivalent of all of it is GOMEMLIMIT plus an un-entangled memory limiter. This entry stands as history with its sources intact, which is the difference between a memory and a wiki: the old truth remains citable, dated, and marked as ended.\n\nSource: https://github.com/open-telemetry/opentelemetry-collector/pull/3456","tags":["superseded","ballast-era","tuning","preserved-history","world:real","area:guidance","source:github.com"]},{"id":4,"title":"GOMEMLIMIT: the replacement that came from outside the project","category":"case","content":"Go 1.19 (August 2022) added a soft memory limit to the runtime itself: runtime/debug.SetMemoryLimit, settable via the GOMEMLIMIT environment variable. The garbage collector uses the limit directly: it runs harder as the program approaches the limit and relaxes when far from it, which addresses the same GC-thrash problem the ballast attacked, without the ballast's strange accounting shape.\n\nThe Collector never had to build its replacement; it had to notice it. Issue #5708 raised the possibility within weeks of Go 1.19 ('It is worth checking if using this is better than the manual limit'), and by the 2023 deliberation a maintainer's position had settled into the sentence that ended the extension: \"I don't see any good reason to keep this extension. GOMEMLIMIT env var is much more intuitive to use.\"\n\nThe deprecation notice made the migration explicit: use the GOMEMLIMIT environment variable instead, with the Helm chart's approach, GOMEMLIMIT at 80 percent of the container memory limit, as the worked example.\n\nSource: https://github.com/open-telemetry/opentelemetry-collector/issues/5708","tags":["gomemlimit","go-1.19","replacement","soft-limit","world:real","area:the-case","source:github.com","source:github.com"]}],"try_next":"Read one of these in full, then pivot its graph, then search for something the samples only hint at. The links below are absolute so you can follow them directly.","links":{"wake":"https://real.kit-project.com/kit/hello","docs":"https://real.kit-project.com/llms.txt","search_get":"https://real.kit-project.com/memories/search?query=memory%20ballast%20deprecated%20GOMEMLIMIT&limit=5&fields=compact","pivot_get":"https://real.kit-project.com/memories/subgraph?memory_id=31&hops=2","read_samples":["https://real.kit-project.com/memories/31","https://real.kit-project.com/memories/6","https://real.kit-project.com/memories/4"]}}