Merge #11191: RPC: Improve help text and behavior of RPC-logging.

c60c49b Improve help text and behavior of RPC-logging (Akio Nakamura)

Pull request description:

  1. It is allowed `libevent` logging to be updated during runtime,
    but still described that restriction in the help text.
    So we delete these text.
  2. Add a descrption about the evaluation order of `<include>` and
    `<exclude>` to clarify how debug loggig categories to be set.
  3. Add a description about the available logging category `"all"`
    which is not explained.
  4. Add `"optional"` to the help text of `<include>` and `<exclude>`.
  5. Add missing new lines before `"Argument:"`.
  6. `"0"`,`"1"` are allowed in both array of `<include>` and `<exclude>`.
    `"0"` is **ignored** and `"1"` is treated **same as** `"all"`.
    It is confusing, so forbid them.
  7. It always returns all logging categories with status.
    Fix the help text to match this behavior.

Tree-SHA512: c2142da1a9bf714af8ebc38ac0d82394e2073fc0bd56f136372e3db7b2af3b6746f8d6b0241fe66c1698c208c124deb076be83f07dec0d0a180ad150593af415
This commit is contained in:
Wladimir J. van der Laan 2017-11-30 09:32:35 +01:00
commit ef14f2e3ff
No known key found for this signature in database
GPG key ID: 1E4AED62986CD25D
3 changed files with 30 additions and 9 deletions

View file

@ -919,7 +919,8 @@ bool AppInitParameterInteraction()
// Special-case: if -debug=0/-nodebug is set, turn off debugging messages
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) {
uint32_t flag = 0;
if (!GetLogCategory(&flag, &cat)) {

View file

@ -533,6 +533,9 @@ uint32_t getCategoryMask(UniValue cats) {
if (!GetLogCategory(&flag, &cat)) {
throw JSONRPCError(RPC_INVALID_PARAMETER, "unknown logging category " + cat);
}
if (flag == BCLog::NONE) {
return 0;
}
mask |= flag;
}
return mask;
@ -542,16 +545,32 @@ UniValue logging(const JSONRPCRequest& request)
{
if (request.fHelp || request.params.size() > 2) {
throw std::runtime_error(
"logging [include,...] <exclude>\n"
"logging ( <include> <exclude> )\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 with arguments, adds or removes categories from debug logging.\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 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"
"libevent logging is configured on startup and cannot be modified by this RPC during runtime."
"Arguments:\n"
"1. \"include\" (array of strings) add debug logging for these categories.\n"
"2. \"exclude\" (array of strings) remove debug logging for these categories.\n"
"\nResult: <categories> (string): a list of the logging categories that are active.\n"
"In addition, the following are available as category names with special meanings:\n"
" - \"all\", \"1\" : represent all logging categories.\n"
" - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n"
"\nArguments:\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"
+ HelpExampleCli("logging", "\"[\\\"all\\\"]\" \"[\\\"http\\\"]\"")
+ HelpExampleRpc("logging", "[\"all\"], \"[libevent]\"")

View file

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