---
title: MNE Tracer
sidebar_label: MNE Tracer
---

# MNE Tracer

> *It is very hard to improve what you cannot measure.*

During development it is common to have to decide between two (or more) different but equivalent implementations. We value improving code maintainability and coherence on top of achieving efficient implementations. But it is not uncommon to find situations where two solutions seem equally valid. Being able to understand the performance implications of each option helps make informed decisions and learn through the process. MNE Tracer was designed for exactly these situations — it is a code tracing tool that records when specified methods are executed.

MNE Tracer writes a JSON file where each traced function call is recorded as an event. The format is compatible with Google Chrome’s built-in tracer (`chrome://tracing`) and with QtCreator’s tracer plugin. To visualize your trace, open Chrome, navigate to `chrome://tracing`, and load the generated JSON file.

![](/img/mnetracer/tracer_example.png)

## Adding MNE Tracer to Your Code

There are three steps to integrate MNE Tracer:

1. **Link the Utils library.** The tracing functionality lives in the Utils library (`src/libraries/utils`). If you are using the standard MNE-CPP build setup, Utils is linked by default. Verify that it is listed in your target’s `CMakeLists.txt`.

2. **Define the `TRACE` macro.** You can do this by passing `-DTRACE=ON` to CMake or by adding `#define TRACE` before including the MNE Tracer header:

```bash
cmake -B build -S . -DTRACE=ON
```

3. **Include the header.** Add `#include <utils/mnetracer.h>` to the files you want to trace. A convenient approach is to include it in your project’s `*_global.h` header, which is typically included by every source file in the project.

With the Utils library linked, the `TRACE` macro defined, and the header included, MNE Tracer is ready to use.
## Using MNE Tracer

### Enabling and Disabling the Tracer

Before recording any function calls, initialize the tracer output file with `MNE_TRACER_ENABLE(filename.json)`. The file name can describe the particular test you are running. The file is saved in the same directory as your application binary.

After this call, every function marked as traceable will be recorded. When you are done tracing, close and finalize the output file with `MNE_TRACER_DISABLE`. No tracing occurs after this point.

For example, in an application’s `main()` function:

```cpp
int main(int argc, char *argv[])
{
    MNE_TRACER_ENABLE(filename.json)

    //... your application starts here
    //... you can trace specific function calls 
    //... at this point by adding the
    //... macro MNE_TRACE() to your code.

    MNE_TRACER_DISABLE

    return returnValue;
}
```

### Specifying Which Functions to Trace

In a typical C++ application, many generic function calls occur to execute a specific piece of code. To focus on only the functions you care about, add the `MNE_TRACE()` macro as the first line after the opening brace of each function you want to trace:

```cpp
void ImportantClass::importantMethod(int a)
{
    MNE_TRACE()
    //...the method continues here
    //...
}
```
### Automatically Tracing All Methods in a Class

If you want to trace every method in a class without manually adding `MNE_TRACE()` to each one, use the provided Python helper script at `tools/mnetracer.py`:

- **Add** the `MNE_TRACE()` macro to every method:

```bash
python tools/mnetracer.py file=<yourfile.cpp> mode=add
```

- **Remove** only the automatically added macros (manually placed `MNE_TRACE()` calls are preserved):

```bash
python tools/mnetracer.py file=<yourfile.cpp> mode=delete
```

- **Remove all** `MNE_TRACE()` occurrences, including manually placed ones:

```bash
python tools/mnetracer.py file=<yourfile.cpp> mode=deleteAll
```
