Chapter 17 Profiling (ocamlprof)

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

17.1 Compiling for profiling

Before profiling an execution, the program must be compiled inprofiling mode, using the ocamlcp front-end to the ocamlc compiler(see chapter 9) or the ocamloptp front-end to theocamlopt compiler (see chapter 12). When compilingmodules separately, ocamlcp or ocamloptp must be used whencompiling the modules (production of .cmo or .cmx files), and canalso be used (though this is not strictly necessary) when linking themtogether.

Note

If a module (.ml file) doesn’t have a correspondinginterface (.mli file), then compiling it with ocamlcp will produceobject files (.cmi and .cmo) that are not compatible with the onesproduced by ocamlc, which may lead to problems (if the .cmi or.cmo is still around) when switching between profiling andnon-profiling compilations. To avoid this problem, you should alwayshave a .mli file for each .ml file. The same problem exists withocamloptp.

Note

To make sure your programs can be compiled inprofiling mode, avoid using any identifier that begins with__ocaml_prof.

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

  • a
  • all options
  • f
  • function calls : a count point is set at the beginning ofeach function body
  • i
  • if …then …else … : count points are set inboth then branch and else branch
  • l
  • while, for loops: a count point is set at the beginning ofthe loop body
  • m
  • match branches: a count point is set at the beginning of thebody of each branch
  • t
  • try …with … branches: a count point is set at thebeginning of the body of each branchFor 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 areprofiled.

Note

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

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

17.2 Profiling an execution

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

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

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

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

17.3 Printing profiling information

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

  1.         ocamlprof foo.ml

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

The following options are recognized by ocamlprof:

  • -argsfilename
  • Read additional newline-terminated command line arguments from filename.
  • -args0filename
  • Read additional null character terminated command line arguments from filename.
  • -fdumpfile
  • Specifies an alternate dump file of profiling information to be read.
  • -Fstring
  • 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 profilingpoint. With option -F s, the annotation will be( sn ).
  • -implfilename
  • Process the file filename as an implementation file, even if itsextension is not .ml.
  • -intffilename
  • Process the file filename as an interface file, even if itsextension 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.

17.4 Time profiling

Profiling with ocamlprof only records execution counts, not the actualtime spent within each function. There is currently no way to performtime profiling on bytecode programs generated by ocamlc.

Native-code programs generated by ocamlopt can be profiled for timeand execution counts using the -p option and the standard Unixprofiler gprof. Just add the -p option when compiling and linkingthe program:

  1.         ocamlopt -o myprog -p other-options files
  2.         ./myprog
  3.         gprof myprog

OCaml function names in the output of gprof have the following format:

  1.         Module-name_function-name_unique-number

Other functions shown are either parts of the OCaml run-time system orexternal C functions linked with the program.

The output of gprof is described in the Unix manual page forgprof(1). It generally consists of two parts: a “flat” profileshowing the time spent in each function and the number of invocationof each function, and a “hierarchical” profile based on the callgraph. Currently, only the Intel x86 ports of ocamlopt underLinux, BSD and MacOS X support the two profiles. On other platforms,gprof will report only the “flat” profile with just timeinformation. When reading the output of gprof, keep in mind thatthe accumulated times computed by gprof are based on heuristics andmay not be exact.

Note

The ocamloptp command also accepts the -poption. In that case, both kinds of profiling are performed by theprogram, and you can display the results with the gprof and ocamlprofcommands, respectively.