Advanced Usage

Temporarily Disabling Logging via Script

You can temporarily disable log creation. This will not strip the code from the Build, but it will exclude log creation execution, reducing the impact of their call to almost zero. To do this, call:

BurstTrace.SetLogDisabled(true);

Pass true to disable logs, pass false to enable logs. You can check if logs are enabled using the function:

BurstTrace.IsLogEnabled();

If logs are disabled OR you excluded the plugin code from the release Build, the function returns false. If logs are enabled, it returns true.

Disabling in Release

You can completely exclude the code from the release Build by checking ProjectSettings > BurstTrace > Disable logs.

This will exclude log creation code but will not make the TraceHandle struct empty. It will still occupy 4 bytes, but its value will always be empty. This is done to avoid theoretical issues with serialization and memory structure between runs.

The creation code itself will turn into empty methods, so calling it inside Burst will cost nothing, as Burst will simply strip it. Calling outside Burst is also extremely cheap, as it is just a call to an empty method.

Automatic Log Creation Without Writing Code at the Call Site

If you want to create a function that automatically creates a log of the calling line instead of manually calling and passing TraceHandle, use the following pattern:

    public void WriteDamageEvent(DamageEvent damageEvent, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
    {
        this.damageSenderTraceHandle = BurstTraceAdvanced.RegisterLog(damageEvent.burstTrace, memberName, sourceFilePath, sourceLineNumber);
    }

In this example, DamageEvent is passed to the function, but you can also pass nothing. The main thing here is the 3 arguments:

[CallerMemberName] string memberName = "",
[CallerFilePath] string sourceFilePath = "",
[CallerLineNumber] int sourceLineNumber = 0

Add them to the function, and then pass them to the custom log registration call:

        TraceHandle customTraceHandle = BurstTraceAdvanced.RegisterLog(memberName, sourceFilePath, sourceLineNumber);

You can also pass another TraceHandle as the first argument to create a chain. Then simply call your function as usual:

        WriteDamageEvent(damageEvent);

DO NOT ASSIGN DATA TO THESE SERVICE ARGUMENTS WHEN CALLING THE FUNCTION! Do not pass values to these arguments manually; the compiler will fill them automatically.

Thus, you can, for example, create a function that, when called, records the place from which it was called without requiring additional code during its call. You can also use this inside Burst and inside parallel Jobs.

Note: this method is slightly slower than the standard TraceHandle.Capture(). Use it only if it is important for you to hide the logging call inside the method. It is only slightly inferior in performance.

Outputting Logs for Further Analysis

If you need to get the full log string, call:

traceHandle.ToAbsolutePath();

This returns a line-by-line output of the log chain.

If you call:

traceHandle.ToProjectLink();

You get the following format (depends on Unity version):

#if UNITY_6000_0_OR_NEWER
string link = $"<color=#40a0ff><link=\"href='{relativePath}' line='{lineNum}'\">{relativePath}:{lineNum}</link></color>";
#else
string link = $"<a href=\"{relativePath}\" line=\"{lineNum}\">{relativePath}:{lineNum}</a>";
#endif

Configuring ProjectSettings

You can configure aspects of the plugin in the menu ProjectSettings > BurstTrace.

⚠️ Do not change the file name or path! It must have the path Resources/Burst Trace Config.asset

Memory Optimization Mode (~x3)

This mode reduces memory usage by approximately 3 times. However, it introduces minor overhead during the initial log registration and when reading logs. It may also truncate or break the log output (string) for projects with deep directory nesting. It is highly recommended not to enable this option if the relative paths of your script files (within the Assets folder) exceed 124 bytes!

Disable 64-hash optimization

The plugin replaces strings with hashes for optimization. By default, a 64-bit hash is used. The chance of collision is negligible but theoretically exists. If you encounter hash collisions (please create an Issue in the repository), enable this option. It will slightly reduce performance and increase memory usage, but completely eliminate the probability of collisions.

Capture profiler

Check this box to display the moment of log creation and recording in the Unity Profiler. It will also show inside Jobs. This way you can find out the exact cost of usage inside your Jobs. It is recommended to disable this in release, as writing to the Profiler can theoretically be more expensive than creating the log itself.

Disable logs

This will exclude log creation code from the Build but will not make the TraceHandle struct empty. It will still occupy 4 bytes, but its value will always be empty. This is done to avoid theoretical issues with serialization and memory structure between runs. The creation code itself will turn into empty methods, so calling it inside Burst will cost nothing, as Burst will simply strip it. Calling outside Burst is also extremely cheap, as it is just a call to an empty method.