Skip to content

Commit c79ab1a

Browse files
abdullah094abdullah094
authored
added exa_statistics section (#48)
* added exa_statistics * Fix RST title overline length in exa_statistics/index.rst * fixed short overline * fixed redirected links
1 parent 4e07a40 commit c79ab1a

7 files changed

Lines changed: 526 additions & 0 deletions

File tree

‎.claude/settings.local.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(claude plugin:*)",
5+
"Bash(cp:*)",
6+
"Bash(poetry run:*)"
7+
]
8+
}
9+
}

‎doc/exa_statistics/auditing.rst‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
======================
2+
Auditing & Compliance
3+
======================
4+
5+
The ``EXA_DBA_AUDIT_*`` tables provide a full audit trail of SQL execution and user sessions.
6+
They are designed for security investigations, compliance reporting, and operational support.
7+
8+
.. note::
9+
All tables in this section require the ``SELECT ANY DICTIONARY`` system privilege.
10+
See :ref:`exa-statistics-access-control` for details on granting this privilege.
11+
12+
EXA_DBA_AUDIT_SQL
13+
==================
14+
15+
Records every SQL statement executed in the database. Key columns:
16+
17+
.. list-table::
18+
:header-rows: 1
19+
:widths: 30 70
20+
21+
* - Column
22+
- Description
23+
* - ``USER_NAME``
24+
- Database user who executed the statement
25+
* - ``SESSION_ID``
26+
- Session identifier
27+
* - ``STMT_ID``
28+
- Statement identifier within the session
29+
* - ``COMMAND_NAME``
30+
- SQL command type (e.g., ``SELECT``, ``CREATE TABLE``)
31+
* - ``COMMAND_CLASS``
32+
- Broad category: ``DQL``, ``DML``, ``DDL``, ``DCL``, ``TCL``
33+
* - ``SQL_TEXT``
34+
- Full SQL text (up to 2,000,000 characters)
35+
* - ``SUCCESS``
36+
- ``TRUE`` if the statement completed without error
37+
* - ``ERROR_CODE`` / ``ERROR_TEXT``
38+
- Error details for failed statements
39+
* - ``DURATION``
40+
- Execution time in seconds
41+
* - ``STMT_START_TIME``
42+
- Timestamp when the statement began executing
43+
44+
EXA_DBA_AUDIT_SESSIONS
45+
========================
46+
47+
Records every database session, including login and logout events. Key columns:
48+
49+
.. list-table::
50+
:header-rows: 1
51+
:widths: 30 70
52+
53+
* - Column
54+
- Description
55+
* - ``SESSION_ID``
56+
- Unique session identifier
57+
* - ``USER_NAME``
58+
- Database user who opened the session
59+
* - ``OS_USER``
60+
- Operating system user on the client machine
61+
* - ``HOST``
62+
- Client host address
63+
* - ``LOGIN_TIME``
64+
- Session start timestamp
65+
* - ``LOGOUT_TIME``
66+
- Session end timestamp (``NULL`` if session is still active)
67+
* - ``SUCCESS``
68+
- ``TRUE`` for successful logins; ``FALSE`` for failed login attempts
69+
* - ``ENCRYPTED``
70+
- ``TRUE`` if the connection was encrypted
71+
72+
Managing Audit Log Size
73+
========================
74+
75+
Audit tables grow continuously. Remove old records while retaining recent history with
76+
``TRUNCATE AUDIT LOGS``:
77+
78+
.. code-block:: sql
79+
80+
-- Keep the last 30 days; remove everything older
81+
TRUNCATE AUDIT LOGS KEEP FROM DAYS=30;
82+
83+
.. warning::
84+
``TRUNCATE AUDIT LOGS`` permanently deletes the removed records. This action cannot be undone.
85+
86+
Recipes
87+
=======
88+
89+
Find All Failed Statements with Error Details
90+
----------------------------------------------
91+
92+
.. code-block:: sql
93+
94+
SELECT USER_NAME, COMMAND_NAME, SQL_TEXT,
95+
ERROR_CODE, ERROR_TEXT, STMT_START_TIME
96+
FROM EXA_DBA_AUDIT_SQL
97+
WHERE SUCCESS = FALSE
98+
ORDER BY STMT_START_TIME DESC
99+
LIMIT 50;
100+
101+
Track Login History for a Specific User
102+
-----------------------------------------
103+
104+
.. code-block:: sql
105+
106+
SELECT SESSION_ID, LOGIN_TIME, LOGOUT_TIME,
107+
HOST, OS_USER, ENCRYPTED
108+
FROM EXA_DBA_AUDIT_SESSIONS
109+
WHERE USER_NAME = 'MY_USER'
110+
ORDER BY LOGIN_TIME DESC;
111+
112+
List All DDL Statements Executed Today
113+
----------------------------------------
114+
115+
.. code-block:: sql
116+
117+
SELECT USER_NAME, COMMAND_NAME, SQL_TEXT, STMT_START_TIME
118+
FROM EXA_DBA_AUDIT_SQL
119+
WHERE COMMAND_CLASS = 'DDL'
120+
AND CAST(STMT_START_TIME AS DATE) = CURRENT_DATE
121+
ORDER BY STMT_START_TIME DESC;
122+
123+
Remove Audit Logs Older Than 30 Days
124+
--------------------------------------
125+
126+
.. code-block:: sql
127+
128+
TRUNCATE AUDIT LOGS KEEP FROM DAYS=30;
129+
130+
**Further reading:** `EXA_DBA_AUDIT_SQL <https://docs.exasol.com/db/latest/sql_references/system_tables/statistical/exa_dba_audit_sql.htm>`_ · `EXA_DBA_AUDIT_SESSIONS <https://docs.exasol.com/db/latest/sql_references/system_tables/statistical/exa_dba_audit_sessions.htm>`_ · `Auditing Concepts <https://docs.exasol.com/db/latest/database_concepts/auditing.htm>`_

‎doc/exa_statistics/index.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
===========================================
2+
EXA_STATISTICS: Database Monitoring & Audit
3+
===========================================
4+
5+
``EXA_STATISTICS`` is a built-in system schema present in every Exasol database. It automatically
6+
collects and stores historical data about query activity, resource usage, database size, and user
7+
sessions. Use it to monitor performance, plan capacity, and maintain a full audit trail — without
8+
installing any additional tools.
9+
10+
.. list-table:: Table Groups at a Glance
11+
:header-rows: 1
12+
:widths: 25 50 25
13+
14+
* - Group
15+
- Purpose
16+
- Access
17+
* - SQL Activity (``EXA_SQL_*``)
18+
- Track executed statements, execution modes, duration, and CPU usage
19+
- All users
20+
* - System Monitor (``EXA_MONITOR_*``)
21+
- Monitor CPU, memory, swap, I/O, and network metrics
22+
- All users
23+
* - Database Size (``EXA_DB_SIZE_*``)
24+
- Track storage volume, compression ratios, and recommended RAM
25+
- All users
26+
* - Audit (``EXA_DBA_AUDIT_*``)
27+
- Full SQL and session audit trail for compliance and security
28+
- ``SELECT ANY DICTIONARY`` required
29+
30+
.. toctree::
31+
:maxdepth: 2
32+
33+
overview
34+
query_analytics
35+
system_health
36+
auditing

‎doc/exa_statistics/overview.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
========
2+
Overview
3+
========
4+
5+
What is EXA_STATISTICS
6+
=======================
7+
8+
``EXA_STATISTICS`` is a system schema built into every Exasol database. It continuously collects
9+
statistics about SQL execution, hardware resource usage, storage, and user sessions. Data is updated
10+
automatically every minute and is immediately available for querying — no configuration required.
11+
12+
The schema covers four functional areas:
13+
14+
* **SQL Activity** — historical record of every executed statement
15+
* **System Monitor** — CPU, memory, I/O, and network metrics over time
16+
* **Database Size** — storage volume, compression ratios, and RAM recommendations
17+
* **Audit** — full audit trail of SQL statements and user sessions
18+
19+
Namespace Integration
20+
=====================
21+
22+
``EXA_STATISTICS`` and ``SYS`` are automatically integrated into Exasol's namespace. You can query
23+
statistical tables directly without specifying the schema name:
24+
25+
.. code-block:: sql
26+
27+
-- Both are equivalent:
28+
SELECT * FROM EXA_SQL_LAST_DAY;
29+
SELECT * FROM EXA_STATISTICS.EXA_SQL_LAST_DAY;
30+
31+
.. _exa-statistics-access-control:
32+
33+
Access Control
34+
==============
35+
36+
Most statistical tables are readable by all database users. Tables with ``DBA`` in their name
37+
contain sensitive data and require the ``SELECT ANY DICTIONARY`` system privilege.
38+
39+
.. list-table::
40+
:header-rows: 1
41+
:widths: 45 55
42+
43+
* - Table Group
44+
- Required Privilege
45+
* - ``EXA_SQL_*``, ``EXA_MONITOR_*``, ``EXA_DB_SIZE_*``
46+
- None — any connected user
47+
* - ``EXA_DBA_AUDIT_*``
48+
- ``SELECT ANY DICTIONARY``
49+
50+
To grant the privilege to a user:
51+
52+
.. code-block:: sql
53+
54+
GRANT SELECT ANY DICTIONARY TO my_user;
55+
56+
Aggregation Levels
57+
==================
58+
59+
Each metric category is available at multiple time granularities:
60+
61+
.. list-table::
62+
:header-rows: 1
63+
:widths: 20 80
64+
65+
* - Suffix
66+
- Description
67+
* - ``_LAST_DAY``
68+
- Rolling 24-hour window — one row per measurement interval
69+
* - ``_HOURLY``
70+
- Aggregated per hour
71+
* - ``_DAILY``
72+
- Aggregated per calendar day
73+
* - ``_MONTHLY``
74+
- Aggregated per calendar month
75+
76+
Use ``_LAST_DAY`` tables for real-time investigation and the aggregated tables for trend analysis
77+
and capacity planning.
78+
79+
Time Zone
80+
=========
81+
82+
All timestamps in ``EXA_STATISTICS`` are stored in the database's configured time zone
83+
(``DBTIMEZONE``). To check your current setting:
84+
85+
.. code-block:: sql
86+
87+
SELECT DBTIMEZONE;
88+
89+
Refreshing Statistics
90+
=====================
91+
92+
Statistics are updated automatically every minute. To force an immediate refresh:
93+
94+
.. code-block:: sql
95+
96+
FLUSH STATISTICS;
97+
COMMIT;
98+
99+
.. note::
100+
Open a new transaction after flushing to see the latest data reflected in your queries.
101+
102+
**Further reading:** `Statistical System Tables <https://docs.exasol.com/db/latest/sql_references/system_tables/statistical_system_tables.htm>`_ · `FLUSH STATISTICS <https://docs.exasol.com/db/latest/sql/flush_statistics.htm>`_

0 commit comments

Comments
 (0)