Debian Codegraph @

doc/README.trace_services

raw
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.