<row>

<entry role="func_table_entry"><para role="func_signature">

<indexterm>

<primary>pg_get_process_memory_contexts</primary>

</indexterm>

<function>pg_get_process_memory_contexts</function> ( <parameter>pid</parameter> <type>integer</type>, <parameter>summary</parameter> <type>boolean</type>, <parameter>timeout</parameter> <type>float</type> )

<returnvalue>setof record</returnvalue>

( <parameter>name</parameter> <type>text</type>,

<parameter>ident</parameter> <type>text</type>,

<parameter>type</parameter> <type>text</type>,

<parameter>path</parameter> <type>integer[]</type>,

<parameter>level</parameter> <type>integer</type>,

<parameter>total_bytes</parameter> <type>bigint</type>,

<parameter>total_nblocks</parameter> <type>bigint</type>,

<parameter>free_bytes</parameter> <type>bigint</type>,

<parameter>free_chunks</parameter> <type>bigint</type>,

<parameter>used_bytes</parameter> <type>bigint</type>,

<parameter>num_agg_contexts</parameter> <type>integer</type>,

<parameter>stats_timestamp</parameter> <type>timestamptz</type> )

</para>

<para>

This function handles requests to display the memory contexts of a

<productname>PostgreSQL</productname> process with the specified

process ID. The function can be used to send requests to backends as

well as <glossterm linkend="glossary-auxiliary-proc">auxiliary processes</glossterm>.

</para>

<para>

The returned record contains extended statistics per each memory

context:

<itemizedlist spacing="compact">

<listitem>

<para>

<parameter>name</parameter> - The name of the memory context.

</para>

</listitem>

<listitem>

<para>

<parameter>ident</parameter> - Memory context ID (if any).

</para>

</listitem>

<listitem>

<para>

<parameter>type</parameter> - The type of memory context, possible

values are: AllocSet, Generation, Slab and Bump.

</para>

</listitem>

<listitem>

<para>

<parameter>path</parameter> - Memory contexts are organized in a

tree model with TopMemoryContext as the root, and all other memory

contexts as nodes in the tree. The <parameter>path</parameter>

displays the path from the root to the current memory context. The

path is limited to 100 children per node, which each node limited

to a max depth of 100, to preserve memory during reporting. The

printed path will also be limited to 100 nodes counting from the

TopMemoryContext.

</para>

</listitem>

<listitem>

<para>

<parameter>level</parameter> - The level in the tree of the current

memory context.

</para>

</listitem>

<listitem>

<para>

<parameter>total_bytes</parameter> - The total number of bytes

allocated to this memory context.

</para>

</listitem>

<listitem>

<para>

<parameter>total_nblocks</parameter> - The total number of blocks

used for the allocated memory.

</para>

</listitem>

<listitem>

<para>

<parameter>free_bytes</parameter> - The amount of free memory in

this memory context.

</para>

</listitem>

<listitem>

<para>

<parameter>free_chunks</parameter> - The number of chunks that

<parameter>free_bytes</parameter> corresponds to.

</para>

</listitem>

<listitem>

<para>

<parameter>used_bytes</parameter> - The total number of bytes

currently occupied.

</para>

</listitem>

<listitem>

<para>

<parameter>num_agg_contexts</parameter> - The number of memory

contexts aggregated in the displayed statistics.

</para>

</listitem>

<listitem>

<para>

<parameter>stats_timestamp</parameter> - When the statistics were

extracted from the process.

</para>

</listitem>

</itemizedlist>

</para>

<para>

When <parameter>summary</parameter> is <literal>true</literal>, statistics

for memory contexts at levels 1 and 2 are displayed, with level 1

representing the root node (i.e., <literal>TopMemoryContext</literal>).

Statistics for contexts on level 2 and below are aggregates of all

child contexts' statistics, where <literal>num_agg_contexts</literal>

indicate the number aggregated child contexts. When

<parameter>summary</parameter> is <literal>false</literal>,

<literal>the num_agg_contexts</literal> value is <literal>1</literal>,

indicating that individual statistics are being displayed.

</para>

<para>

Busy processes can delay reporting memory context statistics,

<parameter>timeout</parameter> specifies the number of seconds

to wait for updated statistics. <parameter>timeout</parameter> can be

specified in fractions of a second.

</para>

<para>

After receiving memory context statistics from the target process, it

returns the results as one row per context. If all the contexts don't

fit within the pre-determined size limit, the remaining context

statistics are aggregated and a cumulative total is displayed. The

<literal>num_agg_contexts</literal> column indicates the number of

contexts aggregated in the displayed statistics. When

<literal>num_agg_contexts</literal> is <literal>1</literal> it means

that the context statistics are displayed separately.

</para></entry>

</row>

<para>

<function>pg_get_process_memory_contexts</function> can be used to request

memory contexts statistics of any <productname>PostgreSQL</productname>

process. For example:

<programlisting>

postgres=# SELECT * FROM pg_get_process_memory_contexts(

(SELECT pid FROM pg_stat_activity

WHERE backend_type = 'checkpointer'),

false, 0.5) LIMIT 1;

-[ RECORD 1 ]----+------------------------------

name | TopMemoryContext

ident |

type | AllocSet

path | {1}

level | 1

total_bytes | 90304

total_nblocks | 3

free_bytes | 2880

free_chunks | 1

used_bytes | 87424

num_agg_contexts | 1

stats_timestamp | 2025-03-24 13:55:47.796698+01

</programlisting>

<note>

<para>

While <function>pg_get_process_memory_contexts</function> can be used to

query memory contexts of the local backend,

<structname>pg_backend_memory_contexts</structname>

(see <xref linkend="view-pg-backend-memory-contexts"/> for more details)

will be less resource intensive when only the local backend is of interest.

</para>

</note>

</para>

<!--

Author: Daniel Gustafsson <dgustafsson@postgresql.org>

2025-04-08 [042a66291] Add function to get memory context stats for processes

Author: Daniel Gustafsson <dgustafsson@postgresql.org>

2025-04-08 [c57971034] Rename argument in pg_get_process_memory_contexts().

-->

<listitem>

<para>

Add function pg_get_process_memory_contexts() to report process memory context statistics (Rahila Syed)

<ulink url="&commit_baseurl;042a66291">&sect;</ulink>

<ulink url="&commit_baseurl;c57971034">&sect;</ulink>

</para>

</listitem>

REVOKE EXECUTE ON FUNCTION

pg_get_process_memory_contexts(integer, boolean, float) FROM PUBLIC;

GRANT EXECUTE ON FUNCTION

pg_get_process_memory_contexts(integer, boolean, float) TO pg_read_all_stats;

/* Publish memory contexts of this process */

if (PublishMemoryContextPending)

ProcessGetMemoryContextInterrupt();

/* Publish memory contexts of this process */

if (PublishMemoryContextPending)

ProcessGetMemoryContextInterrupt();

/* Publish memory contexts of this process */

if (PublishMemoryContextPending)

ProcessGetMemoryContextInterrupt();

/* Publish memory contexts of this process */

if (PublishMemoryContextPending)

ProcessGetMemoryContextInterrupt();

/* Publish memory contexts of this process */

if (PublishMemoryContextPending)

ProcessGetMemoryContextInterrupt();

/* Publish memory contexts of this process */

if (PublishMemoryContextPending)

ProcessGetMemoryContextInterrupt();

#include "utils/memutils.h"

size = add_size(size, MemoryContextReportingShmemSize());

MemoryContextReportingShmemInit();