FB TraceManager 3 - Documentation

Quick Start Guide - Register Project

Quick Start Guide - Register Project

Previous topic Next topic  

Quick Start Guide - Register Project

Previous topic Next topic  

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.

 

fbtm_register_project_wizard_1.zoom25

 

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

 

 

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.

 

fbtm_register_project_wizard_2_database.zoom25

 

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.

 

fbtm_register_project_wizard_2_database_template

 

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/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

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/warning text of failed services requests

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

Main Screen

Register Server

Register Database

Start Trace Session

Trace Data Visualization

Hotspots Analysis