+.. -*- coding: utf-8-with-signature -*-
+
=============
Tahoe Logging
=============
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>`_.
+The Foolscap logging system is documented at
+`<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
+works when foolscap and its dependencies are installed correctly.
+Tahoe-LAFS v1.10.0 and later include a ``tahoe debug flogtool`` command
+that can be used even when foolscap is not installed; to use this, prefix
+all of the example commands below with ``tahoe debug``.
+
+For earlier versions since Tahoe-LAFS v1.8.2, installing Foolscap v0.6.1
+or later and then running ``bin/tahoe @flogtool`` from the root of a
+Tahoe-LAFS source distribution may work (but only on Unix, not Windows).
-The foolscap distribution includes a utility named "``flogtool``" (usually at
-``/usr/bin/flogtool`` on Unix) which is used to get access to many foolscap
-logging features.
Realtime Logging
================
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.
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
===================
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
projects / tahoe-lafs / tahoe-lafs.git / blobdiff