New TraceAPI for FB 2.5

Hi, all.

I glad to introduce new Firebird facility, based on TraceAPI initially developed by Nickolay Samofatov and maintained and given to us by RedSoft (thanks!).

Below is brief overview of what was done. It will be included into HEAD soon, i hope.
Trace session – set of engine-generated events to trace and placement of trace output. Trace session also have its unique ID, optional name, state, flags, creator user and creation timestamp.

List of available trace events is fixed and determined by the Firebird engine. List of events to trace, which data items to trace and placement of trace output is specified by trace configuration when trace session created.

There are two kinds of trace sessions : system audit and user trace. System audit session is started by the engine itself and obtains configuration from the text file. This file name is set via new setting in firebird.conf and by default is “none”, i.e. no system audit is configured. There may be only one system audit trace session, obviously. Configuration file contains list of traced events and placement of trace log(s). It is very flexible and allows to log different set of events for different databases into different log files. Example configuration file is attached.

User trace session is managed by user via Services API. There are five new services for this purposes – to start, stop, suspend, resume trace session and to enlist all known trace sessions. When user application starts trace session it passed optional name and (mandatory) session configuration. Session configuration is a text. Rules and syntax the same as for configuration file mentioned above except of log placement. Engine stores output of user session in set of temporary files and deleted it automatically. After application starts user trace session it must read session’s output from service (using isc_service_query). When application decide to stop its trace session it just do detach from service. Also user may manage (suspend\resume\stop) any own trace session. Administrator allowed to manage any trace session.

If user trace session was created by ordinary user it will trace only connections established by this user.

User trace sessions is not preserved when all Firebird processes is stopped. I.e. if user started trace session and Firebird SS or SC process is shutted down, this session is stopped and will not be restarted with new Firebird process. For CS this is not the case as user trace session can’t live without connection with service manager and dedicated CS process.

There are three main use cases :

1. Constant audit of engine. This is served by system audit trace.
2. On demand interactive trace of some (or all) activity in some (or all) databases. Application start user trace session and show traced events to user in real time on the screen. User may pause\continue trace and at last stop it.
3. Aggregate of some activity for a relatively long period of time (few hours or even whole day) to analyse it later. Application start user trace session and save trace log in file (or set of files). Session must be stopped manually by the same application or by another one.

Firebird’s service manager utility (fbsvcmgr.exe) may be used to manage trace sessions. Later specialized console utility will be introduced (at least i plan to develop it soon after beta). Of course third party vendors are welcome to implement own GUI based monitoring and trace applications 🙂

Regards,
Vlad