.. raw:: latex

  \appcount

.. _parameter_description:

Description of parameters
===========================

.. _db_connection:

Database connection parameters
-----------------------------------------

.. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
.. list-table:: Database connection parameters
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - JDBC driver
     - Select JDBC driver from the drop-down list to create a new database. For Red Database and Firebird JDBC driver ``Jaybird 5`` is recommended.
   * - Connection name 
     - Database connection name
   * - Server name 
     - Database server host or IP address
   * - Port 
     - Port for database connection
   * - Database file 
     - Path to database file or alias
   * - Username
     - Username of user in whose name the database will be created
   * - Password 
     - User password
   * - Save password 
     - Should password be saved for connecting to database
   * - Encrypt password
     - Should password be stored in encrypted form
   * - Encoding 
     - Specifies default character set for string (character) values of the entire database.
   * - Page size 
     - Size of the database page in bytes. Valid values are 4096, 8192 and 16384.

.. _db_extended_connection:

Extended database connection parameters
------------------------------------------------------

This table lists some parameters for the ``Jaybird 5`` driver:

.. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\ttfamily\arraybackslash}\X{3}{17}|>{\arraybackslash}\X{8}{17}|
.. list-table:: Extended database connection parameters
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Type
     - Description
   * - isc_dpb_user_name 
     - string 
     - Name of the connecting user.
   * - isc_dpb_password 
     - string 
     - User Password.
   * - isc_dpb_sql_role_name 
     - string 
     - Role
   * - isc_dpb_sql_dialect 
     - byte 
     - SQL dialect.
   * - isc_dpb_process_id 
     - int 
     - Process ID.
   * - isc_dpb_process_name 
     - string 
     - Process name.
   * - isc_dpb_lc_ctype 
     - string
     - Connection character encoding. This parameter tells database server what encoding should be used to send string values to client.
   * - isc_dpb_connect_timeout 
     - int 
     - Connection timeout (in seconds).
   * - isc_dpb_gss
     - \- 
     - Use trusted authentication ``Gss``.
   * - isc_dpb_num_buffers 
     - int 
     - Number of database pages to be cached.
   * - isc_dpb_set_db_readonly 
     - boolean 
     - Set database to read-only mode.
   * - isc_dpb_set_db_charset 
     - string 
     - Set character set for the database.
   * - isc_dpb_max_inline_blob_size
     - \-
     - Maximum size in bytes of inline blobs. A value of 0 disables transmission of inline blobs. Default 65535, maximum value 65535.
   * - isc_dpb_max_blob_cache_size
     - \-
     - Maximum size in bytes per connection of the inline blob cache. 
       A value of 0 disables the cache. 
       Disabling the cache does not disable transmission of inline blobs: set maxInlineBlobSize to 0 to disable transmission. 
       Default 10485760 (10 MiB).
   * - isc_dpb_set_db_sql_dialect
     - \-
     - Set the SQL dialect of the database.
   * - isc_dpb_parallel_workers
     - \-
     - The number of parallel workers to use.

.. _driver:

Parameters for adding a driver
--------------------------------------

.. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
.. list-table:: Parameters for adding a driver
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - Driver name 
     - Driver name for identification
   * - Description 
     - Description of this driver
   * - Database
     - Select DBMS for which this driver is used
   * - JDBC URL 
     - The ``URL address`` template for this ``JDBC`` driver. For example: ``jdbc:firebirdsql://[host]:[port]/[source]``.
   * - Path 
     - Path to jar file of ``JDBC driver``
   * - Class name
     - Class name of JDBC driver. Select the search button if the name is unknown and the system scans the ``jar`` file entered in the path field to find the driver class name

.. _trace_conf:

Trace manager configuration file settings
-------------------------------------------------

.. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
.. list-table:: Trace manager configuration file settings
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - log_security_incidents 
     - Server security events (security incidents)
   * - log_initfini/log_init 
     - Events of start/stop of database logging
   * - log_connections 
     - Events of connection/disconnection to database
   * - log_transactions 
     - Transaction start and completion events
   * - log_statement_prepare
     - Database query preparation events
   * - log_statement_free 
     - Database query release events
   * - log_statement_start
     - Events of start execution of queries to database
   * - log_statement_finish 
     - Events of finish execution of queries to database
   * - log_procedure_start 
     - Events of start execution stored procedures
   * - log_procedure_finish 
     - Events of finish execution stored procedures
   * - log_function_start 
     - Events of start execution stored function
   * - log_function_finish 
     - Events of finish  execution stored function
   * - log_trigger_start 
     - Trigger execution start events
   * - log_trigger_finish 
     - Trigger execution finish events
   * - log_context 
     - Events of context variable value changes
   * - log_errors 
     - Error logging
   * - log_warnings 
     - Warning logging
   * - print_plan 
     - Print query plans
   * - print_perf 
     - Print query execution statistics
   * - log_blr_requests 
     - Direct execution events of compiled queries in internal server view - ``BLR``
   * - print_blr 
     - Content of ``BLR requests`` will be converted to text representation, otherwise it will remain in binary form
   * - log_dyn_requests
     - Events of direct execution of compiled metadata change queries (``DDL``) in the internal server view - ``DYN``
   * - print_dyn 
     - Content of ``DYN queries`` will be converted to text representation, otherwise it will remain in binary form
   * - log_privilege_changes 
     - Privilege change events
   * - log_changes_only 
     - Recording only those events that changed data in the database
   * - print_stack_trace 
     - Print stack of server function calls when an error event is terminated
   * - log_auth_factors 
     - Events of verification authentication factors
   * - log_mandatory_access 
     - Mandate access audit
   * - log_record_mandatory_access 
     - Events about mandate access to records
   * - log_object_relabeling 
     - Events of object label change
   * - log_record_relabeling 
     - Events of record label change
   * - log_services 
     - Connection/disconnection and service start events
   * - log_service_query 
     - Events of service queries
   * - include_user_filter 
     - Regular expression to which the user name must match
   * - exclude_user_filter 
     - Connections from users matching this regular expression will not be logged
   * - include_process_filter 
     - Regular expression to be matched by the name of the user process
   * - exclude_process_filter 
     - Connections from processes that match this regular expression will not be logged
   * - include_filter 
     - Regular expression in ``SQL`` syntax (``SIMILAR TO``), which must be matched by the text of ``SQL query``.
   * - exclude_filter 
     - Regular expression in ``SQL`` syntax (``SIMILAR TO``), which must not be matched by the text of ``SQL query``.
   * - connection_id 
     - Connection identifie on server that will be monitored
   * - log_filename 
     - Log file name
   * - max_log_size 
     - Maximum size of log files in megabytes. A value of 0 means unlimited size
   * - time_threshold 
     - Events whose execution time is less than specified time (in ms) will not be logged 
   * - max_sql_length 
     - Maximum length of one SQL query record in log file, in bytes
   * - max_blr_length 
     - Maximum length of BLR query to be logged, in bytes
   * - max_dyn_length 
     - Maximum length of DYN-query to be logged, in bytes
   * - max_arg_length 
     - Maximum length of one query/procedure parameter in log file
   * - max_arg_count
     - Maximum number of query/procedure parameters to be logged

.. _trace_manager_table:

Trace manager events table
------------------------------------

Description of each column in events table is given below:

.. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{8}{17}|>{\arraybackslash}\X{9}{17}|
.. list-table:: Description of events table columns
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - NUM 
     - Row number
   * - TSTAMP 
     - Time and date of event
   * - ID_PROCESS 
     - Process ID
   * - ID_THREAD 
     - Thread ID
   * - EVENT_TYPE 
     - Event type
   * - FAILED 
     - In case of unsuccessful or unauthorised attempt to execute query, the result ``FAILED`` or ``UNAUTHORIZED`` is logged
   * - ID_SESSION 
     - Session ID
   * - NAME_SESSION 
     - Session name
   * - ID_SERVICE 
     - Service ID
   * - USERNAME 
     - Username
   * - PROTOCOL_CONNECTION 
     - Connection protocol
   * - CLIENT_ADDRESS 
     - IP address or computer name
   * - TYPE_QUERY_SERVICE 
     - Service query type
   * - OPTIONS_START_SERVICE 
     - Options passed to service manager from client at start
   * - ROLE 
     - User role
   * - DATABASE 
     - Database name
   * - CHARSET 
     - Encoding
   * - ID_CONNECTION 
     - Connection ID
   * - CLIENT_PROCESS 
     - Client process
   * - ID_CLIENT_PROCESS 
     - Client process ID
   * - ID_TRANSACTION 
     - Transaction ID
   * - LEVEL_ISOLATION 
     - Isolation level
   * - MODE_OF_BLOCK 
     - Lock mode (WAIT or NO WAIT)
   * - MODE_OF_ACCESS 
     - Access mode
   * - TIME_EXECUTION 
     - Execution time (in ms)
   * - COUNT_READS 
     - Number of pages read from the disc
   * - COUNT_WRITES 
     - Number of pages written to disc
   * - COUNT_FETCHES 
     - Number of pages fetched from page cache
   * - COUNT_MARKS 
     - Number of pages modified in page cache
   * - ID_STATEMENT 
     - Query ID
   * - RECORDS_FETCHED 
     - Number of fetched records
   * - STATEMENT_TEXT 
     - Query content
   * - PARAMETERS_TEXT 
     - Query execution parameters
   * - PLAN_TEXT 
     - Query plan
   * - TABLE_COUNTERS 
     - Table counters
   * - DECLARE_CONTEXT_VARIABLES 
     - Name and value of context variable
   * - EXECUTOR 
     - Users, roles and database objects for which privileges have been granted
   * - GRANTOR 
     - User who grants privileges
   * - PRIVILEGE 
     - Assigned/revoked privilege
   * - PRIVILEGE_OBJECT 
     - Object for which the privilege is granted (revoked)
   * - PRIVILEGE_USERNAME 
     - User assigned the privilege
   * - PRIVILEGE_ATTACHMENT 
     - Connection ID
   * - PRIVILEGE_TRANSACTION 
     - Transaction ID
   * - PROCEDURE_NAME 
     - Procedure name
   * - RETURN_VALUE 
     - Return values of procedure
   * - TRIGGER_INFO 
     - ``<trigger_name> [FOR <table_name>] (ON <database event> | {BEFORE | AFTER} <table event or DDL event>)``
   * - SENT_DATA 
     - Data passed to service manager
   * - RECEIVED_DATA 
     - Data received by service manager
   * - ERROR_MESSAGE 
     - Error message text
   * - OLDEST_INTERESTING 
     - Number of oldest interested transaction
   * - OLDEST_ACTIVE 
     - Oldest active transaction number
   * - OLDEST_SNAPSHOT 
     - Number of transaction that was active at the time the ``OAT`` transaction was started
   * - NEXT_TRANSACTION 
     - Next transaction number
   * - SORT_MEMORY_USAGE_TOTAL 
     - Total cache size (in bytes) allocated during the sorting process
   * - SORT_MEMORY_USAGE_CACHED 
     - RAM cache size (in bytes) allocated during the sorting process
   * - SORT_MEMORY_USAGE_ON_DISK 
     - Disc cache size

.. _trace_manager_res_table:

Trace analysis
----------------

Description of resulting table columns:

.. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
.. list-table:: Description of resulting table columns:
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - QUERY
     - Query text
   * - COUNT 
     - Query execution count
   * - PLAN_COUNT 
     - Query plan count
   * - TOTAL_TIME 
     - Total execution time in milliseconds
   * - MIN_TIME 
     - Minimum execution time in milliseconds
   * - AVG_TIME
     - Average execution time in milliseconds
   * - MAX_TIME 
     - Maximum execution time in milliseconds
   * - STD_DEV_TIME 
     - Standard deviation of execution time
   * - TOTAL_READ 
     - Total pages read from disc
   * - MIN_READ 
     - Minimum number of pages read from disc
   * - AVG_READ 
     - Average number of pages read from disc
   * - MAX_READ 
     - Maximum number of pages read from disc
   * - STD_DEV_READ 
     - Standard deviation of number of pages read from disc
   * - TOTAL_FETCH 
     - Total number of pages read from page cache
   * - MIN_FETCH 
     - Minimum number of pages read from page cache
   * - AVG_FETCH 
     - Average number of pages read from page cache
   * - MAX_FETCH 
     - Maximum number of pages read from page cache
   * - STD_DEV_FETCH 
     - Standard deviation of number of pages read from page cache
   * - TOTAL_WRITE 
     - Total number of pages recorded on disc
   * - MIN_WRITE 
     - Minimum number of pages recorded on disc
   * - AVG_WRITE 
     - Average number of pages recorded on disc
   * - MAX_WRITE 
     - Maximum number of pages recorded on disc
   * - STD_DEV_WRITE 
     - Standard deviation of number of pages recorded on disc
   * - TOTAL_MARK 
     - Total number of pages edited in page cache
   * - MIN_MARK 
     - Minimum number of pages edited in page cache
   * - AVG_MARK 
     - Average number of pages edited in page cache
   * - MAX_MARK 
     - Maximum number of pages edited in page cache
   * - STD_DEV_MARK 
     - Standard deviation of number of pages edited in page cache
   * - TOTAL_RSORT 
     - Total RAM used for sorting (in bytes)
   * - MIN_RSORT
     - Minimum RAM used for sorting (in bytes)
   * - AVG_RSORT 
     - Average RAM used for sorting (in bytes)
   * - MAX_RSORT 
     - Maximum RAM used for sorting (in bytes)
   * - STD_DEV_RSORT 
     - Standard deviation of RAM used for sorting
   * - TOTAL_DSORT 
     - Total temporary file size used in query (in bytes)
   * - MIN_DSORT 
     - Minimum temporary file size used in query (in bytes)
   * - AVG_DSORT 
     - Average size temporary files used in query (in bytes)
   * - MAX_DSORT 
     - Maximum temporary file size used in query (in bytes)
   * - STD_DEV_DSORT 
     - Standard deviation of temporary file size used in query

.. _gstat:

Database statistics
----------------------------

Statistics of data pages
""""""""""""""""""""""""""""""
 
 .. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
 .. list-table:: Statistics of data pages
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - name 
     - Table name
   * - primary pointer page 
     - First page number of indirect pointers to pages storing table data
   * - index root page 
     - Page number, which is first page of index pointers to table indexes
   * - pointer pages
     - Total indirect pointer pages to pages storing table data
   * - data pages
     - Total pages that store table data. This count includes pages storing unconfirmed versions of records and garbage because gstat cannot distinguish them from each other
   * - data page slots 
     - Number of database page pointers contained in the pointer pages. Must be equal to number of data pages
   * - primary pages
     - Number of pages equal to (``Data pages - Secondary pages``)
   * - secondary pages 
     - Number pages on which no primary versions of records are stored
   * - swept pages
     - Number of pages that have only primary versions of records, and all of them were created by committed transactions. Such data pages should be skipped by sweep procedure
   * - empty pages 
     - Number of pages with no records
   * - full pages 
     - Number of full pages
   * - big record pages 
     - Number of pages that are filled with only one record
   * - blob pages 
     - Number of pages with blobs
   * - average record length 
     - Average size of a compressed record in bytes
   * - total records 
     - Total number of rows in table
   * - average version length 
     - Average length of old versions in bytes
   * - total versions 
     - Total number of old versions in table
   * - max versions 
     - Maximum chain of old versions to be recorded
   * - average fill 
     - Histogram of memory usage distribution for all pages allocated in table
   * - total formats 
     - Total formats in ``RDB$FORMATS`` table
   * - used formats 
     - Number of used formats
   * - average fragment length 
     - Average fragment size in bytes
   * - total fragments 
     - Number of fragments in all records
   * - max fragments 
     - Maximum number of fragments per record
   * - average unpacked length 
     - Average record size in bytes (not compressed)
   * - compression ratio
     - Ratio of average uncompressed key length (``Average prefix length + Average data length``) to average compressed key length (``Average key length``).
   * - blobs 
     - Number of all blobs (level 0, 1 and 2)
   * - total length 
     - Blob size, in bytes
   * - level <n> 
     - Number of blobs per level
   * - table size(without blobs)
     - Table size in bytes (``data pages * page size``). Calculated column
   * - size with blobs 
     - Aggregate size of table data (``table size(without blobs) + blobs total length``). Calculated column
   * - size with blob pages 
     - (``table size(without blobs) + blob pages * page size``). Calculated column
   * - size with indices
     - Aggregate size of table data and aggregate size of all indices on table. Calculated using following formula:

       :math:`X = S + \sum_{i=0}^{n} E_i`,

       ``S`` – ``size with blob pages``;

       ``n`` – number of indexes in table;

       ``E`` – estimated index size in bytes (``estimated full size``).
   * - range <percentage full> 
     - Number of pages that are filled by specified percentage

Index statistics
""""""""""""""""""""""""""""""
 
 .. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
 .. list-table:: Index statistics
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - name 
     - Index name
   * - table name 
     - Table name
   * - real selectivity 
     - Calculated using following formula: ``1 / (nodes - totalDup)``
   * - average data length
     - Average length of each key in bytes. This is likely smaller than actual sum of column sizes because Red Database uses index compression to reduce the amount of data stored on an index sheet page
   * - total dup 
     - Total number of index duplicate rows
   * - max dup
     - Number of nodes that have the highest number of duplicates. Will always be zero for unique indices. If the number is large compared to the number in ``total dup``, it is a sign of low selectivity
   * - root page 
     - Index root page number
   * - depth
     - Number of levels in index tree page. If the depth of the index page tree exceeds 3, access to records through the index will not be maximised. To reduce the depth of the index page tree, increase the page size. If increasing the page size does not reduce the depth, increase the page size again
   * - leaf buckets
     - Number of the lowest level (leaf) pages in the index tree. These are pages that contain pointers to records. High-level pages contain indirect links.
   * - leaf full size 
     - Size of the lowest level (leaf) pages in the index tree (``leaf buckets * page size``). Calculated column
   * - estimated full size
     - Approximate index size in bytes. Calculated using following formula:

       :math:`N = L * (1+\frac{A}{P})^{D - 1}*P`
       
       ``N`` – approximate index size in bytes;

       ``L`` – number of lowest level pages (leaf pages) in index tree (``leaf buckets``);

       ``A`` – average node size in bytes (``average node length``);

       ``P`` – average node size in bytes (``average node length``);

       ``D`` – number of levels in index tree page (``depth``).
   * - nodes
     - Total number of records indexed in the tree. Must be equal to the number of indexed rows in the tree, although the gstat report may include nodes that were deleted but not cleaned up in the garbage collection. May also include multiple items for records that have had their index key changed
   * - average node length 
     - Average node size in bytes
   * - average key length
     - Average key size in bytes including compression. The length of each key is added 1 to 5 bytes depending on the key size and prefix. The average key size is then calculated
   * - compression ratio 
     - Average key and prefix length in bytes
   * - average prefix length 
     - Average size (in bytes) used by node prefixes
   * - average data length
     - Average length of each key in bytes. This is likely smaller than the actual sum of column sizes, because Red Database uses index compression to reduce the amount of data stored on an index sheet page
   * - clustering factor
     - It is a measure of how much I/O the database would perform if it had to read every row in the table by index, in index order. That is, it shows how ordered the rows in the table are by the index values. If the value is close to the total number of pages, then the table is very well ordered. In this case, index entries on the same page of the index sheet usually point to rows that are in the same data pages. If the value is close to the total number of rows, then the table is very disordered. In this case, it is unlikely that index entries on the same page of the index sheet point to the same data pages
   * - ratio 
     - Ratio of ``Clustering factor`` to the total number of nodes in the index
   * - full size
     - Index size in bytes. Calculated by the formula: :math:`L * (1+\frac{A}{P})^{D - 1}*P`,
       
       ``L`` – number of the lowest level pages (leaf pages) in the index tree (``leaf buckets``);

       ``A`` – average node size in bytes (``average node length``);

       ``P`` – database page size (``page size``);

       ``D`` – number of levels in a page of index tree(``depth``).

Tablespace statistics
""""""""""""""""""""""""""""""""""""""""""
 
 .. tabularcolumns:: |>{\ttfamily\arraybackslash}\X{6}{17}|>{\arraybackslash}\X{11}{17}|
 .. list-table:: Tablespace statistics
   :class: longtable
   :header-rows: 1

   * - Parameter
     - Description
   * - name 
     - Tablespace name
   * - full path 
     - Path to tablespace file
   * - table count 
     - Number of tables in the tablespace
   * - index count 
     - Number of indexes in tablespace
