Logging configuration

The logging in neuray is done using an abstract C++ interface class with one member function which is called by neuray whenever some part of the system needs to emit a log message. You can provide a log object, which is an implementation of this abstract interface, and register it with the Iray API. Only one log object can be registered with a neuray process at any time.

In a multi-hosted system all log messages will be sent to an elected logging host. This host will pass all hosts' log messages to the log object of that host. You can influence the log election process to favor a certain host.

Each log message will come with an associated log level and with a log category. You can decide which log messages to report to the user. The method of the log object that you have registered with the Iray API can be called at any time by any thread in the neuray system including application threads which initiated operations in neuray. The log object must be implemented to handle this concurrency properly.

You can configure a log verbosity level and neuray will pre-filter the log messages to avoid the processor load associated with generating log messages which are never presented to the user.

example_configuration.cpp demonstrates how to configure the logging behavior of neuray. You can customize the logging behavior of neuray by providing your own logging object. This object has to implement the mi::base::ILogger interface. A very minimal implementation that prints all messages to stderr is shown in example_configuration.cpp. A similar implementation is used by default if you do not provide your own implementation.

example_configuration.cpp

001 /******************************************************************************
002  * © 1986, 2014 NVIDIA Corporation. All rights reserved.
003  *****************************************************************************/
004 
005 // examples/example_configuration.cpp
006 
007 #include <mi/neuraylib.h>
008 
009 // Include code shared by all examples.
010 #include "example_shared.h"
011 
012 class Logger : public mi::base::Interface_implement<mi::base::ILogger>
013 {
014 public:
015     void message(
016         mi::base::Message_severity level, const char* module_category, const char* message)
017     {
018         const char* log_level = get_log_level( level);
019         fprintf( stderr, "Log level = '%s', module:category = '%s', message = '%s'\n",
020             log_level, module_category, message);
021     }
022 
023 private:
024     const char* get_log_level( mi::base::Message_severity level)
025     {
026         switch( level) {
027             case mi::base::MESSAGE_SEVERITY_FATAL:
028                 return "FATAL";
029             case mi::base::MESSAGE_SEVERITY_ERROR:
030                 return "ERROR";
031             case mi::base::MESSAGE_SEVERITY_WARNING:
032                 return "WARNING";
033             case mi::base::MESSAGE_SEVERITY_INFO:
034                 return "INFO";
035             case mi::base::MESSAGE_SEVERITY_VERBOSE:
036                 return "VERBOSE";
037             case mi::base::MESSAGE_SEVERITY_DEBUG:
038                 return "DEBUG";
039             default:
040                 return "";
041         }
042     }
043 };
044 
045 int main( int /*argc*/, char* /*argv*/[])
046 {
047     // Access the neuray library
048     mi::base::Handle<mi::neuraylib::INeuray> neuray( load_and_get_ineuray());
049     check_success( neuray.is_valid_interface());
050 
051     // Create an instance of our logger
052     mi::base::Handle<mi::base::ILogger> logger( new Logger());
053 
054     // Open new block to ensure that all handles except neuray went out of scope
055     // when calling shutdown() after the end of this block.
056     {
057 
058         // Configure the neuray library before startup. Here we set our own logger.
059         check_success( neuray->get_status() == mi::neuraylib::INeuray::PRE_STARTING);
060         mi::base::Handle<mi::neuraylib::ILogging_configuration> logging_configuration(
061             neuray->get_api_component<mi::neuraylib::ILogging_configuration>());
062         check_success( logging_configuration.is_valid_interface());
063         logging_configuration->set_receiving_logger( logger.get());
064 
065         // other configuration settings go here, none in this example
066 
067         // Start the neuray library
068         check_success( neuray->start() == 0);
069         check_success( neuray->get_status() == mi::neuraylib::INeuray::STARTED);
070 
071         // scene graph manipulations and rendering calls go here, none in this example.
072     }
073 
074     // Shut down the library
075     check_success( neuray->shutdown() == 0);
076     check_success( neuray->get_status() == mi::neuraylib::INeuray::SHUTDOWN);
077     neuray = 0;
078 
079     // Unload the neuray library
080     check_success( unload());
081 
082     keep_console_open();
083     return EXIT_SUCCESS;
084 }