<commit_before>MemTrace
========

MemTrace is a memory debugging tool developed internally at Insomniac Games.
It has been used in production at the studio since 2014 and is now relatively
stable.

Features
--------

- Lightweight C++ runtime component with network recording
- CRT heap hooking on Windows (Durango hooking available on request to licensed devs)
- Full support for custom heaps and allocators
- Supports displaying and analyzing fragmentation for custom heaps
- Can display a delta between two arbitrary points in time.
- Can aggregate memory data along several axes, including custom scopes
- Supports asset and component memory scoping out of the box, but can be
  extended in source to group on arbitrary scopes
- Supports forward and backward scrubbing in trace files during analysis

Using the Tool
--------------

The GUI tool uses memory mapped files and is capable of analyzing very
large trace files (larger than available memory). For best results you should
run it on a 64-bit version of Windows. The tool is based on stream replaying,
quickly moving back and forth between points in time to present a snapshot of
what memory looked like at that exact time. User marks can be used to name a
particular point in time, but you can also jump to an arbitrary point in time
by simply entering a time in seconds.

Captured trace files are standalone (after symbol resolving) and can be sent
off to someone else for analysis without access to the client program or its
symbol data. This also means you can archive them for future reference to see
how a program's behavior has evolved over time. To load a received trace file
simply copy it in to your configured trace directory and it will appear in the
UI for selection.

### Capturing Trace Files ###

Upon starting the tool, it will accept incoming connections and start recording
data. The main window shows statistics about the trace files being recorded.

There is no limit to the number of files that can be concurrently recorded.
You may record and analyze traces at the same time if desired.

A trace may be stopped from the UI by right clicking it and selecting "Stop".

Traces are named automatically, but may be renamed by double clicking the
filename (or hitting F2) and typing in a replacement name.

Marks may be inserted into a running trace by right-clicking the trace file and
selecting "User Trace Mark". This is useful in cases where the client doesn't
have a UI or other logic that allows you to set a trace mark in some other way.
Marks created in this way will be named "UI Mark N", so they're not super
descriptive, but nevertheless useful.

### Resolving Symbols ###

![Symbol Resolver](docs/symbolresolve.png "Symbol resolving dialog")<commit_msg>Add missing main window screenshow.<commit_after>MemTrace
========

MemTrace is a memory debugging tool developed internally at Insomniac Games.
It has been used in production at the studio since 2014 and is now relatively
stable.

Features
--------

- Lightweight C++ runtime component with network recording
- CRT heap hooking on Windows (Durango hooking available on request to licensed devs)
- Full support for custom heaps and allocators
- Supports displaying and analyzing fragmentation for custom heaps
- Can display a delta between two arbitrary points in time.
- Can aggregate memory data along several axes, including custom scopes
- Supports asset and component memory scoping out of the box, but can be
  extended in source to group on arbitrary scopes
- Supports forward and backward scrubbing in trace files during analysis

Using the Tool
--------------

The GUI tool uses memory mapped files and is capable of analyzing very
large trace files (larger than available memory). For best results you should
run it on a 64-bit version of Windows. The tool is based on stream replaying,
quickly moving back and forth between points in time to present a snapshot of
what memory looked like at that exact time. User marks can be used to name a
particular point in time, but you can also jump to an arbitrary point in time
by simply entering a time in seconds.

Captured trace files are standalone (after symbol resolving) and can be sent
off to someone else for analysis without access to the client program or its
symbol data. This also means you can archive them for future reference to see
how a program's behavior has evolved over time. To load a received trace file
simply copy it in to your configured trace directory and it will appear in the
UI for selection.

### Capturing Trace Files ###

Upon starting the tool, it will accept incoming connections and start recording
data. The main window shows statistics about the trace files being recorded.

![Main Window](docs/mainwindow.png "Main Window")

There is no limit to the number of files that can be concurrently recorded.
You may record and analyze traces at the same time if desired.

A trace may be stopped from the UI by right clicking it and selecting "Stop".

Traces are named automatically, but may be renamed by double clicking the
filename (or hitting F2) and typing in a replacement name.

Marks may be inserted into a running trace by right-clicking the trace file and
selecting "User Trace Mark". This is useful in cases where the client doesn't
have a UI or other logic that allows you to set a trace mark in some other way.
Marks created in this way will be named "UI Mark N", so they're not super
descriptive, but nevertheless useful.

### Resolving Symbols ###

![Symbol Resolver](docs/symbolresolve.png "Symbol resolving dialog")
{'fraction_non_alphanumeric': 0.041374347904299336, 'fraction_numerical': 0.0025184385680877856, 'mean_word_length': 4.220657276995305, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4343307', 'n_tokens_mistral': 1312, 'n_tokens_neox': 1259, 'n_words': 893}