From 0f3811b93393bb754c6c558140f7d2c9e40e7c64 Mon Sep 17 00:00:00 2001 From: myk002 Date: Fri, 22 Jul 2022 17:46:11 -0700 Subject: [PATCH] update debugfilter docs --- docs/plugins/debug.rst | 149 ++++++++++++++++++----------------------- plugins/debug.cpp | 121 +++++---------------------------- 2 files changed, 81 insertions(+), 189 deletions(-) diff --git a/docs/plugins/debug.rst b/docs/plugins/debug.rst index 2bef7d28a..331e675ab 100644 --- a/docs/plugins/debug.rst +++ b/docs/plugins/debug.rst @@ -1,89 +1,72 @@ debug ===== -Manager for DFHack runtime debug prints. Debug prints are grouped by plugin name, -category name and print level. Levels are ``trace``, ``debug``, ``info``, -``warning`` and ``error``. + +Tags: +:dfhack-keybind:`debugfilter` + +:index:`Configure verbosity of DFHack debug output. +` Debug output is +grouped by plugin name, category name, and verbosity level. + +The verbosity levels are: + +- ``Trace`` + Possibly very noisy messages which can be printed many times per second. +- ``Debug`` + Messages that happen often but they should happen only a couple of times per + second. +- ``Info`` + Important state changes that happen rarely during normal execution. +- ``Warning`` + Enabled by default. Shows warnings about unexpected events which code + managed to handle correctly. +- ``Error`` + Enabled by default. Shows errors which code can't handle without user + intervention. The runtime message printing is controlled using filters. Filters set the -visible messages of all matching categories. Matching uses regular expression syntax, -which allows listing multiple alternative matches or partial name matches. -This syntax is a C++ version of the ECMA-262 grammar (Javascript regular expressions). -Details of differences can be found at +visible messages of all matching categories. Matching uses regular expression +syntax, which allows listing multiple alternative matches or partial name +matches. This syntax is a C++ version of the ECMA-262 grammar (Javascript +regular expressions). Details of differences can be found at https://en.cppreference.com/w/cpp/regex/ecmascript -Persistent filters are stored in ``dfhack-config/runtime-debug.json``. -Oldest filters are applied first. That means a newer filter can override the -older printing level selection. - -Usage: ``debugfilter [subcommand] [parameters...]`` - -The following subcommands are supported: - -help ----- -Give overall help or a detailed help for a subcommand. - -Usage: ``debugfilter help [subcommand]`` - -category --------- -List available debug plugin and category names. - -Usage: ``debugfilter category [plugin regex] [category regex]`` - -The list can be filtered using optional regex parameters. If filters aren't -given then the it uses ``"."`` regex which matches any character. The regex -parameters are good way to test regex before passing them to ``set``. - -filter ------- -List active and passive debug print level changes. - -Usage: ``debugfilter filter [id]`` - -Optional ``id`` parameter is the id listed as first column in the filter list. -If id is given then the command shows information for the given filter only in -multi line format that is better format if filter has long regex. - -set ---- -Creates a new debug filter to set category printing levels. - -Usage: ``debugfilter set [level] [plugin regex] [category regex]`` - -Adds a filter that will be deleted when DF process exists or plugin is unloaded. - -Usage: ``debugfilter set persistent [level] [plugin regex] [category regex]`` - -Stores the filter in the configuration file to until ``unset`` is used to remove -it. - -Level is the minimum debug printing level to show in log. - -* ``trace``: Possibly very noisy messages which can be printed many times per second - -* ``debug``: Messages that happen often but they should happen only a couple of times per second - -* ``info``: Important state changes that happen rarely during normal execution - -* ``warning``: Enabled by default. Shows warnings about unexpected events which code managed to handle correctly. - -* ``error``: Enabled by default. Shows errors which code can't handle without user intervention. - -unset ------ -Delete a space separated list of filters - -Usage: ``debugfilter unset [id...]`` - -disable -------- -Disable a space separated list of filters but keep it in the filter list - -Usage: ``debugfilter disable [id...]`` - -enable ------- -Enable a space sperate list of filters - -Usage: ``debugfilter enable [id...]`` +Persistent filters are stored in ``dfhack-config/runtime-debug.json``. Oldest +filters are applied first. That means a newer filter can override the older +printing level selection. + +Usage: + +- ``debugfilter category [] []`` + List available debug plugin and category names. If filters aren't givenm + then all plugins/categories are matched. This command is a good way to test + regex parameters before you pass them to ``set``. +- ``debugfilter filter []`` + List active and passive debug print level changes. The optional ``id`` + parameter is the id listed as first column in the filter list. If ``id`` is + given, then the command shows extended information for the given filter + only. +- ``debugfilter set [] [] []`` + Create a new debug filter to set category verbosity levels. This filter + will not be saved when the DF process exists or the plugin is unloaded. +- ``debugfilter set persistent [] [] []`` + Store the filter in the configuration file to until ``unset`` is used to + remove it. +- ``debugfilter unset [ ...]`` + Delete a space separated list of filters. +- ``debugfilter disable [ ...]`` + Disable a space separated list of filters but keep it in the filter list. +- ``debugfilter enable [ ...]`` + Enable a space sperate list of filters. +- ``debugfilter header [enable] | [disable] [ ...]`` + Control which header metadata is shown along with each log message. Run it + without parameters to see the list of configurable elements. Include an + ``enable`` or ``disable`` keyword to change whether specific elements are + shown. + +Examples: + +- ``debugfilter set Warning core script`` + Hide script execution log messages (e.g. "Loading script: + dfhack-config/dfhack.init"), which are normally output at Info verbosity + in the "core" plugin with the "script" category. diff --git a/plugins/debug.cpp b/plugins/debug.cpp index 4fbc48759..f4a22b8d1 100644 --- a/plugins/debug.cpp +++ b/plugins/debug.cpp @@ -104,85 +104,13 @@ JsonArchive& operator>>(JsonArchive& ar, const serialization::nvp& target) static constexpr auto defaultRegex = std::regex::optimize | std::regex::nosubs | std::regex::collate; -static const char* const commandHelp = - " Manage runtime debug print filters.\n" - "\n" - " debugfilter category [ []]\n" - " List categories matching regular expressions.\n" - " debugfilter filter []\n" - " List active filters or show detailed information for a filter.\n" - " debugfilter set [persistent] [ []]\n" - " Set a filter level to categories matching regular expressions.\n" - " debugfilter unset [ ...]\n" - " Unset filters matching space separated list of ids from 'filter'.\n" - " debugfilter disable [ ...]\n" - " Disable filters matching space separated list of ids from 'filter'.\n" - " debugfilter enable [ ...]\n" - " Enable filters matching space separated list of ids from 'filter'.\n" - " debugfilter header [enable] | [disable] [ ...]\n" - " Control which header metadata is shown along with each log message.\n" - " debugfilter help []\n" - " Show detailed help for a command or this help.\n"; -static const char* const commandCategory = - " category [ []]\n" - " List categories with optional filters. Parameters are passed to\n" - " std::regex to limit which once are shown. The first regular\n" - " expression is used to match the category and the second is used\n" - " to match the plugin name.\n"; -static const char* const commandSet = - " set [persistent] [ []]\n" - " Set filtering level for matching categories. 'level' must be one of\n" - " trace, debug, info, warning and error. The 'level' parameter sets\n" - " the lowest message level that will be shown. The command doesn't\n" - " allow filters to disable any error messages.\n" - " Default filter life time is until Dwarf Fortress process exists or\n" - " plugin is unloaded. Passing 'persistent' as second parameter tells\n" - " the plugin to store the filter to dfhack-config. Stored filters\n" - " will be active until always when the plugin is loaded. 'unset'\n" - " command can be used to remove persistent filters.\n" - " Filters are applied FIFO order. The latest filter will override any\n" - " older filter that also matches.\n"; -static const char* const commandFilters = - " filter []\n" - " Show the list of active filters. The first column is 'id' which can\n" - " be used to deactivate filters using 'unset' command.\n" - " Filters are printed in same order as applied - the oldest first.\n"; -static const char* const commandUnset = - " unset [ ...]\n" - " 'unset' takes space separated list of filter ids from 'filter'.\n" - " It will reset any matching category back to the default 'warning'\n" - " level or any other still active matching filter level.\n"; -static const char* const commandDisable = - " disable [ ...]\n" - " 'disable' takes space separated list of filter ids from 'filter'.\n" - " It will reset any matching category back to the default 'warning'\n" - " level or any other still active matching filter level.\n" - " 'disable' will print red filters that were already disabled.\n"; -static const char* const commandEnable = - " enable [ ...]\n" - " 'enable' takes space separated list of filter ids from 'filter'.\n" - " It will reset any matching category back to the default 'warning'\n" - " level or any other still active matching filter level.\n" - " 'enable' will print red filters that were already enabled.\n"; -static const char* const commandHeader = - " header [enable] | [disable] [ ...]\n" - " 'header' allows you to customize what metadata is displayed with\n" - " each log message. Run it without parameters to see the list of\n" - " configurable elements. Include an 'enable' or 'disable' keyword to\n" - " change specific elements.\n"; -static const char* const commandHelpDetails = - " help []\n" - " Show help for any of subcommands. Without any parameters it shows\n" - " short help for all subcommands.\n"; - //! Helper type to hold static dispatch table for subcommands struct CommandDispatch { //! Store handler function pointer and help message for commands struct Command { using handler_t = command_result(*)(color_ostream&,std::vector&); - Command(handler_t handler, const char* help) : - handler_(handler), - help_(help) + Command(handler_t handler) : + handler_(handler) {} command_result operator()(color_ostream& out, @@ -193,12 +121,8 @@ struct CommandDispatch { handler_t handler() const noexcept { return handler_; } - - const char* help() const noexcept - { return help_; } private: handler_t handler_; - const char* help_; }; using dispatch_t = const std::map; //! Name to handler function and help message mapping @@ -1125,28 +1049,14 @@ static command_result configureHeader(color_ostream& out, using DFHack::debugPlugin::CommandDispatch; -static command_result printHelp(color_ostream& out, - std::vector& parameters) -{ - const char* help = commandHelp; - auto iter = CommandDispatch::dispatch.end(); - if (1u < parameters.size()) - iter = CommandDispatch::dispatch.find(parameters[1]); - if (iter != CommandDispatch::dispatch.end()) - help = iter->second.help(); - out << help << std::flush; - return CR_OK; -} - CommandDispatch::dispatch_t CommandDispatch::dispatch { - {"category", {listCategories,commandCategory}}, - {"filter", {listFilters,commandFilters}}, - {"set", {setFilter,commandSet}}, - {"unset", {unsetFilter,commandUnset}}, - {"enable", {enableFilter,commandEnable}}, - {"disable", {disableFilter,commandDisable}}, - {"header", {configureHeader,commandHeader}}, - {"help", {printHelp,commandHelpDetails}}, + {"category", {listCategories}}, + {"filter", {listFilters}}, + {"set", {setFilter}}, + {"unset", {unsetFilter}}, + {"enable", {enableFilter}}, + {"disable", {disableFilter}}, + {"header", {configureHeader}}, }; //! Dispatch command handling to the subcommand or help @@ -1156,13 +1066,14 @@ static command_result commandDebugFilter(color_ostream& out, DEBUG(command,out).print("debugfilter %s, parameter count %zu\n", parameters.size() > 0 ? parameters[0].c_str() : "", parameters.size()); - auto handler = printHelp; auto iter = CommandDispatch::dispatch.end(); if (0u < parameters.size()) iter = CommandDispatch::dispatch.find(parameters[0]); - if (iter != CommandDispatch::dispatch.end()) - handler = iter->second.handler(); - return (handler)(out, parameters); + if (iter != CommandDispatch::dispatch.end()) { + iter->second.handler()(out, parameters); + return CR_OK; + } + return CR_WRONG_USAGE; } } } /* namespace debug */ @@ -1173,9 +1084,7 @@ DFhackCExport DFHack::command_result plugin_init(DFHack::color_ostream& out, commands.emplace_back( "debugfilter", "Manage runtime debug print filters", - DFHack::debugPlugin::commandDebugFilter, - false, - DFHack::debugPlugin::commandHelp); + DFHack::debugPlugin::commandDebugFilter); auto& filMan = DFHack::debugPlugin::FilterManager::getInstance(); DFHack::command_result rv = DFHack::CR_OK; if ((rv = filMan.loadConfig(out)) != DFHack::CR_OK)