OpenTelemetry for Balatro

I should start this blog post with a witty joke, because that’s one of the key ingredients that make Balatro such a beloved game. However, I can’t come up with one, so here’s a different intro: I am fascinated by the possibility that any software I use could, in theory, emit logs, metrics and traces through OpenTelemetry. And Balatro is software that I use a lot. I’ve spent hundreds of hours with it, the best 2 × 10 euros I’ve ever spent¹. So creating OpenTelemetry for Balatro was a side project I wanted to try out for a long time! It turned out to be one of those projects where I cared more about the outcome than about writing the code myself, so it was a perfect candidate to ask an LLM to build for me!

You might be wondering why Balatro can be instrumented at all. First, it’s built with LÖVE and written in Lua, and a modding framework, Steamodded, already exists. Second, the game is “transactional”: you play hands, they get scored, you buy things in a shop, and so on. So “traces” make sense, which is not the case for all games. Based on that, an LLM can follow the OpenTelemetry specification, use OpenTelemetry-specific agent skills and Weaver to build out an instrumentation library for Balatro, which is available here: https://github.com/svrnm/balatro-otel

If you have Balatro installed on your computer, you can try it yourself! You can install the mod from Thunderstore using a mod manager such as r2modman, Gale or imm. Manual installation is covered in the quick-start guide.

Next, you need something that receives your telemetry. The repository provides instructions to set up Jaeger, but of course, since it is OpenTelemetry, you can send your data to your preferred backend. By default the mod sends to http://127.0.0.1:4318. You can change the endpoint in the UI under Mods -> OTel Trace -> Config. I use Bronto, where I work, to keep the telemetry for long-term analysis.

With the telemetry stored in a backend, you can start analyzing your play: which hands you play in which situation, how you spend your money, which boss blinds you struggle the most with. The bot sessions recorded 112 runs with 2,000 hands, of which 1,400 were Pairs. The boss blinds that ended the most runs were The Mouth and The Psychic (8 runs each), and The Water was the hardest: the bot lost to it 7 out of 8 times.

However, observability data’s primary use case is not to analyze, but troubleshooting. I wanted to be able to ask: “What would a game developer or mod author need when something goes wrong?” To answer it, besides errors and stack traces, the mod records janky frames, update and draw times, the length of the animation queue and other game properties. This way I was able to confirm that some known bugs are gone, like the Perkeo and Wheel of Fortune crash, which was fixed in 1.0.1o. I also ran into bugs in the tooling, like in BalatroBot, where skip-opened tag packs are a dead zone. The most interesting one was a bug where blind scores didn’t add up, because under bosses that block hands, like The Psychic, a blocked hand scored 0, but the blind still gained the points. This was fixed in Steamodded already, but my setup pinned an older version, because BalatroBot failed to start on more recent versions. Finally, I reported another bug, where BalatroBot’s responses were cut off when they didn’t fit the socket’s send buffer, which broke it under load.

All in all, instrumenting Balatro or any game like it is not even a terrible idea. The data is useful for analyzing your own play or your bots’ runs and beyond that, it can be used for finding bugs and testing. If you’d like to play around with it, check the repository and send me a message if you tried it out or if you found another game that you have instrumented!