# NVMe系统函数
- gs_candidate_slots_stat() 描述：NVMe缓存等候槽信息。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。
  表1gs_candidate_slots_stat参数说明 
  | 参数类型 | 参数名                        | 类型       | 描述            |
  |:---|:---|:---|:---|
  | 输出参数  | head                         | uint64  | 队列头部信息。       |
  | 输出参数   | tail                        | uint64   | 队列尾部信息。       |
  | 输出参数  | slot_remaining               | uint64    | 槽位剩余数量。        |
  | 输出参数 | cache_capacity               | uint64 | NVMe缓存中的block数量。 |
  | 输出参数 | blocks_in_current_hash_table | uint64   | 哈希表中的block数量。  |
  | 输出参数   | cache_usage                  | uint32 | 缓存使用率。         |
     
  示例，查看当前NVMe缓存等候槽信息：
  ```
  gaussdb=# SELECT * FROM gs_candidate_slots_stat();
   head | tail | slot_remaining | cache_capacity | blocks_in_current_hash_table | cache_usage
  ------+------+----------------+----------------+------------------------------+-------------
   0    | 498  | 498            | 131072         | 1216                         | 0
  (1 row)
  ```
  

- gs_nvme_queue_stat() 描述：NVMe队列信息。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。
  表2gs_nvme_queue_stat参数说明 
  | 参数类型 | 参数名                                                                                    | 类型      | 描述                 |
  |:---|:---|:---|:---|
  | 输出参数   | queue                                                                                   | text     | 队列名称。            |
  | 输出参数  | head                                                                                   | uint64  | 队列头部信息。          |
  | 输出参数 | tail                                                                                    | uint64 | 队列尾部信息。            |
  | 输出参数  | queue_remaining                                                                       | uint64   | 队列剩余数量。           |
  | 输出参数  | push_frequency (times/s)               | text    | NVMe缓存push速率。      |
  | 输出参数  | pop_frequency (times/s)                   | text    | NVMe缓存pop速率。      |
  | 输出参数  | push_frequency_recent_second (times/s)  | text    | NVMe缓存最近一秒push速率。 |
  | 输出参数   | pop_frequency_recent_second (times/s) | text   | NVMe缓存最近一秒pop速率。  |
     
  示例，查看当前NVMe队列信息：
  ```
  gaussdb=# SELECT * FROM gs_nvme_queue_stat();
        queue       | head | tail | queue_remaining | push_frequency(times/s) | pop_frequency(times/s) | push_frequency_recent_second(times/s) | pop_frequency_recent_second(times/s)
  ------------------+------+------+-----------------+-------------------------+------------------------+---------------------------------------+--------------------------------------
   victim queue     | 1739 | 1739 | 0               | 12.42                   | 12.42                  | 0.07                                  | 0.25
   cleaner queue 1 | 282  | 282  | 0               | 2.04                    | 2.04                   | 0.03                                  | 0.03
   cleaner queue 2 | 282  | 282  | 0               | 2.04                    | 2.04                   | 0.03                                  | 0.03
   cleaner queue 3 | 278  | 278  | 0               | 2.01                    | 2.03                   | 0.03                                  | 0.03
   cleaner queue 4 | 273  | 273  | 0               | 1.98                    | 1.99                   | 0.16                                  | 0.16
   cleaner queue 5 | 272  | 272  | 0               | 1.97                    | 1.97                   | 0.03                                  | 0.03
  (6 rows)
  ```
  

- gs_nvme_hit_ratio() 描述：NVMe缓存命中率。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。
  表3gs_nvme_hit_ratio参数说明 
  | 参数类型   | 参数名             | 类型   | 描述            |
  |:---|:---|:---|:---|
  | 输出参数   | nvme_hit_ratio | text | 读NVMe缓存的比率。 |
  | 输出参数 | nvme_write_ratio  | text | 写NVMe缓存的比率。     |
  | 输出参数   | write_ssd_ratio  | text | 写硬盘的比率。        |
     
  示例，查看当前NVMe缓存命中率：
  ```
  gaussdb=# SELECT * FROM gs_nvme_hit_ratio();
   nvme_hit_ratio | nvme_write_ratio | write_ssd_ratio
  ----------------+------------------+-----------------
   0.39           | 0.48             | 0.00
  (1 row)
  ```
  

- gs_nvme_page(space_node, database_node, relation_node, forknum, blocknum, relation_type) 描述：查询NVMe缓存页面状态，或者解析页面，输出解析后的页面存放路径。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。支持解析的表类型有如下几种：heap, uheap, btree, ubtree, indexurq, undo_record, undo_slot。
  表4gs_nvme_page参数说明 
  | 参数类型  | 参数名                          | 类型       | 描述                                                                                                                                                    |
  |:---|:---|:---|:---|
  | 输入参数  | space_node                  | oid       | 表空间id。                                                                                                                                               |
  | 输入参数   | database_node               | oid       | 数据库id。                                                                                                                                                |
  | 输入参数     | relation_node                  | oid        | 表id。                                                                                                                                                  |
  | 输入参数     | forknum                         | int64      | 在 gaussdb数据库中，通过forknum来区分不同的文件，一般取值为0。                                                                                                                |
  | 输入参数   | blocknum                     | int64    | 块id。                                                                                                                                                   |
  | 输入参数    | relation_type                 | text      | 表类型，此参数为非必须入参，无此入参则输出页面状态，加上此入参则输出解析后的页面地址，若此值为'NULL'，则输出该页面对应的二进制.dump文件；取值范围：\[heap, uheap, btree, ubtree, indexurq, undo_record, undo_slot, NULL\] |
  | 输出参数  | option                        | text   | 操作类型，页面状态or页面解析or页面dump。                                                                                                                              |
  | 输出参数 | output_filepath                | text     | 输出页面路径。                                                                                                                                              |
  | 输出参数 | seg_id                       | uint32  | 本地文件段id。                                                                                                                                               |
  | 输出参数   | offset                        | uint32 | 页在段中的偏移量。                                                                                                                                          |
  | 输出参数   | heat                         | uint32    | 页面当前的热度。                                                                                                                                              |
  | 输出参数  | queue_pos                    | uint32  | 页面在队列中的位置。                                                                                                                                           |
  | 输出参数 | io_state                     | uint32 | 页面读写状态。                                                                                                                                             |
  | 输出参数  | in_candidate               | bool       | 是否在等候队列。                                                                                                                                             |
  | 输出参数 | wait_process                  | bool      | 是否在等待中。                                                                                                                                               |
  | 输出参数    | last_process_id              | uint64   | 最后一次处理id。                                                                                                                                             |
  | 输出参数  | last_added_linklist_timestamp | text    | 最后一次加入链表的时间戳。                                                                                                                                        |
  | 输出参数 | rec_lsn                      | uint64 | recycle lsn, Xlog回收标记。                                                                                                                              |
  | 输出参数  | reusable                     | bool      | 是否被复用。                                                                                                                                              |
  | 输出参数   | busy                         | bool      | 是否忙碌。                                                                                                                                                 |
     
  示例，查看页面状态：
  ```
  gaussdb=# CREATE TABLE t1 (a int);
  CREATE TABLE
  gaussdb=# INSERT INTO t1 VALUES(1);
  INSERT 0 1
  gaussdb=# SELECT * FROM pg_relation_filepath('t1');
   pg_relation_filepath
  ----------------------
   base/13093/45095
  (1 row)
  gaussdb=# SELECT spc.oid FROM pg_tablespace spc WHERE (spc.spcname = 'pg_default');
   oid
  ------
   1663
  (1 row)
  gaussdb=# SELECT * FROM gs_nvme_page(1663, 13093, 45095, 0, 0);
     option    | seg_id |  offset  | heat | queue_pos  | io_state | in_candidate | wait_process | last_process_id | last_added_linklist_timestamp |   rec_lsn   | reusable | busy
  -------------+--------+----------+------+------------+----------+--------------+--------------+-----------------+-------------------------------+-------------+----------+------
   Page Status | 3      | 79503360 | 1    | 4294967295 | 0        | t            | f            | 2               | 2024-12-20 15:11:10           | 16226393184 | t        | f
  (1 row)
  ```
  解析页面：
  ```
  gaussdb=# SELECT * FROM gs_nvme_page(1663, 13093, 45095, 0, 0, 'uheap');
     option   |           output_filepath
  ------------+--------------------------------------
   Page Parse | gs_log/dump/1663_13093_45095_0.uheap
  (1 row)
  ```
  dump页面：
  ```
  gaussdb=# SELECT * FROM gs_nvme_page(1663, 13093, 45095, 0, 0, 'NULL');
    option   |           output_filepath
  -----------+-------------------------------------
   Page Dump | gs_log/dump/1663_13093_45095_0.dump
  (1 row)
  gaussdb=# SELECT * FROM gs_nvme_page(1663,12866,17515,0,0,'NULL');
    option   |           output_filepath
  -----------+-------------------------------------
   Page Dump | gs_log/dump/1663_12866_17515_0.dump
  (1 row)
  ```
  

- gs_nvme_shm_header() 描述：查看NVMe共享内存使用状态。
  返回值类型：record
  表5gs_nvme_shm_header参数说明 
  | 参数类型 | 参数名         | 类型     | 描述              |
  |:---|:---|:---|:---|
  | 输出参数   | magic       | integer  | 魔数，用于标识nvme缓存。    |
  | 输出参数 | file_path  | text     | 共享内存文件路径。        |
  | 输出参数 | file_ino      | bigint   | 共享内存文件Inode节点。   |
  | 输出参数   | total_size | bigint | 共享内存空间大小。       |
  | 输出参数 | free_size     | bigint  | 共享内存可用空间大小。      |
  | 输出参数 | critical   | integer   | 当前并发访问哈希关键区的线程数。 |
  | 输出参数   | write_pos   | bigint | 当前段文件的写入位置。     |
  | 输出参数  | flushed_lsn  | bigint    | 事务日志持久化落盘的位置。    |
  | 输出参数 | write_lsn    | bigint | 事务日志写入位置。          |
  | 输出参数    | recovery_lsn | bigint  | NVMe缓存的事务日志恢复点。     |
     
  示例，查看当前NVMe共享内存使用状态：
  ```
  gaussdb=# SELECT * FROM gs_nvme_shm_header();
    magic   |                 file_path                 | file_ino | total_size | free_size | critical | write_pos | flushed_lsn | write_lsn | recovery_lsn
  ----------+-------------------------------------------+----------+------------+-----------+----------+-----------+-------------+-----------+--------------
   38719600 | /dev/shm/gs_nvme_shared_mem_gaussdb_14270 | 16005306 |   27642576 |    360144 |        0 |    901120 |   218506608 | 218506608 |    184556936
  (1 row)
  ```
  
- gs_nvme_thread_status() 描述：查看NVMe线程状态。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。
  表6gs_nvme_thread_status参数说明 
  | 参数类型    | 参数名            | 类型                                                                        | 描述                                    |
  |:---|:---|:---|:---|
  | 输出参数     | node_name         | text                                                                       | 当前节点的名称。                               |
  | 输出参数    | pid               | bigint                                                                   | 当前节点进程中正在运行的线程号。                    |
  | 输出参数  | lwpid          | integer                                                                   | 与pid对应的轻量级线程号。                     |
  | 输出参数   | thread_name        | text                                                                      | 与pid对应的线程名称。                          |
  | 输出参数    | creation_time    | timestamp with time zone | 与pid对应的线程创建的时间。                     |
  | 输出参数  | queue           | text                                                                       | 线程处理的队列名。                             |
  | 输出参数   | force_sync      | bool                                                                       | 线程强制同步状态。                             |
  | 输出参数 | force_sync_time | timestamp with time zone | 最近一次强制同步时间。                          |
  | 输出参数      | mem_ctx_name  | text                                                                    | 线程内存上下文名。                           |
  | 输出参数   | mem_ctx _size     | bigint                                                                   | 线程内存上下文占用的空间。                         |
  | 输出参数   | sleep_time       | integer                                                                  | 缓存消息处理时间间隔（单位：us）。                  |
  | 输出参数     | status         | text                                                                     | 线程状态：running、shutdown、receive_sigterm。 |
     
  示例，查看当前NVMe线程状态：
  ```
  gaussdb=# SELECT * FROM gs_nvme_thread_status();
   node_name |       pid       | lwpid | thread_name  |         creation_time         |      queue       | force_sync |        force_sync_time        | mem_ctx_name  | mem_ctx_size | s
  leep_time | status
  -----------+-----------------+-------+--------------+-------------------------------+------------------+------------+-------------------------------+---------------+--------------+--
  ----------+---------
   sgnode    | 140443066562304 | 31202 | Nvme Thread0 | 2025-01-21 16:36:37.134759-05 | victim queue     | f          | 2025-01-21 16:36:37.134759-05 | Nvme Thread/0 |            0 |
    1000000 | running
   sgnode    | 140442935953152 | 31222 | Nvme Thread1 | 2025-01-21 16:36:37.137438-05 | cleaner queue 1 | f          | 2025-01-21 16:38:39.499682-05 | Nvme Thread/1 |         8192 |
    1000000 | running
   sgnode    | 140443033995008 | 31204 | Nvme Thread2 | 2025-01-21 16:36:37.135368-05 | cleaner queue 2 | f          | 2025-01-21 16:38:39.506283-05 | Nvme Thread/2 |         8192 |
    1000000 | running
   sgnode    | 140442967471872 | 31221 | Nvme Thread3 | 2025-01-21 16:36:37.137247-05 | cleaner queue 3 | f          | 2025-01-21 16:38:39.48926-05  | Nvme Thread/3 |         8192 |
    1000000 | running
   sgnode    | 140442910324480 | 31223 | Nvme Thread4 | 2025-01-21 16:36:37.137935-05 | cleaner queue 4 | f          | 2025-01-21 16:38:39.487436-05 | Nvme Thread/4 |         8192 |
    1000000 | running
   sgnode    | 140443003062016 | 31220 | Nvme Thread5 | 2025-01-21 16:36:37.136249-05 | cleaner queue 5 | f          | 2025-01-21 16:38:39.520229-05 | Nvme Thread/5 |         8192 |
    1000000 | running
  (6 rows)
  ```
  
  
- gs_nvme_heat_map_status() 描述：查看NVMe页面相应热度级别下的页面个数。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。
  表7gs_nvme_heat_map_status参数说明 
  | 参数类型   | 参数名        | 类型     | 描述                                                                                    |
  |:---|:---|:---|:---|
  | 输出参数 | range    | integer  | 热度范围值，当前支持9个热度范围值：0, 3, 4, 5, 10, 20, 30, 40, -1, 其中-1表示MAX_HEAT, 0表示热度值为0，处于空闲队列的页面。 |
  | 输出参数   | page_count | bigint | 处于当前热度范围的页面数。                                                                          |
     
  示例，查看当前NVMe页面相应热度级别下的页面个数：
  ```
  gaussdb=# SELECT * FROM gs_nvme_heat_map_status();
   range | page_count
  -------+------------
       0 |      19544
       3 |          0
       4 |          0
       5 |          0
      10 |          0
      20 |          0
      30 |          0
      40 |          0
      -1 |          0
  (9 rows)
  ```
  
  
- gs_check_segment_table() 描述：查看数据库中是否包含段页式文件，大容量NVMe缓存优化要求不能有段页式表，因此该检查应在开启NVMe缓存优化前执行。
  返回值类型：record
  表8gs_check_segment_table参数说明 
  | 参数类型 | 参数名                    | 类型   | 描述                             |
  |:---|:---|:---|:---|
  | 输出参数 | gs_check_segment_table | text | SUCCESS表示不存在段页式表，FAILED表示存在段页式表。 |
     
  示例：查看当前仓库是否有段页式表。
  ```
  gaussdb=# SELECT * FROM gs_check_segment_table();
             gs_check_segment_table
  --------------------------------------------
   SUCCESS(d0749aaba8b833466dfcbb0428e4f89c).
  (1 row)
  ```
  
- gs_nvme_spdk_stat() 描述：查看NVMe SPDK模式下的运行状态。
  返回值类型：record
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  该系统函数仅支持启用NVMe缓存后使用。
  **表8** gs_nvme_spdk_stat参数说明
  
  | 参数类型 | 参数名                        | 类型                                                                     | 描述                              |
  |:---|:---|:---|:---|
  | 输出参数    | node_name                 | text                                                                    | 当前节点的名称。                        |
  | 输出参数    | io_mode                      | text                                                                   | 当前节点的I/O模式（spdk mode或normal mode）。 |
  | 输出参数    | nvme_read_bandwidth         | float                                                                    | NVMe的读带宽。                         |
  | 输出参数    | nvme_write_bandwidth        | float                                                                   | NVMe的写带宽。                       |
  | 输出参数  | evs_read_bandwidth         | float                                                                   | EVS的读带宽。                        |
  | 输出参数  | evs_write_bandwidth         | float                                                                    | EVS的写带宽。                        |
  | 输出参数  | nvme_io_exception_count    | bigint                                                                 | NVMe历史累计I/O异常数量。              |
  | 输出参数     | recent_nvme_io_exception_time | timestamp with time zone   | NVMe最近一次I/O异常的时间戳。                |
  | 输出参数  | evs_io_exception_count      | bigint                                                                | EVS历史累计I/O异常数量。                 |
  | 输出参数   | evs_nvme_io_exception_time   | timestamp with time zone | EVS最近一次I/O异常的时间戳。                |
     
  示例：查看NVMe SPDK模式下的运行状态。
  ```
  gaussdb=# SELECT * FROM gs_nvme_spdk_stat();
  node_name | io_mode | nvme_read_bandwidth | nvme_write_bandwidth | evs_read_bandwidth | evs_write_bandwidth | nvme_io_exception_count |        recent_nvme_io_exception_time | evs_io_exception_count | evs_nvme_io_exception_time
  -----------+-----------------+-------+--------------+----------------+---------------+-----------------------+-------------------------+----------------------------+-----------------------------+-------------------+-------------------------
   datanode    |  spdk mode  |  16  |  16  |  16  |  16  |  24  | 2025-01-21 16:36:37.134759-05 |  24  |  2025-01-21 16:36:37.134759-05
  (1 row)
  ```
  
 
