Gleam Performance Optimization - Make Your BEAM Apps Actually Fast

Let's cut the bullshit: BEAM isn't fast for CPU-heavy work. It's about as fast as Python, which means slow as shit for number crunching. But that's not the point - BEAM is built for latency and fault tolerance, not raw speed.

But BEAM has two performance superpowers that make it worth the tradeoff:

1. Concurrency is very cheap - you can spawn 200,000+ concurrent processes like it's nothing
2. VM is optimized for latency - per-process heap with no global stop-the-world, pre-emptive scheduling

This design proved its worth at scale: WhatsApp handles 40+ billion messages daily and Discord stores billions of messages using the same BEAM foundation that powers Gleam.

Memory Layout That Actually Matters

Every BEAM process gets four blocks of memory:

• Stack: Return addresses, function arguments, local variables
• Heap: Larger structures like lists and tuples
• Message area (mailbox): Messages from other processes
• Process Control Block: Process metadata

Each process burns about 2KB minimum, which sounds expensive until you realize you can spawn hundreds of thousands without your server catching fire. This lightweight process model is nothing like OS threads - it's what lets BEAM handle insane concurrency.

Why Your Gleam App Is Probably Slow

Pattern matching overhead: Gleam's pattern matching is powerful but not free. Efficient compilation of pattern matching is a surprisingly challenging problem, and complex nested patterns can create expensive dispatch trees.

List operations: Gleam lists are linked lists, not arrays. list.length() is O(n), not O(1). If you're calling list.length(my_list) > 1000, you're already fucked. I spent 6 hours debugging why our API went to shit - some genius was calling list.length() on 50k-item lists in a hot path. Don't be that person.

No tail call optimization awareness: Gleam supports tail call optimization, but the compiler won't warn you when you're not using it. Writing recursive functions without proper accumulators will eat your stack.

String operations: BEAM strings are UTF-8 binaries. Concatenating strings creates new binaries every time. If you're building strings in loops, use `iodata` instead.

Performance Improvements That Actually Shipped

The Gleam team isn't sitting around - they shipped real performance wins:

• v1.11.0 got 30% faster JavaScript compilation in June 2025
• v1.12.0 enabled function inlining with conservative configuration
• Binary operations got optimized - taking a sub-slice is now constant time on JavaScript to match Erlang behavior

These aren't marketing bullshit numbers - Richard Viney actually benchmarked real workloads to prove it.

Debug Performance Issues First, Optimize Second

The `echo` keyword is your best friend for quick performance debugging:

import gleam/io

pub fn slow_function(data) {
  data
  |> echo("Input data size")
  |> expensive_operation()
  |> echo("After expensive operation") 
  |> another_expensive_operation()
  |> echo("Final result")
}

The compiler tracks `echo` usage and will warn you if you try to publish with debug statements still in your code. Use it liberally while profiling, then remove it when you're done. The language server also provides code actions to remove all echos from a module.

Pro tip: Add timestamps to your echo statements:

import gleam/erlang/system_time

pub fn timed_operation(data) {
  let start = system_time.monotonic_time()
  
  let result = data 
    |> expensive_operation()
    |> echo("Operation completed")
  
  let end = system_time.monotonic_time()
  let duration_ms = (end - start) / 1_000_000
  
  io.println("Operation took " <> int.to_string(duration_ms) <> "ms")
  result
}

This gives you microsecond-precision timing without external tools.

Observer: The Swiss Army Knife

Observer is the GUI tool that lets you peek inside your running BEAM system. It works perfectly with Gleam applications because Gleam compiles to BEAM bytecode. The Observer user guide covers all features in detail.

Start Observer locally:

$ erl -name observer@127.0.0.1
1> observer:start().

Connect to remote production node (this is where it gets powerful):

$ erl -name debug@127.0.0.1 -setcookie production_cookie
1> net_adm:ping('myapp@production-server').
2> observer:start().

Click "Nodes" menu → select your production node. Now you can debug production while it's running. For detailed setup instructions, see Fly.io's guide on connecting Observer to production.

What to actually look for in Observer:

• Processes tab: Sort by memory or reductions to find resource hogs
• System tab: Check memory usage, scheduler utilization
• Load Charts: CPU and memory trends over time
• Applications tab: See which OTP applications are running

Spectator: Observer for Gleam Nerds

Spectator is a BEAM observer written specifically for Gleam applications. It understands gleam_otp processes better than standard Observer.

Add to your project:

[dependencies]
spectator = "~> 0.5"

Start in your application:

import spectator

pub fn main() {
  spectator.start()
  // Your app code here
}

Access the web UI at http://localhost:9001.

Tag your processes for easier identification:

import gleam/otp/actor
import spectator

pub fn start_worker() {
  actor.start(0, handle_message)
  |> spectator.tag("worker_process")
}

Heads up: Spectator probes processes using process_info/2, which temporarily locks each process. Don't use it on systems with millions of processes unless you hate yourself.

recon: Production Debugging Without Fear

recon is the tool for when Observer is too much GUI and you need command-line precision. It comes with the excellent "Erlang in Anger" book that actually explains how to debug BEAM in production.

Install recon in your project:

[dependencies]
recon = "~> 2.5"

Find memory hogs:

% Connect to your running system
$ erl -name debug@127.0.0.1 -setcookie your_cookie -remsh myapp@production

% Top 10 processes by memory usage
1> recon:proc_count(memory, 10).

% Top 10 by CPU (reductions)
2> recon:proc_count(reductions, 10).

% Get memory allocation info
3> recon_alloc:memory(used).

Trace function calls safely in production:

% Trace all calls to a slow function for 30 seconds, max 1000 calls
4> recon_trace:calls({module, function, '_'}, 1000, [{time, 30000}]).

This won't crash your production system - recon has safety limits built in. For more advanced tracing patterns, check out the tracing chapter in Erlang in Anger.

Getting Flame Graphs from Gleam

eflame generates flame graphs from BEAM tracing data. These show you exactly where your CPU time is going.

Trace your application:

$ erl -name debug@127.0.0.1 -setcookie your_cookie

1> eflame:apply(normal_with_children, "flame_graph", [], your_module, your_function, [args]).

This creates flame_graph.out - upload it to Flame Graph Generator for visualization. Brendan Gregg's flame graphs guide explains the format in detail.

What flame graphs tell you:

• Width = CPU time spent in function
• Height = call stack depth
• Colors are random (ignore them)
• Look for wide plateaus - those are your bottlenecks

For BEAM-specific flame graph analysis, check out this presentation on BEAM profiling and the eflame README for usage examples.

Linux perf for Low-Overhead Profiling

If you're running on Linux with BEAM JIT enabled, perf gives you system-level profiling with minimal overhead.

Enable JIT profiling:

$ erl +JPperf true -name myapp

Profile your running application:

## Profile for 30 seconds
$ perf record -g --pid=$(pidof beam.smp) sleep 30

## Generate flame graph
$ perf script | stackcollapse-perf.pl | flamegraph.pl > profile.svg

This works even on heavily loaded production systems because perf uses sampling, not tracing. For more details on BEAM JIT profiling, see the Erlang efficiency guide.

Memory Profiling with Observer Allocator Info

BEAM's memory management is complex - it uses multiple allocators for different data types. Observer can show you exactly where your memory is going.

In Observer: System tab → Memory Allocators

Command line version:

1> recon_alloc:memory(used).
2> recon_alloc:memory(allocated).

Look for:

• binary_alloc: Large binaries (strings, files)
• eheap_alloc: Process heaps
• ets_alloc: ETS table storage
• ll_alloc: Linked list data

If one allocator is consuming way more memory than others, that's your starting point for optimization. The recon documentation explains each allocator in detail, and the BEAM memory architecture guide provides deep insights into how BEAM manages memory internally.