RStudio Launcher Plugin SDK  1.1.3
A software development kit for creating plugins that work the the RStudio Launcher.
Classes | Typedefs | Enumerations | Functions | Variables
Logger.hpp File Reference
#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>

Go to the source code of this file.

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_destinationThe 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_destinationThe destination to add.
in_sectionThe 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_strThe 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_toCleanThe 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_actionThe action that will construct the log message if a logger is configured with debug level.
in_sectionThe 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_messageThe message to log as a debug message.
in_locationThe 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_messageThe message to log as a debug message.
in_sectionThe section of the log that the message belongs in.
in_propertiesThe log message properties to log.
in_locationThe 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_messageThe message to log as a debug message.
in_sectionThe 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_errorThe 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_errorThe error to log.
in_errorLocationA 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_errorThe 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_errorThe 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_errorThe 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_messageThe message to log as an error.
in_locationThe 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_messageThe message to log as an error.
in_sectionThe section of the log that the message belongs in.
in_propertiesThe log message properties to log.
in_locationThe 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_messageThe message to log as an error.
in_sectionThe 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_messageThe message to log as an info message.
in_locationThe 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_messageThe message to log as an info message.
in_sectionThe section of the log that the message belongs in.
in_propertiesThe log message properties to log.
in_locationThe 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_messageThe message to log as an info message.
in_sectionThe 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_sourceThe source of the log message.
in_messageThe 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_messageThe message to log as a warning.
in_locationThe 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_messageThe message to log as a warning.
in_sectionThe section of the log that the message belongs in.
in_propertiesThe log message properties to log.
in_locationThe 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_messageThe message to log as a warning.
in_sectionThe 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_refreshParamsRefresh 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_destinationIdThe ID of the destination to remove.
in_sectionThe 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_programIdThe 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_errorThe 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_errorThe error to write.
io_osThe output stream to which to write the error.
Returns
A reference to the specified output stream.