Help Center/ DataArts Fabric/ Developer Guide/ SQL Syntax Reference/ Functions and Operators/ System Management Functions/ Memory Management Functions

Updated on 2025-09-18 GMT+08:00

View PDF

Memory Management Functions

Memory management functions are only supported by clusters of version 25.5.0 or later.

pgxc_total_memory_detail()

Description: Displays the memory usage of all backend actor nodes.

Return type: record.

The function returns the following information:

**Table 1** Output columns of pgxc_total_memory_detail()
Column	Type	Description
nodename	text	Node name.
memorytype	text	Memory name. The options are: max_process_memory: memory occupied by the DataArts Fabric SQL cluster instance. process_used_memory: memory used by the DataArts Fabric SQL process. max_dynamic_memory: maximum dynamic memory. dynamic_used_memory: used dynamic memory. dynamic_peak_memory: dynamic peak value of the memory. dynamic_used_shrctx: maximum dynamic shared memory context. dynamic_peak_shrctx: dynamic peak value of the shared memory context. max_shared_memory: maximum shared memory. shared_used_memory: used shared memory. max_cstore_memory: maximum memory allowed by column storage. cstore_used_memory: used memory of the column-store table. other_used_memory: other used memory size. mmap_used_memory: memory used by mmap.
memorymbytes	integer	Size of the used memory, in MB.

shared_memory_context(actor_name cstring)

Description: Queries statistics about shared memory contexts in a specified actor process.

Parameter: actor_name, indicating the actor name.

Return type: record.

Example:

    
         select * from shared_memory_context('coordinator1') order by totalsize desc limit 10;
             contextname             | level |             parent              | totalsize | freesize | usedsize
-------------------------------------+-------+---------------------------------+-----------+----------+----------
 Query resource track memory context |     2 | Workload manager memory context |  67174520 |    64320 | 67110200
 RawMemory                           |     1 | ProcessMemory                   |  23525840 |        0 | 23525840
 builtin proc name Lookup Table      |     2 | builtin_procGlobalMemoryContext |    425984 |   261152 |   164832
 ProcessMemory                       |     0 |                                 |    196608 |    76992 |   119616
 builtin pro Oid Lookup Table        |     2 | builtin_procGlobalMemoryContext |    196608 |    41664 |   154944
 PoolerMemoryContext                 |     1 | ProcessMemory                   |     73728 |    56832 |    16896
 Node Pool                           |     3 | PoolerCoreContext               |     73640 |    25888 |    47752
 ThreadGroup Hash Table              |     1 | ProcessMemory                   |     65536 |    39936 |    25600
 Aio Sub Memory Context 6            |     2 | Aio Memory Context              |     65536 |    63872 |     1664
 Aio Sub Memory Context 5            |     2 | Aio Memory Context              |     65536 |    63872 |     1664
(10 rows)

shared_memory_context_chunk(actor_name cstring, contextname char(64))

Description: Queries information about all chunks applied for by the shared memory context named contextname of a specified actor.

Parameters:

actor_name: actor name.
contextname: memory context name.

Return type: record.

Example:

    
         select * from shared_memory_context_chunk('executor0_es_group', 'StreamInfoContext') ;
    parent     | level |      file_name       | line_number | chunk_size | request_count | total_size
---------------+-------+----------------------+-------------+------------+---------------+------------
 ProcessMemory |     1 | mcxt.cpp             |        1010 |       8192 |             1 |       8192
 ProcessMemory |     1 | streamThreadPool.cpp |          35 |       1024 |             1 |       1024
(2 rows)

pgxc_session_memory_detail()

Description: Displays the thread memory usage of the corresponding actor or all backend actor nodes by MemoryContext.

The memory context TempSmallContextGroup records the summary information of all memory contexts in the current thread where the totalsize column is fewer than 8,192 bytes, and the count of memory contexts is recorded in the usedsize column. Therefore, in the results, the totalsize and freesize columns in the TempSmallContextGroup memory context represent the aggregate sum of all memory contexts in the thread where totalsize is fewer than 8,192 bytes, and the usedsize column indicates the count of such memory contexts.

Parameter descriptions:

pgxc_session_memory_detail(): no parameters, queries the statistical information of memory contexts for all threads in the CN and all DN processes.
pgxc_session_memory_detail(actor_name), with the input parameter actor_name, outputs the statistical information of memory contexts for all threads in the specified CN or DN process.

Return type: record.

The function returns the following information:

**Table 2** pgxc_session_memory_detail columns
Column	Type	Description
sessid	text	Thread start time + thread ID (string format: timestamp.threadid).
sesstype	text	Thread name.
contextname	text	Memory context name.
level	smallint	Level of the current context within the overall memory context hierarchy.
parent	text	Parent memory context name.
totalsize	bigint	Total memory size of the current memory context, in bytes.
freesize	bigint	Total size of freed memory in the current memory context, in bytes.
usedsize	bigint	Total size of used memory in the current memory context, in bytes. For the TempSmallContextGroup memory context, this column indicates the count statistic.

session_memory_context_chunk(actor_name cstring, tid int64, contextname char(64))

Description: Queries information about all chunks allocated by a specific memory context created by a thread on a specified actor.

Parameter descriptions:

actor_name: actor name.
tid: thread ID.
contextname: memory context name.

Return type: record.

Example:

    
         select * from session_memory_context_chunk('executor0_es_group', 139736895414560, 'Node Pool') order by total_size desc ;
      parent       | level |  file_name   | line_number | chunk_size | request_count | total_size
-------------------+-------+--------------+-------------+------------+---------------+------------
 PoolerCoreContext |     3 | dynahash.cpp |         147 |       2048 |             1 |       2048
 PoolerCoreContext |     3 | dynahash.cpp |         147 |        256 |             1 |        256
 PoolerCoreContext |     3 | dynahash.cpp |         147 |      32584 |             1 |      32584
 PoolerCoreContext |     3 | dynahash.cpp |         147 |       4096 |             3 |      12288
(4 rows)

jemalloc_heap_stats(actor_name cstring)

Description: Queries the memory statistics provided by jemalloc.

Parameter: actor_name indicates the actor name.

Return type: record.

Example:

   
        select * from jemalloc_heap_stats( 'coordinator1' );
  actor_name  |
  stats
--------------+-------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------------------------------------------------
 coordinator1 | ___ Begin jemalloc statistics ___

              | Version: "5.2.1-6-gd04ec97dec5e84ac24f32c29053aa94479402b6d"

              | Build-time option settings

              |   config.cache_oblivious: true

              |   config.debug: false

              |   config.fill: true

              |   config.lazy_lock: false

              |   config.malloc_conf: "tcache:true,background_thread:true,percpu_arena:phycpu,dirty_decay_ms:1000,muzzy_decay_ms:1000"

              |   config.opt_safety_checks: false

              |   config.prof: false

              |   config.prof_libgcc: false

              |   config.prof_libunwind: false

              |   config.stats: true

              |   config.utrace: false

jemalloc_heap_profiling(actor_name cstring, type int)

Description: Samples memory allocations such as malloc in the DataArts Fabric SQL actor process and outputs the sampling results.

**Table 3** jemalloc_heap_profiling parameters
Parameter	Type	Description
actor_name	String	Actor name.
type	Integer	1: Enables memory tracing and records call stack information such as malloc. 0: Disables memory tracing and returns the sampled call stack information such as malloc.

Return type:

actor_name: actor name.
profiling: memory allocation sampling information.

Notes:

If the failure prompt reads "Memory profiling failed, check if $MALLOC_CONF contains 'prof:true'.", it means the environment variable MALLOC_CONF=prof:true was not set because the jemalloc library with memory sampling capability was not used. Add the -j option to the parameters when starting the CN using gov_client.
If the failure prompt reads "Type %d is not supported. The valid range is 0-1.", it indicates an invalid user input. The correct values are 0 or 1.

Outputting Memory Call Stack Information

Procedure:

Output memory call stack information and generate trace files in the directory where the DataArts Fabric SQL process resides.
1

SELECT profiling FROM jemalloc_heap_profiling('coordinator1', 0);
Save the query results as trace files.
Use the jeprof tool provided by jemalloc to parse the log information.
Method 1: Output in text format.
```
jeprof --text --show_bytes $GAUSSHOME/bin/gaussdb trace file 1 >prof.txt
```
Method 2: Export the report in PDF format.
```
jeprof --pdf --show_bytes $GAUSSHOME/bin/gaussdb trace file 1 > prof.pdf
```
- Parsing memory call stack information requires analyzing the DataArts Fabric SQL source code, and the trace files should be sent back to R&D engineers for further analysis.
- Analyzing trace files requires the jeprof tool, which is generated by Jemalloc. Generating PDF call graphs depends on the Perl environment and requires installing the GraphViz tool compatible with the operating system.

Examples

Run gov_client -j to restart the database.

Enable memory tracing during database runtime.

    
         SELECT profiling fromjemalloc_heap_profiling('coordinator1', 1);

Disable memory tracing during database runtime.

    
         SELECT profiling fromjemalloc_heap_profiling('coordinator1', 0);

Save the query results into trace files and export them in text or PDF format.

    
         jeprof --text --show_bytes $GAUSSHOME/bin/gaussdb trace file 1 >prof.txt
jeprof --pdf --show_bytes $GAUSSHOME/bin/gaussdb trace file 1 > prof.pdf