Improve help text and behavior of RPC-logging

A) The changes in behavior are as follows:
1. Introduce logging category "none" as alias of "0" for
   both RPC-logging and bitcoind "-debug" parameter.
2. Same as "0" is given to argument of "-debug",
   if "none" or "0" is given to <include>, all other given logging
   categories are ignored. The same is true for <exclude>.
   (Before this PR, "0" was accepted but just be ignored itself.)

B) The changes in the help text are as follows:
1. Add a descrption about the evaluation order of <include> and
   <exclude> to clarify how debug loggig categories to be set.
2. Delete text that describe restriction about libevent because
   it's already allowed libevent logging to be updated during runtime.
3. Add a description for category "all", "1", "none" and "0".
4. Add "optional" to the help text of <include> and <exclude>.
5. Add missing new lines before "Argument:".
6. This RPC always returns all logging categories with status.
   Fix the help text to match this behavior.
This commit is contained in:
Akio Nakamura 2017-08-29 20:32:16 +09:00
parent a90e6d2bff
commit c60c49b679
3 changed files with 30 additions and 9 deletions

View File

@ -925,7 +925,8 @@ bool AppInitParameterInteraction()
// Special-case: if -debug=0/-nodebug is set, turn off debugging messages // Special-case: if -debug=0/-nodebug is set, turn off debugging messages
const std::vector<std::string> categories = gArgs.GetArgs("-debug"); const std::vector<std::string> categories = gArgs.GetArgs("-debug");
if (find(categories.begin(), categories.end(), std::string("0")) == categories.end()) { if (std::none_of(categories.begin(), categories.end(),
[](std::string cat){return cat == "0" || cat == "none";})) {
for (const auto& cat : categories) { for (const auto& cat : categories) {
uint32_t flag = 0; uint32_t flag = 0;
if (!GetLogCategory(&flag, &cat)) { if (!GetLogCategory(&flag, &cat)) {

View File

@ -577,6 +577,9 @@ uint32_t getCategoryMask(UniValue cats) {
if (!GetLogCategory(&flag, &cat)) { if (!GetLogCategory(&flag, &cat)) {
throw JSONRPCError(RPC_INVALID_PARAMETER, "unknown logging category " + cat); throw JSONRPCError(RPC_INVALID_PARAMETER, "unknown logging category " + cat);
} }
if (flag == BCLog::NONE) {
return 0;
}
mask |= flag; mask |= flag;
} }
return mask; return mask;
@ -586,16 +589,32 @@ UniValue logging(const JSONRPCRequest& request)
{ {
if (request.fHelp || request.params.size() > 2) { if (request.fHelp || request.params.size() > 2) {
throw std::runtime_error( throw std::runtime_error(
"logging [include,...] <exclude>\n" "logging ( <include> <exclude> )\n"
"Gets and sets the logging configuration.\n" "Gets and sets the logging configuration.\n"
"When called without an argument, returns the list of categories that are currently being debug logged.\n" "When called without an argument, returns the list of categories with status that are currently being debug logged or not.\n"
"When called with arguments, adds or removes categories from debug logging.\n" "When called with arguments, adds or removes categories from debug logging and return the lists above.\n"
"The arguments are evaluated in order \"include\", \"exclude\".\n"
"If an item is both included and excluded, it will thus end up being excluded.\n"
"The valid logging categories are: " + ListLogCategories() + "\n" "The valid logging categories are: " + ListLogCategories() + "\n"
"libevent logging is configured on startup and cannot be modified by this RPC during runtime." "In addition, the following are available as category names with special meanings:\n"
"Arguments:\n" " - \"all\", \"1\" : represent all logging categories.\n"
"1. \"include\" (array of strings) add debug logging for these categories.\n" " - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n"
"2. \"exclude\" (array of strings) remove debug logging for these categories.\n" "\nArguments:\n"
"\nResult: <categories> (string): a list of the logging categories that are active.\n" "1. \"include\" (array of strings, optional) A json array of categories to add debug logging\n"
" [\n"
" \"category\" (string) the valid logging category\n"
" ,...\n"
" ]\n"
"2. \"exclude\" (array of strings, optional) A json array of categories to remove debug logging\n"
" [\n"
" \"category\" (string) the valid logging category\n"
" ,...\n"
" ]\n"
"\nResult:\n"
"{ (json object where keys are the logging categories, and values indicates its status\n"
" \"category\": 0|1, (numeric) if being debug logged or not. 0:inactive, 1:active\n"
" ...\n"
"}\n"
"\nExamples:\n" "\nExamples:\n"
+ HelpExampleCli("logging", "\"[\\\"all\\\"]\" \"[\\\"http\\\"]\"") + HelpExampleCli("logging", "\"[\\\"all\\\"]\" \"[\\\"http\\\"]\"")
+ HelpExampleRpc("logging", "[\"all\"], \"[libevent]\"") + HelpExampleRpc("logging", "[\"all\"], \"[libevent]\"")

View File

@ -220,6 +220,7 @@ struct CLogCategoryDesc
const CLogCategoryDesc LogCategories[] = const CLogCategoryDesc LogCategories[] =
{ {
{BCLog::NONE, "0"}, {BCLog::NONE, "0"},
{BCLog::NONE, "none"},
{BCLog::NET, "net"}, {BCLog::NET, "net"},
{BCLog::TOR, "tor"}, {BCLog::TOR, "tor"},
{BCLog::MEMPOOL, "mempool"}, {BCLog::MEMPOOL, "mempool"},