Avoid spurious SUCCESS!?? for test_format_time_y2038.

[tahoe-lafs/tahoe-lafs.git] / docs / logging.rst

diff --git a/docs/logging.rst b/docs/logging.rst
index 8c252b8d5f4d93c941c126eabe0cd9089061b9c8..8d01557aee7324763e449e3b24e2fdc2ce4e99e0 100644 (file)
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -1,3 +1,5 @@
+.. -*- coding: utf-8-with-signature -*-
+
 =============
 Tahoe Logging
 =============
@@ -24,7 +26,7 @@ primarily for use by programmers and grid operators who want to find out what
 went wrong.
 
 The Foolscap logging system is documented at
-`<http://foolscap.lothar.com/docs/logging.html>`_.
+`<http://foolscap.lothar.com/docs/logging.html>`__.
 
 The Foolscap distribution includes a utility named "``flogtool``" that is
 used to get access to many Foolscap logging features. This command only
@@ -184,7 +186,7 @@ Create the Log Gatherer with the "``flogtool create-gatherer WORKDIR``"
 command, and start it with "``tahoe start``". Then copy the contents of the
 ``log_gatherer.furl`` file it creates into the ``BASEDIR/tahoe.cfg`` file
 (under the key ``log_gatherer.furl`` of the section ``[node]``) of all nodes
-that should be sending it log events. (See `<configuration.rst>`_.)
+that should be sending it log events. (See `<configuration.rst>`__.)
 
 The "``flogtool filter``" command, described above, is useful to cut down the
 potentially large flogfiles into a more focussed form.
@@ -196,23 +198,6 @@ the outbound TCP queue), publishing nodes will start dropping log events when
 the outbound queue grows too large. When this occurs, there will be gaps
 (non-sequential event numbers) in the log-gatherer's flogfiles.
 
-Local twistd.log files
-======================
-
-[TODO: not yet true, requires foolscap-0.3.1 and a change to ``allmydata.node``]
-
-In addition to the foolscap-based event logs, certain high-level events will
-be recorded directly in human-readable text form, in the
-``BASEDIR/logs/twistd.log`` file (and its rotated old versions:
-``twistd.log.1``, ``twistd.log.2``, etc). This form does not contain as much
-information as the flogfiles available through the means described
-previously, but they are immediately available to the curious developer, and
-are retained until the twistd.log.NN files are explicitly deleted.
-
-Only events at the ``log.OPERATIONAL`` level or higher are bridged to
-``twistd.log`` (i.e. not the ``log.NOISY`` debugging events). In addition,
-foolscap internal events (like connection negotiation messages) are not
-bridged to ``twistd.log``.
 
 Adding log messages
 ===================
@@ -268,13 +253,17 @@ If a test is failing and you aren't sure why, start by enabling
 
 With ``FLOGTOTWISTED=1``, sufficiently-important log events will be written
 into ``_trial_temp/test.log``, which may give you more ideas about why the
-test is failing. Note, however, that ``_trial_temp/log.out`` will not receive
-messages below the ``level=OPERATIONAL`` threshold, due to this issue:
-`<http://foolscap.lothar.com/trac/ticket/154>`_
+test is failing.
+
+By default, ``_trial_temp/test.log`` will not receive messages below the
+``level=OPERATIONAL`` threshold. You can change the threshold via the ``FLOGLEVEL``
+variable, e.g.::
+
+  make test FLOGLEVEL=10 FLOGTOTWISTED=1
 
+(The level numbers are listed in src/allmydata/util/log.py.)
 
-If that isn't enough, look at the detailed foolscap logging messages instead,
-by running the tests like this::
+To look at the detailed foolscap logging messages, run the tests like this::
 
   make test FLOGFILE=flog.out.bz2 FLOGLEVEL=1 FLOGTOTWISTED=1