Outdated implementation checklist for logging revamp, DO NOT USE

logging_checklist_do_not_use.md

Outdated implementation checklist for logging revamp

DO NOT USE

Contentious issues

What should be the type of "tag", for log filtering purpose?

struct LogTag { const char* name; LogLevel* logLevel; }; LogManager::registerLogTag(const LogTag& logTag); LogTag LogManager::getLogTag(const char* name); LogManager::setLogLevelByTagName(const char* name, LogLevel logLevel); LogManager::setLogLevelForTag(const LogTag& logTag, LogLevel logLevel); // merely writes to the pointer

• Option 1: a C/C++ string.
  • Consequence: to use the tag, string comparison must be performed at each call.
• Option 2: a C/C++ identifier (could be a variable, type name, special const such as NULL, etc)
  • Option 2a: a C/C++ variable name
    • Advantage: variable can be accessed directly
    • Drawback: cannot externally access variable by name (e.g. string from env config)
    • Drawback: each compilation unit need to make sure every tag they specify correspond to a variable with that name.
  • Option 2b: a C/C++ struct variable
    • Best of both

Checklist for core module changes

• New logging macro (tentative name: CV_NEWLOG)

  • Allow compilation units to override some behavior without redefining the main logging macro

• Mapping existing logging macros to new logging macro (see Legacy Compat Spec)

• Allow legacy no-tag logging by specifying tag=NULL (see Legacy Compat Spec)

• Handling for verbose sub-level (see Legacy Compat Spec)

• Allow tagged logging (see Spec)

  • Exact tag name match (string comparison)
    • Allow alternate log level on exact tag name match
    • Parsing environ config for exact tag name and level
  • Wildcard or regex tag name match (see Future Extensions)

• Allow compilation units to define their own const or mutable log level variables

• Implement backend switchability

• Capture relationship between threads when doing work inside cv::ParallelLoopBody

• Implement string formatter switchability (for example fmtlib)

• Implement large matrix logging (frontend and backend work)

• Implement binary blob logging (frontend and backend work)

Checklist for core module changes

• LogMeta class, and classes for pieces of metadata, such as LogLoc, LogObjInfo, LogModuleInfo
• Global filter function that accept LogMeta class, and default implementation
• CV_LOGMETA macro
• Updated existing CV_LOG_(INFO, WARNING, etc) macros to use CV_LOGMETA
• Change backend function prototype (cv::utils::logging::internal::writeLogMessage) to accept LogMeta (or its data members) so that backends that can benefit from those data can use them programmatically without parsing from strings.

Checklist for required changes in every OpenCV module

Checklist for long-term improvement changes in every OpenCV module

• For modules that could use logging but don't have it, add some, strategically.
• For modules that use logging badly, fix those issues
• Where applicable, include LogObjInfo (CV_LOG_THIS) into LogMeta to help identify object instances
• Replace kludge, such as in stitching module