firebird.lib.monitor¶

Enums¶

class firebird.lib.monitor.BackupState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: IntEnum

Physical backup state.

MERGE = 2¶

NORMAL = 0¶

STALLED = 1¶

class firebird.lib.monitor.State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: IntEnum

Object state.

ACTIVE = 1¶

IDLE = 0¶

class firebird.lib.monitor.IsolationMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: IntEnum

Transaction solation mode.

Changed in version 1.4.0: - READ_COMMITTED_READ_CONSISTENCY value added

CONCURRENCY = 1¶

CONSISTENCY = 0¶

READ_COMMITTED_NO_RV = 3¶

READ_COMMITTED_READ_CONSISTENCY = 4¶

READ_COMMITTED_RV = 2¶

class firebird.lib.monitor.Group(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: IntEnum

Statistics group.

ATTACHMENT = 1¶

CALL = 4¶

DATABASE = 0¶

STATEMENT = 3¶

TRANSACTION = 2¶

class firebird.lib.monitor.Security(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Security database.

DEFAULT = 'Default'¶

OTHER = 'Other'¶

SELF = 'Self'¶

class firebird.lib.monitor.CryptState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: IntEnum

Database encryption state.

New in version 1.4.0.

DECRYPTION_IN_PROGRESS = 2¶

ENCRYPTED = 1¶

ENCRYPTION_IN_PROGRESS = 3¶

NOT_ENCRYPTED = 0¶

Classes¶

class firebird.lib.monitor.Monitor(connection: Connection)[source]¶

Bases: object

Class for access to Firebird monitoring tables.

Parameters:: connection (Connection) –

__init__(connection: Connection)[source]¶

Parameters:: connection (Connection) – Connection that should be used to access monitoring tables.

clear()[source]¶: Clear all data fetched from monitoring tables.

Note

A snapshot is created the first time any of the monitoring information is being accessed.

close() → None[source]¶

Sever link to Connection.

Return type:: None

take_snapshot() → None[source]¶

Takes fresh snapshot of the monitoring information.

Return type:: None

property attachments: DataList[AttachmentInfo]¶: List of all attachments.

property callstack: DataList[CallStackInfo]¶: List with complete call stack.

property closed: bool¶: True if link to Connection is closed.

property compiled_statements: DataList[CompiledStatementInfo]¶: List of all compiled statements.

New in version 1.4.0.

property db: DatabaseInfo¶: DatabaseInfo object for attached database.

property iostats: DataList[IOStatsInfo]¶: List of all I/O statistics.

property statements: DataList[StatementInfo]¶: List of all statements.

property tablestats: DataList[TableStatsInfo]¶: List of all table record I/O statistics.

property this_attachment: AttachmentInfo¶: AttachmentInfo object for current connection.

property transactions: DataList[TransactionInfo]¶: List of all transactions.

property variables: DataList[ContextVariableInfo]¶: List of all context variables.

class firebird.lib.monitor.InfoItem(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: object

Base class for all database monitoring objects.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

monitor: Monitor¶: Weak reference to parent Monitor instance.

property stat_id: Group¶: Internal ID.

class firebird.lib.monitor.DatabaseInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about attached database.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

property backup_state: BackupState¶: Current state of database with respect to nbackup physical backup.

property cache_size: int¶: Number of pages allocated in the page cache.

property created: datetime¶: Creation date and time, i.e., when the database was created or last restored.

property crypt_page: int¶: Number of page being encrypted.

property crypt_state: CryptState | None¶: Current state of database encryption.

New in version 1.4.0.

property file_id: str | None¶: Unique ID of the database file at the filesystem level.

New in version 1.4.0.

property forced_writes: bool¶: True if database uses synchronous writes.

property guid: UUID | None¶: Database GUID (persistent until restore / fixup).

New in version 1.4.0.

property iostats: IOStatsInfo¶: IOStatsInfo for this object.

property name: str¶: Database filename or alias.

property next_attachment: int | None¶: Current value of the next attachment ID counter.

New in version 1.4.0.

property next_statement: int | None¶: Current value of the next statement ID counter.

New in version 1.4.0.

property next_transaction: int¶: Transaction ID of the next transaction that will be started.

property oat: int¶: Transaction ID of the oldest active transaction.

property ods: float¶: On-Disk Structure (ODS) version number.

property oit: int¶: Transaction ID of the oldest [interesting] transaction.

property ost: int¶: Transaction ID of the Oldest Snapshot, i.e., the number of the OAT when the last garbage collection was done.

property owner: str¶: User name of database owner.

property page_size: int¶: Size of database page in bytes.

property pages: int¶: Number of pages allocated on disk.

property read_only: bool¶: True if database is Read Only.

property replica_mode: ReplicaMode | None¶: Database replica mode.

New in version 1.4.0.

property reserve_space: bool¶: True if database reserves space on data pages.

property security: Security¶: Type of security database (Default, Self or Other).

property shutdown_mode: ShutdownMode¶: Current shutdown mode.

property sql_dialect: int¶: SQL dialect of the database.

property sweep_interval: int¶: The sweep interval configured in the database header. Value 0 indicates that sweeping is disabled.

property tablestats: Dict[str, TableStatsInfo]¶: Dictionary of TableStatsInfo instances for this object.

class firebird.lib.monitor.AttachmentInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about attachment (connection) to database.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

is_active() → bool[source]¶

Returns True if attachment is active.

Return type:: bool

is_gc_allowed() → bool[source]¶

Returns True if Garbage Collection is enabled for this attachment.

Return type:: bool

is_idle() → bool[source]¶

Returns True if attachment is idle.

Return type:: bool

is_internal() → bool[source]¶

Returns True if attachment is internal system attachment.

Return type:: bool

terminate() → None[source]¶

Terminates client session associated with this attachment.

Raises:: firebird.base.types.Error – If attachement is current session.
Return type:: None

property auth_method: str¶: Authentication method.

property character_set: CharacterSet¶: Character set name for this attachment.

property client_version: str¶: Client library version.

property id: int¶: Attachment ID.

property idle_timeout: int | None¶: Connection level idle timeout.

New in version 1.4.0.

property idle_timer: datetime | None¶: Idle timer expiration time.

New in version 1.4.0.

property iostats: IOStatsInfo¶: IOStatsInfo for this object.

property name: str¶: Database filename or alias.

property remote_address: str | None¶: Remote address.

property remote_host: str¶: Name of remote host.

property remote_os_user: str¶: OS user name of client process.

property remote_pid: int | None¶: Remote client process ID.

property remote_process: str | None¶: Remote client process pathname.

property remote_protocol: str | None¶: Remote protocol name.

property remote_version: str¶: Remote protocol version.

property role: str | None¶: Role name.

property server_pid: int¶: Server process ID.

property session_timezone: str | None¶: Actual timezone of the session.

New in version 1.4.0.

property state: State¶: Attachment state (idle/active).

property statement_timeout: int | None¶: Connection level statement timeout.

New in version 1.4.0.

property statements: DataList[StatementInfo]¶: List of statements associated with attachment.

property system: bool¶: True for system attachments.

property tablestats: Dict[str, TableStatsInfo]¶: Dictionary of TableStatsInfo instances for this object.

property timestamp: datetime¶: Attachment date/time.

property transactions: DataList[TransactionInfo]¶: List of transactions associated with attachment.

property user: str¶: User name.

property variables: DataList[ContextVariableInfo]¶: List of variables associated with attachment.

property wire_compressed: bool | None¶: Wire compression.

New in version 1.4.0.

property wire_crypt_plugin: str | None¶: Name of the wire encryption plugin used by client.

New in version 1.4.0.

property wire_encrypted: bool | None¶: Wire encryption.

New in version 1.4.0.

class firebird.lib.monitor.TransactionInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about transaction.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

is_active() → bool[source]¶

Returns True if transaction is active.

Return type:: bool

is_autocommit() → bool[source]¶

Returns True for autocommited transaction.

Return type:: bool

is_autoundo() → bool[source]¶

Returns True for transaction with automatic undo.

Return type:: bool

is_idle() → bool[source]¶

Returns True if transaction is idle.

Return type:: bool

is_readonly() → bool[source]¶

Returns True if transaction is Read Only.

Return type:: bool

property attachment: AttachmentInfo¶: AttachmentInfo instance to which this transaction belongs.

property id: int¶: Transaction ID.

property iostats: IOStatsInfo¶: IOStatsInfo for this object.

property isolation_mode: IsolationMode¶: Transaction isolation mode code.

property lock_timeout: int¶: Lock timeout.

property oldest: int¶: Oldest transaction (local OIT).

property oldest_active: int¶: Oldest active transaction (local OAT).

property state: State¶: Transaction state (idle/active).

property statements: DataList[StatementInfo]¶: List of statements associated with transaction.

property tablestats: Dict[str, TableStatsInfo]¶: Dictionary of TableStatsInfo instances for this object.

property timestamp: datetime¶: Transaction start datetime.

property top: int¶: Top transaction.

property variables: DataList[ContextVariableInfo]¶: List of variables associated with transaction.

class firebird.lib.monitor.StatementInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about executed SQL statement.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

is_active() → bool[source]¶

Returns True if statement is active.

Return type:: bool

is_idle() → bool[source]¶

Returns True if statement is idle.

Return type:: bool

terminate() → None[source]¶

Terminates execution of statement.

Raises:: Error – If this attachement is current session.
Return type:: None

property attachment: AttachmentInfo¶: AttachmentInfo instance to which this statement belongs.

property callstack: DataList[CallStackInfo]¶: List with call stack for statement.

property compiled_statement: CompiledStatementInfo | None¶: CompiledStatementInfo instance to which this statement relates.

New in version 1.4.0.

property id: int¶: Statement ID.

property iostats: IOStatsInfo¶: IOStatsInfo for this object.

property plan: str¶: Explained execution plan.

property sql: str¶: Statement SQL text, if appropriate.

property state: State¶: Statement state (idle/active).

property tablestats: Dict[str, TableStatsInfo]¶: Dictionary of TableStatsInfo instances for this object.

property timeout: int | None¶: Connection level statement timeout.

New in version 1.4.0.

property timer: datetime | None¶: Statement timer expiration time.

New in version 1.4.0.

property timestamp: datetime¶: Statement start datetime.

property transaction: TransactionInfo¶: TransactionInfo instance to which this statement belongs or None.

class firebird.lib.monitor.CallStackInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about PSQL call (stack frame).

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

property caller: CallStackInfo¶: Call stack entry (CallStackInfo) of the caller.

property column: int¶: SQL source column number.

property compiled_statement: CompiledStatementInfo | None¶: CompiledStatementInfo instance to which this statement relates.

New in version 1.4.0.

property dbobject: Procedure | Trigger | Function¶: Database object.

property id: int¶: Call ID.

property iostats: IOStatsInfo¶: IOStatsInfo for this object.

property line: int¶: SQL source line number.

property object_name: str¶: PSQL object name.

property object_type: ObjectType¶: PSQL object type.

property package_name: str¶: Package name.

property statement: StatementInfo¶: Top-level StatementInfo instance to which this call stack entry belongs.

property timestamp: datetime¶: Request start datetime.

class firebird.lib.monitor.IOStatsInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about page and row level I/O operations, and about memory consumption.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

property backouts: int¶: Number of records where a new primary record version or a change to an existing primary record version is backed out due to rollback or savepoint undo.

property backversion_reads: int¶: Number of record backversion reads.

property conflits: int¶: Number of record conflits.

property deletes: int¶: Number of deleted records.

property expunges: int¶: Number of records where record version chain is being deleted due to deletions by transactions older than OAT.

property fetches: int¶: Number of page fetches.

property fragment_reads: int¶: Number of record fragment reads.

property group: Group¶: Object group code.

property idx_reads: int¶: Number of records read via an index.

property inserts: int¶: Number of inserted records.

property intermediate_gc: int | None¶: Number of records processed by the intermediate garbage collection.

New in version 1.4.0.

property locks: int¶: Number of record locks.

property marks: int¶: Number of pages with changes pending.

property max_memory_allocated: int¶: Maximum number of bytes allocated from the operating system by this object.

property max_memory_used: int¶: Maximum number of bytes used by this object.

property memory_allocated: int¶: Number of bytes currently allocated at the OS level.

property memory_used: int¶: Number of bytes currently in use.

property owner: DatabaseInfo | AttachmentInfo | TransactionInfo | StatementInfo | CallStackInfo¶: Object that owns this IOStats instance.

property purges: int¶: Number of records where record version chain is being purged of versions no longer needed by OAT or younger transactions.

property reads: int¶: Number of page reads.

property repeated_reads: int¶: Number of repeated record reads.

property seq_reads: int¶: Number of records read sequentially.

property updates: int¶: Number of updated records.

property waits: int¶: Number of record waits.

property writes: int¶: Number of page writes.

class firebird.lib.monitor.TableStatsInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about row level I/O operations on single table.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

property backouts: int¶: Number of records where a new primary record version or a change to an existing primary record version is backed out due to rollback or savepoint undo.

property backversion_reads: int¶: Number of record backversion reads.

property conflits: int¶: Number of record conflits.

property deletes: int¶: Number of deleted records.

property expunges: int¶: Number of records where record version chain is being deleted due to deletions by transactions older than OAT.

property fragment_reads: int¶: Number of record fragment reads.

property group: Group¶: Object group code.

property idx_reads: int¶: Number of records read via an index.

property inserts: int¶: Number of inserted records.

property locks: int¶: Number of record locks.

property owner: DatabaseInfo | AttachmentInfo | TransactionInfo | StatementInfo | CallStackInfo¶: Object that owns this TableStatsInfo instance.

property purges: int¶: Number of records where record version chain is being purged of versions no longer needed by OAT or younger transactions.

property repeated_reads: int¶: Number of repeated record reads.

property row_stat_id: int¶: Internal ID.

property seq_reads: int¶: Number of records read sequentially.

property table_name: str¶: Table name.

property updates: int¶: Number of updated records.

property waits: int¶: Number of record waits.

class firebird.lib.monitor.ContextVariableInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about context variable.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

is_attachment_var() → bool[source]¶

Returns True if variable is associated to attachment context.

Return type:: bool

is_transaction_var() → bool[source]¶

Returns True if variable is associated to transaction context.

Return type:: bool

property attachment: AttachmentInfo¶: AttachmentInfo instance to which this context variable belongs or None.

property name: str¶: Context variable name.

property transaction: TransactionInfo¶: TransactionInfo instance to which this context variable belongs or None.

property value: str¶: Value of context variable.

class firebird.lib.monitor.CompiledStatementInfo(monitor: Monitor, attributes: Dict[str, Any])[source]¶

Bases: InfoItem

Information about compiled statement.

New in version 1.4.0.

Parameters:

monitor (Monitor) –
attributes (Dict[str, Any]) –

property id: int¶: Compiled statement ID.

property iostats: IOStatsInfo¶: IOStatsInfo for this object.

property object_name: str | None¶: PSQL object name.

property object_type: ObjectType | None¶: PSQL object type.

property package_name: str | None¶: Package name of the PSQL object.

property plan: str | None¶: Plan (in the explained form) of the SQL query.

property sql: str | None¶: Text of the SQL query.