SignalBus Tracing and Unreal Insights

Review draft. This source page has not completed website editorial and release-specific verification.

SignalBus includes optional Unreal Trace support for recording message activity over time.

Tracing is useful when you need to answer questions such as:

Which SignalBus context handled a message?
Was the message Immediate or Queued?
How long did a subscriber callback take?
How long did a queued message wait before delivery?
Did a publish or enqueue fail?
Were warnings created or resolved?
Did server and client PIE contexts remain separate?
Did a packaged Development build emit SignalBus trace data?

SignalBus tracing is observational only.

It does not:

Publish messages
Create subscriptions
Remove subscriptions
Process queues
Change diagnostics
Change warning analysis
Edit payloads
Replay messages
Change callback order
Affect routing behavior

Unreal Trace

Unreal Trace records structured runtime events into a trace session.

Unreal Insights is the tool used to open and analyze those trace sessions.

For SignalBus:

SignalBus runtime activity
    -> Unreal Trace channel
        -> .utrace session
            -> Unreal Insights or SignalBus trace parser

The SignalBus trace channel is:

SignalBus

Tracing must be explicitly enabled.

If the channel is disabled, SignalBus routing continues normally.

When to Use SignalBus Tracing

Use tracing when:

A problem happens over time and is difficult to reproduce from the live Inspector
You need timing information
You need packaged Development build analysis
You need to compare World and Game Instance activity
You need to inspect Multi-PIE context separation
You need to correlate queued enqueue and later delivery
You need an offline record of SignalBus activity
You need to verify warnings and teardown behavior

Use the SignalBus Runtime Inspector instead when:

You want a live view
You want to see current subscriptions
You want to inspect the pending queue
You want to browse warnings during PIE
You want to view the Broadcast Graph

A useful distinction is:

SignalBus Runtime Inspector
    = live editor debugging

Unreal Trace
    = recorded historical analysis

Captured Data

SignalBus trace events may include:

Context initialization
Context teardown
World scope
Game Instance scope
PIE instance identifier
Message ID
Payload type
Subscription added
Subscription removed
Expired subscription cleanup
Immediate publish start
Immediate publish rejection
Message queued
Queue rejection
Queued dispatch start
Queued dispatch completion
Subscriber callback start
Subscriber callback completion
Callback duration
Dispatch duration
Queue delay
Dispatch result counts
Publish failure reason
Queue failure reason
Warning creation
Warning update
Warning resolution
Warning clearing
Publisher identity
Subscriber identity
World identity
Game Instance identity

Blueprint and C++ activity use the same runtime trace path.

There are no Blueprint-only trace events.

Important Trace Identifiers

SignalBus uses several identifiers to connect related events.

Context ID

ContextId

Identifies one SignalBus subsystem instance.

Examples:

World subsystem in PIE 0
Game Instance subsystem in PIE 0
World subsystem in PIE 1
Game Instance subsystem in PIE 1

Each should have a different Context ID.

Use Context ID first when separating unrelated activity.

Scope

Scope identifies whether the trace event belongs to:

World
Game Instance

The same Message ID in World and Game Instance scope represents separate routes.

PIE Instance ID

PIEInstanceId helps distinguish editor PIE contexts.

Example:

PIE 0
PIE 1

In non-PIE commandlet tests, this may use the non-PIE value:

INDEX_NONE

Queue Entry ID

QueueEntryId connects a queued publish to its later delivery.

Example:

MessageQueued
QueueEntryId: 42

QueuedDispatchStarted
QueueEntryId: 42
DispatchId: 88

Use Queue Entry ID when investigating:

Queue delay
Missing queued delivery
FIFO behavior
Queue backlog

Dispatch ID

DispatchId groups one dispatch and all subscriber callbacks that belong to it.

Example:

DispatchStarted
DispatchId: 88

SubscriberStarted
DispatchId: 88

SubscriberCompleted
DispatchId: 88

DispatchCompleted
DispatchId: 88

Use Dispatch ID when reviewing one publish across several subscribers.

Subscription Handle

SubscriptionHandle identifies the specific subscription that received a callback.

This is useful when:

One listener has multiple subscriptions
Duplicate subscriptions exist
One subscription is slow
One handle was removed
One subscriber is invoked several times

Timing Values

SignalBus records different timing values for different parts of delivery.

Callback Duration

Measures how long one subscriber callback took.

SubscriberStarted
    -> SubscriberCompleted

Use this to find slow listeners.

Example:

BP_HUDController callback: 0.2 ms
BP_QuestManager callback: 4.8 ms

The second callback may deserve investigation.

Dispatch Duration

Measures the time spent performing the dispatch.

It may include:

Matching subscribers
Invoking callbacks
Skipping expired listeners
Producing dispatch results

It does not include queue waiting time.

Queue Delay

Measures how long a queued message waited between:

MessageQueued
    -> QueuedDispatchStarted

Queue delay is separate from dispatch duration.

Example:

Queue delay: 16 ms
Dispatch duration: 1.2 ms

This means the message waited 16 ms, then took 1.2 ms to deliver.

Payload Privacy

SignalBus does not trace full payload values by default.

Trace payload information is metadata-only.

Captured metadata may include:

Payload type name
Reflected struct size
Reflected property count
Payload inspection policy
Truncation state
Capture completion state

SignalBus does not trace:

Full property values
Full strings
Arbitrary serialized payload bytes
Hidden values
Editable payload state

Properties marked:

SignalBusHidden

are never emitted as trace values.

Trace files may still contain:

Object names
Object paths
Message IDs
Payload type names
Warning summaries

Treat trace files as developer diagnostic artifacts.

Diagnostics, Warnings, and Trace Are Separate

SignalBus has three independent observational systems:

Diagnostics
Warning Analysis
Tracing

They do not automatically enable or disable each other.

Diagnostics Disabled

When diagnostics are disabled:

New retained Event History stops
Publisher graph discovery may stop
Routing continues
Trace may still continue

Warning Analysis Disabled

When warning analysis is disabled:

New warnings are not created
Warning trace changes are not emitted
Routing continues
Diagnostics may still continue
Trace may still capture non-warning events

SignalBus Trace Channel Disabled

When the trace channel is disabled:

SignalBus trace events stop
Routing continues
Diagnostics continue according to their own setting
Warnings continue according to their own setting

A valid test matrix is:

Diagnostics ON / Trace ON
Diagnostics ON / Trace OFF
Diagnostics OFF / Trace ON
Diagnostics OFF / Trace OFF

Routing should behave the same in every case.

Quick Start: Automated Trace Verification

The simplest way to verify SignalBus tracing is to run the included automation test.

Test name:

SignalBus.Editor.Trace.AnalysisVerification

This test:

Starts a real trace session.
Produces SignalBus activity.
Writes a .utrace file.
Opens the file through the SignalBus editor-side analyzer.
Verifies expected events and fields.

Typical output file:

<Project>/Saved/SignalBusTraceTests/SignalBusTraceAnalysisVerification.utrace

Run the Test from Unreal Editor

Open Unreal Editor.
Open one of these:

Tools -> Test Automation

or:

Tools -> Session Frontend

If Session Frontend opens, select the Automation tab.
Select the active editor session.
Search for:

SignalBus.Editor.Trace.AnalysisVerification

Select the test.
Click Start Tests.
Wait for completion.
Confirm the test passed.
Check the generated file under:

Saved/SignalBusTraceTests/

Editor PIE Capture

Use this workflow when you want to capture your own gameplay activity.

Step 1: Launch Unreal Insights

Open Unreal Insights from the engine installation:

<UE>/Engine/Binaries/Win64/UnrealInsights.exe

Leave the Session Browser open.

Step 2: Launch the Editor with SignalBus Tracing Enabled

Example:

UnrealEditor.exe <Project>.uproject -trace=default,SignalBus

Replace <Project>.uproject with the actual project path.

Example:

UnrealEditor.exe D:\Projects\MyGame\MyGame.uproject -trace=default,SignalBus

Step 3: Run PIE

Start PIE and generate SignalBus activity.

Recommended test activity:

World Immediate
World Queued
Game Instance Immediate
Game Instance Queued
Blueprint subscriber
C++ subscriber
At least one warning

Step 4: Stop PIE

Stop PIE after the test activity finishes.

The trace session should appear in Unreal Insights or the local Trace Store.

Step 5: Open the Session

In Unreal Insights:

Return to the Session Browser.
Find the recent editor trace.
Double-click the session.
Open the trace.

Important:

SignalBus currently emits custom structured events, but there is no dedicated SignalBus Unreal Insights tab.

The standard Timing view does not automatically show a SignalBus table.

Use the included SignalBus trace analyzer test for direct structured-event verification.

Using Trace Controls Instead of Command-Line Launch

Depending on the editor layout and engine build, trace controls may be available through:

Tools -> Session Frontend

or the editor trace controls.

General workflow:

Open the trace controls.
Select the active editor session.
Find the SignalBus channel.
Enable the channel.
Start capture.
Generate SignalBus activity.
Stop capture.
Open the resulting trace.

Enable the channel before the activity you need to inspect.

Events that occurred before the channel was enabled are not captured.

Command-Line Capture

Use:

UnrealEditor-Cmd.exe <Project>.uproject -trace=default,SignalBus

This is useful for:

Commandlet tests
CI
Headless capture
Reproducible test runs

Example:

UnrealEditor-Cmd.exe D:\Projects\MyGame\MyGame.uproject -trace=default,SignalBus

For file-targeted capture, use the trace-file arguments supported by the installed Unreal Engine build.

Do not assume every engine version uses the same optional trace-file syntax.

Packaged Development Capture

SignalBus tracing also works in packaged Development builds.

Launch:

<PackagedGame>.exe -trace=default,SignalBus

Example:

MyGame.exe -trace=default,SignalBus

Then generate runtime activity.

Recommended packaged test:

World Immediate
World Queued
Game Instance Immediate
Game Instance Queued
Blueprint listener
C++ listener
Warning condition

SignalBus runtime trace emission does not require:

SignalBusEditor
Slate
UnrealEd
BlueprintGraph
GraphEditor
TraceAnalysis

The editor-side analyzer is used only when parsing the resulting trace inside the editor module or automation test.

Example: Immediate Dispatch Trace

Gameplay:

BP_PlayerCharacter
    -> publishes Combat.HealthChanged
        -> BP_HUDController
        -> BP_AudioManager

Expected trace relationship:

ImmediatePublishStarted
DispatchStarted
SubscriberStarted
SubscriberCompleted
SubscriberStarted
SubscriberCompleted
DispatchCompleted

Correlate all events with:

ContextId
DispatchId
Message ID
Payload type

There should be no Queue Entry ID for a normal immediate publish.

Example: Queued Dispatch Trace

Gameplay:

BP_InventoryManager
    -> queues Inventory.Refreshed
        -> BP_InventoryWidget

Expected trace relationship:

MessageQueued
QueueEntryId: 42

QueuedDispatchStarted
QueueEntryId: 42
DispatchId: 88

SubscriberStarted
DispatchId: 88

SubscriberCompleted
DispatchId: 88

QueuedDispatchCompleted
QueueEntryId: 42
DispatchId: 88

Use:

QueueEntryId

to connect enqueue to later delivery.

Use:

DispatchId

to connect delivery to subscriber callbacks.

Example: Multi-PIE Trace

A two-player PIE session may produce:

World - PIE 0
Game Instance - PIE 0
World - PIE 1
Game Instance - PIE 1

Each should have a distinct:

ContextId

Use trace data to verify:

Server and client events stay separate
World and Game Instance events stay separate
Queue IDs are context-local
Dispatch IDs correlate inside the correct context
Teardown events appear for each context

SignalBus does not move events between server and client.

Networking must produce separate local activity on each peer.

Reading SignalBus Events

SignalBus structured events are split into compact schemas.

The analyzer combines related rows using:

ContextId
EventSequence

Captured schema categories include:

ContextInitialized
ContextDeinitialized
DiagnosticEvent
DiagnosticDetails
DiagnosticIdentity
PayloadMetadata
WarningChanged
WarningsCleared

These compact events represent higher-level activity such as:

Subscription added
Subscription removed
Immediate publish
Queued enqueue
Subscriber completion
Dispatch completion
Warning state change

Using the SignalBus Trace Analyzer

The SignalBus editor module includes a TraceAnalysis parser.

It can read the structured SignalBus events from a .utrace file and produce a report containing:

Schema name
Diagnostic event type
Context ID
Scope
PIE instance
Message ID
Payload type
Subscription handle
Queue Entry ID
Dispatch ID
Dispatch mode
Callback duration
Dispatch duration
Queue delay
Warning type
Warning severity

The analyzer does not expose payload values.

Currently, this parser is used through:

SignalBus.Editor.Trace.AnalysisVerification

There is no separate user-facing trace report window in SignalBus 1.0.0.

Common Troubleshooting

No trace session appears

Check:

Unreal Insights is running
Trace Store is available
The editor launched with -trace=default,SignalBus
The SignalBus channel was enabled
The process remained open long enough to connect
A trace session was actually started

Look for Output Log messages about trace connection state.

Output Log says tracing is using an in-memory cache

This usually means no active trace connection or trace store was available.

Start Unreal Insights first, then launch the editor again with:

-trace=default,SignalBus

SignalBus activity is missing

Check:

The channel was enabled before the activity
The expected World or Game Instance context existed
The publish was accepted
The trace was not stopped early
The correct trace session was opened
The runtime and analyzer builds match

Trace file exists but SignalBus events are not visible in Timing Insights

This is expected.

SignalBus 1.0.0 does not include a custom Unreal Insights tab or timing track.

Use:

SignalBus.Editor.Trace.AnalysisVerification

to verify the structured events.

The standard Timing view will not automatically display a dedicated SignalBus table.

Queue delay is zero

Possible explanations:

Delivery occurred during the next immediate queue-processing opportunity
The delay was too small to appear meaningfully
The event was Immediate rather than Queued
Queue Entry IDs were not correlated correctly

Confirm:

DispatchMode
QueueEntryId
DispatchId

Callback duration is unexpectedly high

Check:

Blueprint callback work
Expensive UI updates
Asset loading
Logging
Nested publishing
Large payload copies
Subscriber-side loops

Use the Subscription Handle and subscriber identity to identify the slow listener.

Context IDs appear wrong

Check:

Scope
PIE instance
World identity
Game Instance identity
Whether the session came from PIE or commandlet
Whether multiple sessions were opened

Commandlet trace tests may use:

PIEInstanceId = INDEX_NONE

This is correct for non-PIE execution.

Warning events are missing

Check:

Warning Analysis Enabled
The warning condition actually occurred
Warning state changed
The trace channel was enabled
The warning was already active and did not produce a new state change

SignalBus does not emit warning trace events when warning analysis is disabled.

What the Trace Test Verifies

The automated real-trace test validates:

World context initialization
Game Instance context initialization
Context teardown
Subscription events
Immediate dispatch
Queued enqueue
Queued delivery
Subscriber completion
Dispatch completion
Warning changes
Queue and Dispatch ID correlation
Scope correctness
Payload type metadata
Non-negative timing values
Payload privacy

This is stronger than checking only whether the trace channel was enabled.

It verifies that an actual .utrace file can be parsed.

Known Limitations

SignalBus 1.0.0 provides:

Level A structured trace events
+ editor-side TraceAnalysis parser
+ automated .utrace verification

It does not provide:

Custom SignalBus Unreal Insights tab
Custom Timing Insights track
Searchable SignalBus event table inside Insights
Payload value tracing
Message replay
Trace-driven runtime controls
Source-code scanning
Broadcast Graph reconstruction from trace
Automatic trace report export

Standard Timing Insights does not automatically present SignalBus rows.

The SignalBus Runtime Inspector remains the primary live visual tool.

Recommended Developer Workflow

For normal debugging:

Use SignalBus Runtime Inspector

For timing or historical analysis:

Capture with -trace=default,SignalBus

For automated verification:

Run SignalBus.Editor.Trace.AnalysisVerification

For packaged Development analysis:

Launch <PackagedGame>.exe -trace=default,SignalBus

Quick Checklist

Before capture:

Unreal Insights running
SignalBus channel enabled
Correct project launched
Correct build configuration

During capture:

Trigger Immediate activity
Trigger Queued activity
Trigger World activity
Trigger Game Instance activity
Trigger Blueprint activity
Trigger C++ activity
Trigger warning activity

After capture:

Confirm .utrace exists
Run analyzer verification
Check Context IDs
Check QueueEntryId and DispatchId
Check timing values
Check payload privacy
Check teardown events

Summary

SignalBus tracing provides:

Historical structured event capture
Context separation
Queue and dispatch correlation
Subscriber timing
Warning state tracking
Packaged Development analysis

The simplest way to use it is:

1. Launch with -trace=default,SignalBus
2. Generate SignalBus activity
3. Open the trace session
4. Run SignalBus.Editor.Trace.AnalysisVerification
5. Correlate by ContextId, QueueEntryId, and DispatchId