---
description: Profiling and debugging memory usage in Reth.
---

# Profiling Reth

## Memory profiling

When a program consumes all of the system's available memory (and swap, if any), the OOM killer starts killing processes that are taking up the most memory, until the system has
memory available again. [See kernel.org for a great (although outdated) introduction to out-of-memory management.](https://www.kernel.org/doc/gorman/html/understand/understand016.html).
Reth distributes to many different hardware targets, some with less memory than others. As a result, sometimes bugs can cause memory leaks or out-of-memory crashes for _some_ users, but not others.
Reth is also a complex program, with many moving pieces, and it can be difficult to know where to start when debugging an OOM or other memory leak.
Understanding how to profile memory usage is an extremely valuable skill when faced with this type of problem, and can quickly help shed light on the root cause of a memory leak.

In this tutorial, we will be reviewing:

-   How to monitor reth's memory usage,
-   How to emulate a low-memory environment to lab-reproduce OOM crashes,
-   How to enable `jemalloc` and its built-in memory profiling, and
-   How to use `jeprof` to interpret heap profiles and identify potential root causes for a memory leak.

### Jemalloc

[Jemalloc](https://jemalloc.net/) is a general-purpose allocator that is used [across the industry in production](https://engineering.fb.com/2011/01/03/core-data/scalable-memory-allocation-using-jemalloc/), well known for its performance benefits, predictability, and profiling capabilities.
We've seen significant performance benefits in reth when using jemalloc, but will be primarily focusing on its profiling capabilities.
Jemalloc also provides tools for analyzing and visualizing its allocation profiles it generates, notably `jeprof`.

#### Enabling jemalloc in reth

Reth includes a `jemalloc` feature to explicitly use jemalloc instead of the system allocator:

```
cargo build --features jemalloc
```

While the `jemalloc` feature does enable jemalloc, reth has an additional feature, `jemalloc-prof`, that must be used to enable heap profiling. This feature implicitly enables the `jemalloc`
feature as well:

```
cargo build --features jemalloc-prof
```

When performing a longer-running or performance-sensitive task with reth, such as a sync test or load benchmark, it's usually recommended to use the `maxperf` profile. However, the `maxperf`
profile does not enable debug symbols, which are required for tools like `perf` and `jemalloc` to produce results that a human can interpret. Reth includes a performance profile with debug symbols called `profiling`. To compile reth with debug symbols, jemalloc, profiling, and a performance profile:

```
cargo build --features jemalloc-prof --profile profiling

# May improve performance even more
RUSTFLAGS="-C target-cpu=native" cargo build --features jemalloc-prof --profile profiling
```

### Monitoring memory usage

Reth's dashboard has a few metrics that are important when monitoring memory usage. The **Jemalloc memory** graph shows reth's memory usage. The _allocated_ label shows the memory used by the reth process which cannot be reclaimed unless reth frees that memory. This metric exceeding the available system memory would cause reth to be killed by the OOM killer.

<img
    width="749"
    alt="Jemalloc memory"
    src="https://github.com/paradigmxyz/reth/assets/6798349/2653c5a2-bd7c-46a6-a593-23809389628e"
></img>

Some of reth's internal components also have metrics for the memory usage of certain data structures, usually data structures that are likely to contain many elements or may consume a lot of memory at peak load.

**The bodies downloader buffer**:

<img
    width="749"
    alt="The bodies downloader buffer graph"
    src="https://github.com/paradigmxyz/reth/assets/6798349/75383724-24ae-4f4f-98a9-72d01731a5f9"
></img>

**The blockchain tree block buffer**:

<img
    width="749"
    alt="The blockchain tree block buffer graph"
    src="https://github.com/paradigmxyz/reth/assets/6798349/7162c6d4-ed18-48c1-a327-50a245dabc95"
></img>

**The transaction pool subpools**:

<img
    width="749"
    alt="The transaction pool subpool size graph"
    src="https://github.com/paradigmxyz/reth/assets/6798349/c5066fd6-7ff7-4e62-9226-89327c7a802c"
></img>

One of these metrics growing beyond, 2GB for example, is likely a bug and could lead to an OOM on a low memory machine. It isn't likely for that to happen frequently, so in the best case these metrics can be used to
rule out these components from having a leak, if an OOM is occurring.

### Limiting process memory

Memory leaks that cause OOMs can be difficult to trigger sometimes, and highly depend on the testing hardware. A testing machine with 128GB of RAM is not going to encounter OOMs caused by
memory spikes or leaks as often as a machine with only 8GB of RAM. Development machines are powerful for a reason, so artificially limiting memory usage is often the best way to replicate a
user's hardware. This can help developers debug issues that only occur on devices with limited hardware. `cgroups` is a tool that allows developers to limit the memory usage of a process,
making it extremely useful to developers in understanding how their application performs in low-memory environments.

See the [canonical documentation for cgroups](https://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup.git/tree/Documentation/admin-guide/cgroup-v2.rst) for more information.

### How to use cgroups to limit process memory

In order to use cgroups to limit process memory, sometimes it must be explicitly enabled as a kernel parameter. For example, the following line is sometimes necessary to enable cgroup memory limits on
Ubuntu machines that use GRUB:

```
GRUB_CMDLINE_LINUX_DEFAULT="cgroup_enable=memory"
```

Then, create a named cgroup:

```
sudo cgcreate -t $USER:$USER -a $USER:$USER -g memory:rethMemory
```

The memory limit for the named cgroup can be set in `sys/fs/cgroup/memory`. This for example sets an 8 gigabyte memory limit:

```
echo 8G > /sys/fs/cgroup/memory/rethMemory/memory.limit_in_bytes
```

If the intention of setting up the cgroup is to strictly limit memory and simulate OOMs, a high amount of swap may prevent those OOMs from happening.
To check swap, use `free -m`:

```
ubuntu@bench-box:~/reth$ free -m
              total        used        free      shared  buff/cache   available
Mem:         257668       10695      218760          12       28213      244761
Swap:          8191         159        8032
```

If this is a problem, it may be worth either adjusting the system swappiness or disabling swap overall.

Finally, `cgexec` can be used to run reth under the cgroup:

```
cgexec -g memory:rethMemory reth node
```

### Understanding allocation with jeprof

When reth is built with the `jemalloc-prof` feature, profiling is already enabled at compile time — the binary embeds `prof:true,prof_active:true,lg_prof_sample:19` via a `malloc_conf` static. No environment variable is needed to turn on profiling.

To configure additional options like `lg_prof_interval` at runtime, use the `MALLOC_CONF` environment variable:

```
MALLOC_CONF=lg_prof_interval:32 reth node
```

If you see errors like this:

```
<jemalloc>: Invalid conf pair: prof:true
```

It means reth was not built with the `jemalloc-prof` feature, so jemalloc does not have profiling support compiled in. Rebuild with:

```
cargo build --features jemalloc-prof
```

If everything is working, this will output `jeprof.*.heap` files while reth is running.
[The jemalloc website](https://jemalloc.net/jemalloc.3.html#opt.abort) has a helpful overview of the options available, for example `lg_prof_interval`, `lg_prof_sample`, `prof_leak`, and `prof_final`.

Now that we have the heap snapshots, we can analyze them using `jeprof`. An example of jeprof usage and output can be seen on the jemalloc github repository: https://github.com/jemalloc/jemalloc/wiki/Use-Case:-Leak-Checking

### HTTP pprof endpoint

When built with the `jemalloc-prof` feature, reth exposes a heap profiling endpoint on the metrics server (default port 9001) at `/debug/pprof/heap`. This endpoint returns heap profiles in [pprof format](https://github.com/google/pprof), which is compatible with the standard `pprof` toolchain.

By default, the pprof output contains raw addresses that require external symbolization. You need either `addr2line` or `llvm-addr2line` in your PATH for `pprof` to resolve function names.

For pre-symbolized profiles (useful on macOS or when external tools are unavailable), build with the `jemalloc-symbols` feature:
```
cargo build --features jemalloc-prof,jemalloc-symbols --profile profiling
```
