{"article":{"slug":"why-i-wrote-the-beam-book","title":"Why I Wrote the BEAM Book","subtitle":"Post-mortems, coffee, and a decade of stubborn curiosity","summary":"The story behind The BEAM Book: a decade of keeping Klarna's Erlang core system running, three publishers, and an open-source sprint to finish a deep guide to the BEAM virtual machine's internals, plus lessons learned.","content_type":"essay","language":"en","canonical_url":"https://happihacking.com/blog/posts/2025/why_I_wrote_theBEAMBook/","author":{"name":"Erik Stenman","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"Happi Hacking","url":"https://happihacking.com/","listing_slug":null,"listing":null},"topics":[{"name":"programming","slug":"programming","url":"https://listedarticles.com/topics/programming"},{"name":"open-source","slug":"open-source","url":"https://listedarticles.com/topics/open-source"},{"name":"writing","slug":"writing","url":"https://listedarticles.com/topics/writing"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":1157,"reading_minutes":5,"published_at":"2025-06-03T00:00:00.000Z","added_at":"2026-11-11T05:13:58.551Z","updated_at":"2026-11-11T05:13:58.551Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/why-i-wrote-the-beam-book","markdown_url":"https://listedarticles.com/articles/why-i-wrote-the-beam-book.md","example":false,"citation":"Erik Stenman, Happi Hacking. \"Why I Wrote the BEAM Book.\" 3 Jun 2025. https://happihacking.com/blog/posts/2025/why_I_wrote_theBEAMBook/ (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://happihacking.com/blog/posts/2025/why_I_wrote_theBEAMBook/"},"body_markdown":"# Why I Wrote the BEAM Book\n\nStay in the loop: occasional updates on BEAM and fintech engineering.\n[Subscribe below](#newsletter-signup)\n\n## Why I wrote the Beam Book\n\nAfter ten years of keeping Klarna’s core system upright I know this: a 15\nmillisecond pause in the BEAM can stall millions of peak-shopping payments, trigger a 3 a.m. Christmas-Eve post-mortem, and earn you a very awake call from the CEO. I wrote *The BEAM Book* so the next engineer fixes that pause before the coffee cools.\n\n![A picture of two printed BEAM Books.](https://happihacking.com/images/thebeambooks.jpg \"A picture of two printed BEAM Books.\")\n\n### Origins\n\nI opened the project on 12 October 2012 with a lone DocBook file with four lines of text and an oversized sense of optimism.\nAfter two weeks, the commit log is mostly me adding structure, moving\nheadings, and updating metadata. Most of it is scaffolding. The actual\ncontent is still just a few hopeful lines.\n\nBy November I had abandoned DocBook for AsciiDoc, written a custom build\nscript, and convinced myself the book could be wrapped up in six months.\nThose early commits glow with energy: adds, rewrites, then more\nrewrites to fix the rewrites.\nDelusion is underrated.\n\nIn 2013 I managed to convince O’Reilly to publish. Moving the repo to their\nAtlas system sounded simple until Atlas began hiding my main file and\noverwriting half-finished chapters.\n\nThe Git history reads like a diary of frustration:\n“Moving files to top level to cope with Atlas,” “Atlas seems to be\noverwriting book.asciidoc”. Word count shot past 120 000 while actual\nprogress crawled. On 10 March 2015 I was literally “Smashing chapters into sections” just to keep the build green.\n\nThe quiet cancellation came two months later. No drama, just a polite call and a line through the contract. Relief mingled with embarrassment, I had spent two years rearranging files rather than finishing sentences.\n\nPragmatic Bookshelf took over that same year. I kept working in CVS for\ntheir production system, but progress was slow. Eventually, they cancelled\ntoo. On 20 January 2017, I imported everything into a new repo in one\nmassive commit: 6,622 files, over a million lines.\nThe rewrite stalled, and so did the project.\n\nOn 23 March 2017 I started fresh with Asciidoctor in a private GitHub repo, copy-pasting\nonly the parts that still made sense. Two weeks later, on April 7, minutes before\na lecture at Chalmers, I flipped the repository public. Within twenty-four\nhours strangers fixed typos, added diagrams, and merged a Creative Commons\nBY-4.0 license.\n\n### What Kept Me Going\n\n![A picture of the stars on GitHub passing 3000.](https://api.star-history.com/svg?repos=happi/theBeamBook&type=Date \"A picture of the stars on GitHub passing 3000.\")\n\nI kept going because I wanted to understand the BEAM properly. There’s\nvalue in following the real logic, not just the surface explanations.\n\nCommunity feedback made a difference. As soon as the repo was public,\npeople began sending corrections, examples, and improvements.\n\nSeeing the numbers of people starring the repo on GitHub kept me going.\nOne highlight: **Issue #113 - \"Please continue being awesome.\"**\n(I wrote [a whole post about that issue](https://happihacking.com/blog/posts/2025/an_issue/).)\nThat emoji-laced drive-by encouragement (August 2018) still pops into my\nhead whenever motivation dips.\n\n![Issue 113: This book\nis ridiculously good. I have only read a few bits of it so far and have\nlearned a lot already. Please continue being awesome!](https://happihacking.com/images/issue113.png \"Issue 113: This book\nis ridiculously good. I have only read a few bits of it so far and have\nlearned a lot already. Please continue being awesome!\")\n\nThe book started showing up as a reference in Erlang and BEAM conference\ntalks, sometimes several times in the same event. That was a clear signal\nthat others needed this as much as I did.\n\nEven Twitter (in the good old days of Twitter) played a role. Whenever\nsomeone mentioned the book or shared a\nlink, it was an extra nudge to keep at it.\n\nMostly, I just wanted a manual I could trust myself, a reference for the\nparts of the VM that matter when things go wrong. That’s reason enough to\nkeep writing, even after the third rewrite.\n\n### What’s Inside the Book & Who It Helps\n\nThe book covers what I wish I’d had when building and operating large\nErlang systems:\n\n- Schedulers and process management: How the BEAM schedules,\n  prioritizes, and balances processes under real load.\n- Processes and their memory: How process heaps,\n  stack, messages, and binaries are managed and\n  why these details matter in production.\n- Garbage collection and memory: What actually happens\n  with per-process and global garbage collectors, binary references,\n  and memory leaks.\n- Tagging schemes and terms: How the BEAM represents data-integers,\n  floats, tuples, binaries, references-down to the tagging bits.\n- The compiler and the VM: How code is turned into instructions,\n  what the compiler does (and doesn’t do), and how the emulator executes it.\n- Tracing and debugging: Practical use of dbg, erlang:trace,\n  and other tools to follow messages, events, and identify bottlenecks.\n- Performance tuning: What matters when profiling real code,\n  understanding reductions, and tracking down real-world latency problems.\n- System architecture: How ERTS, the BEAM VM, and their subsystems\n  actually work together in a running node.\n\nIf you build or operate Erlang or Elixir systems, especially under any kind\nof scale-this book is for you. It saves you from hunting through mailing\nlists, scattered docs, and code comments just to answer, “Why is the VM\nbehaving like this?”\n\n### Lessons Learned\n\nPersistence beats perfection. Two cancelled publishing deals look bad on a\nrésumé, but an unfinished idea looks worse.\n\nBoundaries matter. I made progress by blocking time for writing, turning\noff notifications, and treating focus like a real deadline. Fika at 14:30\nis non-negotiable.\n\nThe crowd helps. Making the repo public brought in corrections,\nencouragement, and the occasional nudge when motivation was low.\n\nScope is everything. I cut the details on dirty schedulers, the new JIT,\nand the debugger. Maybe those will end up in an appendix, but not in the\ncore. I wrote more about this scoping process in [The BEAM Book Is Almost Done](https://happihacking.com/blog/posts/2025/the_beam_book_lessons/).\n\nShip, then iterate. The BEAM changes every year. A living Git repo keeps\nup.\n\nA real deadline helps. This January, during my yearly review, I\ndecided to print the book in time for Code Beam Stockholm. I thought I had\nuntil autumn, turns out the conference was June 2. That’s how you find out\nwhat’s truly essential.\n\n### Definition of Done\n\nHolding the print in my hands, it finally feels finished, at least for now. Years of scattered commits are bound into something real, so I’m calling it done.\n\n### Get Involved\n\nYou can now get the paperback-The BEAM Book 1.0 is live on Amazon. Buy it\nhere. [Amazon](https://www.amazon.com/dp/9153142535)\n\nIf you spot an error, want to improve something, or just want to see how it\nworks under the hood, star or fork the repo. File an issue or, even better,\nsubmit a pull request. Contributors are credited in the acknowledgments.\n[GitHub: theBeamBook](https://github.com/happi/theBeamBook)\n\nIf you read the book, please leave an honest review.\nAlgorithms notice real feedback more than marketing copy.\n\nIf your team wants a deep dive, I run hands-on BEAM internals\nworkshops, tailored for real systems, not just hello world.\n\nFrom Here\n\nFor deeper runtime work: [The BEAM Book](https://happihacking.com/resources/the-beam-book/) and [BEAM workshops for teams](https://happihacking.com/resources/beam-deep-dive-course/).\n","body_html":"<h1 id=\"why-i-wrote-the-beam-book\">Why I Wrote the BEAM Book</h1>\n<p>Stay in the loop: occasional updates on BEAM and fintech engineering.\n<a href=\"#newsletter-signup\">Subscribe below</a></p>\n<h2 id=\"why-i-wrote-the-beam-book-2\">Why I wrote the Beam Book</h2>\n<p>After ten years of keeping Klarna’s core system upright I know this: a 15\nmillisecond pause in the BEAM can stall millions of peak-shopping payments, trigger a 3 a.m. Christmas-Eve post-mortem, and earn you a very awake call from the CEO. I wrote <em>The BEAM Book</em> so the next engineer fixes that pause before the coffee cools.</p>\n<figure><img src=\"https://happihacking.com/images/thebeambooks.jpg\" alt=\"A picture of two printed BEAM Books.\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /><figcaption>A picture of two printed BEAM Books.</figcaption></figure>\n<h3 id=\"origins\">Origins</h3>\n<p>I opened the project on 12 October 2012 with a lone DocBook file with four lines of text and an oversized sense of optimism.\nAfter two weeks, the commit log is mostly me adding structure, moving\nheadings, and updating metadata. Most of it is scaffolding. The actual\ncontent is still just a few hopeful lines.</p>\n<p>By November I had abandoned DocBook for AsciiDoc, written a custom build\nscript, and convinced myself the book could be wrapped up in six months.\nThose early commits glow with energy: adds, rewrites, then more\nrewrites to fix the rewrites.\nDelusion is underrated.</p>\n<p>In 2013 I managed to convince O’Reilly to publish. Moving the repo to their\nAtlas system sounded simple until Atlas began hiding my main file and\noverwriting half-finished chapters.</p>\n<p>The Git history reads like a diary of frustration:\n“Moving files to top level to cope with Atlas,” “Atlas seems to be\noverwriting book.asciidoc”. Word count shot past 120 000 while actual\nprogress crawled. On 10 March 2015 I was literally “Smashing chapters into sections” just to keep the build green.</p>\n<p>The quiet cancellation came two months later. No drama, just a polite call and a line through the contract. Relief mingled with embarrassment, I had spent two years rearranging files rather than finishing sentences.</p>\n<p>Pragmatic Bookshelf took over that same year. I kept working in CVS for\ntheir production system, but progress was slow. Eventually, they cancelled\ntoo. On 20 January 2017, I imported everything into a new repo in one\nmassive commit: 6,622 files, over a million lines.\nThe rewrite stalled, and so did the project.</p>\n<p>On 23 March 2017 I started fresh with Asciidoctor in a private GitHub repo, copy-pasting\nonly the parts that still made sense. Two weeks later, on April 7, minutes before\na lecture at Chalmers, I flipped the repository public. Within twenty-four\nhours strangers fixed typos, added diagrams, and merged a Creative Commons\nBY-4.0 license.</p>\n<h3 id=\"what-kept-me-going\">What Kept Me Going</h3>\n<figure><img src=\"https://api.star-history.com/svg?repos=happi/theBeamBook&amp;type=Date\" alt=\"A picture of the stars on GitHub passing 3000.\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /><figcaption>A picture of the stars on GitHub passing 3000.</figcaption></figure>\n<p>I kept going because I wanted to understand the BEAM properly. There’s\nvalue in following the real logic, not just the surface explanations.</p>\n<p>Community feedback made a difference. As soon as the repo was public,\npeople began sending corrections, examples, and improvements.</p>\n<p>Seeing the numbers of people starring the repo on GitHub kept me going.\nOne highlight: <strong>Issue #113 - &quot;Please continue being awesome.&quot;</strong>\n(I wrote <a href=\"https://happihacking.com/blog/posts/2025/an_issue/\" rel=\"nofollow ugc noopener\">a whole post about that issue</a>.)\nThat emoji-laced drive-by encouragement (August 2018) still pops into my\nhead whenever motivation dips.</p>\n<p><img src=\"https://happihacking.com/images/issue113.png\" alt=\"Issue 113: This book\nis ridiculously good. I have only read a few bits of it so far and have\nlearned a lot already. Please continue being awesome!\" title=\"Issue 113: This book\nis ridiculously good. I have only read a few bits of it so far and have\nlearned a lot already. Please continue being awesome!\" loading=\"lazy\" decoding=\"async\" referrerpolicy=\"no-referrer\" /></p>\n<p>The book started showing up as a reference in Erlang and BEAM conference\ntalks, sometimes several times in the same event. That was a clear signal\nthat others needed this as much as I did.</p>\n<p>Even Twitter (in the good old days of Twitter) played a role. Whenever\nsomeone mentioned the book or shared a\nlink, it was an extra nudge to keep at it.</p>\n<p>Mostly, I just wanted a manual I could trust myself, a reference for the\nparts of the VM that matter when things go wrong. That’s reason enough to\nkeep writing, even after the third rewrite.</p>\n<h3 id=\"what-s-inside-the-book-who-it-helps\">What’s Inside the Book &amp; Who It Helps</h3>\n<p>The book covers what I wish I’d had when building and operating large\nErlang systems:</p>\n<ul><li><p>Schedulers and process management: How the BEAM schedules,</p><p>prioritizes, and balances processes under real load.</p></li><li><p>Processes and their memory: How process heaps,</p><p>stack, messages, and binaries are managed and\nwhy these details matter in production.</p></li><li><p>Garbage collection and memory: What actually happens</p><p>with per-process and global garbage collectors, binary references,\nand memory leaks.</p></li><li><p>Tagging schemes and terms: How the BEAM represents data-integers,</p><p>floats, tuples, binaries, references-down to the tagging bits.</p></li><li><p>The compiler and the VM: How code is turned into instructions,</p><p>what the compiler does (and doesn’t do), and how the emulator executes it.</p></li><li><p>Tracing and debugging: Practical use of dbg, erlang:trace,</p><p>and other tools to follow messages, events, and identify bottlenecks.</p></li><li><p>Performance tuning: What matters when profiling real code,</p><p>understanding reductions, and tracking down real-world latency problems.</p></li><li><p>System architecture: How ERTS, the BEAM VM, and their subsystems</p><p>actually work together in a running node.</p></li></ul>\n<p>If you build or operate Erlang or Elixir systems, especially under any kind\nof scale-this book is for you. It saves you from hunting through mailing\nlists, scattered docs, and code comments just to answer, “Why is the VM\nbehaving like this?”</p>\n<h3 id=\"lessons-learned\">Lessons Learned</h3>\n<p>Persistence beats perfection. Two cancelled publishing deals look bad on a\nrésumé, but an unfinished idea looks worse.</p>\n<p>Boundaries matter. I made progress by blocking time for writing, turning\noff notifications, and treating focus like a real deadline. Fika at 14:30\nis non-negotiable.</p>\n<p>The crowd helps. Making the repo public brought in corrections,\nencouragement, and the occasional nudge when motivation was low.</p>\n<p>Scope is everything. I cut the details on dirty schedulers, the new JIT,\nand the debugger. Maybe those will end up in an appendix, but not in the\ncore. I wrote more about this scoping process in <a href=\"https://happihacking.com/blog/posts/2025/the_beam_book_lessons/\" rel=\"nofollow ugc noopener\">The BEAM Book Is Almost Done</a>.</p>\n<p>Ship, then iterate. The BEAM changes every year. A living Git repo keeps\nup.</p>\n<p>A real deadline helps. This January, during my yearly review, I\ndecided to print the book in time for Code Beam Stockholm. I thought I had\nuntil autumn, turns out the conference was June 2. That’s how you find out\nwhat’s truly essential.</p>\n<h3 id=\"definition-of-done\">Definition of Done</h3>\n<p>Holding the print in my hands, it finally feels finished, at least for now. Years of scattered commits are bound into something real, so I’m calling it done.</p>\n<h3 id=\"get-involved\">Get Involved</h3>\n<p>You can now get the paperback-The BEAM Book 1.0 is live on Amazon. Buy it\nhere. <a href=\"https://www.amazon.com/dp/9153142535\" rel=\"nofollow ugc noopener\">Amazon</a></p>\n<p>If you spot an error, want to improve something, or just want to see how it\nworks under the hood, star or fork the repo. File an issue or, even better,\nsubmit a pull request. Contributors are credited in the acknowledgments.\n<a href=\"https://github.com/happi/theBeamBook\" rel=\"nofollow ugc noopener\">GitHub: theBeamBook</a></p>\n<p>If you read the book, please leave an honest review.\nAlgorithms notice real feedback more than marketing copy.</p>\n<p>If your team wants a deep dive, I run hands-on BEAM internals\nworkshops, tailored for real systems, not just hello world.</p>\n<p>From Here</p>\n<p>For deeper runtime work: <a href=\"https://happihacking.com/resources/the-beam-book/\" rel=\"nofollow ugc noopener\">The BEAM Book</a> and <a href=\"https://happihacking.com/resources/beam-deep-dive-course/\" rel=\"nofollow ugc noopener\">BEAM workshops for teams</a>.</p>","headings":[{"level":1,"text":"Why I Wrote the BEAM Book","id":"why-i-wrote-the-beam-book"},{"level":2,"text":"Why I wrote the Beam Book","id":"why-i-wrote-the-beam-book-2"},{"level":3,"text":"Origins","id":"origins"},{"level":3,"text":"What Kept Me Going","id":"what-kept-me-going"},{"level":3,"text":"What’s Inside the Book & Who It Helps","id":"what-s-inside-the-book-who-it-helps"},{"level":3,"text":"Lessons Learned","id":"lessons-learned"},{"level":3,"text":"Definition of Done","id":"definition-of-done"},{"level":3,"text":"Get Involved","id":"get-involved"}]}}