How And Why To Use TDB Tracing

==============================

You can trace all TDB operations, using TDB_TRACE.  It is not complete

(error conditions which expect to the logged will not always be traced

correctly, so you should set up a logging function too), but is designed

to collect benchmark-style traces to allow us to optimize TDB.

Note: tracing is not efficient, and the trace files are huge: a

traverse of the database is particularly large!  But they compress very

well with rzip (http://rzip.samba.org)

How to gather trace files:

--------------------------

1) Uncomment /* #define TDB_TRACE 1 */ in tdb_private.h.

2) Rebuild TDB, and everything that uses it.

3) Run something.

Your trace files will be called <tdbname>.trace.<pid>.  These files

will not be overwritten: if the same process reopens the same TDB, an

error will be logged and tracing will be disabled.

How to replay trace files:

--------------------------

1) For benchmarking, remember to rebuild tdb with #define TDB_TRACE commented

   out again!

2) Grab the latest "replace_trace.c" from CCAN's tdb module (tools/ dir):

	http://ccan.ozlabs.org/tarballs/tdb.tar.bz2

3) Compile up replay_trace, munging as necessary.

4) Run replay_trace <scratch-tdb-name> <tracefiles>...

If given more than one trace file (presumably from the same tdb)

replay_trace will try to figure out the dependencies between the operations

and fire off a child to run each trace.  Occasionally it gets stuck, in

which case it will add another dependency and retry.  Eventually it will

give a speed value.

replay_trace can intuit the existence of previous data in the tdb (ie.

activity prior to the trace(s) supplied) and will prepopulate as

necessary.

You can run --quiet for straight benchmark results, and -n to run multiple

times (this saves time, since it need only calculate dependencies once).

Good luck!

Rusty Russell <rusty@rustcorp.com.au>