README.md

rdb_exporter

This is a prometheus exporter for DBMS "Red Database".

Exported metrics

Name	Description
db_size	The amount of database bytes which are taken to store data.
diff_oldt_nt	The difference between Oldest transaction number and Next transaction number.
active_users	The amount of active users in a database.
mon_io_stats	The amount of read, written, fetched, marked pages of a database/connections/transactions/statements/calls.
mon_memory_usage	Information about memory usage by database/connections/transactions/statements/calls/cached_queries
mon_database	Information about a database: oldest_snapshot: The number of the transaction that was active at the moment when the OAT was started — oldest snapshot transaction (OST) next_transaction: The number of the next transaction, as it stood when the monitoring snapshot was taken oldest_transaction: The number of the oldest [interesting] transaction (OIT) oldest_active: The number of the oldest active transaction (OAT) page_buffers: The number of pages allocated in RAM for the database page cache SQL_dialect: Database SQL Dialect: 1 or 3 shutdown_mode: The current shutdown state of the database: 0 - the database is online 1 - multi-user shutdown 2 - single-user shutdown 3 - full shutdown sweep_interval: sweep interval read_only: Flag indicating whether the database is read-only (value 1) or read-write (value 0) forced_writes: Indicates whether the write mode of the database is set for synchronous write (forced writes ON, value is 1) or asynchronous write (forced writes OFF, value is 0) reserve_space: The flag indicating reserve_space (value 1) or use_all_space (value 0) for filling database pages pages: The number of pages allocated for the database on an external device crypt_page: Number of encrypted pages
mon_attachment	Displays information about active attachments to the database: server_pid: Server process identifier state: Connection state: 0 - idle 1 - active remote_pid: Remote client process identifier character_set_id: Connection character set identifier (see RDB$CHARACTER_SET in system table RDB$TYPES) garbage_collection: Garbage collection flag (as specified in the attachment’s DPB): 1=allowed, 0=not allowed system_flag: Flag that indicates the type of connection: 0 - normal connection 1 - system connection repl_waitflush_count: Number of packets sent to reserve databases. repl_waitflush_time: Time (in ms) that the main server waits for a response from backup servers.
mon_transaction	Reports started transactions: attachment_id: Connection identifier state: Transaction state: 0 - idle 1 - active top_transaction: Top-level transaction identifier (number) oldest_transaction: Transaction ID of the oldest [interesting] transaction (OIT) oldest_active: Transaction ID of the oldest active transaction (OAT) isolation_mode: Isolation mode (level): 0 - consistency (snapshot table stability) 1 - concurrency (snapshot) 2 - read committed record version 3 - read committed no record version lock_timeout: Lock timeout: -1 - wait forever 0 - no waiting 1 or greater - lock timeout in seconds read_only: Flag indicating whether the transaction is read-only (value 1) or read-write (value 0) auto_commit: Flag indicating whether automatic commit is used for the transaction (value 1) or not (value 0) auto_undo: Flag indicating whether the logging mechanism automatic undo is used for the transaction (value 1) or not (value 0)
mon_statement	Displays statements prepared for execution: attachment_id: Connection identifier transaction_id: Transaction identifier state: Statement state: 0 - idle 1 - active 2 - stalled
mon_call_stack	Displays calls to the stack from queries executing in stored procedures and triggers: statement_id: The identifier of the top-level SQL statement, the one that initiated the chain of calls. Use this identifier to find the records about the active statement in the MON$STATEMENTS table caller_id: The identifier of the calling trigger or stored procedure source_line: The number of the source line in the SQL statement being executed at the moment of the snapshot source_column: The number of the source column in the SQL statement being executed at the moment of the snapshot
system_memory	Information about device RAM: used: The amount of used memory by OS and other applications available: The amount of available memory total: The amount of memory which is had by device
system_cpu	Information about cpu usage: percent: CPU load frequency: CPU frequency
trace_statements	Shows amount of failed and successful statements: OK: amount of successful statements FAIL: amount of failed statements

Exporter configuration file

You need to add a configuration json file beside "main.py" file and name it "exporter_conf" and fill it with a content.
The example of required content is:

{
  "port": 8000, 
  "login":  "SYSDBA", 
  "password":  "masterkey",
  "RDB_port": 3050,
  "RedDatabase": "/opt/RedDatabase"
  "databases": {
    "[db_nickname]": "localhost:[insert_path_to_database]",
    "[another_db_nickname]": "localhost:[insert_path_to_another_database]"
  },
  "trace": "[insert_path_to_fdbtrace_text]"
}

Field "port" is the port which will be using by exporter.

Prometheus configuration file

Prometheus can be configured from either a terminal and a configuration file. The most important settings are from which node prometheus scrapes metrics and time between two scrape queries. The example content of prometheus configuration file:

global:
  scrape_interval: 10s # Time between two scrape queries

scrape_configs:
  - job_name: "RedDatabases"
    static_configs:
      - targets: ["localhost:8000"] # A node where exporter is located

Libraries

You need to install next following libraries to make the exporter work:

• psutil version 5.9.4 (pip install psutil==5.9.4)
• firebirdsql version 1.2.2 (pip install firebirdsql==1.2.2)

How to use

1. Install python, libraries, Prometheus, Grafana, Exporter;
2. Launch RedDatabase server;
3. Edit exporter configuration file;
4. Launch this exporter (python main.py);
5. Edit Prometheus configuration file;
6. Launch prometheus;
7. Launch Grafana (on linux: sudo systemctl start grafana-server). It might be on 3000 port now;
8. Open browser and insert into address section the next following string "http://localhost:3000/";
9. Enter login and password to sign in. The string "admin" is default login and password. Grafana make you change default password when you have signed in for the first time;
10. Make a data source. To do it you must go to left side of screen and find a gear picture (configure section) then click on the "Data sources" subsection. Now click the button "add data source, select Prometheus, insert url path to prometheus (default is "http://localhost:9090/")", click the button "Save & test";
11. Import dashboards or build your own. To import dashboards you must find the "Dashboards" section at the left side of the screen and click the "+ Import" button. Click the button "Upload JSON file" and select json file of a dashboard, click "Import". To build your own dashboard follow instructions at Grafana official site.

Congratulations! Use dashboards to watch your RedDatabase.