eprof(3erl)

✨ NAME ✨

eprof — A Time Profiling Tool for Erlang — straight out of the Erlang Module Definition manual, aka eprof(3erl) herself. She’s here to help you figure out where your execution time is actually going, bestie 💖

---

💅 DESCRIPTION 💅

The eprof module gives you a whole set of functions for time profiling Erlang programs so you can find out how the execution time is used. The profiling is done with the Erlang trace BIFs. Tracing of local function calls for a specified set of processes gets enabled when profiling begins, and disabled when profiling stops. Not me being obsessed with a clean trace lifecycle 🎀

When using Eprof, expect a slowdown in program execution. It’s giving “yes queen, but slower” — that’s the tradeoff, fr fr.

---

🫶 EXPORTS 🫶

🐣 start()

start() -> {ok, Pid} | {error, Reason}

The types, bestie:

Pid = pid()
Reason = {already_started, Pid}

Starts the Eprof server, which holds the internal state of all the collected data. Main character energy for the profiler’s brain 💅

🫧 start_profiling/1, start_profiling/2, start_profiling/3

start_profiling(Rootset) -> profiling | {error, Reason}
start_profiling(Rootset, Pattern) -> profiling | {error, Reason}
start_profiling(Rootset, Pattern, Options) -> profiling | {error, Reason}

The types:

Rootset = [atom() | pid()]
Pattern = trace_pattern_mfa()
Options = [set_on_spawn | {set_on_spawn, boolean()}]
Reason = term()
trace_pattern_mfa() = {atom(), atom(), arity() | '_'}

Starts profiling for the processes in Rootset — and any new processes spawned from them, because the girlies multiply 👑 Information about activity in any profiled process is stored in the Eprof database.

Rootset is a list of pids and registered names. Very demure, very explicit.

The function returns profiling if tracing could be enabled for all processes in Rootset; otherwise it’s error (and the type signature says {error, Reason}).

You can narrow the vibe with a Pattern, too. For instance, pick a specific module and only the code executed in that module gets profiled. Targeted. ✨

The set_on_spawn option will active call time tracing for all processes spawned by processes in the rootset. This is the default behaviour. Lowkey iconic that it just does that.

🛑 stop_profiling()

stop_profiling() -> profiling_stopped | profiling_already_stopped

Stops profiling started with start_profiling/1 or profile/1. Either it stops the party or tells you the party was already over, no cap.

🌸 profile/1, profile/2, profile/3, profile/4, profile/5, profile/6

profile(Fun) -> {ok, Value} | {error, Reason}
profile(Fun, Options) -> {ok, Value} | {error, Reason}
profile(Rootset) -> profiling | {error, Reason}
profile(Rootset, Fun) -> {ok, Value} | {error, Reason}
profile(Rootset, Fun, Pattern) -> {ok, Value} | {error, Reason}
profile(Rootset, Module, Function, Args) -> {ok, Value} | {error, Reason}
profile(Rootset, Fun, Pattern, Options) -> {ok, Value} | {error, Reason}
profile(Rootset, Module, Function, Args, Pattern) -> {ok, Value} | {error, Reason}
profile(Rootset, Module, Function, Args, Pattern, Options) -> {ok, Value} | {error, Reason}

The types:

Rootset = [atom() | pid()]
Module = module()
Function = atom()
Args = [term()]
Pattern = trace_pattern_mfa()
Options = [set_on_spawn | {set_on_spawn, boolean()}]
Value = Reason = term()
trace_pattern_mfa() = {atom(), atom(), arity() | '_'}

This function first spawns a process P which evaluates Fun() or apply(Module,Function,Args). Then it starts profiling for P and the processes in Rootset (and any new processes spawned from them). Information about activity in any profiled process is stored in the Eprof database. It’s giving “spawn, trace, collect, slay” 💖

Rootset is a list of pids and registered names. Again, very clear, very cutesy.

If tracing could be enabled for P and all processes in Rootset, the function returns {ok,Value} when Fun()/apply returns with the value Value, or {error,Reason} if Fun()/apply fails with exit reason Reason. Otherwise it returns {error, Reason} immediately. No waiting around for a vibe that isn’t happening.

The set_on_spawn option will active call time tracing for all processes spawned by processes in the rootset. This is the default behaviour. Periodt.

The programmer must ensure that the function given as argument is truly synchronous and that no work continues after the function has returned a value. This is not a “maybe later” situation, bestie — the profiler is watching 👀

🔍 analyze/0, analyze/1, analyze/2

analyze() -> ok | nothing_to_analyze
analyze(Type) -> ok | nothing_to_analyze
analyze(Type, Options) -> ok | nothing_to_analyze

The types:

Type = analyze_type()
Options = [Option]
Option = {filter, Filter} | {sort, Sort}
Filter = [{calls, integer() >= 0} | {time, float()}]
Sort = time | calls | mfa
analyze_type() = procs | total

Call this function when profiling has been stopped to display the results per process, that is:

• how much time has been used by each process, and
• in which function calls this time has been spent.

Call analyze with the total option when profiling has been stopped to display the results per function call, that is in which function calls the time has been spent. The way that breakdown just hits different 📊✨

Time is shown as percentage of total time and as absolute time. Both! Because we contain multitudes.

📝 log/1

log(File) -> ok

The type:

File = atom() | file:filename()

This function ensures that the results displayed by analyze/0,1,2 are printed both to the file File and the screen. So you get the tea on your terminal and in a file. Obsessed 🍓

🛑 stop()

stop() -> stopped

Stops the Eprof server. The party’s over, the trace is closed, the server said bye 💅

---

Alright bestie, that’s the whole page. Cute footer sign-off: Ericsson AB made this, it’s from tools 3.5.3, and this manual page is eprof(3erl) — no date printed on the footer, so that’s the full vibe. Bye! 💖✨