added exa_statistics section

.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(claude plugin:*)",
+      "Bash(cp:*)",
+      "Bash(poetry run:*)"
+    ]
+  }
+}

doc/exa_statistics/auditing.rst

@@ -0,0 +1,130 @@
+======================
+Auditing & Compliance
+======================
+
+The ``EXA_DBA_AUDIT_*`` tables provide a full audit trail of SQL execution and user sessions.
+They are designed for security investigations, compliance reporting, and operational support.
+
+.. note::
+   All tables in this section require the ``SELECT ANY DICTIONARY`` system privilege.
+   See :ref:`exa-statistics-access-control` for details on granting this privilege.
+
+EXA_DBA_AUDIT_SQL
+==================
+
+Records every SQL statement executed in the database. Key columns:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Column
+     - Description
+   * - ``USER_NAME``
+     - Database user who executed the statement
+   * - ``SESSION_ID``
+     - Session identifier
+   * - ``STMT_ID``
+     - Statement identifier within the session
+   * - ``COMMAND_NAME``
+     - SQL command type (e.g., ``SELECT``, ``CREATE TABLE``)
+   * - ``COMMAND_CLASS``
+     - Broad category: ``DQL``, ``DML``, ``DDL``, ``DCL``, ``TCL``
+   * - ``SQL_TEXT``
+     - Full SQL text (up to 2,000,000 characters)
+   * - ``SUCCESS``
+     - ``TRUE`` if the statement completed without error
+   * - ``ERROR_CODE`` / ``ERROR_TEXT``
+     - Error details for failed statements
+   * - ``DURATION``
+     - Execution time in seconds
+   * - ``STMT_START_TIME``
+     - Timestamp when the statement began executing
+
+EXA_DBA_AUDIT_SESSIONS
+========================
+
+Records every database session, including login and logout events. Key columns:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Column
+     - Description
+   * - ``SESSION_ID``
+     - Unique session identifier
+   * - ``USER_NAME``
+     - Database user who opened the session
+   * - ``OS_USER``
+     - Operating system user on the client machine
+   * - ``HOST``
+     - Client host address
+   * - ``LOGIN_TIME``
+     - Session start timestamp
+   * - ``LOGOUT_TIME``
+     - Session end timestamp (``NULL`` if session is still active)
+   * - ``SUCCESS``
+     - ``TRUE`` for successful logins; ``FALSE`` for failed login attempts
+   * - ``ENCRYPTED``
+     - ``TRUE`` if the connection was encrypted
+
+Managing Audit Log Size
+========================
+
+Audit tables grow continuously. Remove old records while retaining recent history with
+``TRUNCATE AUDIT LOGS``:
+
+.. code-block:: sql
+
+   -- Keep the last 30 days; remove everything older
+   TRUNCATE AUDIT LOGS KEEP FROM DAYS=30;
+
+.. warning::
+   ``TRUNCATE AUDIT LOGS`` permanently deletes the removed records. This action cannot be undone.
+
+Recipes
+=======
+
+Find All Failed Statements with Error Details
+----------------------------------------------
+
+.. code-block:: sql
+
+   SELECT USER_NAME, COMMAND_NAME, SQL_TEXT,
+          ERROR_CODE, ERROR_TEXT, STMT_START_TIME
+   FROM EXA_DBA_AUDIT_SQL
+   WHERE SUCCESS = FALSE
+   ORDER BY STMT_START_TIME DESC
+   LIMIT 50;
+
+Track Login History for a Specific User
+-----------------------------------------
+
+.. code-block:: sql
+
+   SELECT SESSION_ID, LOGIN_TIME, LOGOUT_TIME,
+          HOST, OS_USER, ENCRYPTED
+   FROM EXA_DBA_AUDIT_SESSIONS
+   WHERE USER_NAME = 'MY_USER'
+   ORDER BY LOGIN_TIME DESC;
+
+List All DDL Statements Executed Today
+----------------------------------------
+
+.. code-block:: sql
+
+   SELECT USER_NAME, COMMAND_NAME, SQL_TEXT, STMT_START_TIME
+   FROM EXA_DBA_AUDIT_SQL
+   WHERE COMMAND_CLASS = 'DDL'
+     AND CAST(STMT_START_TIME AS DATE) = CURRENT_DATE
+   ORDER BY STMT_START_TIME DESC;
+
+Remove Audit Logs Older Than 30 Days
+--------------------------------------
+
+.. code-block:: sql
+
+   TRUNCATE AUDIT LOGS KEEP FROM DAYS=30;
+
+**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

@@ -0,0 +1,36 @@
+===========================================
+EXA_STATISTICS: Database Monitoring & Audit
+===========================================
+
+``EXA_STATISTICS`` is a built-in system schema present in every Exasol database. It automatically
+collects and stores historical data about query activity, resource usage, database size, and user
+sessions. Use it to monitor performance, plan capacity, and maintain a full audit trail — without
+installing any additional tools.
+
+.. list-table:: Table Groups at a Glance
+   :header-rows: 1
+   :widths: 25 50 25
+
+   * - Group
+     - Purpose
+     - Access
+   * - SQL Activity (``EXA_SQL_*``)
+     - Track executed statements, execution modes, duration, and CPU usage
+     - All users
+   * - System Monitor (``EXA_MONITOR_*``)
+     - Monitor CPU, memory, swap, I/O, and network metrics
+     - All users
+   * - Database Size (``EXA_DB_SIZE_*``)
+     - Track storage volume, compression ratios, and recommended RAM
+     - All users
+   * - Audit (``EXA_DBA_AUDIT_*``)
+     - Full SQL and session audit trail for compliance and security
+     - ``SELECT ANY DICTIONARY`` required
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   query_analytics
+   system_health
+   auditing

doc/exa_statistics/overview.rst

@@ -0,0 +1,102 @@
+========
+Overview
+========
+
+What is EXA_STATISTICS
+=======================
+
+``EXA_STATISTICS`` is a system schema built into every Exasol database. It continuously collects
+statistics about SQL execution, hardware resource usage, storage, and user sessions. Data is updated
+automatically every minute and is immediately available for querying — no configuration required.
+
+The schema covers four functional areas:
+
+* **SQL Activity** — historical record of every executed statement
+* **System Monitor** — CPU, memory, I/O, and network metrics over time
+* **Database Size** — storage volume, compression ratios, and RAM recommendations
+* **Audit** — full audit trail of SQL statements and user sessions
+
+Namespace Integration
+=====================
+
+``EXA_STATISTICS`` and ``SYS`` are automatically integrated into Exasol's namespace. You can query
+statistical tables directly without specifying the schema name:
+
+.. code-block:: sql
+
+   -- Both are equivalent:
+   SELECT * FROM EXA_SQL_LAST_DAY;
+   SELECT * FROM EXA_STATISTICS.EXA_SQL_LAST_DAY;
+
+.. _exa-statistics-access-control:
+
+Access Control
+==============
+
+Most statistical tables are readable by all database users. Tables with ``DBA`` in their name
+contain sensitive data and require the ``SELECT ANY DICTIONARY`` system privilege.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - Table Group
+     - Required Privilege
+   * - ``EXA_SQL_*``, ``EXA_MONITOR_*``, ``EXA_DB_SIZE_*``
+     - None — any connected user
+   * - ``EXA_DBA_AUDIT_*``
+     - ``SELECT ANY DICTIONARY``
+
+To grant the privilege to a user:
+
+.. code-block:: sql
+
+   GRANT SELECT ANY DICTIONARY TO my_user;
+
+Aggregation Levels
+==================
+
+Each metric category is available at multiple time granularities:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Suffix
+     - Description
+   * - ``_LAST_DAY``
+     - Rolling 24-hour window — one row per measurement interval
+   * - ``_HOURLY``
+     - Aggregated per hour
+   * - ``_DAILY``
+     - Aggregated per calendar day
+   * - ``_MONTHLY``
+     - Aggregated per calendar month
+
+Use ``_LAST_DAY`` tables for real-time investigation and the aggregated tables for trend analysis
+and capacity planning.
+
+Time Zone
+=========
+
+All timestamps in ``EXA_STATISTICS`` are stored in the database's configured time zone
+(``DBTIMEZONE``). To check your current setting:
+
+.. code-block:: sql
+
+   SELECT DBTIMEZONE;
+
+Refreshing Statistics
+=====================
+
+Statistics are updated automatically every minute. To force an immediate refresh:
+
+.. code-block:: sql
+
+   FLUSH STATISTICS;
+   COMMIT;
+
+.. note::
+   Open a new transaction after flushing to see the latest data reflected in your queries.
+
+**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>`_