workload_mgmt_resgroups.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1" xml:lang="en">
  <title id="iz173472">Using Resource Groups</title>
  <body>
    <p>You use resource groups to set and enforce CPU, memory, and concurrent transaction limits in
      Greenplum Database. After you define a resource group, you can then assign the group to one or
      more Greenplum Database roles, or to an external component such as PL/Container, in order to
      control the resources used by those roles or components.</p>
    <p>When you assign a resource group to a role (a role-based resource group), the resource limits
      that you define for the group apply to all of the roles to which you assign the group. For
      example, the memory limit for a resource group identifies the maximum memory usage for all
      running transactions submitted by Greenplum Database users in all roles to which you assign
      the group.</p>
    <p>Similarly, when you assign a resource group to an external component, the group limits apply
      to all running instances of the component. For example, if you create a resource group for a
      PL/Container external component, the memory limit that you define for the group specifies the
      maximum memory usage for all running instances of each PL/Container runtime to which you
      assign the group.</p>
    <p>This topic includes the following subtopics:</p>
    <ul id="ul_wjf_1wy_sp">
      <li id="im168064">
        <xref href="#topic8339intro" type="topic" format="dita"/>
      </li>
      <li id="im168064x">
        <xref href="#topic8339introattrlim" type="topic" format="dita"/><ul>
          <li id="im16806az">
            <xref href="#topic8339777" type="topic" format="dita"/>
          </li>
          <li id="im16806a">
            <xref href="#topic8339717179" type="topic" format="dita"/>
          </li>
          <li id="im16806b">
            <xref href="#topic833971717" type="topic" format="dita"/>
          </li>
          <li id="im16806c">
            <xref href="#topic8339717" type="topic" format="dita"/>
          </li>
        </ul></li>
      <li id="im16806gpcc" otherprops="pivotal">
        <xref href="#topic999" format="dita"/>
      </li>
      <li id="im16806d">
        <xref href="#topic71717999" type="topic" format="dita"/>
        <ul id="ul_wjf_1wy_spXX">
          <li id="im16806e">
            <xref href="#topic8" type="topic" format="dita"/>
          </li>
          <li id="im16806f">
            <xref href="#topic10" type="topic" format="dita"/>
          </li>
          <li><xref href="#topic_jlz_hzg_pkb" format="dita"/></li>
          <li id="im16806g">
            <xref href="#topic17" type="topic" format="dita"/>
          </li>
        </ul></li>
          <li id="im16806h">
            <xref href="#topic22" type="topic" format="dita"/>
          </li>
      <li>
        <xref href="#moverg" type="topic" format="dita"/>
      </li>
      <li>
        <xref href="#topic777999" type="topic" format="dita"/>
      </li>
    </ul>
  </body>
  <topic id="topic8339intro" xml:lang="en">
    <title>Understanding Role and Component Resource Groups</title>
    <body>
      <p>Greenplum Database supports two types of resource groups: groups that manage resources for
        roles, and groups that manage resources for external components such as PL/Container.</p>
      <p>The most common application for resource groups is to manage the number of active queries
        that different roles may execute concurrently in your Greenplum Database cluster. You can
        also manage the amount of CPU and memory resources that Greenplum allocates to each
        query.</p>
      <p>Resource groups for roles use Linux control groups (cgroups) for CPU resource management.
        Greenplum Database tracks virtual memory internally for these resource groups using a memory
        auditor referred to as <codeph>vmtracker</codeph>.</p>
      <p>When the user executes a query, Greenplum Database evaluates the query against a set of
        limits defined for the resource group. Greenplum Database executes the query immediately if
        the group's resource limits have not yet been reached and the query does not cause the group
        to exceed the concurrent transaction limit. If these conditions are not met, Greenplum
        Database queues the query. For example, if the maximum number of concurrent transactions for
        the resource group has already been reached, a subsequent query is queued and must wait
        until other queries complete before it runs. Greenplum Database may also execute a pending
        query when the resource group's concurrency and memory limits are altered to large enough
        values.</p>
      <p>Within a resource group for roles, transactions are evaluated on a first in, first out
        basis. Greenplum Database periodically assesses the active workload of the system,
        reallocating resources and starting/queuing jobs as necessary.</p>
      <p>You can also use resource groups to manage the CPU and memory resources of external
        components such as PL/Container. Resource groups for external components use Linux cgroups
        to manage both the total CPU and total memory resources for the component.</p>
      <note>Containerized deployments of Greenplum Database, such as Greenplum for Kubernetes, might
        create a hierarchical set of nested cgroups to manage host system resources. The nesting of
        cgroups affects the Greenplum Database resource group limits for CPU percentage, CPU cores,
        and memory (except for Greenplum Database external components). The Greenplum Database
        resource group system resource limit is based on the quota for the parent group.<p>For
          example, Greenplum Database is running in a cgroup demo, and the Greenplum Database cgroup
          is nested in the cgroup demo. If the cgroup demo is configured with a CPU limit of 60% of
          system CPU resources and the Greenplum Database resource group CPU limit is set 90%, the
          Greenplum Database limit of host system CPU resources is 54% (0.6 x 0.9).</p><p>Nested
          cgroups do not affect memory limits for Greenplum Database external components such as
          PL/Container. Memory limits for external components can only be managed if the cgroup that
          is used to manage Greenplum Database resources is not nested, the cgroup is configured as
          a top-level cgroup.</p><p>For information about configuring cgroups for use by resource
          groups, see <xref href="#topic71717999" format="dita"/>.</p></note>
    </body>
  </topic>
  <topic id="topic8339introattrlim" xml:lang="en">
    <title>Resource Group Attributes and Limits</title>
    <body>
      <p>When you create a resource group, you:</p>
      <ul>
        <li>Specify the type of resource group by identifying how memory for the group is
          audited.</li>
        <li>Provide a set of limits that determine the amount of CPU and memory resources available
          to the group.</li>
      </ul>
      <p>Resource group attributes and limits:</p>
      <table id="resgroup_limit_descriptions">
        <tgroup cols="3">
          <colspec colnum="1" colname="col1" colwidth="1*"/>
          <colspec colnum="2" colname="col2" colwidth="1*"/>
          <thead>
            <row>
              <entry colname="col1">Limit Type</entry>
              <entry colname="col2">Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">MEMORY_AUDITOR</entry>
              <entry colname="col2">The memory auditor in use for the resource group.
                  <codeph>vmtracker</codeph> (the default) is required if you want to assign the
                resource group to roles. Specify <codeph>cgroup</codeph> to assign the resource
                group to an external component.</entry>
            </row>
            <row>
              <entry colname="col1">CONCURRENCY</entry>
              <entry colname="col2">The maximum number of concurrent transactions, including active
                and idle transactions, that are permitted in the resource group.</entry>
            </row>
            <row>
              <entry colname="col1">CPU_RATE_LIMIT</entry>
              <entry colname="col2">The percentage of CPU resources available to this resource
                group.</entry>
            </row>
            <row>
              <entry colname="col1">CPUSET</entry>
              <entry colname="col2">The CPU cores to reserve for this resource group.</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_LIMIT</entry>
              <entry colname="col2">The percentage of reserved memory resources available to
                this resource group.</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SHARED_QUOTA</entry>
              <entry colname="col2">The percentage of reserved memory to share across transactions submitted
                in this resource group.</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SPILL_RATIO</entry>
              <entry colname="col2">The memory usage threshold for memory-intensive transactions.
                When a transaction reaches this threshold, it spills to disk.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <note>Resource limits are not enforced on <codeph>SET</codeph>, <codeph>RESET</codeph>, and
          <codeph>SHOW</codeph> commands.</note>
    </body>
  </topic>
  <topic id="topic8339777" xml:lang="en">
    <title>Memory Auditor</title>
    <body>
      <p>The <codeph>MEMORY_AUDITOR</codeph> attribute specifies the type of resource group by
        identifying the memory auditor for the group. A resource group that specifies the
          <codeph>vmtracker</codeph>
        <codeph>MEMORY_AUDITOR</codeph> identifies a resource group for roles. A resource group
        specifying the <codeph>cgroup</codeph>
        <codeph>MEMORY_AUDITOR</codeph> identifies a resource group for external components.</p>
      <p>The default <codeph>MEMORY_AUDITOR</codeph> is <codeph>vmtracker</codeph>.</p>
      <p>The <codeph>MEMORY_AUDITOR</codeph> that you specify for a resource group determines if and
        how Greenplum Database uses the limit attributes to manage CPU and memory resources:</p>
      <table id="resgroup_limit_descriptions">
        <tgroup cols="3">
          <colspec colnum="1" colname="col1" colwidth="1*"/>
          <colspec colnum="2" colname="col2" colwidth="1*"/>
          <colspec colnum="3" colname="col3" colwidth="1*"/>
          <thead>
            <row>
              <entry colname="col1">Limit Type</entry>
              <entry colname="col2">Resource Group for Roles</entry>
              <entry colname="col3">Resource Group for External Components</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">CONCURRENCY</entry>
              <entry colname="col2">Yes</entry>
              <entry colname="col3">No; must be zero (0)</entry>
            </row>
            <row>
              <entry colname="col1">CPU_RATE_LIMIT</entry>
              <entry colname="col2">Yes</entry>
              <entry colname="col3">Yes</entry>
            </row>
            <row>
              <entry colname="col1">CPUSET</entry>
              <entry colname="col2">Yes</entry>
              <entry colname="col3">Yes</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_LIMIT</entry>
              <entry colname="col2">Yes</entry>
              <entry colname="col3">Yes</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SHARED_QUOTA</entry>
              <entry colname="col2">Yes</entry>
              <entry colname="col2">Component-specific</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SPILL_RATIO</entry>
              <entry colname="col2">Yes</entry>
              <entry colname="col2">Component-specific</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <p>
        <note>For queries managed by resource groups that are configured to use the
            <codeph>vmtracker</codeph> memory auditor, Greenplum Database supports the automatic
          termination of queries based on the amount of memory the queries are using. See the server
          configuration parameter <codeph><xref
              href="../ref_guide/config_params/guc-list.xml#runaway_detector_activation_percent"
              type="section"/></codeph>. </note>
      </p>
    </body>
  </topic>
  <topic id="topic8339717179" xml:lang="en">
    <title>Transaction Concurrency Limit</title>
    <body>
      <p>The <codeph>CONCURRENCY</codeph> limit controls the maximum number of concurrent
        transactions permitted for a resource group for roles.
        <note>The <codeph>CONCURRENCY</codeph> limit is not applicable to resource groups for
          external components and must be set to zero (0) for such groups.</note></p>
      <p>Each resource group for roles is logically divided into a fixed number of slots equal to
        the <codeph>CONCURRENCY</codeph> limit. Greenplum Database allocates these slots an equal,
        fixed percentage of memory resources.</p>
      <p>The default <codeph>CONCURRENCY</codeph> limit value for a resource group for roles is
        20.</p>
      <p>Greenplum Database queues any transactions submitted after the resource group reaches its
          <codeph>CONCURRENCY</codeph> limit. When a running transaction completes, Greenplum
        Database un-queues and executes the earliest queued transaction if sufficient memory
        resources exist.</p>
      <p>You can set the server configuration parameter <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_group_bypass" type="section"
            scope="peer">gp_resource_group_bypass</xref></codeph> to bypass a resource group
        concurrency limit.</p>
      <p>You can set the server configuration parameter <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_group_queuing_timeout" type="section"
            scope="peer">gp_resource_group_queuing_timeout</xref></codeph> to specify the
         amount of time a transaction remains in the queue before Greenplum Database
         cancels the transaction. The default timeout is zero, Greenplum queues
         transactions indefinitely.</p>
    </body>
  </topic>
  <topic id="topic833971717" xml:lang="en">
    <title>CPU Limits</title>
    <body>
      <p>You configure the share of CPU resources to reserve for a resource group on a segment host
        by assigning specific CPU core(s) to the group, or by identifying the percentage of segment
        CPU resources to allocate to the group. Greenplum Database uses the <codeph>CPUSET</codeph>
        and <codeph>CPU_RATE_LIMIT</codeph> resource group limits to identify the CPU resource
        allocation mode. You must specify only one of these limits when you configure a resource
        group.</p>
      <p>You may employ both modes of CPU resource allocation simultaneously in your Greenplum
        Database cluster. You may also change the CPU resource allocation mode for a resource group
        at runtime.</p>
      <p>The <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_group_cpu_limit" type="topic"
          /></codeph> server configuration parameter identifies the maximum percentage of system CPU
        resources to allocate to resource groups on each Greenplum Database segment host. This limit
        governs the maximum CPU usage of all resource groups on a segment host regardless of the CPU
        allocation mode configured for the group. The remaining unreserved CPU resources are used
        for the OS kernel and the Greenplum Database auxiliary daemon processes. The default
          <codeph>gp_resource_group_cpu_limit</codeph> value is .9 (90%).</p>
      <note>The default <codeph>gp_resource_group_cpu_limit</codeph> value may not leave sufficient
        CPU resources if you are running other workloads on your Greenplum Database cluster nodes,
        so be sure to adjust this server configuration parameter accordingly.</note>
      <note type="warning">Avoid setting <codeph>gp_resource_group_cpu_limit</codeph> to a value
        higher than .9. Doing so may result in high workload queries taking near all CPU resources,
        potentially starving Greenplum Database auxiliary processes.</note>
    </body>
    <topic id="cpuset" xml:lang="en">
      <title>Assigning CPU Resources by Core</title>
      <body>
        <p>You identify the CPU cores that you want to reserve for a resource group with the
            <codeph>CPUSET</codeph> property. The CPU cores that you specify must be available in
          the system and cannot overlap with any CPU cores that you reserved for other resource
          groups. (Although Greenplum Database uses the cores that you assign to a resource group
          exclusively for that group, note that those CPU cores may also be used by non-Greenplum
          processes in the system.)</p>
        <p>Specify a comma-separated list of single core numbers or number intervals when you
          configure <codeph>CPUSET</codeph>. You must enclose the core numbers/intervals in single
          quotes, for example, '1,3-4'.</p>
        <p>When you assign CPU cores to <codeph>CPUSET</codeph> groups, consider the following:<ul>
            <li>A resource group that you create with <codeph>CPUSET</codeph> uses the specified
              cores exclusively. If there are no running queries in the group, the reserved cores
              are idle and cannot be used by queries in other resource groups. Consider minimizing
              the number of <codeph>CPUSET</codeph> groups to avoid wasting system CPU
              resources.</li>
            <li>Consider keeping CPU core 0 unassigned. CPU core 0 is used as a fallback mechanism
              in the following cases:<ul>
                <li><codeph>admin_group</codeph> and <codeph>default_group</codeph> require at least
                  one CPU core. When all CPU cores are reserved, Greenplum Database assigns CPU core
                  0 to these default groups. In this situation, the resource group to which you
                  assigned CPU core 0 shares the core with <codeph>admin_group</codeph> and
                    <codeph>default_group</codeph>.</li>
                <li>If you restart your Greenplum Database cluster with one node replacement and the
                  node does not have enough cores to service all <codeph>CPUSET</codeph> resource
                  groups, the groups are automatically assigned CPU core 0 to avoid system start
                  failure.</li>
              </ul></li>
            <li>Use the lowest possible core numbers when you assign cores to resource groups. If
              you replace a Greenplum Database node and the new node has fewer CPU cores than the
              original, or if you back up the database and want to restore it on a cluster with
              nodes with fewer CPU cores, the operation may fail. For example, if your Greenplum
              Database cluster has 16 cores, assigning cores 1-7 is optimal. If you create a
              resource group and assign CPU core 9 to this group, database restore to an 8 core node
              will fail.</li>
          </ul></p>
        <p>Resource groups that you configure with <codeph>CPUSET</codeph> have a higher priority on
          CPU resources. The maximum CPU resource usage percentage for all resource groups
          configured with <codeph>CPUSET</codeph> on a segment host is the number of CPU cores
          reserved divided by the number of all CPU cores, multiplied by 100.</p>
        <p>When you configure <codeph>CPUSET</codeph> for a resource group, Greenplum Database
          disables <codeph>CPU_RATE_LIMIT</codeph> for the group and sets the value to -1.</p>
        <note>You must configure <codeph>CPUSET</codeph> for a resource group <i>after</i> you have
          enabled resource group-based resource management for your Greenplum Database
          cluster.</note>
      </body>
    </topic>
    <topic id="cpu_rate_limit" xml:lang="en">
      <title>Assigning CPU Resources by Percentage</title>
      <body>
        <p>The Greenplum Database node CPU percentage is divided equally among each segment on the
          Greenplum node. Each resource group that you configure with a
            <codeph>CPU_RATE_LIMIT</codeph> reserves the specified percentage of the segment CPU for
          resource management.</p>
        <p>The minimum <codeph>CPU_RATE_LIMIT</codeph> percentage you can specify for a resource
          group is 1, the maximum is 100.</p>
        <p>The sum of <codeph>CPU_RATE_LIMIT</codeph>s specified for all resource groups that you
          define in your Greenplum Database cluster must not exceed 100.</p>
        <p>The maximum CPU resource usage for all resource groups configured with a
            <codeph>CPU_RATE_LIMIT</codeph> on a segment host is the minimum of:<ul>
            <li>The number of non-reserved CPU cores divided by the number of all CPU cores,
              multiplied by 100, and</li>
            <li>The <codeph>gp_resource_group_cpu_limit</codeph> value.</li>
          </ul></p>
        <p>CPU resource assignment for resource groups configured with a
            <codeph>CPU_RATE_LIMIT</codeph> is elastic in that Greenplum Database may allocate the
          CPU resources of an idle resource group to a busier one(s). In such situations, CPU
          resources are re-allocated to the previously idle resource group when that resource group
          next becomes active. If multiple resource groups are busy, they are allocated the CPU
          resources of any idle resource groups based on the ratio of their
            <codeph>CPU_RATE_LIMIT</codeph>s. For example, a resource group created with a
            <codeph>CPU_RATE_LIMIT</codeph> of 40 will be allocated twice as much extra CPU resource
          as a resource group that you create with a <codeph>CPU_RATE_LIMIT</codeph> of 20.</p>
        <p>When you configure <codeph>CPU_RATE_LIMIT</codeph> for a resource group, Greenplum
          Database disables <codeph>CPUSET</codeph> for the group and sets the value to -1.</p>
      </body>
    </topic>
  </topic>
  <topic id="topic8339717" xml:lang="en">
    <title>Memory Limits</title>
    <body>
      <p>When resource groups are enabled, memory usage is managed at the Greenplum Database node,
        segment, and resource group levels. You can also manage memory at the transaction level with
        a resource group for roles.</p>
      <p>The <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_group_memory_limit"
            type="topic"/></codeph> server configuration parameter identifies the maximum percentage
        of system memory resources to allocate to resource groups on each Greenplum Database segment
        host. The default <codeph>gp_resource_group_memory_limit</codeph> value is .7 (70%).</p>
      <p>The memory resource available on a Greenplum Database node is further divided equally among
        each segment on the node. When resource group-based resource management is active, the
        amount of memory allocated to each segment on a segment host is the memory available to
        Greenplum Database multiplied by the <codeph>gp_resource_group_memory_limit</codeph> server
        configuration parameter and divided by the number of active primary segments on the
        host:</p>
      <p>
        <codeblock>
rg_perseg_mem = ((RAM * (vm.overcommit_ratio / 100) + SWAP) * gp_resource_group_memory_limit) / num_active_primary_segments</codeblock>
      </p>
      <p>Each resource group may reserve a percentage of the segment memory for resource management.
        You identify this percentage via the <codeph>MEMORY_LIMIT</codeph> value that you specify
        when you create the resource group. The minimum <codeph>MEMORY_LIMIT</codeph> percentage you
        can specify for a resource group is 0, the maximum is 100. When <codeph>MEMORY_LIMIT</codeph>
        is 0, Greenplum Database reserves no memory for the resource group, but uses resource
        group global shared memory to fulfill all memory requests in the group. Refer to
        <xref href="#topic833glob" type="topic" format="dita"/>
        for more information about resource group global shared memory.</p>
      <p>The sum of <codeph>MEMORY_LIMIT</codeph>s specified for all resource groups that you define
        in your Greenplum Database cluster must not exceed 100.</p>
    </body>
    <topic id="mem_roles" xml:lang="en">
      <title>Additional Memory Limits for Role-based Resource Groups</title>
      <body>
        <p>If resource group memory is reserved for roles (non-zero
          <codeph>MEMORY_LIMIT</codeph>), the memory is further divided into fixed and
          shared components. The <codeph>MEMORY_SHARED_QUOTA</codeph> value that you specify when
          you create the resource group identifies the percentage of reserved resource group memory
          that may be shared among the currently running transactions. This memory is allotted on a
          first-come, first-served basis. A running transaction may use none, some, or all of the
            <codeph>MEMORY_SHARED_QUOTA</codeph>.</p>
        <p>The minimum <codeph>MEMORY_SHARED_QUOTA</codeph> that you can specify is 0, the maximum
          is 100. The default <codeph>MEMORY_SHARED_QUOTA</codeph> is 80.</p>
        <p>As mentioned previously, <codeph>CONCURRENCY</codeph> identifies the maximum number of
          concurrently running transactions permitted in a resource group for roles. If fixed
          memory is reserved by a resource group (non-zero <codeph>MEMORY_LIMIT</codeph>),
          it is divided into <codeph>CONCURRENCY</codeph> number of
          transaction slots. Each slot is allocated a fixed, equal amount of the resource group memory.
          Greenplum Database guarantees this fixed memory to each transaction. <fig
            id="fig_py5_1sl_wlrg">
            <title>Resource Group Memory Allotments</title>
            <image href="graphics/resgroupmem.png" id="image_iqn_dsl_wlrg" align="left" scale="72"
              placement="break"/>
          </fig></p>
        <p>When a query's memory usage exceeds the fixed per-transaction memory usage amount,
          Greenplum Database allocates available resource group shared memory to the query. The
          maximum amount of resource group memory available to a specific transaction slot is the
          sum of the transaction's fixed memory and the full resource group shared memory
          allotment.</p>
      </body>
      <topic id="topic833glob" xml:lang="en">
        <title>Global Shared Memory</title>
        <body>
          <p>The sum of the <codeph>MEMORY_LIMIT</codeph>s configured for all resource groups
            (including the default <codeph>admin_group</codeph> and <codeph>default_group</codeph>
            groups) identifies the percentage of reserved resource group memory. If this sum is less
            than 100, Greenplum Database allocates any unreserved memory to a resource group global
            shared memory pool.</p>
          <p>Resource group global shared memory is available only to resource groups that you
            configure with the <codeph>vmtracker</codeph> memory auditor.</p>
          <p>When available, Greenplum Database allocates global shared memory to a transaction
            after first allocating slot and resource group shared memory (if applicable). Greenplum Database
            allocates resource group global shared memory to transactions on a first-come
            first-served basis.</p>
          <note>Greenplum Database tracks, but does not actively monitor, transaction memory usage
            in resource groups. If the memory usage for a resource group exceeds its fixed memory
            allotment, a transaction in the resource group fails when <i>all</i> of these conditions
            are met:<ul>
              <li>No available resource group shared memory exists.</li>
              <li>No available global shared memory exists.</li>
              <li>The transaction requests additional memory.</li>
            </ul></note>
          <p>Greenplum Database uses resource group memory more efficiently when you leave some
            memory (for example, 10-20%) unallocated for the global shared memory pool. The
            availability of global shared memory also helps to mitigate the failure of
            memory-consuming or unpredicted queries.</p>
        </body>
      </topic>
      <topic id="topic833sp" xml:lang="en">
        <title>Query Operator Memory</title>
        <body>
          <p>Most query operators are non-memory-intensive; that is, during processing, Greenplum
            Database can hold their data in allocated memory. When memory-intensive query operators
            such as join and sort process more data than can be held in memory, data is spilled to
            disk.</p>
          <p>The <codeph><xref
                href="../ref_guide/config_params/guc-list.xml#gp_resgroup_memory_policy"
                type="topic"/></codeph> server configuration parameter governs the memory allocation
            and distribution algorithm for all query operators. Greenplum Database supports
              <codeph>eager-free</codeph> (the default) and <codeph>auto</codeph> memory policies
            for resource groups. When you specify the <codeph>auto</codeph> policy, Greenplum
            Database uses resource group memory limits to distribute memory across query operators,
            allocating a fixed size of memory to non-memory-intensive operators and the rest to
            memory-intensive operators. When the <codeph>eager_free</codeph> policy is in place,
            Greenplum Database distributes memory among operators more optimally by re-allocating
            memory released by operators that have completed their processing to operators in a
            later query stage.</p>
          <p><codeph>MEMORY_SPILL_RATIO</codeph> identifies the memory usage threshold for
            memory-intensive operators in a transaction. When this threshold is reached, a
            transaction spills to disk. Greenplum Database uses the
              <codeph>MEMORY_SPILL_RATIO</codeph> to determine the initial memory to allocate to a
            transaction.</p>
          <p>You can specify an integer percentage value from 0 to 100 inclusive for
            <codeph>MEMORY_SPILL_RATIO</codeph>. The default <codeph>MEMORY_SPILL_RATIO</codeph>
           is 0.</p>
          <p>When <codeph>MEMORY_SPILL_RATIO</codeph> is 0, Greenplum Database uses the
            <xref href="../ref_guide/config_params/guc-list.xml#statement_mem" format="dita"><codeph>statement_mem</codeph></xref>
            server configuration parameter value to control initial query operator memory.</p>
          <note>When you set <codeph>MEMORY_LIMIT</codeph> to 0,
            <codeph>MEMORY_SPILL_RATIO</codeph> must also be set to 0.</note>
          <p>You can selectively set the <codeph>MEMORY_SPILL_RATIO</codeph> on a per-query basis
            at the session level with the
            <codeph><xref href="../ref_guide/config_params/guc-list.xml#memory_spill_ratio"
                type="topic"/></codeph> server configuration parameter.</p>
          <section id="topic833low" xml:lang="en">
            <title>memory_spill_ratio and Low Memory Queries </title>
            <p>A low <codeph>statement_mem</codeph> setting (for example, in the 10MB range)
              has been shown to increase the performance of queries with low memory requirements.
              Use the <codeph>memory_spill_ratio</codeph> and <codeph>statement_mem</codeph> server
              configuration parameters to override the setting on a per-query basis. For example:
              <codeblock>SET memory_spill_ratio=0;
SET statement_mem='10 MB';</codeblock></p>
          </section>
        </body>
      </topic>
    </topic>
    <topic id="topic833fvs" xml:lang="en">
      <title>About Using Reserved Resource Group Memory vs. Using Resource Group Global Shared Memory</title>
      <body>
        <p>When you do not reserve memory for a resource group (<codeph>MEMORY_LIMIT</codeph>
          and <codeph>MEMORY_SPILL_RATIO</codeph> are set to 0):</p><ul>
          <li>It increases the size of the resource group global shared memory pool.</li>
          <li>The resource group functions similarly to a resource queue, using the
            <xref href="../ref_guide/config_params/guc-list.xml#statement_mem" format="dita"><codeph>statement_mem</codeph></xref>
            server configuration parameter value to control initial query operator memory.</li>
          <li>Any query submitted in the resource group competes for resource group global
            shared memory on a first-come, first-served basis with queries running in other
            groups.</li>
          <li>There is no guarantee that Greenplum Database will be able to allocate memory
            for a query running in the resource group. The risk of a query in the group
            encountering an out of memory (OOM) condition increases when there are many
            concurrent queries consuming memory from the resource group global shared
            memory pool at the same time.</li>
        </ul>
        <p>To reduce the risk of OOM for a query running in an important resource group,
          consider reserving some fixed memory for the group. While reserving fixed memory
          for a group reduces the size of the resource group global shared memory pool,
          this may be a fair tradeoff to reduce the risk of encountering an OOM condition
          in a query running in a critical resource group.</p>
      </body>
    </topic>
    <topic id="topic833cons" xml:lang="en">
      <title>Other Memory Considerations</title>
      <body>
        <p>Resource groups for roles track all Greenplum Database memory allocated via the
            <codeph>palloc()</codeph> function. Memory that you allocate using the Linux
            <codeph>malloc()</codeph> function is not managed by these resource groups. To ensure
          that resource groups for roles are accurately tracking memory usage, avoid using
            <codeph>malloc()</codeph> to allocate large amounts of memory in custom Greenplum
          Database user-defined functions.</p>
      </body>
    </topic>
  </topic>
  <topic id="topic999" otherprops="pivotal" xml:lang="en">
    <title>Using Greenplum Command Center to Manage Resource Groups</title>
    <body>
      <p>Using Pivotal Greenplum Command Center, an administrator can create and manage resource
        groups, change roles' resource groups, and create workload management rules. </p>
      <p>Workload management assignment rules assign transactions to different resource groups based
        on user-defined criteria. If no assignment rule is matched, Greenplum Database assigns the
        transaction to the role's default resource group.</p>
      <p>Refer to the <xref href="http://gpcc.docs.pivotal.io/latest" format="html" scope="external"
          >Greenplum Command Center documentation</xref> for more information about creating and
        managing resource groups and workload management rules. </p>
    </body>
  </topic>
  <topic id="topic71717999" xml:lang="en">
    <title>Configuring and Using Resource Groups</title>
    <body>
      <note type="important">Significant Greenplum Database performance degradation has been
        observed when enabling resource group-based workload management on RedHat 6.x and CentOS 6.x
        systems. This issue is caused by a Linux cgroup kernel bug. This kernel bug has been fixed
        in CentOS 7.x and Red Hat 7.x systems. <p>If you use RedHat 6 and the performance with
          resource groups is acceptable for your use case, upgrade your kernel to version 2.6.32-696
          or higher to benefit from other fixes to the cgroups implementation. </p></note>
      <section id="topic833" xml:lang="en">
        <title>Prerequisite</title>
        <p>Greenplum Database resource groups use Linux Control Groups (cgroups) to manage CPU
          resources. Greenplum Database also uses cgroups to manage memory for resource groups for
          external components. With cgroups, Greenplum isolates the CPU and external component
          memory usage of your Greenplum processes from other processes on the node. This allows
          Greenplum to support CPU and external component memory usage restrictions on a
          per-resource-group basis.</p>
        <p>For detailed information about cgroups, refer to the Control Groups documentation for
          your Linux distribution.</p>
        <p>Complete the following tasks on each node in your Greenplum Database cluster to set up
          cgroups for use with resource groups:</p>
        <ol>
          <li>If you are running the SuSE 11+ operating system on your Greenplum Database cluster
            nodes, you must enable swap accounting on each node and restart your Greenplum Database
            cluster. The <codeph>swapaccount</codeph> kernel boot parameter governs the swap
            accounting setting on SuSE 11+ systems. After setting this boot parameter, you must
            reboot your systems. For details, refer to the <xref
              href="https://www.suse.com/releasenotes/x86_64/SUSE-SLES/11-SP2/#fate-310471"
              format="html" scope="external">Cgroup Swap Control</xref> discussion in the SuSE 11
            release notes. You must be the superuser or have <codeph>sudo</codeph> access to
            configure kernel boot parameters and reboot systems. </li>
          <li>Create the Greenplum Database cgroups configuration file
              <codeph>/etc/cgconfig.d/gpdb.conf</codeph>. You must be the superuser or have
              <codeph>sudo</codeph> access to create this file:
            <codeblock>sudo vi /etc/cgconfig.d/gpdb.conf</codeblock>
          </li>
          <li>Add the following configuration information to
              <codeph>/etc/cgconfig.d/gpdb.conf</codeph>: <codeblock>group gpdb {
     perm {
         task {
             uid = gpadmin;
             gid = gpadmin;
         }
         admin {
             uid = gpadmin;
             gid = gpadmin;
         }
     }
     cpu {
     }
     cpuacct {
     }
     cpuset {
     }
     memory {
     }
} </codeblock>
            <p>This content configures CPU, CPU accounting, CPU core set, and memory control groups
              managed by the <codeph>gpadmin</codeph> user. Greenplum Database uses the memory
              control group only for those resource groups created with the <codeph>cgroup</codeph>
              <codeph>MEMORY_AUDITOR</codeph>.</p>
          </li>
          <li>If not already installed and running, install the Control Groups operating system
            package and start the cgroups service on each Greenplum Database node. The commands that
            you run to perform these tasks will differ based on the operating system installed on
            the node. You must be the superuser or have <codeph>sudo</codeph> access to run these
            commands: <ul>
              <li> Redhat/CentOS 7.x systems:
                <codeblock>sudo yum install libcgroup-tools
sudo cgconfigparser -l /etc/cgconfig.d/gpdb.conf </codeblock>
              </li>
              <li> Redhat/CentOS 6.x systems:
                <codeblock>sudo yum install libcgroup
sudo service cgconfig start </codeblock>
              </li>
              <li> SuSE 11+ systems:
                <codeblock>sudo zypper install libcgroup-tools
sudo cgconfigparser -l /etc/cgconfig.d/gpdb.conf </codeblock>
              </li>
            </ul>
          </li>
          <li>Identify the <codeph>cgroup</codeph> directory mount point for the node:
              <codeblock>grep cgroup /proc/mounts</codeblock><p>The first line of output identifies
              the <codeph>cgroup</codeph> mount point.</p>
          </li>
          <li>Verify that you set up the Greenplum Database cgroups configuration correctly by
            running the following commands. Replace &lt;cgroup_mount_point&gt; with the mount point
            that you identified in the previous step: <codeblock>ls -l &lt;cgroup_mount_point&gt;/cpu/gpdb
ls -l &lt;cgroup_mount_point&gt;/cpuacct/gpdb
ls -l &lt;cgroup_mount_point&gt;/cpuset/gpdb
ls -l &lt;cgroup_mount_point&gt;/memory/gpdb</codeblock>
            <p>If these directories exist and are owned by <codeph>gpadmin:gpadmin</codeph>, you
              have successfully configured cgroups for Greenplum Database CPU resource
              management.</p>
          </li>
          <li>To automatically recreate Greenplum Database required cgroup hierarchies and
            parameters when your system is restarted, configure your system to enable the Linux
            cgroup service daemon <codeph>cgconfig.service</codeph> (Redhat/CentOS 7.x and SuSE 11+)
            or <codeph>cgconfig</codeph> (Redhat/CentOS 6.x) at node start-up. For example,
            configure one of the following cgroup service commands in your preferred service
            auto-start tool: <ul>
              <li>Redhat/CentOS 7.x and SuSE11+ systems: <codeblock>sudo systemctl enable cgconfig.service</codeblock>
                <p>To start the service immediately (without having to reboot)
                  enter:<codeblock>sudo systemctl start cgconfig.service</codeblock></p></li>
              <li>Redhat/CentOS 6.x systems: <codeblock>sudo chkconfig cgconfig on</codeblock></li>
            </ul>
            <p>You may choose a different method to recreate the Greenplum Database resource group
              cgroup hierarchies.</p>
          </li>
        </ol>
      </section>
      <section id="topic8339191" xml:lang="en">
        <title>Procedure</title>
        <p>To use resource groups in your Greenplum Database cluster, you:</p>
        <ol>
          <li><xref href="#topic8" type="topic" format="dita">Enable resource groups for your
              Greenplum Database cluster</xref>.</li>
          <li><xref href="#topic10" type="topic" format="dita">Create resource groups</xref>.</li>
          <li><xref href="#topic17" type="topic" format="dita">Assign the resource groups to one or
              more roles</xref>.</li>
          <li><xref href="#topic22" type="topic" format="dita">Use resource management system views
              to monitor and manage the resource groups</xref>.</li>
        </ol>
      </section>
    </body>
  </topic>
  <topic id="topic8" xml:lang="en">
    <title id="iz153124">Enabling Resource Groups</title>
    <body>
      <p>When you install Greenplum Database, resource queues are enabled by default. To use
        resource groups instead of resource queues, you must set the <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_manager" type="topic"
          /></codeph> server configuration parameter.</p>
      <ol id="ol_ec5_4dy_wq">
        <li>Set the <codeph>gp_resource_manager</codeph> server configuration parameter to the value
            <codeph>"group"</codeph>:
          <codeblock>gpconfig -s gp_resource_manager
gpconfig -c gp_resource_manager -v "group"
</codeblock>
        </li>
        <li>Restart Greenplum Database: <codeblock>gpstop
gpstart
</codeblock>
        </li>
      </ol>
      <p>Once enabled, any transaction submitted by a role is directed to the resource group
        assigned to the role, and is governed by that resource group's concurrency, memory, and CPU
        limits. Similarly, CPU and memory usage by an external component is governed by the CPU and
        memory limits configured for the resource group assigned to the component.</p>
      <p>Greenplum Database creates two default resource groups for roles named
          <codeph>admin_group</codeph> and <codeph>default_group</codeph>. When you enable resources
        groups, any role that was not explicitly assigned a resource group is assigned the default
        group for the role's capability. <codeph>SUPERUSER</codeph> roles are assigned the
          <codeph>admin_group</codeph>, non-admin roles are assigned the group named
          <codeph>default_group</codeph>.</p>
      <p>The default resource groups <codeph>admin_group</codeph> and <codeph>default_group</codeph>
        are created with the following resource limits:</p>
      <table id="default_resgroup_limits">
        <tgroup cols="3">
          <colspec colnum="1" colname="col1" colwidth="1*"/>
          <colspec colnum="2" colname="col2" colwidth="1*"/>
          <colspec colnum="3" colname="col3" colwidth="1*"/>
          <thead>
            <row>
              <entry colname="col1">Limit Type</entry>
              <entry colname="col2">admin_group</entry>
              <entry colname="col3">default_group</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry colname="col1">CONCURRENCY</entry>
              <entry colname="col2">10</entry>
              <entry colname="col3">20</entry>
            </row>
            <row>
              <entry colname="col1">CPU_RATE_LIMIT</entry>
              <entry colname="col2">10</entry>
              <entry colname="col3">30</entry>
            </row>
            <row>
              <entry colname="col1">CPUSET</entry>
              <entry colname="col2">-1</entry>
              <entry colname="col3">-1</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_LIMIT</entry>
              <entry colname="col2">10</entry>
              <entry colname="col3">0</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SHARED_QUOTA</entry>
              <entry colname="col2">80</entry>
              <entry colname="col3">80</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SPILL_RATIO</entry>
              <entry colname="col2">0</entry>
              <entry colname="col3">0</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_AUDITOR</entry>
              <entry colname="col2">vmtracker</entry>
              <entry colname="col3">vmtracker</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <p>Keep in mind that the <codeph>CPU_RATE_LIMIT</codeph> and <codeph>MEMORY_LIMIT</codeph>
        values for the default resource groups <codeph>admin_group</codeph> and
          <codeph>default_group</codeph> contribute to the total percentages on a segment host. You
        may find that you need to adjust these limits for <codeph>admin_group</codeph> and/or
          <codeph>default_group</codeph> as you create and add new resource groups to your Greenplum
        Database deployment.</p>
    </body>
  </topic>
  <topic id="topic10" xml:lang="en">
    <title id="iz139857">Creating Resource Groups</title>
    <body>
      <p><i>When you create a resource group for a role</i>, you provide a name and a CPU resource
        allocation mode. You can optionally provide a concurrent transaction limit and 
        memory limit, shared quota, and spill ratio values. Use the <codeph><xref
            href="../ref_guide/sql_commands/CREATE_RESOURCE_GROUP.xml#topic1" type="topic"
            format="dita"/></codeph> command to create a new resource group. </p>
      <p id="iz152723">When you create a resource group for a role, you must provide a
         <codeph>CPU_RATE_LIMIT</codeph> or <codeph>CPUSET</codeph> limit value. These
         limits identify the percentage of Greenplum Database CPU resources to allocate
         to this resource group. You may specify a <codeph>MEMORY_LIMIT</codeph> to
         reserve a fixed amount of memory for the resource group. If you specify
         a <codeph>MEMORY_LIMIT</codeph> of 0, Greenplum Database uses global shared memory
         to fulfill all memory requirements for the resource group.</p>
      <p>For example, to create
        a resource group named <i>rgroup1</i> with a CPU limit of 20, a memory limit of 25,
        and a memory spill ratio of 20:</p>
      <p>
        <codeblock>=# CREATE RESOURCE GROUP <i>rgroup1</i> WITH (CPU_RATE_LIMIT=20, MEMORY_LIMIT=25, MEMORY_SPILL_RATIO=20);
</codeblock>
      </p>
      <p>The CPU limit of 20 is shared by every role to which <codeph>rgroup1</codeph> is assigned.
        Similarly, the memory limit of 25 is shared by every role to which <codeph>rgroup1</codeph>
        is assigned. <codeph>rgroup1</codeph> utilizes the default <codeph>MEMORY_AUDITOR</codeph>
        <codeph>vmtracker</codeph> and the default <codeph>CONCURRENCY</codeph> setting of 20.</p>
      <p id="iz1527231"><i>When you create a resource group for an external component</i>, you must
        provide <codeph>CPU_RATE_LIMIT</codeph> or <codeph>CPUSET</codeph> and
          <codeph>MEMORY_LIMIT</codeph> limit values. You must also provide the
          <codeph>MEMORY_AUDITOR</codeph> and explicitly set <codeph>CONCURRENCY</codeph> to zero
        (0). For example, to create a resource group named <i>rgroup_extcomp</i> for which you
        reserve CPU core 1 and assign a memory limit of 15:</p>
      <p>
        <codeblock>=# CREATE RESOURCE GROUP <i>rgroup_extcomp</i> WITH (MEMORY_AUDITOR=cgroup, CONCURRENCY=0,
     CPUSET='1', MEMORY_LIMIT=15);
</codeblock>
      </p>
      <p>The <codeph><xref href="../ref_guide/sql_commands/ALTER_RESOURCE_GROUP.xml#topic1"
            type="topic" format="dita"/></codeph> command updates the limits of a resource group. To
        change the limits of a resource group, specify the new values that you want for the group.
        For example:</p>
      <p>
        <codeblock>=# ALTER RESOURCE GROUP <i>rg_role_light</i> SET CONCURRENCY 7;
=# ALTER RESOURCE GROUP <i>exec</i> SET MEMORY_SPILL_RATIO 25;
=# ALTER RESOURCE GROUP <i>rgroup1</i> SET CPUSET '2,4';
</codeblock>
      </p>
      <note>You cannot set or alter the <codeph>CONCURRENCY</codeph> value for the
          <codeph>admin_group</codeph> to zero (0).</note>
      <p>The <codeph><xref href="../ref_guide/sql_commands/DROP_RESOURCE_GROUP.xml#topic1"
            type="topic" format="dita"/></codeph> command drops a resource group. To drop a resource
        group for a role, the group cannot be assigned to any role, nor can there be any
        transactions active or waiting in the resource group. Dropping a resource group for an
        external component in which there are running instances kills the running instances.</p>
      <p>To drop a resource group:</p>
      <p>
        <codeblock>=# DROP RESOURCE GROUP <i>exec</i>; </codeblock>
      </p>
    </body>
  </topic>
  <topic id="topic_jlz_hzg_pkb">
    <title>Configuring Automatic Query Termination Based on Memory Usage</title>
    <body>
      <p>When resource groups have a global shared memory pool, the server configuration parameter
            <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#runaway_detector_activation_percent"
            type="section"/></codeph> sets the percent of utilized global shared memory that
        triggers the termination of queries that are managed by resource groups that are configured
        to use the <codeph>vmtracker</codeph> memory auditor, such as <codeph>admin_group</codeph>
        and <codeph>default_group</codeph>. </p>
      <p>Resource groups have a global shared memory pool when the sum of the
          <codeph>MEMORY_LIMIT</codeph> attribute values configured for all resource groups is less
        than 100. For example, if you have 3 resource groups configured with
          <codeph>MEMORY_LIMIT</codeph> values of 10 , 20, and 30, then global shared memory is 40%
        = 100% - (10% + 20% + 30%). </p>
      <p>For information about global shared memory, see <xref href="#topic833glob"/>.</p>
    </body>
  </topic>
  <topic id="topic17" xml:lang="en">
    <title id="iz172210">Assigning a Resource Group to a Role</title>
    <body>
      <p id="iz172211">When you create a resource group with the default
          <codeph>MEMORY_AUDITOR</codeph>
        <codeph>vmtracker</codeph>, the group is available for assignment to one or more roles
        (users). You assign a resource group to a database role using the <codeph>RESOURCE
          GROUP</codeph> clause of the <codeph><xref
            href="../ref_guide/sql_commands/CREATE_ROLE.xml#topic1" type="topic" format="dita"
          /></codeph> or <codeph><xref href="../ref_guide/sql_commands/ALTER_ROLE.xml#topic1"
            type="topic" format="dita"/></codeph> commands. If you do not specify a resource group
        for a role, the role is assigned the default group for the role's capability.
          <codeph>SUPERUSER</codeph> roles are assigned the <codeph>admin_group</codeph>, non-admin
        roles are assigned the group named <codeph>default_group</codeph>.</p>
      <p>Use the <codeph>ALTER ROLE</codeph> or <codeph>CREATE ROLE</codeph> commands to assign a
        resource group to a role. For example:</p>
      <p>
        <codeblock>=# ALTER ROLE <i>bill</i> RESOURCE GROUP <i>rg_light</i>;
=# CREATE ROLE <i>mary</i> RESOURCE GROUP <i>exec</i>;
</codeblock>
      </p>
      <p>You can assign a resource group to one or more roles. If you have defined a role hierarchy,
        assigning a resource group to a parent role does not propagate down to the members of that
        role group.</p>
      <note>You cannot assign a resource group that you create for an external component to a
        role.</note>
      <p>If you wish to remove a resource group assignment from a role and assign the role the
        default group, change the role's group name assignment to <codeph>NONE</codeph>. For
        example:</p>
      <p>
        <codeblock>=# ALTER ROLE <i>mary</i> RESOURCE GROUP NONE;
</codeblock>
      </p>
    </body>
  </topic>
  <topic id="topic22" xml:lang="en">
    <title id="iz152239">Monitoring Resource Group Status</title>
    <body>
      <p>Monitoring the status of your resource groups and queries may involve the following
        tasks:</p>
      <ul>
        <li id="iz153669">
          <xref href="#topic221" type="topic" format="dita"/>
        </li>
        <li id="iz153670">
          <xref href="#topic23" type="topic" format="dita"/>
        </li>
        <li id="iz153671">
          <xref href="#topic25" type="topic" format="dita"/>
        </li>
        <li id="iz15367125">
          <xref href="#topic252525" type="topic" format="dita"/>
        </li>
        <li id="iz153679">
          <xref href="#topic27" type="topic" format="dita"/>
        </li>
      </ul>
    </body>
    <topic id="topic221" xml:lang="en">
      <title id="iz152239">Viewing Resource Group Limits</title>
      <body>
        <p>The <codeph><xref href="../ref_guide/system_catalogs/gp_resgroup_config.xml" type="topic"
              format="dita"/></codeph>
          <codeph>gp_toolkit</codeph> system view displays the current limits for a
          resource group. To view the limits of all resource groups:</p>
        <p>
          <codeblock>=# SELECT * FROM gp_toolkit.gp_resgroup_config;
</codeblock>
        </p>
      </body>
    </topic>
    <topic id="topic23" xml:lang="en">
      <title id="iz152239">Viewing Resource Group Query Status and CPU/Memory Usage</title>
      <body>
        <p>The <codeph><xref href="../ref_guide/gp_toolkit.xml#topic31x" type="topic" format="dita"
            /></codeph>
          <codeph>gp_toolkit</codeph> system view enables you to view the status and activity of a
          resource group. The view displays the number of running and queued transactions. It also
          displays the real-time CPU and memory usage of the resource group. To view this
          information:</p>
        <p>
          <codeblock>=# SELECT * FROM gp_toolkit.gp_resgroup_status;
</codeblock>
        </p>
      </body>
      <topic id="topic23a" xml:lang="en">
        <title id="iz152239">Viewing Resource Group CPU/Memory Usage Per Host</title>
        <body>
          <p>The <codeph><xref href="../ref_guide/gp_toolkit.xml#perhost" type="topic" format="dita"
            /></codeph>
          <codeph>gp_toolkit</codeph> system view enables you to view the real-time CPU
            and memory usage of a resource group on a per-host basis. To view this
            information:</p>
        <p>
          <codeblock>=# SELECT * FROM gp_toolkit.gp_resgroup_status_per_host;
</codeblock>
        </p>
        </body>
      </topic>
      <topic id="topic23b" xml:lang="en">
        <title id="iz152239">Viewing Resource Group CPU/Memory Usage Per Segment</title>
        <body>
          <p>The <codeph><xref href="../ref_guide/gp_toolkit.xml#perseg" type="topic" format="dita"
            /></codeph>
          <codeph>gp_toolkit</codeph> system view enables you to view the real-time CPU
            and memory usage of a resource group on a per-segment, per-host basis. To
            view this information:</p>
        <p>
          <codeblock>=# SELECT * FROM gp_toolkit.gp_resgroup_status_per_segment;
</codeblock>
        </p>
        </body>
      </topic>
    </topic>
    <topic id="topic25" xml:lang="en">
      <title id="iz152239">Viewing the Resource Group Assigned to a Role</title>
      <body>
        <p>To view the resource group-to-role assignments, perform the following query on the
              <codeph><xref href="../ref_guide/system_catalogs/pg_roles.xml" type="topic"
              format="dita"/></codeph> and <codeph><xref
              href="../ref_guide/system_catalogs/pg_resgroup.xml" type="topic" format="dita"
            /></codeph> system catalog tables:</p>
        <p>
          <codeblock>=# SELECT rolname, rsgname FROM pg_roles, pg_resgroup
     WHERE pg_roles.rolresgroup=pg_resgroup.oid;
</codeblock>
        </p>
      </body>
    </topic>
    <topic id="topic252525" xml:lang="en">
      <title id="iz15223925">Viewing a Resource Group's Running and Pending Queries</title>
      <body>
        <p>To view a resource group's running queries, pending queries, and how long the pending
          queries have been queued, examine the <codeph><xref
              href="../ref_guide/system_catalogs/pg_stat_activity.xml" type="topic" format="dita"
            /></codeph> system catalog table:</p>
        <p>
          <codeblock>=# SELECT query, waiting, rsgname, rsgqueueduration 
     FROM pg_stat_activity;
</codeblock>
        </p>
        <p>
          <codeph>pg_stat_activity</codeph> displays information about the user/role that initiated
          a query. A query that uses an external component such as PL/Container is composed of two
          parts: the query operator that runs in Greenplum Database and the UDF that runs in a
          PL/Container instance. Greenplum Database processes the query operators under the resource
          group assigned to the role that initiated the query. A UDF running in a PL/Container
          instance runs under the resource group assigned to the PL/Container runtime. The latter is
          not represented in the <codeph>pg_stat_activity</codeph> view; Greenplum Database does not
          have any insight into how external components such as PL/Container manage memory in
          running instances. </p>
      </body>
    </topic>
    <topic id="topic27" xml:lang="en">
      <title id="iz153732">Cancelling a Running or Queued Transaction in a Resource Group</title>
      <body>
        <p>There may be cases when you want to cancel a running or queued transaction in a resource
          group. For example, you may want to remove a query that is waiting in the resource group
          queue but has not yet been executed. Or, you may want to stop a running query that is
          taking too long to execute, or one that is sitting idle in a transaction and taking up
          resource group transaction slots that are needed by other users.</p>
        <p>By default, transactions can remain queued in a resource group indefinitely.
          If you want Greenplum Database to cancel a queued transaction after a
          specific amount of time, set the server configuration parameter <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_group_queuing_timeout" type="section"
            scope="peer">gp_resource_group_queuing_timeout</xref></codeph>. When this
          parameter is set to a value (milliseconds) greater than 0, Greenplum cancels
          any queued transaction when it has waited longer than the configured timeout.</p>
        <p>To manually cancel a running or queued transaction, you must first determine the process id (pid)
          associated with the transaction. Once you have obtained the process id, you can invoke
            <codeph>pg_cancel_backend()</codeph> to end that process, as shown below.</p>
        <p>For example, to view the process information associated with all statements currently
          active or waiting in all resource groups, run the following query. If the query returns no
          results, then there are no running or queued transactions in any resource group.</p>
        <p>
          <codeblock>=# SELECT rolname, g.rsgname, pid, waiting, state, query, datname 
     FROM pg_roles, gp_toolkit.gp_resgroup_status g, pg_stat_activity 
     WHERE pg_roles.rolresgroup=g.groupid
        AND pg_stat_activity.usename=pg_roles.rolname;
</codeblock>
        </p>
        <p>Sample partial query output:</p>
        <codeblock> rolname | rsgname  | pid     | waiting | state  |          query           | datname 
---------+----------+---------+---------+--------+------------------------ -+---------
  sammy  | rg_light |  31861  |    f    | idle   | SELECT * FROM mytesttbl; | testdb
  billy  | rg_light |  31905  |    t    | active | SELECT * FROM topten;    | testdb</codeblock>
        <p>Use this output to identify the process id (<codeph>pid</codeph>) of the transaction you
          want to cancel, and then cancel the process. For example, to cancel the pending query
          identified in the sample output above:</p>
        <p>
          <codeblock>=# SELECT pg_cancel_backend(31905);</codeblock>
        </p>
        <p>You can provide an optional message in a second argument to
            <codeph>pg_cancel_backend()</codeph> to indicate to the user why the process was
          cancelled.</p>
        <note type="note">
          <p>Do not use an operating system <codeph>KILL</codeph> command to cancel any Greenplum
            Database process.</p>
        </note>
      </body>
    </topic>
  </topic>
  <topic id="moverg" xml:lang="en">
    <title>Moving a Query to a Different Resource Group</title>
    <body>
      <p>A user with Greenplum Database superuser privileges can run the
        <codeph>gp_toolkit.pg_resgroup_move_query()</codeph> function to move a
        running query from one resource group to another, without stopping the
        query. Use this function to expedite a long-running query by moving it to
        a resource group with a higher resource allotment or availability.</p>
      <note>You can move only an active or running query to a new resource group.
        You cannot move a queued or pending query that is in an idle state due to
        concurrency or memory limits.</note>
      <p><codeph>pg_resgroup_move_query()</codeph> requires the process id
        (pid) of the running query, as well as the name of the resource group
        to which you want to move the query. The signature of the function follows:</p>
      <codeblock>pg_resgroup_move_query( pid int4, group_name text );</codeblock>
      <p>You can obtain the pid of a running query from the
        <codeph>pg_stat_activity</codeph> system view as described in
        <xref href="#topic27" type="topic" format="dita"/>. Use the
        <codeph>gp_toolkit.gp_resgroup_status</codeph> view to list the name, id,
        and status of each resource group.</p>
      <p>When you invoke <codeph>pg_resgroup_move_query()</codeph>, the query is
        subject to the limits configured for the destination resource group:</p>
      <ul>
        <li>If the group has already reached its concurrent task limit,
          Greenplum Database queues the query until a slot opens.</li>
        <li>If the destination resource group does not have enough memory
          available to service the query's current memory requirements,
          Greenplum Database returns the error: 
          <codeph>group &lt;group_name> doesn't have enough memory ...</codeph>.
          In this situation, you may choose to increase the group shared memory
          allotted to the destination resource group, or perhaps wait a period
          of time for running queries to complete and then invoke the function
          again.</li>
      </ul>
      <p>After Greenplum moves the query, there is no way to guarantee that a
        query currently running in the destination resource group does not
        exceed the group memory quota. In this situation, one or more running
        queries in the destination group may fail, including the moved query.
        Reserve enough resource group global shared memory to minimize the
        potential for this scenario to occur.</p>
      <p><codeph>pg_resgroup_move_query()</codeph> moves only the specified
        query to the destination resource group. Greenplum Database assigns
        subsequent queries that you submit in the session to the original
        resource group.</p>
    </body>
  </topic>
  <topic id="topic777999" xml:lang="en">
    <title>Resource Group Frequently Asked Questions</title>
    <body>
      <section id="topic791" xml:lang="en">
        <title>CPU</title>
        <ul>
          <li><b>Why is CPU usage lower than the <codeph>CPU_RATE_LIMIT</codeph> configured for the
              resource group?</b>
            <p>You may run into this situation when a low number of queries and slices are running
              in the resource group, and these processes are not utilizing all of the cores on the
              system.</p></li>
          <li><b>Why is CPU usage for the resource group higher than the configured
                <codeph>CPU_RATE_LIMIT</codeph>?</b>
            <p>This situation can occur in the following circumstances:<ul>
                <li>A resource group may utilize more CPU than its <codeph>CPU_RATE_LIMIT</codeph>
                  when other resource groups are idle. In this situation, Greenplum Database
                  allocates the CPU resource of an idle resource group to a busier one. This
                  resource group feature is called CPU burst.</li>
                <li>The operating system CPU scheduler may cause CPU usage to spike, then drop down.
                  If you believe this might be occurring, calculate the average CPU usage within a
                  given period of time (for example, 5 seconds) and use that average to determine if
                  CPU usage is higher than the configured limit.</li>
              </ul></p></li>
        </ul>
      </section>
      <section id="topic795" xml:lang="en">
        <title>Memory</title>
        <ul>
          <li><b>Why did my query return an "out of memory" error?</b>
            <p>A transaction submitted in a resource group fails and exits when memory usage exceeds
              its fixed memory allotment, no available resource group shared memory exists, and the
              transaction requests more memory.</p></li>
          <li><b>Why did my query return a "memory limit reached" error?</b>
            <p>Greenplum Database automatically adjusts transaction and group memory to the new
              settings when you use <codeph>ALTER RESOURCE GROUP</codeph> to change a resource
              group's memory and/or concurrency limits. An "out of memory" error may occur if you
              recently altered resource group attributes and there is no longer a sufficient amount
              of memory available for a currently running query.</p></li>
          <li><b>Why does the actual memory usage of my resource group exceed the amount configured
              for the group?</b>
            <p>The actual memory usage of a resource group may exceed the configured amount when one
              or more queries running in the group is allocated memory from the global shared memory
              pool. (If no global shared memory is available, queries fail and do not impact the
              memory resources of other resource groups.)</p><p>When global shared memory is
              available, memory usage may also exceed the configured amount when a transaction
              spills to disk. Greenplum Database statements continue to request memory when they
              start to spill to disk because:<ul>
                <li>Spilling to disk requires extra memory to work.</li>
                <li>Other operators may continue to request memory.</li>
              </ul> Memory usage grows in spill situations; when global shared memory is available,
              the resource group may eventually use up to 200-300% of its configured group memory
              limit.</p></li>
        </ul>
      </section>
      <section id="topic797" xml:lang="en">
        <title>Concurrency</title>
        <ul>
          <li><b>Why is the number of running transactions lower than the
                <codeph>CONCURRENCY</codeph> limit configured for the resource group?</b>
            <p>Greenplum Database considers memory availability before running a transaction, and
              will queue the transaction if there is not enough memory available to serve it. If you
              use <codeph>ALTER RESOURCE GROUP</codeph> to increase the <codeph>CONCURRENCY</codeph>
              limit for a resource group but do not also adjust memory limits, currently running
              transactions may be consuming all allotted memory resources for the group. When in
              this state, Greenplum Database queues subsequent transactions in the resource
              group.</p></li>
          <li><b>Why is the number of running transactions in the resource group higher than the
              configured <codeph>CONCURRENCY</codeph> limit?</b>
            <p>The resource group may be running <codeph>SET</codeph> and <codeph>SHOW</codeph>
              commands, which bypass resource group transaction checks.</p></li>
        </ul>
      </section>
    </body>
  </topic>
</topic>