#include <TraceAuxiliary.h>

Classes
struct	FChannelPreset

struct	FOptions

Public Types
enum class	ETraceSystemStatus : uint8 { NotAvailable , Available , TracingToServer , TracingToFile , TracingToCustomRelay , NumValues }

enum class	EEnumerateResult : uint8 { Continue , Stop }

enum class	EConnectionType : uint8 { Network , File , Relay , None }

typedef TFunctionRef< EEnumerateResult(const FChannelPreset &Preset)>	PresetCallback

typedef FLogCategoryBase	FLogCategoryAlias

Public Member Functions
	DECLARE_TS_MULTICAST_DELEGATE (FOnConnection)

	DECLARE_TS_MULTICAST_DELEGATE_TwoParams (FOnTraceStarted, FTraceAuxiliary::EConnectionType TraceType, const FString &TraceDestination)

	DECLARE_TS_MULTICAST_DELEGATE_TwoParams (FOnTraceStopped, FTraceAuxiliary::EConnectionType TraceType, const FString &TraceDestination)

	DECLARE_TS_MULTICAST_DELEGATE_TwoParams (FOnSnapshotSaved, FTraceAuxiliary::EConnectionType TraceType, const FString &TraceDestination)

Static Public Member Functions
static CORE_API bool	Start (EConnectionType Type, const TCHAR Target, const TCHAR Channels=TEXT("default"), FOptions *Options=nullptr, const FLogCategoryAlias &LogCategory=LogCore)

static CORE_API bool	Relay (UPTRINT Handle, UE::Trace::IoWriteFunc WriteFunc, UE::Trace::IoCloseFunc CloseFunc, const TCHAR Channels=TEXT("default"), const FOptions Options=nullptr)

static CORE_API bool	Stop ()

static CORE_API bool	Pause ()

static CORE_API bool	IsPaused ()

static CORE_API bool	Resume ()

static CORE_API bool	WriteSnapshot (const TCHAR *FilePath)

static CORE_API bool	SendSnapshot (const TCHAR *Host=nullptr, uint32 Port=0)

static CORE_API void	Initialize (const TCHAR *CommandLine)

static CORE_API void	InitializePresets (const TCHAR *CommandLine)

static CORE_API void	Shutdown ()

static CORE_API void	TryAutoConnect ()

static CORE_API void	EnableCommandlineChannels ()

static CORE_API void	EnableChannels (TConstArrayView< uint32 > ChannelIds, TMap< uint32, FString > *OutErrors=nullptr)

static CORE_API void	DisableChannels (TConstArrayView< uint32 > ChannelIds, TMap< uint32, FString > *OutErrors=nullptr)

static CORE_API void	EnableChannels (const TCHAR *Channels)

static CORE_API void	DisableChannels (const TCHAR *Channels=nullptr)

static CORE_API FString	GetTraceDestinationString ()

static CORE_API bool	IsConnected ()

static CORE_API bool	IsConnected (FGuid &OutSessionGuid, FGuid &OutTraceGuid)

static CORE_API EConnectionType	GetConnectionType ()

static CORE_API void	GetActiveChannelsString (FStringBuilderBase &String)

static CORE_API void	Panic ()

static CORE_API struct UE::Trace::FInitializeDesc const *	GetInitializeDesc ()

static CORE_API void	EnumerateFixedChannelPresets (PresetCallback Callback)

static CORE_API void	EnumerateChannelPresetsFromSettings (PresetCallback Callback)

static CORE_API ETraceSystemStatus	GetTraceSystemStatus ()

Static Public Attributes
static CORE_API FOnConnection	OnConnection

static CORE_API FOnTraceStarted	OnTraceStarted

static CORE_API FOnTraceStopped	OnTraceStopped

static CORE_API FOnSnapshotSaved	OnSnapshotSaved

Member Typedef Documentation

◆ FLogCategoryAlias

typedef FLogCategoryBase FTraceAuxiliary::FLogCategoryAlias

◆ PresetCallback

typedef TFunctionRef<EEnumerateResult(const FChannelPreset& Preset)> FTraceAuxiliary::PresetCallback

Member Enumeration Documentation

◆ EConnectionType

enum class FTraceAuxiliary::EConnectionType : uint8

strong

Enumerator
Network	Connect to a trace server. Target is IP address or hostname.
File	Write to a file. Target string is filename. Absolute or relative current working directory. If target is null the current date and time is used.
Relay	Relay connection. Pass user defined I/O functions to write raw trace data.
None	Don't connect, just start tracing to memory.

◆ EEnumerateResult

enum class FTraceAuxiliary::EEnumerateResult : uint8

strong

Enumerator
Continue
Stop

◆ ETraceSystemStatus

enum class FTraceAuxiliary::ETraceSystemStatus : uint8

strong

This enum is serialized and sent via the trace service. Do not change the values or modify the order. Only add new values to the end. Should be kept in sync with FTraceStatus::ETraceSystemStatus from ITraceController.h

Enumerator
NotAvailable
Available
TracingToServer
TracingToFile
TracingToCustomRelay
NumValues

Member Function Documentation

◆ DECLARE_TS_MULTICAST_DELEGATE()

FTraceAuxiliary::DECLARE_TS_MULTICAST_DELEGATE ( FOnConnection )

Callback type when a new connection is established.

◆ DECLARE_TS_MULTICAST_DELEGATE_TwoParams() [1/3]

FTraceAuxiliary::DECLARE_TS_MULTICAST_DELEGATE_TwoParams	(	FOnSnapshotSaved	,
		FTraceAuxiliary::EConnectionType	TraceType,
		const FString &	TraceDestination
	)

Callback whenever a trace snapshot is saved. Path is the file system path of the snapshot file.

◆ DECLARE_TS_MULTICAST_DELEGATE_TwoParams() [2/3]

FTraceAuxiliary::DECLARE_TS_MULTICAST_DELEGATE_TwoParams	(	FOnTraceStarted	,
		FTraceAuxiliary::EConnectionType	TraceType,
		const FString &	TraceDestination
	)

Callback whenever a trace is started

◆ DECLARE_TS_MULTICAST_DELEGATE_TwoParams() [3/3]

FTraceAuxiliary::DECLARE_TS_MULTICAST_DELEGATE_TwoParams	(	FOnTraceStopped	,
		FTraceAuxiliary::EConnectionType	TraceType,
		const FString &	TraceDestination
	)

Callback whenever a trace recording is stopped. TraceType tells what kind of trace it is. TraceDestination will be either the filename and path for a file trace or the network connection for a network trace

◆ DisableChannels() [1/2]

void FTraceAuxiliary::DisableChannels ( const TCHAR * Channels = nullptr )

static

Disable channels to stop recording traces with them.

Parameters

Channels Comma separated list of channels and presets to disable. If null it will disable all active channels.

◆ DisableChannels() [2/2]

void FTraceAuxiliary::DisableChannels	(	TConstArrayView< uint32 >	ChannelIds,
		TMap< uint32, FString > *	OutErrors = `nullptr`
	)

static

Disable channels to mute events belonging to this category.

Note: Note that presets cannot be used when specifying channel ids.

Parameters

ChannelIds	List of channels to disable.
OutErrors	Contains deny reasons for channels that could not be disabled.

◆ EnableChannels() [1/2]

void FTraceAuxiliary::EnableChannels ( const TCHAR * Channels )

static

Enable channels to emit events from this category.

Parameters

Channels Comma separated list of channels and presets to enable.

◆ EnableChannels() [2/2]

void FTraceAuxiliary::EnableChannels	(	TConstArrayView< uint32 >	ChannelIds,
		TMap< uint32, FString > *	OutErrors = `nullptr`
	)

static

Enable channels to emit events belonging to this category.

Note: Note that presets cannot be used when specifying channel ids.

Parameters

ChannelIds	List of channels to enable.
OutErrors	Contains deny reasons for channels that could not be enabled.

◆ EnableCommandlineChannels()

void FTraceAuxiliary::EnableCommandlineChannels ( )

static

Enable previously selected channels. This method can be called multiple times as channels can be announced on module loading.

◆ EnumerateChannelPresetsFromSettings()

void FTraceAuxiliary::EnumerateChannelPresetsFromSettings ( PresetCallback Callback )

static

Enumerate the channel presets that are defined in BaseEngine.ini, under the [Trace.ChannelPresets] section.

◆ EnumerateFixedChannelPresets()

void FTraceAuxiliary::EnumerateFixedChannelPresets ( PresetCallback Callback )

static

Enumerate the channel presets that are defined in code.

◆ GetActiveChannelsString()

void FTraceAuxiliary::GetActiveChannelsString ( FStringBuilderBase & String )

static

Adds a comma separated list of currently active channels to the passed in StringBuilder

◆ GetConnectionType()

FTraceAuxiliary::EConnectionType FTraceAuxiliary::GetConnectionType ( )

static

Returns the current connection type.

◆ GetInitializeDesc()

UE::Trace::FInitializeDesc const * FTraceAuxiliary::GetInitializeDesc ( )

static

Get the settings used to initialize TraceLog

◆ GetTraceDestinationString()

FString FTraceAuxiliary::GetTraceDestinationString ( )

static

Returns the destination string that is currently being traced to. Contains either a file path or network address. Empty if tracing is disabled.

◆ GetTraceSystemStatus()

FTraceAuxiliary::ETraceSystemStatus FTraceAuxiliary::GetTraceSystemStatus ( )

static

Returns the current status of the trace system.

◆ Initialize()

void FTraceAuxiliary::Initialize ( const TCHAR * CommandLine )

static

Initialize Trace systems.

Parameters

CommandLine to use for initializing

◆ InitializePresets()

void FTraceAuxiliary::InitializePresets ( const TCHAR * CommandLine )

static

Initialize channels that use the config driven presets.

Parameters

CommandLine to use for initializing

◆ IsConnected() [1/2]

bool FTraceAuxiliary::IsConnected ( )

static

Returns whether the trace system is currently connected to a trace sink (network, file or custom relay).

◆ IsConnected() [2/2]

bool FTraceAuxiliary::IsConnected	(	FGuid &	OutSessionGuid,
		FGuid &	OutTraceGuid
	)

static

Returns whether the trace system is currently connected. If connected, it writes the session/trace identifiers.

Parameters

OutSessionGuid	If connected, the session guid
OutTraceGuid	If connected, the trace guid

Returns: True if connected

◆ IsPaused()

bool FTraceAuxiliary::IsPaused ( )

static

Returns: True if trace was paused and the list of channels to resume exists.

◆ Panic()

void FTraceAuxiliary::Panic ( )

static

Used when process is panicking. Stops all tracing immediately to avoid further allocations. Process is not expected to continue after this call.

◆ Pause()

bool FTraceAuxiliary::Pause ( )

static

Pause all tracing by disabling all active channels.

◆ Relay()

bool FTraceAuxiliary::Relay	(	UPTRINT	Handle,
		UE::Trace::IoWriteFunc	WriteFunc,
		UE::Trace::IoCloseFunc	CloseFunc,
		const TCHAR *	Channels = `TEXT("default")`,
		const FOptions *	Options = `nullptr`
	)

static

Start tracing to a custom target by providing a handle and a write and close function. If a connection is already active this call does nothing.

Parameters

Handle	Anonymous handle to trace to. This will be passed to the writer and close functions.
WriteFunc	A function to handle writing of trace data
CloseFunc	A function to handle closing of the data stream.
Channels	Comma separated list of channels to enable. Default set of channels are enabled if argument is not specified. If the pointer is null no channels are enabled.
Options	Optional additional tracing options.

Returns: True when successfully starting the trace, false if the data connection could not be made.

◆ Resume()

bool FTraceAuxiliary::Resume ( )

static

Resume tracing by enabling all previously active channels.

◆ SendSnapshot()

bool FTraceAuxiliary::SendSnapshot	(	const TCHAR *	Host = `nullptr`,
		uint32	Port = `0`
	)

static

Write tailing memory state to a trace server.

Parameters

FilePath Path to the file to write the snapshot to. If it is null or empty a file path will be generated.

◆ Shutdown()

void FTraceAuxiliary::Shutdown ( )

static

Shut down Trace systems.

◆ Start()

bool FTraceAuxiliary::Start	(	EConnectionType	Type,
		const TCHAR *	Target,
		const TCHAR *	Channels = `TEXT("default")`,
		FOptions *	Options = `nullptr`,
		const FLogCategoryAlias &	LogCategory = `LogCore`
	)

static

Start tracing to a target (network connection or file) with an active set of channels. If a connection is already active this call does nothing.

Parameters

Type	Type of connection. Network or File type. If a custom target is desired use FTraceAuxiliary::Relay.
Target	String to use for connection. See /ref EConnectionType for details.
Channels	Comma separated list of channels to enable. Default set of channels are enabled if argument is not specified. If the pointer is null no channels are enabled.
Options	Optional additional tracing options.
LogCategory	Log channel to output messages to. Default set to 'Core'.

Returns: True when successfully starting the trace, false if the data connection could not be made.

◆ Stop()

bool FTraceAuxiliary::Stop ( )

static

Stop tracing.

Returns: True if the trace was stopped, false if there was no data connection.

◆ TryAutoConnect()

void FTraceAuxiliary::TryAutoConnect ( )

static

Attempts to auto connect to an active trace server if an active session of Unreal Insights Session Browser is running.

◆ WriteSnapshot()

bool FTraceAuxiliary::WriteSnapshot ( const TCHAR * FilePath )

static

Write tailing memory state to a utrace file.

Parameters

FilePath Path to the file to write the snapshot to. If it is null or empty a file path will be generated.

Member Data Documentation

◆ OnConnection

FTraceAuxiliary::FOnConnection FTraceAuxiliary::OnConnection

static

Delegate that triggers when a connection is established. Gives subscribers a chance to trace events that appear after important events but before regular events (including tail). The following restrictions apply:

Only NoSync event types can be emitted.
Important events should not be emitted. They will appear after the events in the tail.
Callback is issued from a worker thread. User is responsible to synchronize shared resources.

Note: This is an advanced feature to avoid using important events in cases where event data can be recalled easily.

Parameters

Callback Delegate to call on new connections.

◆ OnSnapshotSaved

FTraceAuxiliary::FOnSnapshotSaved FTraceAuxiliary::OnSnapshotSaved

static

Delegate that triggers when a snapshot has been saved. The path to the snapshot file is passed to the delegate.

◆ OnTraceStarted

FTraceAuxiliary::FOnTraceStarted FTraceAuxiliary::OnTraceStarted

static

Delegate that triggers when a trace session is started. The type of recording and the destination (filepath or network) is passed to the delegate.

◆ OnTraceStopped

FTraceAuxiliary::FOnTraceStopped FTraceAuxiliary::OnTraceStopped

static

Delegate that triggers when a trace has finished recording. Useful if you need to collect all completed trace files in a session. The type of recording and the destination (filepath or network) is passed to the delegate.

The documentation for this class was generated from the following files:

Engine/Source/Runtime/Core/Public/ProfilingDebugging/TraceAuxiliary.h
Engine/Source/Runtime/Core/Private/ProfilingDebugging/TraceAuxiliary.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Member Typedef Documentation

◆ FLogCategoryAlias

◆ PresetCallback

Member Enumeration Documentation

◆ EConnectionType

◆ EEnumerateResult

◆ ETraceSystemStatus

Member Function Documentation

◆ DECLARE_TS_MULTICAST_DELEGATE()

◆ DECLARE_TS_MULTICAST_DELEGATE_TwoParams() [1/3]

◆ DECLARE_TS_MULTICAST_DELEGATE_TwoParams() [2/3]

◆ DECLARE_TS_MULTICAST_DELEGATE_TwoParams() [3/3]

◆ DisableChannels() [1/2]

◆ DisableChannels() [2/2]

◆ EnableChannels() [1/2]

◆ EnableChannels() [2/2]

◆ EnableCommandlineChannels()

◆ EnumerateChannelPresetsFromSettings()

◆ EnumerateFixedChannelPresets()

◆ GetActiveChannelsString()

◆ GetConnectionType()

◆ GetInitializeDesc()

◆ GetTraceDestinationString()

◆ GetTraceSystemStatus()

◆ Initialize()

◆ InitializePresets()

◆ IsConnected() [1/2]

◆ IsConnected() [2/2]

◆ IsPaused()

◆ Panic()

◆ Pause()

◆ Relay()

◆ Resume()

◆ SendSnapshot()

◆ Shutdown()

◆ Start()

◆ Stop()

◆ TryAutoConnect()

◆ WriteSnapshot()

Member Data Documentation

◆ OnConnection

◆ OnSnapshotSaved

◆ OnTraceStarted

◆ OnTraceStopped