trackrdrd: update the README/manpage to reflect the addition of the MQ

           interface and the ActiveMQ plugin (fixing up some obsolete
           docs along the way), and add a new README/manpage for the
           ActiveMQ plugin

trackrdrd/README.rst

@@ -9,8 +9,8 @@ Tracking Log Reader demon
 -------------------------
 
 :Author: Geoffrey Simmons
-:Date:   2013-03-13
-:Version: 2.0
+:Date:   2014-05-20
+:Version: 3.0
 :Manual section: 3
 
 
@@ -23,8 +23,9 @@ DESCRIPTION
 ===========
 
 The ``trackrdrd`` demon reads from the shared memory log of a running
-instance of Varnish, collects data relevant to tracking for the Otto
-project, and forwards the data to ActiveMQ message brokers.
+instance of Varnish, aggregates data for a request that are relevant
+to tracking, and forwards the data to a messaging system (such as
+ActiveMQ or Kafka).
 
 ``trackrdrd`` reads data from ``VCL_Log`` entries that are displayed
 in this format by the ``varnishlog`` tool::
@@ -59,8 +60,8 @@ request and its ESI includes.
 
 When the request processing for an XID is complete (i.e. when
 ``trackrdrd`` reads ``ReqEnd`` for that XID), the data record is
-complete and ready to be forwarded to ActiveMQ message
-brokers. ``trackrdrd`` comprises a reader thread, which reads from the
+complete and ready to be forwarded to the messaging
+system. ``trackrdrd`` comprises a reader thread, which reads from the
 shared memory log, and one or more worker threads, which send records
 to one or more message brokers.
 
@@ -69,6 +70,15 @@ field ``XID=<xid>`` to the data, and appends a field ``req_endt=<t>``
 containg the epoch time at which request processing ended (from the
 ``ReqEnd`` entry).
 
+The interface to the messaging system is implemented in a messaging
+plugin -- a shared object that provides definitions for the functions
+declared in the MQ interface in ``include/mq.h``. See ``mq.h`` for
+documentation of the interface.
+
+The source distribution for ``trackrdrd`` includes an implementation
+of the MQ interface for ActiveMQ, see libtrackrdr-activemq(3) for
+details.
+
 EXAMPLE
 =======
 
@@ -102,8 +112,9 @@ are in::
 
 	git@repo.org:varnish-cache
 
-``trackrdrd`` must link with the CMS or ActiveMQ-CPP library
-(``libactivemq-cpp``) at runtime. The sources can be obtained from::
+To build the messaging plugin for ActiveMQ (``libtrackrdr-activemq``)
+it is neccessary to link with the CMS or ActiveMQ-CPP library
+(``libactivemq-cpp``). The sources can be obtained from::
 
         http://activemq.apache.org/cms/
 
@@ -139,14 +150,17 @@ build::
 	$ CFLAGS=-m64 ./configure
 	$ make
 
-Building and installing ActiveMQ-CPP
-------------------------------------
+Building and installing packaged MQ implementations
+---------------------------------------------------
+
+The ``trackrdrd`` distribution includes an implementation of the MQ
+interface for ActiveMQ message brokers. For details of the build and
+its dependencies, see libtrackrdr-activemq(3) (``README.rst`` in
+``src/mq/activemq``).
 
-``trackrdrd`` has been tested with versions 3.4.4 and 3.5.0 of
-ActiveMQ-CPP. If the library ``libactivemq-cpp`` is already installed
-on the platform where ``trackrdrd`` will run, then no further action
-is necessary. To build the library from source, follow the
-instructions in the ``README.txt`` file of its source distribution.
+Since the global make targets for ``trackrdrd`` also build the MQ
+implementations, it is necessary to configure the build for them as
+well, for example by setting ``CXXFLAGS`` to compile C++ sources.
 
 Building and installing trackrdrd
 ---------------------------------
@@ -161,8 +175,12 @@ The steps to build ``trackrdrd`` are very similar to those for
 building Varnish. The only difference is in the ``configure``
 step:
 
-* The path to the Varnish source directory must be given in the variable ``VARNISHSRC``.
-* The flag ``CXXFLAGS``, like ``CFLAGS``, must also be set to ``-m64``, because C++ code is also compiled. It may be necessary to add additional ``CXXFLAGS`` to compile the ActiveMQ API calls, for example as obtained from ``pkg-config --cflags apr-1``.
+* The path to the Varnish source directory must be given in the
+  variable ``VARNISHSRC``.
+* The flag ``CXXFLAGS``, like ``CFLAGS``, must also be set to
+  ``-m64``, because C++ code is also compiled. It may be necessary to
+  add additional ``CXXFLAGS`` to compile the ActiveMQ API calls, for
+  example as obtained from ``pkg-config --cflags apr-1``.
 
 At minimum, run these steps::
 
@@ -297,10 +315,11 @@ character after the equals sign up to the last non-whitespace
 character on the line. Comments begin with the hash character and
 extend to the end of the line. There are no continuation lines.
 
-The parameters ``mq.uri`` and ``mq.qname`` are required (have no
-default values), and (only) ``mq.uri`` may be specified more than
-once. All other config parameters have default values, and some of
-them correspond to command-line options, as shown below.
+The parameter ``mq.module`` is required (has no default value), and
+``mq.config_file`` is optional (depending on whether the MQ
+implementation requires a configuration file). All other config
+parameters have default values, and some of them correspond to
+command-line options, as shown below.
 
 .. include:: config.rst
 
@@ -316,8 +335,8 @@ to the log (as configured with the parameter
 ``info`` log level, with additional formatting of the log lines,
 depending on how syslog is configured)::
 
- Hash table: len=16384 seen=23591972 drop_reqstart=0 drop_vcl_log=0 drop_reqend=0 expired=0 evacuated=0 open=0 load=0.00 collisions=58534 insert_probes=58974 find_probes=2625 fail=0 occ_hi=591 occ_hi_this=1 
- Data table: len=116384 nodata=11590516 submitted=12001456 wait_room=0 data_hi=3187 data_overflows=0 done=0 open=0 load=0.00 sent=12001456 reconnects=17 failed=0 occ_hi=4345 occ_hi_this=1 
+ Hash table: len=8192 seen=375862067 drop_reqstart=0 drop_vcl_log=0 drop_reqend=14 expired=50 evacuated=0 open=29 load=0.35 collisions=1526027 insert_probes=1534686 find_probes=45907 fail=0 occ_hi=530 occ_hi_this=85
+ Data table: len=18192 nodata=280295531 submitted=95566507 wait_room=0 data_hi=6217 data_overflows=0 done=9 open=29 load=0.21 sent=95566498 reconnects=0 failed=0 restarts=0 abandoned=0 occ_hi=944 occ_hi_this=111
 
 If monitoring of worker threads is switched on, then monitoring logs
 such as this are emitted for each thread::
@@ -349,6 +368,7 @@ each worker thread, one of:
 * ``initializing``
 * ``running``
 * ``waiting``
+* ``abandoned``
 * ``shutting down``
 * ``exited``
 
@@ -405,6 +425,9 @@ SEE ALSO
 ========
 
 * ``varnishd(1)``
+* ``libtrackrdr-activemq(3)``
+* ``ld.so(8)``
+* ``syslog(3)``
 
 COPYRIGHT AND LICENCE
 =====================
@@ -413,8 +436,8 @@ For both the software and this document are governed by a BSD 2-clause
 licence.
 
 
-| Copyright (c) 2012-2013 UPLEX Nils Goroll Systemoptimierung
-| Copyright (c) 2012-2013 Otto Gmbh & Co KG
+| Copyright (c) 2012-2014 UPLEX Nils Goroll Systemoptimierung
+| Copyright (c) 2012-2014 Otto Gmbh & Co KG
 | All rights reserved
 | Use only with permission
 

trackrdrd/config.rst

@@ -5,11 +5,11 @@ Parameter            CLI Option Description
                                 shared memory segment for the Varnish log. This parameter and ``varnish.bindump`` are
                                 mutually exclusive.
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------
-``mq.uri``                      URIs for the message broker. This is the only parameter that can appear more than once in None, this parameter is required.
-                                the configuration; if more than one MQ URIs are specified, than worker threads
-                                distribute their connections to the different message brokers.
+``mq.module``                   Name of the shared object implementing the MQ interface. May be an absolute path, or the  None, this parameter is required.
+                                name of a library that the dynamic linker finds according to the rules described in
+                                ld.so(8).
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------
-``mq.qname``                    Name of the queue (destination) to which messages are sent at the message broker(s).      None, this parameter is required.
+``mq.config_file``              Path of a configuration file used by the MQ implementation                                None, this parameter is optional.
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------
 ``nworkers``                    Number of worker threads used to send messages to the message broker(s).                  1
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------
@@ -50,6 +50,12 @@ Parameter            CLI Option Description
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------
 ``restarts``                    Maximum number of restarts of the child process by the management process                 1
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------
+``thread.restarts``             Maximum number of restarts of a worker thread by the child process. A thread is restarted 1
+                                after a message send, message system reconnect and message resend have all failed. If the
+                                restart limit for a thread is reached, then the thread goes into the state ``abandoned``
+                                and no more restarts are attempted. If all worker threads are abandoned, then the child
+                                process stops.
+-------------------- ---------- ----------------------------------------------------------------------------------------- -------
 ``monitor.interval``            Interval in seconds at which monitoring statistics are emitted to the log. If set to 0,   30
                                 then no statistics are logged.
 -------------------- ---------- ----------------------------------------------------------------------------------------- -------

trackrdrd/datalog.rst

@@ -32,6 +32,12 @@ Field              Description
 ``reconnects``     How often worker threads reconnected to a message broker
                    after an unsuccessful send
 ------------------ ------------------------------------------------------------
+``restarts``       How often worker threads were restarted after a message
+                   send, reconnect and resend all failed
+------------------ ------------------------------------------------------------
+``abandoned``      Number of worker threads that have been abandoned due to
+                   reaching the restart limit (``thread.restarts``)
+------------------ ------------------------------------------------------------
 ``failed``         Number of failed sends (failure after reconnect)
 ------------------ ------------------------------------------------------------
 ``occ_hi``         Occupancy high watermark -- highest number of records (open

trackrdrd/src/mq/activemq/Makefile.am

@@ -20,3 +20,13 @@ libtrackrdr_activemq_la_LIBADD = \
 	@APU_LIBS@
 
 libtrackrdr_activemq_la_LDFLAGS = -version-info 1:0:0
+
+if HAVE_RST2MAN
+dist_man_MANS = libtrackrdr-activemq.3
+MAINTAINERCLEANFILES = $(dist_man_MANS)
+endif
+
+libtrackrdr-activemq.3: README.rst
+if HAVE_RST2MAN
+	${RST2MAN} README.rst $@
+endif

trackrdrd/src/mq/activemq/README.rst

+.. _ref-trackrdrd:
+
+=====================
+ libtrackrdr-activemq
+=====================
+
+-----------------------------------------------------------------------
+ActiveMQ implementation of the MQ interface for the Tracking Log Reader
+-----------------------------------------------------------------------
+
+:Author: Geoffrey Simmons
+:Date:   2014-05-20
+:Version: 3.0
+:Manual section: 3
+
+
+DESCRIPTION
+===========
+
+``libtrackrdr-activemq.so`` provides an implementation of the tracking
+reader's MQ interface to send messages to ActiveMQ message
+brokers. See ``include/mq.h`` in the ``trackrdrd`` source distribution
+for documentation of the interface.
+
+To use this implementation with ``trackrdrd``, specify the shared
+object as the value of ``mq.module`` in the tracking reader's
+configuration (see trackrdrd(3)). The configuration value may be the
+absolute path of the shared object; or its name, provided that it can
+be found by the dynamic linker (see ld.so(8)).
+
+``libtrackrdr-activemq`` also requires a configuration file, whose
+path is specified as ``mq.config_fname`` in the configuration of
+``trackrdrd``.
+
+``libtrackrdrd-activemq`` in turn depends on the library ActiveMQ-CPP
+(or CMS), a client library for ActiveMQ, packaged on many systems as
+``libactivemq-cpp``. The dynamic linker must also be able to find
+``libactivemq-cpp.so`` at runtime.
+
+BUILD/INSTALL
+=============
+
+The sources for ``libtrackrdr-activemq`` are provided in the source
+repository for ``trackrdrd``, in the subdirectory ``src/mq/activemq/``
+of::
+
+	git@repo.org:trackrdrd
+
+The sources for ActiveMQ-CPP can be obtained from::
+
+        http://activemq.apache.org/cms/
+
+Building and installing ActiveMQ-CPP
+------------------------------------
+
+The ActiveMQ interface has been tested with versions 3.4.4 through
+3.8.2 of ActiveMQ-CPP. If the library ``libactivemq-cpp`` is already
+installed on the platform where ``trackrdrd`` will run, then no
+further action is necessary. To build the library from source, follow
+the instructions in the ``README.txt`` file of its source
+distribution.
+
+Building and installing libtrackrdr-activemq
+--------------------------------------------
+
+``libactivemq-trackrdr`` is built as part of the global build for
+``trackrdrd``; for details and requirements of the build, see
+trackrdrd(3). Note that for the ActiveMQ implementation, which
+includes C++ classes, it is necessary to configure the build for C++
+compilation (for example by setting ``CXXFLAGS``), and it may be
+necessary to add additional configuration for compiling and linking
+with the ActiveMQ-CPP library, for example as obtained from
+``pkg-config --cflags apr-1``.
+
+To specifically build the MQ implementation (without building all of
+the rest of ``trackrdrd``), it suffices to invoke ``make`` commands in
+the subdirectory ``src/mq/activemq`` (after having executed the
+``configure`` script for ``trackrdrd``)::
+
+        # in trackrdrd/trackrdrd
+	$ cd src/mq/activemq
+	$ make
+
+For self-tests after the build, run::
+
+	$ make check
+
+If a connection is open at port 61616 on the host where the self-tests
+are run, then it is assumed that an ActiveMQ message broker is
+listening, and tests are run against the MQ URI
+``tcp://localhost:61616``. If the port is not open, then the ``make
+check`` test exits with the status ``SKIPPED``.
+
+(When ``make check`` is run globally for the ``trackrdrd`` build, then
+it is also run for ``libtrackrdr-activemq``).
+
+To install the shared object ``libtrackrdr-activemq``, run ``make
+install`` as root, for example with ``sudo``::
+
+	$ sudo make install
+
+In standard configuration, the ``.so`` file will be installed by
+``libtool(1)``, and its location may be affected by the ``--libdir``
+option to ``configure``.
+
+CONFIGURATION
+=============
+
+As mentioned above, a configuration file for ``libtrackrdr-activemq``
+must be specified in the configuration parameter ``mq.config_fname``
+for ``trackrdrd``, and initialization of the MQ implementation fails
+if this file cannot be found or read by the process owner of
+``trackrdrd`` (or if its syntax is false, or if either of the two
+required parameters are missing).
+
+The syntax of the configuration file is the same as that of
+``trackrdrd``. Both of the parameters ``mq.uri`` and ``mq.qname`` are
+required (there are no default values), and (only) ``mq.uri`` may be
+specified more than once.
+
+================== ============================================================
+Parameter          Description
+================== ============================================================
+``mq.uri``         URIs for the message broker. If more than one MQ URI is
+                   specified, than worker threads distribute their connections
+                   to the different message brokers.
+------------------ ------------------------------------------------------------
+``mq.qname``       Name of the queue (destination) to which messages are sent
+                   at the message broker(s)
+================== ============================================================
+
+SEE ALSO
+========
+
+* ``trackrdrd(3)``
+* ``ld.so(8)``
+* http://activemq.apache.org/cms/
+
+COPYRIGHT AND LICENCE
+=====================
+
+For both the software and this document are governed by a BSD 2-clause
+licence.
+
+| Copyright (c) 2012-2014 UPLEX Nils Goroll Systemoptimierung
+| Copyright (c) 2012-2014 Otto Gmbh & Co KG
+| All rights reserved
+| Use only with permission
+
+| Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.