Improve the help message for tracereport --date

CHANGES.rst

@@ -1,11 +1,18 @@
 Changes
 =======
 
+1.4.0 (2015-05-06)
+------------------
+
+- tracereport can be limited to a date range with --date=YYYY-MM-DD..YYYY-MM-DD
+
+
 1.3.2 (2012-03-20)
 ------------------
 
 - Slight refactoring to allow alternative tracelog implementations.
 
+
 1.3.1 (2012-03-20)
 ------------------
 
@@ -20,6 +27,7 @@ Changes
   This is somewhat experimental. The tracereport script ignores D
   records.
 
+
 1.2.1 (2010-01-27)
 ------------------
 

src/zc/zservertracelog/tracereport.py

@@ -601,44 +601,53 @@ def print_app_requests_html(requests, dt, min_seconds, max_requests, allurls,
 
 parser.add_option("--app-request-threshold", "-a", dest='apps',
                   type="int", default=10,
-                  help="""
+                  help="""\
 Number of pending application requests at which detailed request information
 if printed.
 """)
 parser.add_option("--app-requests", "-r", dest='app_requests',
                   type="int", default=10,
-                  help="""
+                  help="""\
 How many requests to show when the maximum number of pending
 apps is exceeded.
 """)
 parser.add_option("--old-requests", "-o", dest='old_requests',
                   type="int", default=10,
-                  help="""
+                  help="""\
 Number of seconds beyond which a request is considered old.
 """)
 parser.add_option("--event-log", "-e", dest='event_log',
-                  help="""
+                  help="""\
 The name of an event log that goes with the trace log.  This is used
 to determine when the server is restarted, so that the running trace data structures can be reinitialized.
 """)
 parser.add_option("--html", dest='html', action='store_true',
-                  help="""
+                  help="""\
 Generate HTML output.
 """)
 parser.add_option("--remove-prefix", dest='remove_prefix',
-                  help="""
-A prefex to be removed from URLS.
+                  help="""\
+A prefix to be removed from URLS.
 """)
 parser.add_option("--summary-only", dest='summary_only', action='store_true',
-                  help="""
+                  help="""\
 Only output summary lines.
 """)
 parser.add_option("--summary-lines", dest='summary_lines',
                   type="int", default=999999999,
                   help="""The number of summary lines to show""")
 parser.add_option("--date", "-d", dest='date', default=None,
-                  help="""Date range that will be parsed from log""")
-
+                  metavar='DATESPEC',
+                  help="""\
+Only consider events in the specified date range.  Syntax:
+"YYYY-MM[-DD [HH[:MM[:SS]]]][ +/-[days=N][, hours=N][, minutes=N][,
+seconds=N]]".
+
+E.g. -d 2015-04 would select the entire month, -d 2015-04-20 would
+select the entire day, -d "2015-04-20 14" would select one hour,
+-d "2015-04-20 14:00 +hours=2" would select two hours, and
+-d "2015-04-20 16:00 -hours=2" would select the same two hours.
+""")
 
 
 if __name__ == '__main__':

src/zc/zservertracelog/tracereport.txt

@@ -15,6 +15,7 @@ The '--help' option displays the following usage information:
     ...     zc.zservertracelog.tracereport.main(['--help'])
     ... except SystemExit:
     ...     pass
+    ... # doctest: +REPORT_NDIFF
     Usage: test [options] trace_log_file
     <BLANKLINE>
     Output trace log data showing:
@@ -43,27 +44,37 @@ The '--help' option displays the following usage information:
     Options:
       -h, --help            show this help message and exit
       -a APPS, --app-request-threshold=APPS
-                             Number of pending application requests at
+                            Number of pending application requests at
                             which detailed request information if
                             printed.
       -r APP_REQUESTS, --app-requests=APP_REQUESTS
-                             How many requests to show when the maximum
+                            How many requests to show when the maximum
                             number of pending apps is exceeded.
       -o OLD_REQUESTS, --old-requests=OLD_REQUESTS
-                             Number of seconds beyond which a request is
+                            Number of seconds beyond which a request is
                             considered old.
       -e EVENT_LOG, --event-log=EVENT_LOG
-                             The name of an event log that goes with the
+                            The name of an event log that goes with the
                             trace log.  This is used to determine when
                             the server is restarted, so that the running
                             trace data structures can be reinitialized.
-      --html                 Generate HTML output.
+      --html                Generate HTML output.
       --remove-prefix=REMOVE_PREFIX
-                             A prefex to be removed from URLS.
-      --summary-only         Only output summary lines.
+                            A prefix to be removed from URLS.
+      --summary-only        Only output summary lines.
       --summary-lines=SUMMARY_LINES
                             The number of summary lines to show
-      -d DATE, --date=DATE  Date range that will be parsed from log
+      -d DATESPEC, --date=DATESPEC
+                            Only consider events in the specified date
+                            range.  Syntax: "YYYY-MM[-DD
+                            [HH[:MM[:SS]]]][ +/-[days=N][, hours=N][,
+                            minutes=N][, seconds=N]]".  E.g. -d 2015-04
+                            would select the entire month, -d 2015-04-20
+                            would select the entire day, -d "2015-04-20
+                            14" would select one hour, -d "2015-04-20
+                            14:00 +hours=2" would select two hours, and
+                            -d "2015-04-20 16:00 -hours=2" would select
+                            the same two hours.
 
 Here, we display the summarized report for a sample trace log.