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 CPU limit for a resource group identifies the maximum CPU 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="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 id="im16806g">
            <xref href="#topic17" type="topic" format="dita"/>
          </li>
          <li id="im16806h">
            <xref href="#topic22" type="topic" format="dita"/>
          </li>
        </ul>
      </li>
      <li id="im16806c">
        <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> 
    </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">MEMORY_LIMIT</entry>
            <entry colname="col2">The percentage of memory resources available to this resource
              group.</entry>
          </row>
          <row>
            <entry colname="col1">MEMORY_SHARED_QUOTA</entry>
            <entry colname="col2">The percentage of 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">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>
    </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>
    </body>
  </topic>

  <topic id="topic833971717" xml:lang="en">
    <title>CPU Limit</title>
    <body>
      <p>The <codeph><xref
            href="../ref_guide/config_params/guc-list.xml#gp_resource_group_cpu_limit"
            type="section"/></codeph> server configuration parameter identifies the maximum
        percentage of system CPU resources to allocate to resource groups on each Greenplum Database
        segment host. The remaining 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>
      <p>The Greenplum Database node CPU percentage is further divided equally among each segment on
        the Greenplum node. Each resource group reserves a percentage of the segment CPU for
        resource management. You identify this percentage via the <codeph>CPU_RATE_LIMIT</codeph>
        value that you provide when you create the resource group.</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>CPU resource assignment 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>
    </body>
  </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="section"/></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 reserves 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 1, the
        maximum is 100.</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>The memory reserved by a resource group for roles 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 20.</p>

      <p>As mentioned previously, <codeph>CONCURRENCY</codeph> identifies the maximum number of
        concurrently running transactions permitted in a resource group for roles. The fixed memory reserved
        by a resource group is divided into <codeph>CONCURRENCY</codeph> number of transaction
        slots. Each slot is allocated a fixed, equal amount of 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"/>
        </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>
      <note>Greenplum Database tracks, but does not actively monitor, transaction memory usage
        in resource groups. A transaction submitted in a resource group will fail and exit
        when memory usage exceeds its fixed memory allotment, no available resource group
        shared memory exists, and the transaction requests more memory.</note>
      </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 role-based groups.</p>
         <p>When available, Greenplum Database allocates global shared memory
          to a transaction after first allocating slot and resource group shared
          memory. Greenplum Database allocates resource group global shared memory to
          transactions on a first-come first-served basis.</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="section"/></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> The minimum <codeph>MEMORY_SPILL_RATIO</codeph> percentage that you can specify for a
          resource group is 0. The maximum is 100. The default <codeph>MEMORY_SPILL_RATIO</codeph>
          is 20.</p>
        <p>You define the <codeph>MEMORY_SPILL_RATIO</codeph> when you create a resource group for roles. You
          can selectively set this limit 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="section"/></codeph> server configuration parameter.</p>

        <section id="topic833low" xml:lang="en">
          <title>memory_spill_ratio and Low Memory Queries </title>
            <p>A <codeph>memory_spill_ratio</codeph> setting of zero (0) has been shown
              to increase the performance of queries with low memory requirements. Use
              the <codeph>memory_spill_ratio</codeph> server configuration parameter
              to override the setting on a per-query basis. For example:
              <codeblock>SET memory_spill_ratio=0;</codeblock></p>
        </section>
        </body>
      </topic>
      </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="topic71717999" xml:lang="en">
    <title>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, CentOS 6.x,
        and SuSE 11 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, and on SuSE 12 SP2/SP3 systems with kernel
        version 4.4.73-5.1 or newer. <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><p>SuSE 11 does not have a
          kernel version that resolves this issue; resource groups are still considered to be an
          experimental feature on this platform. <ph otherprops="pivotal">Resource groups are not
            supported on SuSE 11 for production use.</ph></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 {
     }
     memory {
     }
 } </codeblock>
            <p>This content configures CPU, CPU accounting, 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;/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>
              </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="section"
          /></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">MEMORY_LIMIT</entry>
              <entry colname="col2">10</entry>
              <entry colname="col3">30</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SHARED_QUOTA</entry>
              <entry colname="col2">50</entry>
              <entry colname="col3">50</entry>
            </row>
            <row>
              <entry colname="col1">MEMORY_SPILL_RATIO</entry>
              <entry colname="col2">20</entry>
              <entry colname="col3">20</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, CPU limit, and memory limit. You can
        optionally provide a concurrent transaction limit and memory shared quota and spill ratio.
        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
          <codeph>CPU_RATE_LIMIT</codeph> and <codeph>MEMORY_LIMIT</codeph> limit values. These
        limits identify the percentage of Greenplum Database resources to allocate to this resource
        group. For example, to create a resource group named <i>rgroup1</i> with a CPU limit of 20
        and a memory limit of 25:</p>
      <p>
        <codeblock>=# CREATE RESOURCE GROUP <i>rgroup1</i> WITH (CPU_RATE_LIMIT=20, MEMORY_LIMIT=25);
</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> 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> with a CPU limit of 10
        and a memory limit of 15:</p>
      <p>
        <codeblock>=# CREATE RESOURCE GROUP <i>rgroup_extcomp</i> WITH (MEMORY_AUDITOR=cgroup, CONNCURENCY=0,
     CPU_RATE_LIMIT=10, 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_LIMIT 25;
</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="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 and proposed limits for a
          resource group. The proposed limit differs from the current limit when you alter the limit
          but the new value can not be immediately applied. 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>

    <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 current_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>To 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, procpid, waiting, current_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  | procpid | waiting |     current_query     | datname 
---------+----------+---------+---------+-----------------------+---------
  sammy  | rg_light |  31861  |    f    | &lt;IDLE&gt; in transaction | testdb
  billy  | rg_light |  31905  |    t    | SELECT * FROM topten; | testdb</codeblock>
        <p>Use this output to identify the process id (<codeph>procpid</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="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>
        <p></p>
      </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>