# This file is part of vmod-binlog
# Copyright (C) 2013-2014 Sergey Poznyakoff
#
# Vmod-binlog is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# Vmod-binlog is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with vmod-binlog.  If not, see <http://www.gnu.org/licenses/>.

$Module binlog 3 Binary Log File Support

COLOPHON
========
This document provides a short description of the **vmod-binlog** module.
For a detailed documentation, please see the vmod-binlog(3) manual page.

You will find documentation sources in subdirectory **doc** of the
**vmod-binlog** source tree.

DESCRIPTION
===========
This module adds binary log files support to Varnish Cache.

Binary  log  file  consists  of  an  arbitrary  number of equally sized
records.  Each record contains a UNIX  timestamp  in  binary  form  and
user-defined  data.  The file begins with a header containing auxiliary
information.

Binary log files are rotated at preconfigured time intervals.  In order
to speed up searches, their names follow the strftime(3) pattern:

%Y%m%dT%H%M%S.log

Binary logs can be viewed using the binlogcat(1) and binlogsel(1) utilities.

$Init module_init
$Function VOID init(PRIV_VCL, STRING, STRING, STRING)

Description
	Initializes binary log engine.
Example
	::

	  binlog.init("/var/lib/varnish/binlog", "LZ[64]L",
                      "size=1G;index=1;umask=027;roundts=1;debug=2");

		      
$Function VOID start(PRIV_VCL)

Description
	Initialize new binary record.  It should be followed by one or
	more calls to **binlog.pack** and a final call to **binlog.commit**.
Example
	::
	  binlog.start();
	  
$Function VOID pack(PRIV_VCL, STRING)

Description
	Pack next data item into the binary log record.  The item is
	converted according to the second argument of **binlog.init**.
	The conversion specifier is selected using the ordinal number
	of this **pack** call after the latest **binlog.start**.

$Function VOID commit(PRIV_VCL)

Description
	Finalize the binary log record and commit it.  Any uninitialized
	fields will be set to 0.

Example
	::

	  binlog.start();
          binlog.pack(http.X-Id);
          binlog.pack(http.req.url);
	  binlog.pack(http.X-Node);
          binlog.commit();

$Function VOID sync(PRIV_VCL)

Description
	Synchronize the binary log with the disk file.

$Function VOID close(PRIV_VCL)

Description
	Close the log.  This is supposed to be called from **vcl_fini**.

SEE ALSO
========

* binlogcat(1)
* binlogsel(1)
* vcl(7)
* varnishd(1)