VisiBroker for C++ Logging

This chapter describes the classes that support VisiBroker for C++ logging.

VISDLoggerMgr

This class is a bootstrap class into the functionality provided by the logging library vdlog.

Include file

Include the vdlog.h file when you use this class.

VISDLoggerMgr methods

static VISDLoggerMgr_ptr instance();

Static function to access a singleton instance of VISDLoggerMgr.

CORBA::Boolean global_log_enabled();

Returns true if the global log switch is enabled, else false.

void global_log_enabled(CORBA::Boolean b);

Setter method for the global log level switch.

Parameter	Description
b	Boolean value to enable or disable the global log level switch.

VISDLogLevel::Level global_log_level();

Returns the current global log level (verbosity) setting on the log manager.

void global_log_level(VISDLogLevel::Level l);

Setter for the global log level on the log manager.

Parameter	Description
l	Global verbosity setting.

VISDLogger_ptr get_default_logger();

Returns the default logger. If not created, creates and returns. The name of the returned logger is “default”.

VISDLogger_ptr get_logger(const char* name, VISDAppender_ptr* apps = NULL, CORBA::Short num_apps = 0);

Creates (if not created) and returns a logger with the given name.

Parameter	Description
name	Input name of the logger.
apps	Pointer to an array of appender pointers indicating an initial list of appenders for the logger.
num_apps	Number of appenders in the array of appender pointer.

void register_app_factory(VISDAppenderFactory* fac);

API for custom appender factories to register themselves with the logger framework. Factory will be added to a dictionary of appender factories indexed by its name. If a factory is not registered with the framework, then an instance of its type cannot be created.

Parameter	Description
fac	Appender factory to be registered.

VISDAppender_ptr create_app(const char* logger_name, VISDConfig::LogAppenderConfig_ptr p);

API to create an appender for the logger specified by its name using the configuration information pointed.

Parameter	Description
logger_name	Name of the logger for which the appender instance is to be created.
p	Pointer to the logger appender instance configuration.

void register_lyt_factory(VISDLayoutFactory* fact);

API for custom layout factories to register themselves with the logger framework.

Parameter	Description
fact	Pointer to the implemented layout factory to be registered.

VISDLayout_ptr create_lyt(const char* logger_name, VISDConfig::LogAppenderConfig_ptr p);

API to create a layout instance.

Parameter	Description
logger_name	Name of the logger in which the appender instance is associated which needs to use the layout.
p	Pointer to the logger appender instance configuration.

VISDLogger

Class providing the logging interface.

Include file

Include the vdlog.h file when you use this class.

VISDLogger methods

const char* name() const;

Returns the name of the logger object.

void log(VISDLogLevel::Level level, const char* component, const char* message, const char *sourcefile = NULL, CORBA::ULong linenum = 0, const void *bindata = NULL, size_t binsize = 0)

API to log messages.

Parameter	Description
level	Log level of the logged message.
component	Source name from where the message is being logged. The source name is the logical module name that can be useful during filtering.
message	Logged message data.
sourcefile	Source file name from where the message is being logged.
linenum	Source file line number from where the message is being logged.
bindata	Binary data pointer.
binsize	Size of any binary data.

VISDAppenderFactory

Interface for appender factory implementations to implement. The logger framework calls on this interface for appender instance creation.

Include file

Include the vdlog.h file when you use this class.

VISDAppenderFactory methods

virtual const char* type_name() = 0;

This method is invoked by the logger framework when it needs to know the type of the factory. For example, when a factory registers itself with the logger manager, this API is called to get the type name. The type name identifies the type of destination to which its appenders will forward the logger. Type names “stdout”, “rolling” and others as mentioned in the developer guide are restricted from usage. Should return back a unique type name for the appender type.

virtual VISDAppender_ptr create(const char* logger_name, VISDConfig::LogAppenderConfig_ptr p) = 0;

This method is invoked by the logger framework when it needs to create an instance of the appender supported by this factory. The return value should be an instance of desired appender.

Parameter	Description
logger_name	Name of the logger with which the appender instance is to be associated.
p	Pointer to the logger’s appender instance configuration.

virtual void destroy(VISDAppender_ptr p) = 0;

This method is invoked by the logger framework when it is done with using the appender instance. The API is supposed to remove all resources dedicated to the appender instance when it was created.

Parameter	Description
p	Pointer to the appender instance that is to be destroyed.

VISDAppender

class VISDAppender : public VISResource

Interface providing the appender interface. The logger object uses this interface to log to specific destinations.

Include file

Include the vdlog.h file when you use this class.

VISDAppender methods

virtual VISDAppenderFactory* factory() = 0;

Should return the associated factory object which created this appender instance.

virtual CORBA::Boolean append(const VISDLogRecord& record) = 0;

API used by the logger to forward the log message to a specific destination. The log record abstracts the complete log message. On successful completion of forwarding, the API should return TRUE.

Parameter	Description
record	The log record to be appended to the destination.

virtual CORBA::Boolean ORB_initialized(void* orb_ptr) = 0;

This is a notification from the ORB that it has initialized. If an appender is going to use any of the ORB functionality, then it needs to wait for this notification and return back TRUE. Otherwise, it should return back FALSE.

After this notification, the appender can start using any of the ORB interfaces.

Parameter	Description
orb_ptr	Reference to the ORB.

virtual void ORB_shutdown() = 0;

This is a notification from the ORB that it is shutting down. If the appender is using any ORB functionality, then it needs to stop using that after this notification.

VISDLayoutFactory

Interface for layout factory implementations to implement. The logger framework calls on this interface for layout instance creation.

Include file

Include the vdlog.h file when you use this class.

VISDLayoutFactory methods

virtual const char* type_name() = 0;

Returns the type name of the layout that this factory will create.

virtual VISDLayout_ptr create(const char* logger_name, VISDConfig::LogAppenderConfig_ptr p) = 0;

Should creates a layout instance. This API is called by the logger framework when an instance of the layout is desired.

Parameter	Description
logger_name	Name of the logger whose associated appender instance needs this layout instance.
p	Pointer to the logger's appender instance configuration.

virtual void destroy(VISDLayout_ptr layout) = 0;

Framework calls this API when it is done with usage of the layout and needs to factory to destroy the instance.

Parameter	Description
layout	Pointer to the layout instance that needs to be destroyed.

VISDLayout

class VISDLayout : public VISResource

Interface which all layout instances should implement. Appenders which desire to format the log message before outputting to the desired destination will make use of this interface.

Include file

Include the vdlog.h file when you use this class.

VISDLayout methods

virtual VISDLayoutFactory* factory() = 0;

Should return the factory of the layout instance that created it.

virtual void format(const VISDLogRecord& record, char*
buf, CORBA::ULong buf_size, CORBA::String_var&
other_buf) = 0;

API that is called by the appender instances for formatting the log record. The appender allocates buffer and sends the buffer into this API and expects the layout to format the message and set in this buffer. However, if the layout wants more memory than that has been sent to it by the appender, then it can itself allocate memory and make use of other_buf.

Parameter	Description
record	Log record containing the log message.
buf	Memory buffer sent by the appender onto which the layout can set the formatted message.
buf_size	Size of the memory buffer sent in by the appender.
other_buffer	If the layout needs more memory than that sent by the appender, then it can allocate memory into this buffer and set the formatted text into it.

VISDConfig

Namespace class for configuration structures.

Include file

Include the vdlog.h file when you use this class.

LogAppenderConfig structure

struct LogAppenderConfig {
CORBA::String_var appender_name;
CORBA::String_var appender_type;
CORBA::String_var layout_type;
};
typedef LogAppenderConfig* LogAppenderConfig_ptr;

This structure contains a single appender instance configuration on a logger. This is filled and passed to the factory interfaces by the logger framework after reading from the configurations.

Parameter	Description
appender_name	Name of the appender instance configured on the logger.
appender_type	The type name of the appender instance. This implies which appender factory needs to be used.
layout_type	The type name of the layout instance desired. Again this implies which layout factory should be used to obtain layout instance.

VISDLogRecord

Class abstracting a log message. Apart from the actual log message, it also captures various other states such as thread id, timestamp parameter, and others.

Include file

Include the vdlog.h file when you use this class.

VISDLogRecord methods

Timestamp get_timestamp() const;

Returns the timestamp of the log record.

CORBA::ULong get_seq_number() const;

Returns a sequence number if many log records are logged at the same time interval.

CORBA::ULong get_process_id() const;

Returns the process id.

CORBA::ULong get_thread_id() const;

Returns the thread id of the thread that logged this message.

const char* get_thread_name() const;

If the thread is named, then it returns the thread name.

const char* get_logger_name() const;

Returns the logger object's name.

VISDLogLevel::Level get_log_level() const;

Returns the verbosity of the logged message.

const char* get_component_name() const;

Returns the source name of the source that logged the message.

const char* get_filename() const;

Returns the name of the file that logged the message.

CORBA::ULong get_line_number() const;

Returns the line number in the file from where the log message is emanating.

const char* get_message() const;

This is the actual logged message.

const unsigned char* get_bindata() const;

Returns any binary data that is piggybacking on the log record.

size_t get_binsize() const;

Returns the size of the binary data.

VISDLogLevel

Class enclosing the verbosity enumeration Level.

Include file

Include the vdlog.h file when you use this class.

Level enumeration

enum Level {

OFF_ = 1000,
EMERG_ = 800,
EXCEP_ = 800,
FATAL_ = 800,
ALERT_ = 700,
CRIT_ = 600,
ERROR_ = 500,
WARN_ = 400,
NOTICE_ = 300,
INFO_ = 200,
DEBUG_ = 100,

ALL_ = 0,

DEFAULT_ = -1

};