Loading
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") andNS_LOG_FILTER_NODES(e.g.,"0,2,*"). - Programmatic API: Full C++ API available via
LogSetTimeFilter(),LogSetNodeFilter(), andLogAddNodeFilter().
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_LOGmacros now evaluate a single global boolean (g_logFilterActive) viaLogFilterCheck()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.ccsits at the very bottom of the dependency tree and cannot includens3/simulator.h), this implementation introducesLogTimeProviderandLogNodeProvidercallbacks. These are registered bysimulator.ccduring instantiation, mirroring the existingTimePrinter/NodePrinterdesign pattern. - Cache-Friendly Lookups: The node filter utilizes a
std::vector<uint32_t>instead of astd::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-filtertest suite (src/core/test/log-filter-test-suite.cc) containing 10 unit test cases that cover open/closed time windows, multi-node filters,NO_CONTEXTsuppression, and combined AND logic. - The test suite handles the fact that macro outputs are suppressed in
optimizedbuilds by safely wrapping capturing tests in#ifdef NS3_LOG_ENABLE. - Passed all core module regression tests.
- Code conforms to
.clang-formatstyling.
Edited by Ayush Suri