|
Quick Start Guide - Register Project |
|
|
|
|
Quick Start Guide - Register Project |
|
|
Quick Start Guide - Register Project
|
Quick Start Guide - Register Project |
|
|
|
|
Quick Start Guide - Register Project |
|
|
A project in FB TraceManager 3 is bound to a registered server and basically defines an optional trace session name and a trace configuration used when starting a new trace session.
To create/register a new project, first connect to a server then click the New Project button in the toolbar of section 3 in the Main Screen. This will open the Project Registration Wizard dialog.
Step 1
In a first step, select the server name and an optional registered database, enter the project name and an optional trace session name, e.g. shown as session name when fetching the list of started trace sessions. By selecting a different server, you are able to duplicate an existing project to another server you are currently attached to.
The Autostart option lets you run the project automatically, upon server connect.
Define optional default Session Options, a Description, which is used as default description of the trace session, and Regex Filters per project, to be used in the Trace Data Visualization facility when running a trace session, mainly for the Parsed trace data output. See the Trace Data Visualization section for a detailed discussion on the available options. The Auto Start startup option let you run the project automatically, upon server connect. Use Prompt Description to get prompted for entering a trace session description.
The Logger Service tab is explained in the FBTMLoggerSvc - Windows Service section in more detail.
The Hotspot Options tab allow you to set defaults for the Hotspots Analysis area.
Step 2
In a second step, you are prompted to define the trace configuration via various trace configuration parameters as discussed in the Firebird 2.5 release notes.
You can either load a trace configuration by selecting the Load trace configuration from file option and specifying a trace configuration file name, or by providing an user-defined trace configuration using the various options in the Database and/or Services tab.
New in V3.5: Two new trace configuration options are available: log_function_start and log_function_finish. They enable tracing stored functions in Firebird 3. If you are connecting to a Firebird 2.5.x server, then they are disabled.
Use the Template drop-down box to choose from pre-installed trace configurations or create your own, custom trace configuration options. The pre-installed templates provide a quick way to set trace configuration options for different use cases.
New in V3.0: Use the Template drop-down box to choose from pre-installed trace configurations or create your own, custom trace configuration options. The pre-installed templates provide a quick way to set trace configuration options for different use cases.
Use the New Template, Delete Template and Save Template buttons to manage your own trace configuration templates.
Database
Parameter |
Description |
Values |
database name |
Name of the database(s), which should be traced |
String (regular expression) |
enabled |
Active / Not active |
true | false |
log_connections |
Trace of connect / disconnect |
true | false |
log_transactions |
Trace of transaction events (e.g. start, commit, rollback) |
true | false |
log_statement_prepare |
Trace of statement prepare events |
true | false |
log_statement_free |
Trace of statement free events |
true | false |
log_statement_start |
Trace of statement start events |
true | false |
log_statement_finish |
Trace of statement finish events |
true | false |
log_procedure_start |
Trace of stored procedure start events |
true | false |
log_procedure_finish |
Trace of stored procedure finish events |
true | false |
log_trigger_start |
Trace of trigger start events |
true | false |
log_trigger_finish |
Trace of trigger finish events |
true | false |
log_context |
Trace of setting user-defined context variables |
true | false |
print_plan |
Print execution plan |
true | false |
print_perf |
Print detailed performance statistics |
true | false |
log_blr_requests |
Trace of BLR requests (e.g. from ESQL) |
true | false |
print_blr |
Print BLR output |
true | false |
log_dyn_requests |
Trace of DYN requests |
true | false |
print_dyn |
Print DYN output |
true | false |
log_errors |
Print error text of failed statements |
true | false |
log_warnings |
Print warning text of failed statements |
true | false |
log_sweep |
Trace of database sweep operations |
true | false |
log_function_start |
Firebird 3 only: Trace of stored function start events |
true | false |
log_function_finish |
Firebird 3 only: Trace of stored function finish events |
true | false |
explain_plan |
Firebird 3 only: New execution plan output |
true | false |
log_initfini |
Trace of session init / finish events |
true | false |
include_filter |
Explicitly trace statements, which fulfill the filter criteria |
String (regular expression) |
exclude_filter |
Explicitly not trace statements, which fulfill the filter criteria |
String (regular expression) |
connection id |
Enable trace for particular connection id's only. 0 = all connections |
Integer |
time threshold |
*_finish parameters will only apply, if execution time exceeds this value |
Integer (milliseconds) |
max. SQL length |
Maximum length of the traced SQL statement in the trace output |
Integer (number of characters) |
max. BLR length |
Maximum length of the traced BLR output in the trace output |
Integer (number of characters) |
max. DYN length |
Maximum length of the traced DYN output in the trace output |
Integer (number of characters) |
max. argument length |
Maximum length of the traced parameter names in the trace output in case of a parameterized statement |
Integer (number of characters) |
max. argument count |
Maximum number of trace parameters in the trace output in case of a parameterized statement |
Integer |
Attention: Although an empty database name is allowed (which means "all databases"), we recommend providing a database name, otherwise events on the FB TraceManager 3 database might be traced too, which can lead to unpredictable side-effects in FB TraceManager 3!
Services
Parameter |
Description |
Values |
enabled |
Active / Not active |
true | false |
log_services |
Trace of service manager attach/detach/start events |
true | false |
log_service_query |
Trace of service call results |
true | false |
log_errors |
Print error text of failed services requests |
true | false |
log_warnings |
Print warning text of failed services requests |
true | false |
log_initfini |
Trace of session init / finish events |
true | false |
include filter |
Explicitly trace service events, which fulfill the filter criteria |
String (regular expression) |
exclude filter |
Explicitly not trace service events, which fulfill the filter criteria |
String (regular expression) |
In the Services tab you are able to configure tracing of Services API requests (e.g. backup, restore, get server log etc.). A meaningful filter criteria should take into account that there is a fixed list of names defining the supported service event types by the Audit and Trace Services API of the Firebird engine. The following list is taken from the pre-installed fbtrace.conf of a Firebird 2.5.0 installation:
| • | Backup Database |
| • | Restore Database |
| • | Repair Database |
| • | Add User |
| • | Delete User |
| • | Modify User |
| • | Display User |
| • | Database Properties |
| • | Database Stats |
| • | Get Log File |
| • | Incremental Backup Database |
| • | Incremental Restore Database |
| • | Start Trace Session |
| • | Stop Trace Session |
| • | Suspend Trace Session |
| • | Resume Trace Session |
| • | List Trace Sessions |
| • | Set Domain Admins Mapping to RDB$ADMIN |
| • | Drop Domain Admins Mapping to RDB$ADMIN |
As an example, the include filter criteria %Log%|%Backup% will trace service event types with Log and Backup in its names. Thus, the Get Log File, Backup Database and Incremental Backup Database Services API requests are part of the trace output.
Attention: Use the log_service_query parameter with care, because:
| 1. | Depending on the traced Services API request, a lot of trace entries can be the result |
| 2. | When Trace Session related Services API requests are traced, this may end-up in an endless loop receiving raw (and parsed) trace data, because FB TraceManager 3 needs to use these types of Services API requests to communicate with the Audit and Trace Services API of the Firebird engine. You must exclude Trace Session related trace events when using the log_service_query parameter. |
Hint: In general, if you are unsure about your entered regular expression, simply run a similar SQL query such as:
SELECT 1 FROM RDB$DATABASE WHERE 'your constant string' SIMILAR TO 'your regular expression'
because regular expressions are internally resolved by using the SIMILAR TO predicate, introduced in Firebird 2.5.
For example, to test, if a services include filter criteria %Log% results in tracing the Get Log File service, execute:
SELECT 1 FROM RDB$DATABASE WHERE 'Get Log File' SIMILAR TO '%Log%'
If the result set includes one row and column with the value 1, then the SIMILAR TO comparison was evaluated against True.
A click on Next shows the resulting trace configuration. Click Finish to finish the creation of the new project. You are now ready to start your first trace session.
What's next: The next QSG section Start Trace Session will show you how to run a project (start a trace session).
See also