#include <map>
#include <memory>
#include <ostream>
#include <string>
#include <vector>
#include <boost/any.hpp>
#include <boost/function.hpp>
#include <Optional.hpp>
#include <system/User.hpp>
#include <PImpl.hpp>

Classes
struct	rstudio::launcher_plugins::logging::RefreshParams
	A struct encapsulating various params to pass when refreshing log destinations. This carries data that some loggers may be interested in consuming to determine how the refresh should be carried out. See the FileLogDestination for a concrete example of this. More...

Typedefs
typedef std::vector< std::pair< std::string, boost::any > >	rstudio::launcher_plugins::logging::LogMessageProperties
	Convenience type for log message properties. Using a boost::any instead of a boost::variant allows access to json as it is currently impossible to include json types here because that would cause a circular dependency.

Enumerations
enum	rstudio::launcher_plugins::logging::LogLevel { OFF = 0, ERR = 1, WARN = 2, INFO = 3, DEBUG = 4 }
	Enum which represents the level of detail at which to log messages.

enum	rstudio::launcher_plugins::logging::LogMessageFormatType { PRETTY = 0, JSON = 1 }
	Enum which represents the format type for log messages.

Functions
std::string	rstudio::launcher_plugins::logging::cleanDelimiters (const std::string &in_str)
	Helper function which cleans the log delimiter character from a string. More...

void	rstudio::launcher_plugins::logging::setProgramId (const std::string &in_programId)
	Sets the program ID for the logger. More...

void	rstudio::launcher_plugins::logging::addLogDestination (const std::shared_ptr< ILogDestination > &in_destination)
	Adds an un-sectioned log destination to the logger. More...

void	rstudio::launcher_plugins::logging::addLogDestination (const std::shared_ptr< ILogDestination > &in_destination, const std::string &in_section)
	Adds a sectioned log destination to the logger. More...

bool	rstudio::launcher_plugins::logging::hasFileLogDestination ()
	Returns whether or not a file log destination is configured. More...

bool	rstudio::launcher_plugins::logging::hasStderrLogDestination ()
	Returns whether or not a stderr log destination is configured. More...

bool	rstudio::launcher_plugins::logging::isLogLevel (logging::LogLevel level)
	Use to write code conditioned on whether logging is configured or not. More...

std::string	rstudio::launcher_plugins::logging::cleanDelims (const std::string &in_toClean)
	Replaces logging delimiters with ' ' in the specified string. More...

void	rstudio::launcher_plugins::logging::logError (const Error &in_error)
	Logs an error to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logError (const Error &in_error, const ErrorLocation &in_location)
	Logs an error to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logErrorAsWarning (const Error &in_error)
	Logs an error as a warning to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logErrorAsInfo (const Error &in_error)
	Logs an error as an info message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logErrorAsDebug (const Error &in_error)
	Logs an error as a debug message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logErrorMessage (const std::string &in_message, const std::string &in_section=std::string())
	Logs an error to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logErrorMessage (const std::string &in_message, const ErrorLocation &in_loggedFrom)
	Logs an error to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logErrorMessage (const std::string &in_message, const std::string &in_section, const Optional< LogMessageProperties > &in_properties, const ErrorLocation &in_loggedFrom)
	Logs an error to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logWarningMessage (const std::string &in_message, const std::string &in_section=std::string())
	Logs a warning message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logWarningMessage (const std::string &in_message, const ErrorLocation &in_loggedFrom)
	Logs a warning message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logWarningMessage (const std::string &in_message, const std::string &in_section, const Optional< LogMessageProperties > &in_properties, const ErrorLocation &in_loggedFrom)
	Logs a warning message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logDebugMessage (const std::string &in_message, const std::string &in_section=std::string())
	Logs a debug message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logDebugMessage (const std::string &in_message, const ErrorLocation &in_loggedFrom)
	Logs a debug message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logDebugMessage (const std::string &in_message, const std::string &in_section, const Optional< LogMessageProperties > &in_properties, const ErrorLocation &in_loggedFrom)
	Logs a debug message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logDebugAction (const boost::function< std::string(Optional< LogMessageProperties > *)> &in_action, const std::string &in_section=std::string())
	Logs a debug message to all registered destinations by invoking an action. More...

void	rstudio::launcher_plugins::logging::logInfoMessage (const std::string &in_message, const std::string &in_section=std::string())
	Logs an info message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logInfoMessage (const std::string &in_message, const ErrorLocation &in_loggedFrom)
	Logs an info message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logInfoMessage (const std::string &in_message, const std::string &in_section, const Optional< LogMessageProperties > &in_properties, const ErrorLocation &in_loggedFrom)
	Logs an info message to all registered destinations. More...

void	rstudio::launcher_plugins::logging::logPassthroughMessage (const std::string &in_source, const std::string &in_message)
	Logs an entire log message as is with an annotation indicating it came from source. More...

void	rstudio::launcher_plugins::logging::refreshAllLogDestinations (const logging::RefreshParams &in_refreshParams=logging::RefreshParams())
	Refreshes all log destinations. May be used after fork to prevent stale file handles. More...

void	rstudio::launcher_plugins::logging::removeLogDestination (const std::string &in_destinationId, const std::string &in_section=std::string())
	Removes a log destination from the logger. More...

void	rstudio::launcher_plugins::logging::removeReloadableLogDestinations ()
	Removes log destinations that are marked as reloadable from the logger. These loggers can then be reinitialized and re-registered with the logger to update the desired changes to the logging system.

std::ostream &	rstudio::launcher_plugins::logging::writeError (const Error &in_error, std::ostream &io_os)
	Writes an error to the specified output stream. More...

std::string	rstudio::launcher_plugins::logging::writeError (const Error &in_error)
	Writes an error to string. More...

Variables
constexpr char	rstudio::launcher_plugins::logging::s_delim = ';'
	Log delimiting character which may be used for custom log formatting.

Detailed Description

Logging definitions and functions.

Function Documentation

◆ addLogDestination() [1/2]

void rstudio::launcher_plugins::logging::addLogDestination ( const std::shared_ptr< ILogDestination > & in_destination )

Adds an un-sectioned log destination to the logger.

If a duplicate destination is added, the duplicate will be ignored.

Parameters

in_destination The destination to add.

◆ addLogDestination() [2/2]

void rstudio::launcher_plugins::logging::addLogDestination	(	const std::shared_ptr< ILogDestination > &	in_destination,
		const std::string &	in_section
	)

Adds a sectioned log destination to the logger.

If a duplicate destination is added, the duplicate will be ignored. The log destination will be registered to only record log messages with that section. A log destination may be added to multiple sections and as an un-sectioned log.

Parameters

in_destination	The destination to add.
in_section	The name of the log section to which this logger is assigned.

◆ cleanDelimiters()

std::string rstudio::launcher_plugins::logging::cleanDelimiters ( const std::string & in_str )

Helper function which cleans the log delimiter character from a string.

Parameters

in_str The string to be cleaned

Returns: The cleaned string.

◆ cleanDelims()

std::string rstudio::launcher_plugins::logging::cleanDelims ( const std::string & in_toClean )

Replaces logging delimiters with ' ' in the specified string.

Parameters

in_toClean The string from which to clean logging delimiters.

Returns: The cleaned string.

◆ hasFileLogDestination()

bool rstudio::launcher_plugins::logging::hasFileLogDestination ( )

Returns whether or not a file log destination is configured.

Returns: Whether or not a file log destination is configured.

◆ hasStderrLogDestination()

bool rstudio::launcher_plugins::logging::hasStderrLogDestination ( )

Returns whether or not a stderr log destination is configured.

Returns: Whether or not a stderr log destination is configured.

◆ isLogLevel()

bool rstudio::launcher_plugins::logging::isLogLevel ( logging::LogLevel level )

Use to write code conditioned on whether logging is configured or not.

Returns: true if log messages at this level will be displayed.

◆ logDebugAction()

void rstudio::launcher_plugins::logging::logDebugAction ( const boost::function< std::string(Optional< LogMessageProperties > * ) const &

Logs a debug message to all registered destinations by invoking an action.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::DEBUG, no log will be written.

Parameters

in_action	The action that will construct the log message if a logger is configured with debug level.
in_section	The section of the log that the message belongs in.

◆ logDebugMessage() [1/3]

void rstudio::launcher_plugins::logging::logDebugMessage	(	const std::string &	in_message,
		const ErrorLocation &	in_loggedFrom
	)

Logs a debug message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::DEBUG, no log will be written.

Parameters

in_message	The message to log as a debug message.
in_location	The location from which the error message was logged.

◆ logDebugMessage() [2/3]

void rstudio::launcher_plugins::logging::logDebugMessage	(	const std::string &	in_message,
		const std::string &	in_section,
		const Optional< LogMessageProperties > &	in_properties,
		const ErrorLocation &	in_loggedFrom
	)

Logs a debug message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::DEBUG, no log will be written.

Parameters

in_message	The message to log as a debug message.
in_section	The section of the log that the message belongs in.
in_properties	The log message properties to log.
in_location	The location from which the message was logged.

◆ logDebugMessage() [3/3]

void rstudio::launcher_plugins::logging::logDebugMessage	(	const std::string &	in_message,
		const std::string &	in_section = `std::string()`
	)

Logs a debug message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::DEBUG, no log will be written.

Parameters

in_message	The message to log as a debug message.
in_section	The section of the log that the message belongs in. Default: no section.

◆ logError() [1/2]

void rstudio::launcher_plugins::logging::logError ( const Error & in_error )

Logs an error to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::ERR, no log will be written.

Parameters

in_error The error to log.

◆ logError() [2/2]

void rstudio::launcher_plugins::logging::logError	(	const Error &	in_error,
		const ErrorLocation &	in_location
	)

Logs an error to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::ERR, no log will be written.

Parameters

in_error	The error to log.
in_errorLocation	A location higher in the stack than the ErrorLocation in in_error. Provides more context.

◆ logErrorAsDebug()

void rstudio::launcher_plugins::logging::logErrorAsDebug ( const Error & in_error )

Logs an error as a debug message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::DEBUG, no log will be written.

Parameters

in_error The error to log as a debug message.

◆ logErrorAsInfo()

void rstudio::launcher_plugins::logging::logErrorAsInfo ( const Error & in_error )

Logs an error as an info message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::INFO, no log will be written.

Parameters

in_error The error to log as an info message.

◆ logErrorAsWarning()

void rstudio::launcher_plugins::logging::logErrorAsWarning ( const Error & in_error )

Logs an error as a warning to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::WARN, no log will be written.

Parameters

in_error The error to log as a warning.

◆ logErrorMessage() [1/3]

void rstudio::launcher_plugins::logging::logErrorMessage	(	const std::string &	in_message,
		const ErrorLocation &	in_loggedFrom
	)

Logs an error to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::ERR, no log will be written.

Parameters

in_message	The message to log as an error.
in_location	The location from which the error message was logged.

◆ logErrorMessage() [2/3]

void rstudio::launcher_plugins::logging::logErrorMessage	(	const std::string &	in_message,
		const std::string &	in_section,
		const Optional< LogMessageProperties > &	in_properties,
		const ErrorLocation &	in_loggedFrom
	)

Logs an error to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::ERR, no log will be written.

Parameters

in_message	The message to log as an error.
in_section	The section of the log that the message belongs in.
in_properties	The log message properties to log.
in_location	The location from which the message was logged.

◆ logErrorMessage() [3/3]

void rstudio::launcher_plugins::logging::logErrorMessage	(	const std::string &	in_message,
		const std::string &	in_section = `std::string()`
	)

Logs an error to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::ERR, no log will be written.

Parameters

in_message	The message to log as an error.
in_section	The section of the log that the message belongs in. Default: no section.

◆ logInfoMessage() [1/3]

void rstudio::launcher_plugins::logging::logInfoMessage	(	const std::string &	in_message,
		const ErrorLocation &	in_loggedFrom
	)

Logs an info message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::INFO, no log will be written.

Parameters

in_message	The message to log as an info message.
in_location	The location from which the error message was logged.

◆ logInfoMessage() [2/3]

void rstudio::launcher_plugins::logging::logInfoMessage	(	const std::string &	in_message,
		const std::string &	in_section,
		const Optional< LogMessageProperties > &	in_properties,
		const ErrorLocation &	in_loggedFrom
	)

Logs an info message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::INFO, no log will be written.

Parameters

in_message	The message to log as an info message.
in_section	The section of the log that the message belongs in.
in_properties	The log message properties to log.
in_location	The location from which the error message was logged.

◆ logInfoMessage() [3/3]

void rstudio::launcher_plugins::logging::logInfoMessage	(	const std::string &	in_message,
		const std::string &	in_section = `std::string()`
	)

Logs an info message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::INFO, no log will be written.

Parameters

in_message	The message to log as an info message.
in_section	The section of the log that the message belongs in. Default: no section.

◆ logPassthroughMessage()

void rstudio::launcher_plugins::logging::logPassthroughMessage	(	const std::string &	in_source,
		const std::string &	in_message
	)

Logs an entire log message as is with an annotation indicating it came from source.

If no destinations are registered, no log will be written.

Parameters

in_source	The source of the log message.
in_message	The log entire log message (as would be logged by the logging engine).

◆ logWarningMessage() [1/3]

void rstudio::launcher_plugins::logging::logWarningMessage	(	const std::string &	in_message,
		const ErrorLocation &	in_loggedFrom
	)

Logs a warning message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::WARN, no log will be written.

Parameters

in_message	The message to log as a warning.
in_location	The location from which the error message was logged.

◆ logWarningMessage() [2/3]

void rstudio::launcher_plugins::logging::logWarningMessage	(	const std::string &	in_message,
		const std::string &	in_section,
		const Optional< LogMessageProperties > &	in_properties,
		const ErrorLocation &	in_loggedFrom
	)

Logs a warning message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::WARN, no log will be written.

Parameters

in_message	The message to log as a warning.
in_section	The section of the log that the message belongs in.
in_properties	The log message properties to log.
in_location	The location from which the message was logged.

◆ logWarningMessage() [3/3]

void rstudio::launcher_plugins::logging::logWarningMessage	(	const std::string &	in_message,
		const std::string &	in_section = `std::string()`
	)

Logs a warning message to all registered destinations.

If no destinations are registered, no log will be written. If the configured log level is below LogLevel::WARN, no log will be written.

Parameters

in_message	The message to log as a warning.
in_section	The section of the log that the message belongs in. Default: no section.

◆ refreshAllLogDestinations()

void rstudio::launcher_plugins::logging::refreshAllLogDestinations ( const logging::RefreshParams & in_refreshParams = logging::RefreshParams() )

Refreshes all log destinations. May be used after fork to prevent stale file handles.

Parameters

in_refreshParams Refresh params to use when refreshing the log destinations (if applicable).

◆ removeLogDestination()

void rstudio::launcher_plugins::logging::removeLogDestination	(	const std::string &	in_destinationId,
		const std::string &	in_section = `std::string()`
	)

Removes a log destination from the logger.

If a log destination does not exist with the given ID, no destination will be removed. The log will be removed from the set of default log destinations as well as any sections it has been registered to, if in_section is empty. If in_section is not empty, the log will be removed only from that section.

Parameters

in_destinationId	The ID of the destination to remove.
in_section	The name of the section from which to remove the log. Default: all sections.

◆ setProgramId()

void rstudio::launcher_plugins::logging::setProgramId ( const std::string & in_programId )

Sets the program ID for the logger.

Parameters

in_programId The ID of the program.

◆ writeError() [1/2]

std::string rstudio::launcher_plugins::logging::writeError ( const Error & in_error )

Writes an error to string.

Parameters

in_error The error to write.

Returns: The error as a string.

◆ writeError() [2/2]

std::ostream& rstudio::launcher_plugins::logging::writeError	(	const Error &	in_error,
		std::ostream &	io_os
	)

Writes an error to the specified output stream.

Parameters

in_error	The error to write.
io_os	The output stream to which to write the error.

Returns: A reference to the specified output stream.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Function Documentation

◆ addLogDestination() [1/2]

◆ addLogDestination() [2/2]

◆ cleanDelimiters()

◆ cleanDelims()

◆ hasFileLogDestination()

◆ hasStderrLogDestination()

◆ isLogLevel()

◆ logDebugAction()

◆ logDebugMessage() [1/3]

◆ logDebugMessage() [2/3]

◆ logDebugMessage() [3/3]

◆ logError() [1/2]

◆ logError() [2/2]

◆ logErrorAsDebug()

◆ logErrorAsInfo()

◆ logErrorAsWarning()

◆ logErrorMessage() [1/3]

◆ logErrorMessage() [2/3]

◆ logErrorMessage() [3/3]

◆ logInfoMessage() [1/3]

◆ logInfoMessage() [2/3]

◆ logInfoMessage() [3/3]

◆ logPassthroughMessage()

◆ logWarningMessage() [1/3]

◆ logWarningMessage() [2/3]

◆ logWarningMessage() [3/3]

◆ refreshAllLogDestinations()

◆ removeLogDestination()

◆ setProgramId()

◆ writeError() [1/2]

◆ writeError() [2/2]