General instrumentation framework

[ghost]

This RFC generalises the support for bisect_ppx to allow Dune to support other instrumentation tools such as landmarks. With this proposal, Dune will no longer have specific knowledge of bisect_ppx and will instead offer a more general and open instrumentation framework.

The usability of the system will also be improved. Indeed, it will become possible to enable instrumentation via the command line directly.

Declaring an instrumentation backend

Instrumentation backends are OCaml libraries with the special field (instrumentation.backend). This field instructs Dune that the library can be used as an intrumentation backend and also provides the parameters that are specific to this backend.

Initially, Dune will only support ppx instrumentation tools, and the instrumentation library must specify the ppx rewriters that instruments the code. This will is as follow:

(library
 (name ...)
 ...
 (instrumentation.backend
  (ppx <ppx-rewriter-name>)))

For instance:

(library
 (name bisect_ppx)
 (instrumentation.backend
  (ppx bisect_ppx)))

(library
 (name landmarks)
 (instrumentation.backend
  (ppx landmarks.ppx)))

When such an instrumentation backend is activated, Dune will implicitly add the mentioned ppx rewriter to the list of ppx rewriters for libraries and executables that support this instrumentation backend.

Marking code that should be instrumented

When an instrumentation backend is activated, Dune will only instrument libraries and executables for which the user has requested instrumentation.

To request instrumentation, one must add the following field to a library or executable stanza:

(library
 (name ...)
 (instrumentation
  (backend <name>)))

This field can be repeated multiple times in order to support various backends. For instance:

(library
 (name foo)
 (instrumentation
  (backend bisect_ppx))
 (instrumentation
  (backend landmarks)))

This will instruct Dune that when either the bisect_ppx or landmarks instrumentation is activated, the library should be instrumented with this backend.

By default, these fields are simply ignored. However, when the corresponding instrumentation backend is activated, Dune will implicitly add the relevant ppx rewriter to the list of ppx rewriters.

At the moment, it is not possible to instrument code that is preprocessed via an action preprocessors. These preprocessors are quite rare now, so it doesn't seem too bad.

Activating an instrumentation backend

Activating an instrumentation backend can be done via the command line or the dune-workspace file.

Via the command line:

$ dune build --instrument-with <name>

For instance:

$ dune build --instrument-with bisect_ppx
$ dune build --instrument-with landmarks

This will instruct Dune to activate the given backend globally, i.e. in all defined build contexts.

It is also possible to do it via the dune-workspace file, either globally:

(lang dune 2.7)
(instrument_with bisect_ppx)

or for each context individually:

(lang dune 2.7)
(context default)
(context (default (name coverage) (instrument_with bisect_ppx)))
(context (default (name profiling) (instrument_with landmarks)))

If both the global and local fields are present, the precedence is the same as for the profile field:

• the local field as precedence over the command line flag
• the command line flag has precedence over the global field

[nojb]

Do I understand well that the instrumentation.backend field in library exists solely to make the association between the names of the library and that of the ppx rewriter? Does the library itself play any role otherwise?

[ghost]

@nojb that's right. And it is also to get a better error message if we pass a library that is not meant to be used for instrumentation.

FTR, we do something very similar for inline tests.

[nojb]

When a library or an executable declares that it wants to use and instrumentation with (instrumentation (backend <lib>)), shouldn't we automatically add <lib> to the list of library dependencies? It seems a bit strange to go through the trouble of making the association between the library name and the ppx rewriter explicit in the syntax and then to still require the user to manually add the library to the set of dependencies.

On the other hand, I wonder if it is the case that adding the instrumentation library to the set of dependencies of the buildable being instrumented is always the right thing to do.

[nojb]

When a library or an executable declares that it wants to use and instrumentation with (instrumentation (backend <lib>)), shouldn't we automatically add <lib> to the list of library dependencies?

Answering to myself: this is already handled by the ppx_runtime_libraries field, but it wasn't being set by landmarks.

[ghost]

Indeed, I did wondered about this myself when writing the proposal and came to the same conclusion.

[rgrinberg]

This was done in 2.7