Skip to content

Fix trace docs still using parts of FB 2.5 syntax #8823

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mrotteveel merged 1 commit into from
Dec 12, 2025
+77 −77
Merged

Fix trace docs still using parts of FB 2.5 syntax #8823

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions doc/README.trace_services
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@

Trace and audit services.

Firebird 2.5 offers new trace and audit facilities. These new abilities allow
Expand All @@ -12,7 +12,7 @@ engine. List of events to trace, which data items to trace and placement of
trace output is specified by trace configuration when trace session is created.

There are two kinds of trace sessions : system audit and user trace.

System audit session is started by the engine itself and obtains configuration
from the text file. The name of this file is set via new setting in firebird.conf
("AuditTraceConfigFile") and by default has empty value, i.e. no system audit
Expand Down Expand Up @@ -44,7 +44,7 @@ session. When application reads part of the output so output size stay less than

When application decides to stop its trace session it just does detach from
service. Also there is ability to manage trace sessions (suspend\resume\stop).
Administrators are allowed to manage any trace session while ordinary users are
Administrators are allowed to manage any trace session while ordinary users are
allowed to manage their own trace sessions only.

If user trace session was created by ordinary user it will trace only
Expand All @@ -65,9 +65,9 @@ plugin is responsible for logging these events in some form.

There is "standard" implementation of trace plugin, fbtrace.dll (.so) located
in \plugins folder.


There is new specialized standalone utility to work with trace services :

There is new specialized standalone utility to work with trace services :
fbtracemgr. It has the following command line switches :

Action switches :
Expand All @@ -94,20 +94,20 @@ Also, it prints usage screen if run without parameters.


Examples

I. Sample configuration files for user trace sessions:

a) Trace prepare, free and execution of all statements within connection 12345

database
{
enabled true
connection_id 12345
log_statement_prepare true
log_statement_free true
log_statement_start true
log_statement_finish true
time_threshold 0
enabled = true
connection_id = 12345
log_statement_prepare= true
log_statement_free = true
log_statement_start = true
log_statement_finish = true
time_threshold = 0
}

b) Trace all connections of given user to database mydatabase.fdb
Expand All @@ -116,28 +116,28 @@ b) Trace all connections of given user to database mydatabase.fdb

database = %[\\/]mydatabase.fdb
{
enabled true
include_filter (%)(INSERT|UPDATE|DELETE)(%)
log_statement_finish true
log_procedure_finish true
log_trigger_finish true
print_plan true
print_perf true
time_threshold 0
enabled = true
include_filter = (%)(INSERT|UPDATE|DELETE)(%)
log_statement_finish = true
log_procedure_finish = true
log_trigger_finish = true
print_plan = true
print_perf = true
time_threshold = 0
}

c) Trace connections and transactions in all databases except of security database

database
{
enabled true
log_connections true
log_transactions true
enabled = true
log_connections = true
log_transactions = true
}

database = security.db
{
enabled false
enabled = false
}


Expand All @@ -148,27 +148,27 @@ a) Start user trace named "My trace" using configuration file fbtrace.conf and r
its output on the screen :

fbtracemgr -se service_mgr -start -name "My trace" -config fbtrace.conf

To stop this trace session press Ctrl+C at fbtracemgr console window. Or, in
another console : list sessions and look for interesting session ID (b) and stop it
another console : list sessions and look for interesting session ID (b) and stop it
using this found ID (e).

b) List trace sessions

fbtracemgr -se service_mgr -list

c) Suspend trace session with ID 1

fbtracemgr -se service_mgr -suspend -id 1

d) Resume trace session with ID 1

fbtracemgr -se service_mgr -resume -id 1

e) Stop trace session with ID 1

fbtracemgr -se service_mgr -stop -id 1



There are three general use cases :
Expand Down
88 changes: 44 additions & 44 deletions src/utilities/ntrace/fbtrace.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@
# expression which is matched against fully qualified database path name.
#
# For log file name Sed syntax for substitutions is supported.
# I.e. \0 - whole matched string, \1 ... \9 - parenthesis subexpressions.
# I.e. \0 - whole matched string, \1 ... \9 - parenthesis subexpressions.
# \\ is backslash.
#
# String values should be enclosed into double quotes if contains
# String values should be enclosed into double quotes if contains
# spaces embedded, for example:
# log_filename "C:\\Documents and Settings\\Firebird\\My Documents\\trace.log"
# include_filter "Database Stats"
#
# To enter curvy brackets { } somewhere in a configuration dup them: {{ }}.
# To enter braces { } in a configuration value, double them: {{ }}.
# For example - to enter this regular expression
# database = (%[\\/](e[[:DIGIT:]]{2}).fdb)
# type
Expand All @@ -41,72 +41,72 @@ database
# Operations log file name. For use by system audit trace only
#log_filename = name

# Maximum size of log file (megabytes). Used by system audit trace for
# Maximum size of log file (megabytes). Used by system audit trace for
# log's rotation : when current log file reached this limit it is renamed
# using current date and time and new log file is created. Value of zero
# using current date and time and new log file is created. Value of zero
# means that the log file size is unlimited and rotation will never happen.
#max_log_size = 0


# SQL query filters.
# SQL query filters.
#
# Only SQL statements falling under given regular expression are reported
# Only SQL statements falling under given regular expression are reported
# in the log.
#include_filter
#include_filter =

# SQL statements falling under given regular expression are NOT reported
# SQL statements falling under given regular expression are NOT reported
# in the log.
#exclude_filter
#exclude_filter =


# Put attach/detach log records
# Put attach/detach log records
#log_connections = false

# Trace only given connection id. If zero - trace all connections
# Trace only given connection id. If zero - trace all connections
#connection_id = 0

# Put transaction start/end records
# Put transaction start/end records
#log_transactions = false


# Put sql statement prepare records
# Put sql statement prepare records
#log_statement_prepare = false

# Put sql statement free records
# Put sql statement free records
#log_statement_free = false

# Put sql statement execution start records
# Put sql statement execution start records
#log_statement_start = false
# Put sql statement execution finish\fetch to eof records

# Put sql statement execution finish\fetch to eof records
#log_statement_finish = false


# Put record when stored procedure is being compiled
#log_procedure_compile = false

# Put record when stored procedure is start execution
# Put record when stored procedure is start execution
#log_procedure_start = false

# Put record when stored procedure is finish execution
# Put record when stored procedure is finish execution
#log_procedure_finish = false

# Put record when stored function is being compiled
#log_function_compile = false

# Put record when stored function is start execution
# Put record when stored function is start execution
#log_function_start = false

# Put record when stored function is finish execution
# Put record when stored function is finish execution
#log_function_finish = false

# Put record when trigger is being compiled
#log_trigger_compile = false

# Put trigger execute records
# Put trigger execute records
#log_trigger_start = false

# Put trigger execute records
# Put trigger execute records
#log_trigger_finish = false


Expand All @@ -125,11 +125,11 @@ database

# Include filter. If empty, trace all errors\warnings events.
# Else trace event if any code from list is found in status-vector.
#include_gds_codes
#include_gds_codes =

# Exclude filter. If empty, trace all errors\warnings events.
# Else trace event if no code from list is found in status-vector.
#exclude_gds_codes
#exclude_gds_codes =

# Put trace session init and finish messages
#log_initfini = true
Expand All @@ -148,13 +148,13 @@ database
#print_perf = false


# Put blr requests compile/execute records
# Put blr requests compile/execute records
#log_blr_requests = false

# Print blr requests or not
#print_blr = false

# Put dyn requests execute records
# Put dyn requests execute records
#log_dyn_requests = false

# Print dyn requests or not
Expand All @@ -164,27 +164,27 @@ database
# Put xxx_finish record only if its timing exceeds this number of milliseconds
#time_threshold = 100

# Maximum length of SQL string logged
# Maximum length of SQL string logged
#max_sql_length = 300

# Maximum length of blr request logged
# Maximum length of blr request logged
#max_blr_length = 500

# Maximum length of dyn request logged
# Maximum length of dyn request logged
#max_dyn_length = 500

# Maximum length of individual string argument we log
# Maximum length of individual string argument we log
#max_arg_length = 80

# Maximum number of query arguments to put in log
# Maximum number of query arguments to put in log
#max_arg_count = 30
}



# default services section
#
# List of names of currently existing Firebird services (to use with service
# List of names of currently existing Firebird services (to use with service
# filters below) :
# Backup Database
# Restore Database
Expand All @@ -209,27 +209,27 @@ database
# Display User with Admin Info
# Validate Database
#
services
services
{
# Do we trace services events or not
#enabled = false

# Operations log file name. For use by system audit trace only
#log_filename = name

# Maximum size of log file (megabytes). Used by system audit trace for
# log's rotation
# Maximum size of log file (megabytes). Used by system audit trace for
# log's rotation
#max_log_size = 0

# Services filters.
#
# Only services whose names fall under given regular expression are
# Only services whose names fall under given regular expression are
# reported in the log.
#include_filter
#include_filter =

# Services whose names fall under given regular expression are NOT
# Services whose names fall under given regular expression are NOT
# reported in the log.
#exclude_filter
#exclude_filter =

# Put service attach, detach and start records
#log_services = false
Expand All @@ -249,11 +249,11 @@ services

# Include filter. If empty, trace all errors\warnings events.
# Else trace event if any code from list is found in status-vector.
#include_gds_codes
#include_gds_codes =

# Exclude filter. If empty, trace all errors\warnings events.
# Else trace event if no code from list is found in status-vector.
#exclude_gds_codes
#exclude_gds_codes =

# Put trace session init and finish messages
#log_initfini = true
Expand All @@ -271,7 +271,7 @@ database = %[\\/]my_database.fdb


# Enable logging for test.fdb, azk2.fdb and rulez.fdb in any directory
# into log file name matching database name - test.log, azk2.log and
# into log file name matching database name - test.log, azk2.log and
# rulez.log appropriately
#
database = %[\\/](test|azk2|rulez).fdb
Expand Down
Loading