This Singleton class provides an Interface to manage and control the LTTng tracing on the PLCnext controller. More...

#include <TraceController.hpp>

Inheritance diagram for Arp::System::Commons::Diagnostics::TraceController:

Public Types
typedef std::list< Arp::String >	SessionList

Public Member Functions
bool	IsSessionDaemonAlive (void) const
	Checks if the LTTng session daemon for tracing is alive. More...

void	LoadTracepointLibrary (void)
	Loads the PLCnext userspace Tracepoint library. More...

void	UnloadTracepointLibrary (void)
	Unloads the userspace Tracepoint library. More...

bool	LoadSessionConfiguration (const Arp::String &session, const Arp::String &config)
	Tries to loads a tracing session from a given configuration file. More...

SessionList	ListSessions (void)
	Queries a list of all loaded (both started and stopped sessions) LTTng tracing sessions. More...

bool	StartSession (const Arp::String &session)
	Starts a LTTng tracing session. More...

bool	StopSession (const Arp::String &session)
	Stops a LTTng tracing session. More...

bool	DestroySession (const Arp::String &session)
	Destroys/Unloads a LTTng tracing session. More...

bool	TriggerSavingTraceOutputs (const bool &stopTriggerSession)
	Triggers the recording/saving all outputs of a configured session. Saving will be performed by another thread (delayed). More...

bool	IsSessionInSnapshotMode (const Arp::String &session)
	Checks if a tracing session is in Snapshot Mode. More...

bool	IsSessionEnabled (const Arp::String &session)
	Checks if a tracing session is already enabled/started. More...

bool	IsSessionLoaded (const Arp::String &session)
	Checks if a trace session is already loaded. More...

void	SetTracesSavingConfigs (const Arp::String &triggerSession, const Arp::String &outPath, const Arp::uint32 &maxDirectorySize, const Arp::uint32 &savingDelayTimeout)
	Sets the configuration of the trigger saving function More...

Friends
class	Singleton< TraceController >

Additional Inherited Members
Static Public Member Functions inherited from Arp::Singleton< TraceController >
static Instance &	CreateInstance (Args &&... args)
	Creates this singleton instance. More...

static bool	IsCreated (void)
	Determines if this singleton instance is create yet. More...

static Instance &	GetInstance (void)
	Gets a reference of the singleton instance. More...

static Instance *	GetInstancePtr (void)
	Deprecated! Gets a pointer to the singleton instance. More...

static void	DisposeInstance (void)
	Disposes this singleton instance. More...

Protected Types inherited from Arp::Singleton< TraceController >
typedef Singleton< TraceController >	SingletonBase
	Defines this type to be used from derived classes.

Protected Member Functions inherited from Arp::Singleton< TraceController >
	Singleton (void)=default
	The protected default constructor.

	~Singleton (void)=default
	The protected default destructor.

Static Protected Member Functions inherited from Arp::Singleton< TraceController >
static void	SetInstance (Instance *pOther)
	Depreacated! Sets the singleton instance. More...

static void	AssignInstanceFrom (Instance &other)
	Assigns the singleton instance from another singleton instance of the same type. More...

Detailed Description

This Singleton class provides an Interface to manage and control the LTTng tracing on the PLCnext controller.

This service is defined in library Arp.Services.TraceController.

A recording session belongs to a session daemon (see lttng-sessiond(8)). For a given session daemon, each Unix user has its own, private recording sessions. Note, however, that the root Linux user may operate on or destroy another user's tracing session. The plcnext_firmware user will not be able to see or control tracing sessions of another users.

LTTng generally offers four recording session modes (see LTTng Documentation):

Local mode: Write the trace data to the local file system.
Network streaming mode: Send the trace data over the network to a listening relay daemon.
Snapshot mode: Only write the trace data to the local file system or send it to a listening relay daemon when LTTng takes a snapshot.
Live mode: Send the trace data over the network to a listening relay daemon for live reading..

Running LTTng tracing may affect the performance of the PLCnext controller.

Member Function Documentation

◆ DestroySession()

bool Arp::System::Commons::Diagnostics::TraceController::DestroySession ( const Arp::String & session )

Destroys/Unloads a LTTng tracing session.

A tracing session with the specified name must be loaded (see IsSessionLoaded) and stopped (see IsSessionEnabled).

Parameters

session Name of Session which will be destroyed/unloaded.

Exceptions

Arp.Exception if the session does not exist or an internal LTTng error is occured.

Returns: false if the Arp.System.Commons.Diagnostics.TraceController singleton instance was not created or if the instance was desposed, otherwise true.

◆ IsSessionDaemonAlive()

bool Arp::System::Commons::Diagnostics::TraceController::IsSessionDaemonAlive ( void ) const

Checks if the LTTng session daemon for tracing is alive.

The tracing sessions can only loaded/started if the LTTng daemon is running.

Returns: true if the LTTng session daemon is running, otherwise false.

◆ IsSessionEnabled()

bool Arp::System::Commons::Diagnostics::TraceController::IsSessionEnabled ( const Arp::String & session )

Checks if a tracing session is already enabled/started.

A tracing session can be enabled/started with the method StartSession and stopped with the method (see StopSession)

Parameters

session Session Name, which mode will be checked

Exceptions

Arp.Exception if the session does not exist or an internal LTTng error has occurred.

Returns: true if the session is in enabled/started, otherwise false

◆ IsSessionInSnapshotMode()

bool Arp::System::Commons::Diagnostics::TraceController::IsSessionInSnapshotMode ( const Arp::String & session )

Checks if a tracing session is in Snapshot Mode.

The specified trace session must exist (see ListSessions and IsSessionLoaded) when this method is called .

The specified trace session must exist when this method is called (see ListSessions).

See lttng-sessiond(8) for more information about LTTng snapshot sessions.

Parameters

session Session name

Exceptions

Arp.Exception if the specified session does not exist or an internal LTTng error has occurred.

Returns: true if the tracing session is in snapshot mode, otherwise false.

◆ IsSessionLoaded()

bool Arp::System::Commons::Diagnostics::TraceController::IsSessionLoaded ( const Arp::String & session )

Checks if a trace session is already loaded.

Parameters

session Session Name, which mode will be checked

Exceptions

Arp.Exception if an internal LTTng error has occurred.

Returns: true if the session is in loaded, otherwise false

◆ ListSessions()

SessionList Arp::System::Commons::Diagnostics::TraceController::ListSessions ( void )

Queries a list of all loaded (both started and stopped sessions) LTTng tracing sessions.

Exceptions

Arp.Exception if an internal LTTng error has occurred.

Returns: vector container with names of loaded LTTng sessions.

◆ LoadSessionConfiguration()

bool Arp::System::Commons::Diagnostics::TraceController::LoadSessionConfiguration	(	const Arp::String &	session,
		const Arp::String &	config
	)

Tries to loads a tracing session from a given configuration file.

The PLCnext firmware provides two .lttng configuration files in the folder /opt/plcnext/lttng:

plcnexttrace.lttng: LTTng session configuration for default tracing mode for both kernel and user space traces
plcnexttrace_snapshot.lttng: LTTng session configuration for snapshot tracing mode for both kernel and user space traces

See LTTng documentaion for more information about session configuration.

This method fails if a tracing session with the same name is already loaded in the system. The method IsSessionLoaded can be used to check if a tracing session is already loaded.

Restrictions:

A session name must not contain the character //.
The concatenation of the tracepoint provider name and the tracepoint name must not exceed 254 characters.

See LTTng documentaion for more information about defined restrictions.

A tracing session can be unloaded/destroyed with the method (see DestroySession)

Parameters

session	Session name, which must be identical with the trace name configured in the .lttng configuration file.
path	Path to the .lttng configuration file of the specified tracing session.

Exceptions

Arp.Exception if the specified tracing session is already loaded or an internal LTTng error has occurred.

Returns: true if the session was loaded successfully, otherwise false.

◆ LoadTracepointLibrary()

void Arp::System::Commons::Diagnostics::TraceController::LoadTracepointLibrary ( void )

Loads the PLCnext userspace Tracepoint library.

The user trace points will not be exported to lttng if the Tracepoint library is not loaded.

Exceptions

Arp.System.Commons.InvalidConfigException	if the path to the Tracepoint library does not exist.
Arp.System.Commons.InvalidOperationException	if the Tracepoint library ist already loaded.
Arp.Exception	an internal error occurred while loading the Tracepoint library.

◆ SetTracesSavingConfigs()

void Arp::System::Commons::Diagnostics::TraceController::SetTracesSavingConfigs	(	const Arp::String &	triggerSession,
		const Arp::String &	outPath,
		const Arp::uint32 &	maxDirectorySize,
		const Arp::uint32 &	savingDelayTimeout
	)

Sets the configuration of the trigger saving function

Parameters

triggerSession	Session Name, which will be user for the Saving Trigger
outPath	Output path for the Saving Trigger Function
maxDirectorySize	Max Directory Size of the Saving Trigger Output Directory
savingDelayTimeout	Trigger Saving Delay Timeout

◆ StartSession()

bool Arp::System::Commons::Diagnostics::TraceController::StartSession ( const Arp::String & session )

Starts a LTTng tracing session.

A tracing session with the specified name must have been both loaded (see IsSessionLoaded) and stopped (see IsSessionEnabled).

The Tracepoint library must be loaded to start the tracing session LoadTracepointLib.

Parameters

session Name of Session which will be started.

Exceptions

Arp.Exception	an exception will be thrown if: The tracing session is already started. The tracing session does not exist. An internal LTTng error has occurred.
Arp.System.Commons.InvalidOperationException	if the Tracepoint library was not loaded.

Returns: true if the tracing session was started successfully, otherwise false.

◆ StopSession()

bool Arp::System::Commons::Diagnostics::TraceController::StopSession ( const Arp::String & session )

Stops a LTTng tracing session.

A tracing session with the specified name must be loaded (see IsSessionLoaded) and started (see IsSessionEnabled).

Parameters

session Name of Session which will be stopped.

Exceptions

Arp.Exception

an exception will be thrown if:

The tracing session is already stopped.
The tracing session does not exist.
An internal LTTng error has occurred.

Returns: true if the session was stopped successfully, otherwise false.

◆ TriggerSavingTraceOutputs()

bool Arp::System::Commons::Diagnostics::TraceController::TriggerSavingTraceOutputs ( const bool & stopTriggerSession )

Triggers the recording/saving all outputs of a configured session. Saving will be performed by another thread (delayed).

The configuration file of the TraceController PLCnext component (under /opt/plcnext/projects/Default/Services/TraceController/) contains the following configuration parameters for the traces saving trigger:

Path to the output directory in which the traces output will be saved (Default path is /opt/plcnext/lttng_traces/). The trace data are saved after each trigger call in a separate folder within the traces output directory.
The name of a trace output folder corresponds to the current timestamp and is composed as follows: TT.MM.JJ_hh:mm:ss.
Maximum size of the traces output directory in MB.
Used tracing session for the saving trigger.
Timeout for saving the trace data in ms. When this method is called, a timer runs in the background with the configured timeout, after which the trace of the trigger session is recorded/saved and then moved to the configured traces output directory.

/para>

The traces output directory works as a ring buffer. If the configured maximum size of the folder is reached, the oldest trace(s) is/are deleted from this folder as needed and the new trace is then saved.

The way the session data is stored depends on its operation mode:

Session is in snapshot mode: a session snapshot will be recorded and the snapshot will then be moved to the recording output directory.
Session is in default local mode: the temporary saved tracing session output will be moved to the recording output directory.

Returns: true if the recording/saving of the tracing session was successful, otherwise false.

◆ UnloadTracepointLibrary()

void Arp::System::Commons::Diagnostics::TraceController::UnloadTracepointLibrary ( void )

Unloads the userspace Tracepoint library.

All LTTng tracing sessions must be stopped before unloading the Tracepoint library (see methods ListSessions IsSessionEnabled).

Exceptions

Arp.System.Commons.InvalidConfigException	if the path to the Tracepoint library cannot be resolved.
Arp.System.Commons.InvalidOperationException	if at least one tracing session still running.
Arp.Exception	an internal error occurred while unloading the Tracepoint library.

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

Arp/System/Commons/Diagnostics/TraceController.hpp

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ DestroySession()

◆ IsSessionDaemonAlive()

◆ IsSessionEnabled()

◆ IsSessionInSnapshotMode()

◆ IsSessionLoaded()

◆ ListSessions()

◆ LoadSessionConfiguration()

◆ LoadTracepointLibrary()

◆ SetTracesSavingConfigs()

◆ StartSession()

◆ StopSession()

◆ TriggerSavingTraceOutputs()

◆ UnloadTracepointLibrary()