From 39722afaedcb568501d08ec69b657de4af95b14b Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 31 May 2014 09:40:03 -0700 Subject: [PATCH] irkerd.xml: Cleanup syslog docs and shift 'os' import This fixes some issues with 672240a (Use syslog facility when irkerd is backgtrounded and no -l was given, 2014-05-31): * Shift the 'os' import to keep the stdlib imports alphabetized. * Move the syslog docs from a stand-alone paragraph into the -d/--log-level section. * Add some text to the -d/--log-level docs explaining the distinction between the -l/--log-file traffic logs and the -d/--log-level program-tracing logs. * StreamHandler logs to standard error (not standard output) by default [1]. Change "stndard output" to "standard error". * Add articles to background and foreground ("the background"). * Fix a "packground" -> "background" typo. * Explain our background-detection logic, and point out some of the assumptions made by the current implementation. I still think that it's better to have an explicit --syslog setting, and to leave it to packagers/users to descide explicitly if they prefer logging to syslog or stderr. But whatever the syslog-switching logic is, it should be clearly documented so folks don't have to read the source to understand it. [1]: https://docs.python.org/3/library/logging.handlers.html#logging.StreamHandler Signed-off-by: Eric S. Raymond --- irkerd | 2 +- irkerd.xml | 39 +++++++++++++++++++++++++++++---------- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/irkerd b/irkerd index f7adadc..2c66a18 100755 --- a/irkerd +++ b/irkerd @@ -42,11 +42,11 @@ CONNECTION_MAX = 200 # To avoid hitting a thread limit version = "2.8" -import os import argparse import logging import logging.handlers import json +import os try: # Python 3 import queue except ImportError: # Python 2 diff --git a/irkerd.xml b/irkerd.xml index d9de17f..00e7bc2 100644 --- a/irkerd.xml +++ b/irkerd.xml @@ -108,10 +108,35 @@ joining a channel to log its traffic. -d -Takes a following value, setting the debugging level -from it; possible values are 'critical', 'error', 'warning', 'info', -'debug'. This option will generally only be of interest to developers; -consult the source code for details. + + + Takes a following value, setting the debugging level from it; + possible values are 'critical', 'error', 'warning', 'info', + 'debug'. This option will generally only be of interest to + developers, as the logs are designed to help trace + irkerd's internal state. These tracing + logs are independent of the traffic logs controlled by + -l. + + + Logging will be to standard error (if + irkerd is running in the foreground) or + to /dev/syslog with facility "daemon" (if + irkerd is running in the background). + The background-ness of irkerd is + determined by comparing the process group id with the process + group associated with the terminal attached to stdout (with + non-matches for background processes). We assume you aren't + running irkerd in Windows or another OS + that doesn't support os.getpgrp or + tcgetpgrp or . We also assume that you have + stdout attached to a TTY (and haven't closed or redirected it). + We also assume that if stdout is attached to a TTY associated with + the same process group as irkerd, you + do intend to log to stderr and not syslog. + + + -l @@ -150,12 +175,6 @@ terminate. -If no is set, logging will be to stndard -output (if irkerd is running in foreground) -or to /dev/syslog with facility "daemon" (if -irkerd is running in packground). - - LIMITATIONS Requests via UDP optimizes for lowest latency and network load by avoiding TCP connection setup time; the cost is that delivery is -- 2.26.2