#pragma section-numbers 2
= Blackbox Extension =

'''This extension is distributed with Mercurial 2.6 and up.'''

''Author: Durham Goode''

The blackbox extension logs events to ''`.hg/blackbox.log`'' for post-mortem debugging.  It is useful for administrators to find out what a user did recently when trying to fix a repository.

<<TableOfContents>>

== Events ==
By default the extension logs the following events:

 * user commands and exit codes
 * unhandled exceptions
 * incoming revisions
 * hooks that are run

The recent log entries can be viewed with the '`hg blackbox`' command.  Each log entry includes the date, time, and the user performing the action.
{{{
$ hg blackbox
2013/02/13 15:06:11 durham> pull -u
2013/02/13 15:06:14 durham> 17 incoming changes - new heads: 7daed3c67aaa
2013/02/13 15:06:14 durham> pull exited None after 3.28 seconds
2013/02/13 15:30:36 durham> log -l 1 --stat
2013/02/13 15:30:37 durham> log exited None after 0.75 seconds
}}}

== Configuration ==
Which events are logged can be configured by changing the blackbox.track setting in ''`.hgrc`''.

Log only user commands:
{{{
[blackbox]
track=command, commandfinish, commandexception
}}}

Log only incoming revisions:
{{{
[blackbox]
track=incoming
}}}

Log only hooks:
{{{
[blackbox]
track=exthook, pythonhook
}}}

== Logging custom events ==
It's possible to log custom events to the blackbox from another extension or from elsewhere in mercurial by calling {{{ui.log}}} like so:
{{{
ui.log("myeventkind", "Something happened\n")
}}}
If the blackbox extension is enabled, the event will be logged as:
{{{
2013/02/13 15:30:44 durham> Something happened
}}}

----
CategoryBundledExtension