Debian Codegraph @

doc/README.performance_monitoring

raw
1 Performance analysis with Firebird.
2 Document version 0.2
3 Created by Nickolay Samofatov
4
5 Performance monitoring framework is consisted of 2 parts:
6 - Trace API
7 - Reference implementation of analysis plugin
8
9
10 Trace API.
11
12 Trace API allows to plug a monitoring module into the engine and notify it of
13 processes happening there. List of analysis plugins is specified in firebird.conf
14 parameter TracePlugins. Each trace plugin receives notifications on each database
15 opened by the engine as a call of procedure having following signature:
16
17 NTRACE_BOOLEAN trace_attach(const char* db_filename, const TracePlugin** plugin);
18
19 Conceptually TracePlugin is the plugin trace interface. It is implemented as a
20 structure of function pointers and void* object pointer to be passed as first
21 argument for each function.
22
23 Given this interface plugin may install hooks for particular events and receive
24 notifications for them. If plugin has interest in some kind of events for given
25 database it sets plugin pointer to a structure containing non-null hook function
26 pointers and returns NTRACE_TRUE value. Otherwise it should return NTRACE_FALSE.
27
28 One category of hooks receives the same parameters as corresponding Y-Valve
29 (public API) methods plus internal objects identifiers, generated PLANs for
30 statements and performance counters. One more hook receives performance
31 statistics for each procedure execution.
32
33 Each hook function returns boolean value indicating success or failure. When hook
34 function fails engine collects error message from plugin in the same thread
35 context as hook was called, writes message to firebird.log and stops calling
36 hooks for this particular database and trace plugin.
37
38 See jrd/ntrace.h module for definitions of structures and events supported.
39
40
41 Default analysis module.
42
43 Reference implementation of analysis plugin is centered around a concept of
44 performance snapshot. Snapshot detail may vary, but in any case it contains
45 information on all activities performed by server for database during a given
46 period of time, possibly in aggregated form. All snapshots may be compared to
47 allow quantitative measurements of performance improvements due to various
48 optimization activities or changes in user applications and infrastucture.
49
50 Snapshot data is collected by trace module in raw form in a binary log file and
51 then may be loaded into a stats database using ntrace utility.
52
53 Stored snapshots may contain data on usage of indices, statements executed, their
54 plans and performance counters, IO statistics and other performance data.
55
56 Level of detail for information collected is set up in analysis trace module
57 configuration file on per-database basis.
58
59 Default analysis module does not have GUI and only provides a database with data
60 on server activities and some stored procedures to use and maintain it.
61
62 It is expected that third parties develop GUI tools, custom trace modules and
63 statistics tools to statisfy rich client needs.