• Batch compilation (ocamlc)
• The toplevel system or REPL (ocaml)
• The runtime system (ocamlrun)
• Native-code compilation (ocamlopt)
• Lexer and parser generators (ocamllex, ocamlyacc)
• Dependency generator (ocamldep)
• The browser/editor (ocamlbrowser)
• The documentation generator (ocamldoc)
• The debugger (ocamldebug)
• Profiling (ocamlprof)
• The ocamlbuild compilation manager
• Interfacing C with OCaml
• Optimisation with Flambda
• Memory profiling with Spacetime
• Fuzzing with afl-fuzz

Chapter 18  Profiling (ocamlprof)

This chapter describes how the execution of OCaml programs can be profiled, by recording how many times functions are called, branches of conditionals are taken, …

1  Compiling for profiling

Before profiling an execution, the program must be compiled in profiling mode, using the ocamlcp front-end to the ocamlc compiler (see chapter 9) or the ocamloptp front-end to the ocamlopt compiler (see chapter 12). When compiling modules separately, ocamlcp or ocamloptp must be used when compiling the modules (production of .cmo or .cmx files), and can also be used (though this is not strictly necessary) when linking them together.

Note

If a module (.ml file) doesn’t have a corresponding interface (.mli file), then compiling it with ocamlcp will produce object files (.cmi and .cmo) that are not compatible with the ones produced by ocamlc, which may lead to problems (if the .cmi or .cmo is still around) when switching between profiling and non-profiling compilations. To avoid this problem, you should always have a .mli file for each .ml file. The same problem exists with ocamloptp.

Note

To make sure your programs can be compiled in profiling mode, avoid using any identifier that begins with __ocaml_prof.

The amount of profiling information can be controlled through the -P option to ocamlcp or ocamloptp, followed by one or several letters indicating which parts of the program should be profiled:

a

all options

f

function calls : a count point is set at the beginning of each function body

i

if …then …else … : count points are set in both then branch and else branch

l

while, for loops: a count point is set at the beginning of the loop body

m

match branches: a count point is set at the beginning of the body of each branch

t

try …with … branches: a count point is set at the beginning of the body of each branch

For instance, compiling with ocamlcp -P film profiles function calls, if…then…else…, loops and pattern matching.

Calling ocamlcp or ocamloptp without the -P option defaults to -P fm, meaning that only function calls and pattern matching are profiled.

Note

For compatibility with previous releases, ocamlcp also accepts the -p option, with the same arguments and behaviour as -P.

The ocamlcp and ocamloptp commands also accept all the options of the corresponding ocamlc or ocamlopt compiler, except the -pp (preprocessing) option.

2  Profiling an execution

Running an executable that has been compiled with ocamlcp or ocamloptp records the execution counts for the specified parts of the program and saves them in a file called ocamlprof.dump in the current directory.

If the environment variable OCAMLPROF_DUMP is set when the program exits, its value is used as the file name instead of ocamlprof.dump.

The dump file is written only if the program terminates normally (by calling exit or by falling through). It is not written if the program terminates with an uncaught exception.

If a compatible dump file already exists in the current directory, then the profiling information is accumulated in this dump file. This allows, for instance, the profiling of several executions of a program on different inputs. Note that dump files produced by byte-code executables (compiled with ocamlcp) are compatible with the dump files produced by native executables (compiled with ocamloptp).

3  Printing profiling information

The ocamlprof command produces a source listing of the program modules where execution counts have been inserted as comments. For instance,

        ocamlprof foo.ml

prints the source code for the foo module, with comments indicating how many times the functions in this module have been called. Naturally, this information is accurate only if the source file has not been modified after it was compiled.

The following options are recognized by ocamlprof:

-args filename

Read additional newline-terminated command line arguments from filename.

-args0 filename

Read additional null character terminated command line arguments from filename.

-f dumpfile

Specifies an alternate dump file of profiling information to be read.

-F string

Specifies an additional string to be output with profiling information. By default, ocamlprof will annotate programs with comments of the form (* n *) where n is the counter value for a profiling point. With option -F s, the annotation will be (* sn *).

-impl filename

Process the file filename as an implementation file, even if its extension is not .ml.

-intf filename

Process the file filename as an interface file, even if its extension is not .mli.

-version

Print version string and exit.

-vnum

Print short version number and exit.

-help or --help

Display a short usage summary and exit.

4  Time profiling

Profiling with ocamlprof only records execution counts, not the actual time spent within each function. There is currently no way to perform time profiling on bytecode programs generated by ocamlc. For time profiling of native code, users are recommended to use standard tools such as perf (on Linux), Instruments (on macOS) and DTrace. Profiling with gprof is no longer supported.