Invetigate improvements to logging within Tesseract

[Levi-Armstrong]

There are two areas identified.

1. General logging by replacing console bridge with something more flexible
2. How can we improve the logging of Task Composer Pipeline. There is a lot of information in the dotgraph but is there something higher level that can be returned that is human readable a first step. There are tools for loading task composer logs for detailed introspection but looking for something in between that might work for the majority of case and not need a deep dive into the task composer log.

Potential Console Bridge Replacements that allow Custom Sinks

• easyloggingpp
• Boost.Log
• spdlog
• plog
• g3log
• abseil-cpp Log

Library	Debian Package	Async	Pros	Cons
spdlog	libspdlog-dev	✓	Very fast, header-only or compiled, zero dependencies; Optional async mode via lock-free queues	Heavy template usage can slow compile times
Boost.Log	libboost-log-dev	✓	Rich feature set (attributes, filters, formatters); Multiple built-in sinks (files, syslog, sockets)	Pulls in the entire Boost stack (large dependency); Steep learning curve
abseil-cpp	libabsl-dev	–	Familiar LOG() / CHECK() macros with streaming API; absl::AddLogSink() extensibility	No built-in rotating/file sinks; Must link against Abseil libraries; Synchronous only
easyloggingpp	libeasyloggingpp-dev	–	Single-header simplicity; Built-in dispatch callbacks	No built-in async mode; Smaller community
g3log	Not available on Debian	✓	Fully asynchronous, crash-safe logging; Dynamic runtime sink registration	Manual build & packaging required; Higher runtime footprint
plog	libplog-dev	–	Tiny header-only library; Simple API with extensible appenders	No async support; Minimal filtering capabilities
log4cplus	liblog4cplus-dev	✓	Thread-safe, Java-Log4j-style API	Synchronous by default—requires AsyncAppender for async
log4cpp	liblog4cpp5-dev	–	Flexible appenders (files, syslog, etc.); Hierarchical categories & filters	No built-in async—requires custom AsyncAppender implementation
log4cxx	liblog4cxx-dev	✓	Full Apache Log4j port with built-in AsyncAppender support	Large Apache dependency; Async setup requires XML configurator
Quill	Not available on Debian	✓	Ultra-low-latency async logging with background threads; Compile-time log-level stripping	Potential pitfalls with shared mutable data
Reckless	Not available on Debian	✓	Lock-free queue push, minimal call-site overhead	Limited community support and fewer updates
lwlog	Not available on Debian	✓	Async mode with thread-affinity control	Basic argument formatting implementation

[Levi-Armstrong]

FYI @johnwason @marip8

[Levi-Armstrong]

So far I like spdlog

• Debian-packaged available as libspdlog-dev (in bookworm and newer) so it fits your “Debian distributed” requirement
• High performance designed for speed, with both sync and optional lock-free async modes capable of millions of messages/sec
• Modular sinks trivial to write a custom sink (just subclass spdlog::sinks::sink or base_sink) to forward logs into OpenTelemetry or any other backend
• Lightweight dependency footprint header-only by default (or compiled library if you prefer), no heavy Boost linkage, and a familiar fmt-style formatting API.
• Rich, fmt-based formatting
  Leverages the fmt library for powerful, Python-style format strings (positional args, padding, hex/bin/oct formatting, alignment, precision, custom flags, etc.)
• Multiple built-in sinks
  Out-of-the-box support for console (with ANSI colors), rotating files, daily files, syslog, Windows Event Log, OutputDebugString, Qt widgets, and more.
• Asynchronous mode (optional)
  Zero-allocation, lock-free queue based async logging for high-throughput scenarios.
• Compile-time & runtime log levels
  Strip out less-important levels at compile time via SPDLOG_ACTIVE_LEVEL and adjust thresholds at runtime with set_level().
• Backtrace support
  Ring-buffer storage of recent debug messages that you can dump on demand (e.g. when an error occurs).
• Periodic flush
  Built-in flush_every() utility to automatically flush all registered loggers on a timer.
• Stopwatch utility
  A simple spdlog::stopwatch type to measure and log elapsed time with minimal ceremony.
• Global registry & named loggers
  Create and retrieve loggers by name via spdlog::get("name"), with a process-wide registry under the hood.
• Multi-threaded vs. single-threaded loggers
  Choose _mt or _st variants to explicitly control thread-safety, minimizing overhead when you don’t need synchronization.
• Environment- and argv-driven configuration
  Load log levels (and even patterns) from command-line arguments or environment variables for easy deployment tuning.
• Custom error handlers
  Hook into formatting or sink errors via spdlog::set_error_handler() to recover from internal logger failures gracefully.
• Binary data logging
  Helpers like spdlog::to_hex() let you dump raw buffers in hex, with options for uppercase, no delimiters, ASCII annotations, etc.

[johnwason]

I think we need to have a "record" structure that contains more information about the errors rather than just having string output. I'd like to have errors that are machine readable so that we can make decisions based on the output automatically. For example, we should have a string "code" like org.tesseract-robotics.error.Collision or org.tesseract-robotics.error.InfeasableWaypoint that corresponds to the problem. GCC uses string codes to describe the compiler errors, although they don't use Java style scoping. (These error names are examples .) Some examples from my other projects are the record type for Robot Raconteur:
https://github.com/robotraconteur/robotraconteur/blob/0fe6efd8c448f68ae6c33c261b9df734b372ee47/RobotRaconteurCore/include/RobotRaconteur/Logging.h

class ROBOTRACONTEUR_CORE_API RRLogRecord
{
  public:
    /** @brief The source node */
    RR_WEAK_PTR<RobotRaconteurNode> Node;
    /** @brief The log level */
    RobotRaconteur_LogLevel Level;
    /** @brief The source component */
    RobotRaconteur_LogComponent Component;
    /** @brief The source component name */
    std::string ComponentName;
    /** @brief The source component object ID */
    std::string ComponentObjectID;
    /** @brief The source endpoint */
    int64_t Endpoint;
    /** @brief The service path of the source object */
    std::string ServicePath;
    /** @brief The source member */
    std::string Member;
    /** @brief Human readable log message */
    std::string Message;
    /** @brief Time of logging event */
    boost::posix_time::ptime Time;
    /** @brief The sourcecode filename */
    std::string SourceFile;
    /** @brief The line within the sourcecode file */
    uint32_t SourceLine;
    /** @brief The source thread */
    std::string ThreadID;
    /** @brief The source coroutine fiber */
    std::string FiberID;

    RRLogRecord();
};

A more interesting example is the EventLog structure types from Robot Raconteur that are based on the types of log messages on industrial devices:

enum EventLogLevel
    undefined = 0,
    trace = 1,
    debug,
    info,
    warning,
    error,
    safety_violation_error,
    fatal_error,
    emergency_error,
    catastrophic_error
end

struct EventLogType
    field Identifier event_category
    field string event_type
end

struct EventLogMessageHeader
    field EventLogType type
    field EventLogLevel level
    field Identifier source_device
    field string source_component
    field string source_object
    field uint64 message_number
    field DateTimeUTC timestamp
end

struct EventLogMessage
    field EventLogMessageHeader header
    field string title
    field string message
    field varvalue{string} extended
end

struct EventLogInfo
    field DeviceInfo device_info
    field Identifier logged_device
    field uint64 min_message_number
    field uint64 max_message_number
    field varvalue{string} extended
end

In Robot Raconteur an Identifier is a combination of a qualified string name and/or a UUID. See https://github.com/robotraconteur/robotraconteur_standard_robdef/blob/master/docs/group1/com.robotraconteur.identifier.md . The extended field allows for arbitrary parameters to be attached to the message.