firebird/firebird-mirror
firebird/firebird-mirror
8
0
Fork 1
mirror of https://github.com/FirebirdSQL/firebird.git synced 2025-01-22 18:43:02 +01:00
Code Issues

Trim trailing spaces per Adriano request.

Browse Source
This commit is contained in:
hvlad 2009-02-15 00:09:44 +00:00
parent 9fcfe6dcf8
commit 8bd19f9054
1 changed files with 54 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
doc/README.trace_services
View File

@ -1,59 +1,59 @@
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.
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
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.
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
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
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
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.
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
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.
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
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
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.
@ -74,7 +74,7 @@ a) Trace prepare, free and execution of all statements within connection 12345
</database>
b) Trace all connections of given user to database mydatabase.fdb
Log executed INSERT, UPDATE and DELETE statements, nested calls to procedures
Log executed INSERT, UPDATE and DELETE statements, nested calls to procedures
and triggers and show corresponding PLAN's and performance statistics.
<database mydatabase.fdb>
@ -92,13 +92,13 @@ b) Trace all connections of given user to database mydatabase.fdb
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
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
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
@ -121,24 +121,24 @@ e) Stop trace sesson with ID 1
There are three general use cases :
1. Constant audit of engine.
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
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
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.
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
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
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.
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.