Warning, /eic-opticks/sysrap/SLOG.rst is written in an unsupported language. File is not indexed.
0001 SLOG : Logging Infrastructure
0002 =================================
0003
0004 This was formerly within SLOG.hh but as touching
0005 that header causes a full build of everything
0006 have moved docs into this separate file.
0007
0008 Opticks initialization
0009 ------------------------
0010
0011 Opticks executables follow the following pattern.
0012
0013 .. code-block:: c
0014
0015
0016 #include "OPTICKS_LOG.hh" // brings in separate headers for each projects logger depending on defines such as OPTICKS_GGEO
0017
0018 int main(int argc, char** argv)
0019 {
0020 OPTICKS_LOG(argc, argv); // pass arguments to SLOG_ macro
0021
0022 // ... exercise Opticks ...
0023
0024 return 0 ;
0025 }
0026
0027
0028
0029 OPTICKS_LOG is a macro from OPTICKS_LOG.hh that must be placed in the main program::
0030
0031 #define OPTICKS_LOG(argc, argv) { SLOG_COLOR(argc, argv); OPTICKS_LOG_::Initialize(SLOG::instance, plog::get(), NULL ); }
0032
0033 The SLOG_COLOR macro from SLOG_INIT.hh creates two static appenders in the main compilation unit::
0034
0035 #define SLOG_COLOR(argc, argv) \
0036 { \
0037 SLOG* _plog = new SLOG(argc, argv); \
0038 static plog::RollingFileAppender<plog::TxtFormatter> fileAppender( _plog->filename, _plog->maxFileSize, _plog->maxFiles ); \
0039 static plog::ColorConsoleAppender<plog::TxtFormatter> consoleAppender; \
0040 SLOG_INIT( _plog->level, &consoleAppender, &fileAppender ); \
0041 } \
0042
0043 The SLOG_INIT macro also from SLOG_INIT.hh applies plog::init to the main consoleAppender and adds the fileAppender::
0044
0045 #define SLOG_INIT(level, app1, app2 ) \
0046 { \
0047 plog::IAppender* appender1 = static_cast<plog::IAppender*>(app1) ; \
0048 plog::IAppender* appender2 = static_cast<plog::IAppender*>(app2) ; \
0049 plog::Severity severity = static_cast<plog::Severity>(level) ; \
0050 plog::init( severity , appender1 ); \
0051 if(appender2) \
0052 plog::get()->addAppender(appender2) ; \
0053 } \
0054
0055
0056 The subsequent OPTICKS_LOG_::Initialize passes the primary instance returned by plog::get() in the
0057 main compilation unit to the static logging setup in each of the shared object libraries selected
0058 by compilation defines such as OPTICKS_SYSRAP, OPTICKS_BRAP.
0059
0060 Extracts from OPTICKS_LOG.hh showing the OPTICKS_LOG_::Initialize::
0061
0062 ...
0063 #ifdef OPTICKS_SYSRAP
0064 #include "SYSRAP_LOG.hh"
0065 #endif
0066 #ifdef OPTICKS_BRAP
0067 #include "BRAP_LOG.hh"
0068 #endif
0069 #ifdef OPTICKS_NPY
0070 #include "NPY_LOG.hh"
0071 #endif
0072
0073 ...
0074
0075 class SYSRAP_API OPTICKS_LOG_ {
0076 public:
0077 // initialize all linked loggers and hookup the main logger
0078 static void Initialize(SLOG* instance, void* app1, void* app2 )
0079 {
0080 int max_level = instance->parse("info") ;
0081 // note : can decrease verbosity from the max_level in the subproj, but not increase
0082
0083 #ifdef OPTICKS_SYSRAP
0084 SYSRAP_LOG::Initialize(instance->prefixlevel_parse( max_level, "SYSRAP"), app1, NULL );
0085 #endif
0086 #ifdef OPTICKS_BRAP
0087 BRAP_LOG::Initialize(instance->prefixlevel_parse( max_level, "BRAP"), app1, NULL );
0088 #endif
0089 #ifdef OPTICKS_NPY
0090 NPY_LOG::Initialize(instance->prefixlevel_parse( max_level, "NPY"), app1, NULL );
0091 #endif
0092
0093
0094 From SYSRAP_LOG.cc::
0095
0096 void SYSRAP_LOG::Initialize(int level, void* app1, void* app2 )
0097 {
0098 SLOG_INIT(level, app1, app2);
0099 }
0100
0101
0102 The somewhat bizarre usage implementation based on preprocessor
0103 macros allows the static logger symbols to be planted within
0104 each of the shared objects in a manner that works on Mac, Linux
0105 and Windows.
0106
0107 The structure was based on the Chained example from my fork of the upstream plog
0108
0109 * https://github.com/simoncblyth/plog/tree/master/samples/Chained
0110
0111 The structure relies on the static plog instances in all of the libraries and
0112 those in the main being distinct which means that it needs
0113 compilation options::
0114
0115 -fvisibility=hidden
0116 -fvisibility-inlines-hidden
0117
0118 These are configured in cmake/Modules/OpticksCXXFlags.cmake
0119 The big advantage of this is that the logging level can be
0120 individually controlled for each of the libraries.
0121
0122 Notice that without this hidden visibility you will get perplexing failures, of form::
0123
0124 CSGOptiXSimtraceTest: /data/blyth/junotop/ExternalLibs/opticks/head/externals/plog/include/plog/Logger.h:22: plog::Logger<instance>& plog::Logger<instance>::addAppender(plog::IAppender*) [with int instance = 0]: Assertion `appender != this' failed.
0125
0126
0127 For details see notes/issues/plog-appender-not-equal-this-assert.rst
0128
0129
0130
0131 *SLOG* parses command line arguments and configures the
0132 logging level of each project, for example:
0133
0134 .. code-block:: sh
0135
0136 OpticksResourceTest --sysrap trace --npy info # lower cased tags identify the projects
0137 GGeoViewTest --npy debug
0138
0139 Available logging levels are:
0140
0141 * *trace* : most verbose level, providing a great deal of output
0142 * *debug*
0143 * *info* : normal default logging level
0144 * *warning*
0145 * *error*
0146 * *fatal*
0147
0148
0149 The tags for each project are listed below.
0150
0151 ======================= ============================
0152 Project Folder Tag
0153 ======================= ============================
0154 sysrap SYSRAP
0155 boostrap BRAP
0156 opticksnpy NPY
0157 optickscore OKCORE
0158 ggeo GGEO
0159 assimprap ASIRAP
0160 openmeshrap MESHRAP
0161 opticksgeo OKGEO
0162 oglrap OGLRAP
0163 cudarap CUDARAP
0164 thrustrap THRAP
0165 optixrap OXRAP
0166 opticksop OKOP
0167 opticksgl OKGL
0168 ok OK
0169 cfg4 CFG4
0170 ======================= ============================
0171
0172
0173
0174
0175
0176
0177
0178 older low level approach
0179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0180
0181 This old approach has been replaced by the OPTICKS_LOG
0182 approach described above, although some test executables
0183 have yet to be updated.
0184
0185 .. code-block:: c
0186
0187
0188 #include "SYSRAP_LOG.hh" // headers for each projects logger
0189 #include "BRAP_LOG.hh"
0190 #include "NPY_LOG.hh"
0191 #include "OKCORE_LOG.hh"
0192
0193 #include "SLOG.hh" // infrastructure header
0194
0195 int main(int argc, char** argv)
0196 {
0197 SLOG_(argc, argv); // pass arguments to SLOG_ macro
0198
0199 SYSRAP_LOG__ ; // setup loggers for all projects you want to see output from
0200 BRAP_LOG__ ;
0201 NPY_LOG__ ;
0202 OKCORE_LOG__ ;
0203
0204 Opticks ok(argc, argv);
0205
0206 // ... exercise Opticks ...
0207
0208 return 0 ;
0209 }
0210
0211
0212
0213
0214 Changing SLOG formatter
0215 -------------------------
0216
0217 Sometimes when debugging prefer shorter logging::
0218
0219 epsilon:Formatters blyth$ opticks-f MessageOnlyFormatter
0220 ./sysrap/tests/PLogTest.cc:#include <plog/Formatters/MessageOnlyFormatter.h>
0221 ./sysrap/tests/PLogTest.cc: //typedef plog::MessageOnlyFormatter FMT ;
0222 ./sysrap/SLOG_INIT.hh:#include <plog/Formatters/MessageOnlyFormatter.h>
0223 ./sysrap/SLOG_INIT.hh://typedef plog::MessageOnlyFormatter FMT ; // really minimal
0224 epsilon:opticks blyth$
0225
0226
0227 Can do that by changing the typedef in SLOG_INIT.hh::
0228
0229 31 typedef plog::FuncMessageFormatter FMT ; // useful to avoid dates and pids when comparing logs
0230 32 //typedef plog::MessageOnlyFormatter FMT ; // really minimal
0231 33 //typedef plog::TxtFormatter FMT ; // default full format
0232 34 //typedef plog::CsvFormatter FMT ; // semicolon delimited full format
0233 35
0234
0235 Unfortunately that forces full recompile of everything
0236
0237
0238
