Chapter 7. Trace configuration

The trace facility of Firebird can be used to trace (record) various types of actions (e.g. connect, prepare, execute, commit) for databases and services. See also Trace and Audit Services in the Firebird 2.5 Release Notes. Beware, the configuration syntax changed between Firebird 2.5 and Firebird 3.0.

Server administrators can use the system trace to trace actions for services, all databases, or a subset of databases. The system trace can be configured in a configuration file, whose path is set in configuration item Section 3.1.7, “AuditTraceConfigFile” in firebird.conf. A default Firebird installation contains a file fbtrace.conf that shows the layout and configuration items for a system trace; this file is not used by default (the default value of AuditTraceConfigFile is empty, meaning no system trace).

Any user can start and manage a user trace using the services API. An ordinary user — not an administrator, and without the TRACE_ANY_ATTACHMENT system privilege — can request a trace only on their own connections, and cannot manage trace sessions started by other users. Administrators can manage any user trace session.

The configuration of a user trace is sent as a string to the services manager, with the same syntax as the system trace configuration file.

The actual trace output is handled by a plugin, configured in Section 3.1.27, “TracePlugin” in firebird.conf. This documentation assumes the default trace plugin included with Firebird, fbtrace.

7.1. Trace configuration syntax

The trace configuration has two main keywords.

services

The services keyword only has a Section 2.1.2, “Scope”; that is, it does not have = simple-value. This default section contains the entire trace configuration for all services.

database

The database keyword is a scoped value. It is used to configure tracing databases.

The database keyword can occur without = simple-value and only a scope — the default section. The default section contains the trace configuration items for all databases, and establishes defaults that can be overridden by a later occurrence of a database section with a simple value.

The simple value of a non-default database section is either a database filename without path or a SQL regular expression pattern which is matched against the absolute path of the database file.

ⓘ
Note

Firebird 2.5 used a different syntax for trace configuration. This reference does not cover that syntax.

The order of evaluation and description of configuration items (but not their syntax) are generally the same — assuming the configuration item existed in that version.

7.1.1. Order of evaluation

A trace configuration has the following order of evaluation rules to match a database or service

  • the configuration is processed from top to bottom

  • configuration items of a default section are applied for all databases or services

    • only one default section of each type is allowed

    • for a service, search ends

    • for a database, search continues

  • if a database name matches the pattern of a non-default section

    • its configuration items are applied

    • search ends

In other words, there can only be one (default) services section, and one default database section. At most one other database section (with value) is used for a database, the first one to match.