core: (fixes #83) Add filtering capability to log outputs

Resolves #83 by introducing high-performance, non-intrusive filtering capabilities to the ns-3 logging system. This allows users to suppress log messages based on simulation time windows and/or node IDs at runtime, avoiding the overhead of post-processing massive log files.

Key Features:

  • Time Window Filtering: Configure a specific time range [start, end] within which logs are emitted.
  • Node Context Filtering: Focus logs on specific node IDs (or a set of nodes).
  • Environment Variable Support: Configure filters without touching C++ code using NS_LOG_FILTER_TIME (e.g., "1.5s:3.0s") and NS_LOG_FILTER_NODES (e.g., "0,2,*").
  • Programmatic API: Full C++ API available via LogSetTimeFilter(), LogSetNodeFilter(), and LogAddNodeFilter().

Design Note: Filtering is performed before log message construction (inside the NS_LOG macro, after the severity-level check but before any std::clog << msg formatting). This ensures zero string-formatting overhead for filtered-out messages.

Architecture & Performance Details:

  • Zero-Overhead Fast Path: The NS_LOG macros now evaluate a single global boolean (g_logFilterActive) via LogFilterCheck() after the initial severity check. If no filters are active, the overhead is reduced to a single branch.
  • Strict Dependency Layering: To avoid circular dependencies (as log.cc sits at the very bottom of the dependency tree and cannot include ns3/simulator.h), this implementation introduces LogTimeProvider and LogNodeProvider callbacks. These are registered by simulator.cc during instantiation, mirroring the existing TimePrinter/NodePrinter design pattern.
  • Cache-Friendly Lookups: The node filter utilizes a std::vector<uint32_t> instead of a std::set. Because node filters typically contain only 1-5 nodes, contiguous memory linear searches significantly outperform tree traversal.

API Additions/Changes

Added the following public APIs in a new ns3/log-filter.h header:

  • LogSetTimeFilter(int64_t start, int64_t end) / LogClearTimeFilter()
  • LogSetNodeFilter(const std::vector<uint32_t>& nodes, bool includeNoContext) / LogAddNodeFilter(uint32_t nodeId) / LogClearNodeFilter()

Testing & Verification

  • Added the log-filter test suite (src/core/test/log-filter-test-suite.cc) containing 10 unit test cases that cover open/closed time windows, multi-node filters, NO_CONTEXT suppression, and combined AND logic.
  • The test suite handles the fact that macro outputs are suppressed in optimized builds by safely wrapping capturing tests in #ifdef NS3_LOG_ENABLE.
  • Passed all core module regression tests.
  • Code conforms to .clang-format styling.
Edited by Ayush Suri

Merge request reports

Loading
Loading