firebird-mirror/doc/README.trace_services

		
		Trace and audit services.

	Firebird 2.5 offers new trace and audit facilities. This new abilities allows 
to log various events performed inside the engine (such as statement execution, 
connect\disconnect etc) and to collect corresponding performance characteristics 
in real time. The base term is trace session. Each trace session have its own 
configuration, state and output. 

	List of available events to trace 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 is 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. The name of this file is set via new setting in firebird.conf 
("AuditTraceConfigFile") and by default have empty vale, 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 fbtrace.conf
placed in the Firebird root directory and contains full description of its 
format, rules and syntax.

	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 list all known trace sessions. See README.services_extension for details.

	When user application starts trace session it set (optional) session name 
and (mandatory) session configuration. Session configuration is a text. Rules 
and syntax are the same as for configuration file mentioned above except of 
placement of trace output. Engine stores output of user session in set of 
temporary files (1MB each) and deletes it automatically when file was read 
completely. Maximum size of user session's output is limited and set via 
"MaxUserTraceLogSize" setting in firebird.conf. Default value is 10 MB. 

	After application starts user trace session it must read session's output 
from service (using isc_service_query). Session output could be produced by the 
engine faster than application is able to read it. When session output grows 
more than "MaxUserTraceLogSize" engine automatically suspends this trace 
session. When application reads part of the output so output size stay less than 
"MaxUserTraceLogSize" engine automatically resumed trace session.

	When application decide to stop its trace session it just do detach from 
service. Also there is abilities to manage trace sessions (suspend\resume\stop). 
Administrators allowed to manage any trace session while ordinary users allowed 
to manage its own trace sessions only. 

    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.


	Examples
	
	Sample configuration files for user trace sessions:
	
a) Trace prepare, free and execution of all statements within connection 12345

<database>
	enabled			true
	connection_id	12345
	log_statement_prepare	true
	log_statement_free		true
	log_statement_start		true
	log_statement_finish	true
	time_threshold	0
</database>

b) Trace all connections of given user to database mydatabase.fdb
   Log executed INSERT, UPDATE and DELETE statements, nested calls to procedures 
   and triggers and show corresponding PLAN's and performance statistics.

<database mydatabase.fdb>
	enabled					true
	include_filter			(.*)(INSERT|UPDATE|DELETE)(.*)
	log_statement_finish	true
	log_procedure_finish	true
	log_trigger_finish		true
	print_plan				true
	print_perf				true
	time_threshold			0
</database>
	

	So far there is no specialized standalone utility to work with trace services.
Therefore examples below uses more general utility fbsvcmrg.

a) Start user trace named "My trace" using configuration file fbtrace.conf and read 
   its output on the screen :

	fbsvcmgr service_mgr action_trace_start trc_name "My trace" trc_cfg fbtrace.conf
	
	To stop this trace session press Ctrl+C at fbsvcmgr console window. Or, in 
another console : list sessions and look for interesting session ID (b) and stop 
it using this found ID (e).

b) List trace sesions

	fbsvcmgr service_mgr action_trace_list
	
c) Suspend trace sesson with ID 1

	fbsvcmgr service_mgr action_trace_suspend trc_id 1
	
d) Resume trace sesson with ID 1

	fbsvcmgr service_mgr action_trace_resume trc_id 1
	
e) Stop trace sesson with ID 1

	fbsvcmgr service_mgr action_trace_stop trc_id 1
	


    There are three general use cases :

1. Constant audit of engine. 

    This is served by system audit trace. Administrator edit (or create new) 
trace configuration file, set its name in firebird.conf (AuditTraceConfigFile 
setting) and restarts Firebird. Later administrator could suspend\resume\stop
this session without need to restart Firebird. To make audit configuration 
changes accepted by the engine, Firebird needs to be restarted.

2. On demand interactive trace of some (or all) activity in some (or all) 
   databases. 

    Application start user trace session, read its output and show traced events 
to user in real time on the screen. User could suspend\resume trace and at last 
stop it.

3. Collect some engine activity for a relatively long period of time (few hours 
   or even whole day) to analyse it later.

    Application start user trace session and read and save trace output to file 
(or set of files). Session must be stopped manually by the same application or 
by another one.