diff --git a/doc/README.trace_services b/doc/README.trace_services index a21aec216fc..f88a337adea 100644 --- a/doc/README.trace_services +++ b/doc/README.trace_services @@ -1,4 +1,4 @@ - + Trace and audit services. Firebird 2.5 offers new trace and audit facilities. These new abilities allow @@ -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 @@ -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 @@ -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 : @@ -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 @@ -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 } @@ -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 : diff --git a/src/utilities/ntrace/fbtrace.conf b/src/utilities/ntrace/fbtrace.conf index a8c6a359df7..daf0bd2a1d1 100644 --- a/src/utilities/ntrace/fbtrace.conf +++ b/src/utilities/ntrace/fbtrace.conf @@ -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 @@ -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 @@ -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 @@ -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 @@ -164,19 +164,19 @@ 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 } @@ -184,7 +184,7 @@ database # 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 @@ -209,7 +209,7 @@ database # Display User with Admin Info # Validate Database # -services +services { # Do we trace services events or not #enabled = false @@ -217,19 +217,19 @@ services # 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 @@ -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 @@ -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