| 1 |
|
| 2 |
Trace and audit services. |
| 3 |
|
| 4 |
Firebird 2.5 offers new trace and audit facilities. These new abilities allow |
| 5 |
to log various events performed inside the engine (such as statement execution, |
| 6 |
connect\disconnect etc) and to collect corresponding performance characteristics |
| 7 |
in real time. The base term is trace session. Each trace session has its own |
| 8 |
configuration, state and output. |
| 9 |
|
| 10 |
List of available events to trace is fixed and determined by the Firebird |
| 11 |
engine. List of events to trace, which data items to trace and placement of |
| 12 |
trace output is specified by trace configuration when trace session is created. |
| 13 |
|
| 14 |
There are two kinds of trace sessions : system audit and user trace. |
| 15 |
|
| 16 |
System audit session is started by the engine itself and obtains configuration |
| 17 |
from the text file. The name of this file is set via new setting in firebird.conf |
| 18 |
("AuditTraceConfigFile") and by default has empty value, i.e. no system audit |
| 19 |
is configured. There may be only one system audit trace session, obviously. |
| 20 |
Configuration file contains list of traced events and placement of trace log(s). |
| 21 |
It is very flexible and allows to log different set of events for different |
| 22 |
databases into different log files. Example configuration file fbtrace.conf is |
| 23 |
placed in the Firebird root directory and contains full description of its |
| 24 |
format, rules and syntax. |
| 25 |
|
| 26 |
User trace session is managed by user via Services API. There are five new |
| 27 |
services for this purpose - to start, stop, suspend, resume trace session and |
| 28 |
to list all known trace sessions. See README.services_extension for details. |
| 29 |
|
| 30 |
When user application starts trace session it sets (optional) session name |
| 31 |
and (mandatory) session configuration. Session configuration is a text. Rules |
| 32 |
and syntax are the same as for configuration file mentioned above except of |
| 33 |
placement of trace output. Engine stores output of user session in set of |
| 34 |
temporary files (1MB each) and deletes it automatically when file was read |
| 35 |
completely. Maximum size of user session's output is limited and set via |
| 36 |
"MaxUserTraceLogSize" setting in firebird.conf. Default value is 10 MB. |
| 37 |
|
| 38 |
After application starts user trace session, it must read session's output |
| 39 |
from service (using isc_service_query). Session output could be produced by the |
| 40 |
engine faster than application is able to read it. When session output grows |
| 41 |
more than "MaxUserTraceLogSize" engine automatically suspends this trace |
| 42 |
session. When application reads part of the output so output size stay less than |
| 43 |
"MaxUserTraceLogSize" engine automatically resumes trace session. |
| 44 |
|
| 45 |
When application decides to stop its trace session it just does detach from |
| 46 |
service. Also there is ability to manage trace sessions (suspend\resume\stop). |
| 47 |
Administrators are allowed to manage any trace session while ordinary users are |
| 48 |
allowed to manage their own trace sessions only. |
| 49 |
|
| 50 |
If user trace session was created by ordinary user it will trace only |
| 51 |
connections established by this user. |
| 52 |
|
| 53 |
User trace sessions are not preserved when all Firebird processes are stopped. |
| 54 |
I.e. if user started trace session and Firebird SS or SC process is shut down, |
| 55 |
this session is stopped and will not be restarted with new Firebird process. For |
| 56 |
CS this is not the case as user trace session can't live without connection with |
| 57 |
service manager and dedicated CS process. |
| 58 |
|
| 59 |
|
| 60 |
There is new Trace API introduced for use with trace facilities. This API is |
| 61 |
not stable and will be changed in next Firebird releases, therefore it is not |
| 62 |
officially published. Trace API is a set of hooks which is implemented by external |
| 63 |
trace plugin module and called by the engine when any traced event happens. Trace |
| 64 |
plugin is responsible for logging these events in some form. |
| 65 |
|
| 66 |
There is "standard" implementation of trace plugin, fbtrace.dll (.so) located |
| 67 |
in \plugins folder. |
| 68 |
|
| 69 |
|
| 70 |
There is new specialized standalone utility to work with trace services : |
| 71 |
fbtracemgr. It has the following command line switches : |
| 72 |
|
| 73 |
Action switches : |
| 74 |
-STA[RT] Start trace session |
| 75 |
-STO[P] Stop trace session |
| 76 |
-SU[SPEND] Suspend trace session |
| 77 |
-R[ESUME] Resume trace session |
| 78 |
-L[IST] List existing trace sessions |
| 79 |
|
| 80 |
Action parameters switches : |
| 81 |
-N[AME] <string> Session name |
| 82 |
-I[D] <number> Session ID |
| 83 |
-C[ONFIG] <string> Trace configuration file name |
| 84 |
|
| 85 |
Connection parameters switches : |
| 86 |
-SE[RVICE] <string> Service name |
| 87 |
-U[SER] <string> User name |
| 88 |
-P[ASSWORD] <string> Password |
| 89 |
-FE[TCH] <string> Fetch password from file |
| 90 |
-T[RUSTED] <string> Force trusted authentication |
| 91 |
|
| 92 |
Also, it prints usage screen if run without parameters. |
| 93 |
|
| 94 |
|
| 95 |
Examples |
| 96 |
|
| 97 |
I. Sample configuration files for user trace sessions: |
| 98 |
|
| 99 |
a) Trace prepare, free and execution of all statements within connection 12345 |
| 100 |
|
| 101 |
database |
| 102 |
{ |
| 103 |
enabled true |
| 104 |
connection_id 12345 |
| 105 |
log_statement_prepare true |
| 106 |
log_statement_free true |
| 107 |
log_statement_start true |
| 108 |
log_statement_finish true |
| 109 |
time_threshold 0 |
| 110 |
} |
| 111 |
|
| 112 |
b) Trace all connections of given user to database mydatabase.fdb |
| 113 |
Log executed INSERT, UPDATE and DELETE statements, nested calls to procedures |
| 114 |
and triggers and show corresponding PLAN's and performance statistics. |
| 115 |
|
| 116 |
database = %[\\/]mydatabase.fdb |
| 117 |
{ |
| 118 |
enabled true |
| 119 |
include_filter (%)(INSERT|UPDATE|DELETE)(%) |
| 120 |
log_statement_finish true |
| 121 |
log_procedure_finish true |
| 122 |
log_trigger_finish true |
| 123 |
print_plan true |
| 124 |
print_perf true |
| 125 |
time_threshold 0 |
| 126 |
} |
| 127 |
|
| 128 |
c) Trace connections and transactions in all databases except of security database |
| 129 |
|
| 130 |
database |
| 131 |
{ |
| 132 |
enabled true |
| 133 |
log_connections true |
| 134 |
log_transactions true |
| 135 |
} |
| 136 |
|
| 137 |
database = security.db |
| 138 |
{ |
| 139 |
enabled false |
| 140 |
} |
| 141 |
|
| 142 |
|
| 143 |
|
| 144 |
II. Working with fbtracemgr : |
| 145 |
|
| 146 |
a) Start user trace named "My trace" using configuration file fbtrace.conf and read |
| 147 |
its output on the screen : |
| 148 |
|
| 149 |
fbtracemgr -se service_mgr -start -name "My trace" -config fbtrace.conf |
| 150 |
|
| 151 |
To stop this trace session press Ctrl+C at fbtracemgr console window. Or, in |
| 152 |
another console : list sessions and look for interesting session ID (b) and stop it |
| 153 |
using this found ID (e). |
| 154 |
|
| 155 |
b) List trace sesions |
| 156 |
|
| 157 |
fbtracemgr -se service_mgr -list |
| 158 |
|
| 159 |
c) Suspend trace sesson with ID 1 |
| 160 |
|
| 161 |
fbtracemgr -se service_mgr -suspend -id 1 |
| 162 |
|
| 163 |
d) Resume trace sesson with ID 1 |
| 164 |
|
| 165 |
fbtracemgr -se service_mgr -resume -id 1 |
| 166 |
|
| 167 |
e) Stop trace sesson with ID 1 |
| 168 |
|
| 169 |
fbtracemgr -se service_mgr -stop -id 1 |
| 170 |
|
| 171 |
|
| 172 |
|
| 173 |
There are three general use cases : |
| 174 |
|
| 175 |
1. Constant audit of engine. |
| 176 |
|
| 177 |
This is served by system audit trace. Administrator edits (or creates new) |
| 178 |
trace configuration file, sets its name in firebird.conf (AuditTraceConfigFile |
| 179 |
setting) and restarts Firebird. Later, administrator could suspend\resume\stop |
| 180 |
this session without need to restart Firebird. To make audit configuration |
| 181 |
changes accepted by the engine, Firebird needs to be restarted. |
| 182 |
|
| 183 |
2. On demand interactive trace of some (or all) activity in some (or all) |
| 184 |
databases. |
| 185 |
|
| 186 |
Application starts user trace session, reads its output and shows traced events |
| 187 |
to user in real time on the screen. User could suspend\resume trace and at last |
| 188 |
stop it. |
| 189 |
|
| 190 |
3. Collect some engine activity for a relatively long period of time (few hours |
| 191 |
or even whole day) to analyse it later. |
| 192 |
|
| 193 |
Application starts user trace session and reads and saves trace output to a file |
| 194 |
(or set of files). Session must be stopped manually by the same application or |
| 195 |
by another one. |