Skip to content
Tuxedo CatSTUDIO
Menu

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

Section titled “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

Section titled “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

Section titled “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

Section titled “Important Trace Identifiers”

SignalBus uses several identifiers to connect related events.

Context ID

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Timing Values”

SignalBus records different timing values for different parts of delivery.

Callback Duration

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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:

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

Typical output file:

<Project>/Saved/SignalBusTraceTests/SignalBusTraceAnalysisVerification.utrace

Run the Test from Unreal Editor

Section titled “Run the Test from Unreal Editor”
  1. Open Unreal Editor.
  2. Open one of these:
Tools -> Test Automation

or:

Tools -> Session Frontend
  1. If Session Frontend opens, select the Automation tab.
  2. Select the active editor session.
  3. Search for:
SignalBus.Editor.Trace.AnalysisVerification
  1. Select the test.
  2. Click Start Tests.
  3. Wait for completion.
  4. Confirm the test passed.
  5. Check the generated file under:
Saved/SignalBusTraceTests/

Editor PIE Capture

Section titled “Editor PIE Capture”

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

Step 1: Launch Unreal Insights

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Step 5: Open the Session”

In Unreal Insights:

  1. Return to the Session Browser.
  2. Find the recent editor trace.
  3. Double-click the session.
  4. 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

Section titled “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:

  1. Open the trace controls.
  2. Select the active editor session.
  3. Find the SignalBus channel.
  4. Enable the channel.
  5. Start capture.
  6. Generate SignalBus activity.
  7. Stop capture.
  8. 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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Common Troubleshooting”

No trace session appears

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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