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

#include <ITraceControllerService.hpp>

Inheritance diagram for Arp::Services::TraceController::Services::ITraceControllerService:

Public Types
using	Ptr = std::shared_ptr< ITraceControllerService >

Public Types inherited from Arp::Base::Rsc::Commons::IRscService
using	Ptr = std::shared_ptr< IRscService >
	The shared_ptr type of IRscService.

Public Member Functions
	ITraceControllerService (void)=default
	Constructs an ITraceControllerService instance.

virtual boolean	IsSessionDaemonAlive ()=0
	Checks if the LTTng session daemon for tracing is alive. More...

virtual boolean	LoadSessionConfiguration (const RscString< 512 > &session, const RscString< 512 > &path)=0
	Tries to loads a tracing session from a given configuration file. More...

virtual std::vector< RscString< 512 > >	ListSessions ()=0
	Queries a list of all loaded (both started and stopped sessions) LTTng tracing sessions. More...

virtual boolean	StartSession (const RscString< 512 > &session)=0
	Starts a LTTng tracing session. More...

virtual boolean	StopSession (const RscString< 512 > &session)=0
	Stops a LTTng tracing session. More...

virtual boolean	DestroySession (const RscString< 512 > &session)=0
	Destroys/Unloads a LTTng tracing session. More...

virtual void	LoadTracepointLib ()=0
	Loads the PLCnext userspace Tracepoint library. More...

virtual void	UnloadTracepointLib ()=0
	Unloads the userspace Tracepoint library. More...

virtual boolean	TriggerSavingTraceOutputs (boolean stopTriggerSession)=0
	Triggers the recording/saving all outputs of a configured session. Saving will be performed by another thread (delayed). More...

virtual boolean	IsSessionInSnapshotMode (const RscString< 512 > &session)=0
	Checks if a tracing session is in Snapshot Mode. More...

virtual boolean	IsSessionEnabled (const RscString< 512 > &session)=0
	Checks if a tracing session is already enabled/started. More...

virtual boolean	IsSessionLoaded (const RscString< 512 > &session)=0
	Checks if a trace session is already loaded. More...

Public Member Functions inherited from Arp::Base::Rsc::Commons::IRscService
	IRscService (void)=default
	The default constructor.

	IRscService (const IRscService &arg)=delete
	The deleted copy constructor. More...

	IRscService (IRscService &&arg) noexcept=default
	The default move constructor. More...

IRscService &	operator= (const IRscService &arg)=delete
	The deleted assignment operator. More...

IRscService &	operator= (IRscService &&arg) noexcept=default
	The default move-assignment operator. More...

virtual	~IRscService (void)=default
	Destructs this instance and frees all resources.

Static Public Member Functions
static IRscServiceProxyFactory &	GetProxyFactory (void)

Static Public Member Functions inherited from Arp::Base::Rsc::Commons::IRscService
static IRscServiceProxyFactory &	GetProxyFactory (void)
	Returns a reference to service proxy factory to create a proxy instance of this service. More...

Detailed Description

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

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

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

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.

Realtime Usage: This API call does not have to be deterministic in runtime behaviour, so an asynchronous execution should be considered.

Member Function Documentation

◆ DestroySession()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::DestroySession ( const RscString< 512 > & session )

pure virtual

Destroys/Unloads a LTTng tracing session.

A tracing session with the specified name must be loaded (see Arp.Services.TraceController.Services.ITraceControllerService.IsSessionLoaded) and stopped (see Arp.Services.TraceController.Services.ITraceControllerService.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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::IsSessionDaemonAlive ( )

pure virtual

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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::IsSessionEnabled ( const RscString< 512 > & session )

pure virtual

Checks if a tracing session is already enabled/started.

A tracing session can be enabled/started with the method Arp.Services.TraceController.Services.ITraceControllerService.StartSession and stopped with the method (see Arp.Services.TraceController.Services.ITraceControllerService.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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::IsSessionInSnapshotMode ( const RscString< 512 > & session )

pure virtual

Checks if a tracing session is in Snapshot Mode.

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

The specified trace session must exist when this method is called (see Arp.Services.TraceController.Services.ITraceControllerService.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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::IsSessionLoaded ( const RscString< 512 > & session )

pure virtual

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()

virtual std::vector< RscString< 512 > > Arp::Services::TraceController::Services::ITraceControllerService::ListSessions ( )

pure virtual

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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::LoadSessionConfiguration	(	const RscString< 512 > &	session,
		const RscString< 512 > &	path
	)

pure virtual

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.

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

This method fails if a tracing session with the same name is already loaded in the system. The method Arp.Services.TraceController.Services.ITraceControllerService.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 Arp.Services.TraceController.Services.ITraceControllerService.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.

◆ LoadTracepointLib()

virtual void Arp::Services::TraceController::Services::ITraceControllerService::LoadTracepointLib ( )

pure virtual

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.

◆ StartSession()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::StartSession ( const RscString< 512 > & session )

pure virtual

Starts a LTTng tracing session.

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

The Tracepoint library must be loaded to start the tracing session Arp.Services.TraceController.Services.ITraceControllerService.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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::StopSession ( const RscString< 512 > & session )

pure virtual

Stops a LTTng tracing session.

A tracing session with the specified name must be loaded (see Arp.Services.TraceController.Services.ITraceControllerService.IsSessionLoaded) and started (see Arp.Services.TraceController.Services.ITraceControllerService.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()

virtual boolean Arp::Services::TraceController::Services::ITraceControllerService::TriggerSavingTraceOutputs ( boolean stopTriggerSession )

pure virtual

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.

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.

◆ UnloadTracepointLib()

virtual void Arp::Services::TraceController::Services::ITraceControllerService::UnloadTracepointLib ( )

pure virtual

Unloads the userspace Tracepoint library.

All LTTng tracing sessions must be stopped before unloading the Tracepoint library (see methods Arp.Services.TraceController.Services.ITraceControllerService.ListSessions Arp.Services.TraceController.Services.ITraceControllerService.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/Services/TraceController/Services/ITraceControllerService.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ DestroySession()

◆ IsSessionDaemonAlive()

◆ IsSessionEnabled()

◆ IsSessionInSnapshotMode()

◆ IsSessionLoaded()

◆ ListSessions()

◆ LoadSessionConfiguration()

◆ LoadTracepointLib()

◆ StartSession()

◆ StopSession()

◆ TriggerSavingTraceOutputs()

◆ UnloadTracepointLib()