trace.h

The Emscripten tracing API provides some useful capabilities to better see what is going on inside of your application, in particular with respect to memory usage (which is otherwise not available to traditional browser performance tools).

The tracing API can talk to a custom collection server (see Running the Server for more details) or it can talk with the Google Web Tracing Framework. When talking with the Google Web Tracing Framework, a subset of the data available is collected.

Usage 

Compiler Interaction 

When using the tracing API, you should pass --tracing to emcc at each compile and link stage. This will automatically include the library_trace.js library file as well as set the preprocessor flag __EMSCRIPTEN_TRACING__. If you are invoking clang directly to build your C / C++ code, then you will want to pass -D__EMSCRIPTEN_TRACING__ when building code. When the preprocessor flag __EMSCRIPTEN_TRACING__ is not defined, the tracing API implementation will be provided by inlined empty stubs.

Also, since enabling tracing modifies the implementation of dlmalloc.c in the libc implementation, it is advised that you manually clear your cache before switching to using the tracing API. If you do not do this, then you will not get full allocation details recorded. You can clear the cache with this emcc command:

emcc --clear-cache

Initialization and Teardown 

To initialize the tracing API, you call emscripten_trace_configure():

emscripten_trace_configure("http://127.0.0.1:5000/", "MyApplication");

If you are simply going to use the tracing API with the Google Web Tracing Framework, then you can just call emscripten_trace_configure_for_google_wtf() instead:

emscripten_trace_configure_for_google_wtf();

If you have the concept of a username or have some other way to identify a given user of the application, then passing that to the tracing API can make it easier to identify sessions in the collector server:

emscripten_trace_set_session_username(username);

To shut it down at application exit, you simply call emscripten_trace_close():

emscripten_trace_close();

Contexts 

Contexts are a way to tell the tracing API what part of your application is currently running. Contexts are effectively maintained as a stack of current contexts.

A context might be something as big as “running physics” or as small as “updating animations on entity X”.

The granularity of the context stack is up to the team instrumenting their application. Some applications may find fine-grained contexts more useful, while others are more comfortable with larger contexts.

Rather than getting a stack trace on every tracing call, we can often look at the current context stack and record that instead, which is much cheaper.

When contexts are fully implemented by the server, they will also be used to track how much time is spent in each context (a primitive profiling mechanism), as well as how much memory has been allocated and freed while the context was active. This should help give a good idea of which parts of your application are using more memory or creating a lot of churn (and possibly heap fragmentation).

Recording context entry and exit is simple:

emscripten_trace_enter_context("Physics Update");
...
emscripten_trace_exit_context();

Frames 

It is important to record where your frame or event loop begins and ends. This allows the tracing API to perform useful additional analysis.

Noting the start of an event loop is as easy as:

emscripten_trace_record_frame_start();

And noting the end of the event loop is just as easy:

emscripten_trace_record_frame_end();

Annotating Allocations 

Each allocation and free operation should be recorded. Ideally, the data type name will also be recorded, but this must currently be done manually.

When building with --tracing and a cleared cache, the libc that Emscripten builds will automatically record all calls to malloc, realloc and free.

As for recording the data type name, after you’ve allocated the memory, you can annotate the address:

emscripten_trace_annotate_address_type(model, "UI::Model");

Additionally, some applications may want to associate the size of additional storage with an allocation. This can be done via emscripten_trace_associate_storage_size():

emscripten_trace_associate_storage_size(mesh, mesh->GetTotalMemoryUsage());

Overall Memory Usage 

Periodically, the overall heap layout and memory usage should be reported to the trace API.

This is done with 2 calls:

emscripten_trace_report_memory_layout();
emscripten_trace_report_off_heap_data();

Logging Messages 

Messages can be logged and recorded via the Emscripten tracing API. These messages can have both a channel and the actual message. The channel name will help to categorize and filter messages within the visualization interface. You should avoid allocating memory on the heap while logging a message.

emscripten_trace_log_message("Application", "Started");

Over time, the visualization interface will improve to help you better correlate these log messages with other views, such as memory usage over time. Logging messages for things that may cause large amounts of memory activity, like loading a new model or game asset, is very useful when analyzing memory usage behavior patterns.

Tasks 

Specific tasks can be recorded and analyzed. A task is typically a unit of work that is not repeating. It may be suspended or blocked due to having portions performed asynchronously.

An example of a task is loading an asset which usually involves chains of callbacks.

The application should keep track of task IDs (integers) and ensure that they are unique.

The task ID need not be passed to every trace call involving tasks as most calls operate on the current task.

Tasks can be started and stopped with:

emscripten_trace_task_start(taskID, name);
emscripten_trace_task_end();

If a task is suspended / blocked, this can be noted via:

emscripten_trace_task_suspend("loading via HTTP");

And when it is resumed:

emscripten_trace_task_resume(taskID, "parsing");

It is common to need to associate additional data with the current task for use when examining task data later. An example of this would be the URL of an asset that was loaded:

emscripten_trace_task_associate_data("url", url);

Reporting Errors 

Errors encountered by the application can be reported to the tracing API as an ancillary service:

emscripten_trace_report_error("Assertion failed: ...");

This feature is included as an indication of the future direction of the Emscripten tracing API.

Running the Server 

Obtain a copy of the emscripten-trace-collector server.
Follow the directions in the README.rst.

Design Notes 

Client / Server Design 

The Emscripten tracing API gathers data from instrumented code and transmits it to a collector server. The server also performs data analysis and provides a web interface for viewing the collected data.

This client / server design is intended to allow the tool to run without interfering with the browser on lower-end hardware where memory might be at a premium, like 32 bit Windows machines.

This design also allows for a single server to be run to collect data from a variety of clients.

Data Batching 

Data is batched and sent to the server in chunks, roughly once or twice per second. This avoids having to open a new connection to the server for every single event being recorded.

Do Not Perturb The Heap 

When using the Emscripten tracing API, you should be careful that you do not perform operations that would perturb the heap. For example, you shouldn’t allocate a string to pass to emscripten_trace_log_message() as that would result in the allocation being tracked and possibly disturbing the behavior or results that you are trying to analyze.

For this reason, the Emscripten tracing API also keeps all of its own data off of the Emscripten heap and performs no writes to the Emscripten heap.

Functions 

void emscripten_trace_configure(const char *collector_url, const char *application)

Parameters:

collector_url (const char*) – The base URL for the collector server.
application (const char*) – The name of the application being traced.

Return type:

void

Configure the connection to the collector server.

This should be one of the very first things that is done after the application has started.

In most cases, the collector_url will be http://127.0.0.1:5000/.

void emscripten_trace_configure_for_google_wtf(void)

Return type:: void

Configure tracing to communicate with the Google Web Tracing Framework.

Not all features of the tracing are available within the Google WTF tools. (Currently, only contexts, log messages and marks.)

void emscripten_trace_set_enabled(bool enabled)

Parameters:

enabled (bool) – Whether or not tracing is enabled.

Return type:

void

Set whether or not tracing is enabled. Using this option to disable tracing will likely result in inaccurate data being collected about memory usage.

void emscripten_trace_set_session_username(const char *username)

Parameters:

username (const char*) – The username of the person running the application.

Return type:

void

This is useful when a collector server is being used by multiple people and you want to be able to identify individual sessions by a means other than their timestamped session ID.

This can be set after tracing has already started, so it is fine to set this after the user has gone through a login or authentication process.

void emscripten_trace_record_frame_start(void)

Return type:: void

This should be called at the start of the frame / event loop.

The current timestamp is associated with this data.

The server uses this to track frame times (and therefore frames per second), as well as accounting for memory operations that happen during the frame processing.

void emscripten_trace_record_frame_end(void)

Return type:: void

This should be called at the end of the frame / event loop.

The current timestamp is associated with this data.

The server uses this to stop accruing memory operations and elapsed time to the frame.

void emscripten_trace_log_message(const char *channel, const char *message)

Parameters:

channel (const char*) – The category of the timeline event being emitted.
message (const char*) – The description for the timeline event being emitted.

Return type:

void

Record a log message. This is useful for noting events or actions which have occurred which might be advantageous to have correlated against memory usage or changes in frame rate.

The current timestamp is associated with this data.

The server doesn’t yet do enough with this data. This will improve in the future.

void emscripten_trace_mark(const char *message)

Parameters:

message (const char*) – The name of the mark begin emitted.

Return type:

void

Record a mark in the timeline. This is primary for use with the Google Web Tracing Framework.

The current timestamp is associated with this data.

void emscripten_trace_report_error(const char *error)

Parameters:

error (const char*) – The error message being reported.

Return type:

void

The API will obtain the current callstack and include that in the report to the server.

The current timestamp is associated with this data.

This could be used for various things including capturing JavaScript and web-worker errors, as well as failed assertions or other run-time errors from within the C/C++ code.

void emscripten_trace_record_allocation(const void *address, int32_t size)

Parameters:

address (const void*) – Memory address which has been allocated.
size (int32_t) – Size of the memory block allocated.

Return type:

void

This must be called for each and every memory allocation. The best place to do this is within the dlmalloc implementation in Emscripten.

The current timestamp is associated with this data.

void emscripten_trace_record_reallocation(const void *old_address, const void *new_address, int32_t size)

Parameters:

old_address (const void*) – Old address of the memory block which has been reallocated.
new_address (const void*) – New address of the memory block which has been reallocated.
size (int32_t) – New size of the memory block reallocated.

Return type:

void

This must be called for each and every memory re-allocation. The best place to do this is within the dlmalloc implementation in Emscripten.

The current timestamp is associated with this data.

void emscripten_trace_record_free(const void *address)

Parameters:

address (const void*) – Memory address which is being freed.

Return type:

void

This must be called for each and every free operation. The best place to do this is within the dlmalloc implementation in Emscripten.

The current timestamp is associated with this data.

It is also important that this not be called multiple times for a single free operation.

void emscripten_trace_annotate_address_type(const void *address, const char *type)

Parameters:

address (const void*) – Memory address which should be annotated.
type (const char*) – The name of the data type being allocated.

Return type:

void

Annotate an address with the name of the data type that is stored there. This is used by the server to help breakdown what is in memory.

void emscripten_trace_associate_storage_size(const void *address, int32_t size)

Parameters:

address (const void*) – Memory address which should be annotated.
size (int32_t) – Size of the memory associated with this allocation.

Return type:

void

Associate an amount of additional storage with this address. This does not represent the size of the allocation itself, but rather associated memory that should be taken into account when looking at the size of this object.

This associated storage is application specific in nature.

An example is when an object contains a vector or string, you may want to be aware of that when analyzing memory usage and this provides a way to let the server be aware of that additional storage.

void emscripten_trace_report_memory_layout(void)

Return type:: void

This should be called periodically to report the usage of the normal Emscripten heap. This provides details of both the stack and the dynamic memory usage as well as the total memory size.

The current timestamp is associated with this data.

void emscripten_trace_report_off_heap_data(void)

Return type:: void

This should be called periodically to report memory usage that is not part of the normal Emscripten heap. This is currently used to report OpenAL memory usage.

The current timestamp is associated with this data.

The server does not yet display this data.

void emscripten_trace_enter_context(const char *name)

Parameters:

name (const char*) – Context name.

Return type:

void

The current timestamp is associated with this data.

void emscripten_trace_exit_context(void)

Return type:: void

The current timestamp is associated with this data.

void emscripten_trace_task_start(int task_id, const char *name);

Parameters:

task_id (int) – Task ID
name (const char*) – Task name

Return type:

void

A task is initiated. The task ID should be unique over the lifetime of the application. It should be managed / tracked by the application.

The current timestamp is associated with this data.

void emscripten_trace_task_associate_data(const char *key, const char *value);

Parameters:

key (const char*) – Key
value (const char*) – Value

Return type:

void

Associate a key / value pair with the current task.

void emscripten_trace_task_suspend(const char *explanation);

Parameters:

explanation (const char*) – Why the task is suspending.

Return type:

void

The current task is suspended.

The explanation should indicate why the task is being suspended so that this information can be made available when viewing the task’s history.

The current timestamp is associated with this data.

void emscripten_trace_task_resume(int task_id, const char *explanation);

Parameters:

task_id (int) – Task ID
explanation (const char*) – Why the task is being resumed.

Return type:

void

The task identified by task_id is resumed and made the current task.

The explanation should indicate what the task is being resumed to do so that this information can be made available when viewing the task’s history.

The current timestamp is associated with this data.

void emscripten_trace_task_end(void);

Return type:: void

The current task is ended.

The current timestamp is associated with this data.

void emscripten_trace_close(void)

Return type:: void

This should be closed during application termination. It helps ensure is flushed to the server and terminates the tracing code.