docs - SQL ref page updates for resgroup memory_auditor (#4860)

* docs - sql ref page updates for resgroup memory_auditor

* edits from engineering review

* some of the edits requested by david

* use plural where appropriate

gpdb-doc/dita/ref_guide/sql_commands/ALTER_RESOURCE_GROUP.xml

@@ -19,11 +19,13 @@ MEMORY_SPILL_RATIO <varname>integer</varname></codeblock>
       <title>Description</title>
       <p><codeph>ALTER RESOURCE GROUP</codeph> changes the limits of a resource group. 
         Only a superuser can alter a resource group.</p>
-        <p>You can set or reset the concurrency limit of a resource group to control the maximum
+        <p>You can set or reset the concurrency limit of a resource group that you create for roles to control the maximum
         number of active concurrent statements in that group. You can also reset the memory or CPU
         rate limit of a resource group to control the amount of memory or CPU resources that all
         queries submitted through the group can consume on each segment host.</p>
-        <p>The new resource limit is immediately applied if current resource usage is less than or equal to the new value and there are no running transactions in the resource group. If current resource usage exceeds the new limit value, or there are running transactions in other resource groups holding some of the resource, Greenplum Database will defer the new limit assignment until resource usage is within the range of the new value.</p>
+        <p>When you alter the CPU limit of a resource group, the new limit is immediately applied.</p>
+        <p>When you alter a memory limit of a resource group that you create for roles, the new resource limit is immediately applied if current resource usage is less than or equal to the new value and there are no running transactions in the resource group. If the current resource usage exceeds the new memory limit value, or if there are running transactions in other resource groups that hold some of the resource, then Greenplum Database defers assigning the new limit until resource usage falls within the range of the new value.</p>
+        <p>When you increase the memory limit of a resource group that you create for external components, the new resource limit is phased in as system memory resources become available. If you decrease the memory limit of a resource group that you create for external components, the behavior is component-specific. For example, if you decrease the memory limit of a resource group that you create for a PL/Container runtime, queries in a running container may fail with an out of memory error.</p>
         <p>You can alter one limit type in a single <codeph>ALTER RESOURCE GROUP</codeph> call.</p>
     </section>
     <section id="section4">
@@ -35,13 +37,13 @@ MEMORY_SPILL_RATIO <varname>integer</varname></codeblock>
         </plentry>
         <plentry>
           <pt>CONCURRENCY <varname>integer</varname></pt>
-          <pd>The maximum number of concurrent transactions, including active and idle transactions, that are permitted for this resource group.
+          <pd>The maximum number of concurrent transactions, including active and idle transactions, that are permitted for resource groups that you assign to roles.
             Any transactions submitted after the <codeph>CONCURRENCY</codeph> value limit is
             reached are queued. When a running transaction completes, the earliest queued
             transaction is executed.</pd>
           <pd> The <codeph>CONCURRENCY</codeph> value
             must be an integer in the range [0 .. <codeph>max_connections</codeph>]. The default 
-            <codeph>CONCURRENCY</codeph> value is 20.</pd>
+            <codeph>CONCURRENCY</codeph> value for a resource group that you create for roles is 20.</pd>
             <pd><note>You cannot set the <codeph>CONCURRENCY</codeph> value for the <codeph>admin_group</codeph> to zero (0).</note></pd>
         </plentry>
         <plentry>

gpdb-doc/dita/ref_guide/sql_commands/ALTER_ROLE.xml

@@ -65,7 +65,8 @@ ALTER ROLE <varname>name</varname> [ [WITH] <varname>option</varname> [ ... ] ]<
           more information.</li>
         <li id="av1370583"><b>RESOURCE GROUP</b> — Assigns a resource group to the role. The role
           would then be subject to the concurrent transaction, memory, and CPU limits configured for
-          the resource group. You can assign a single resource group to one or more roles. See
+          the resource group. You can assign a single resource group to one or more roles. You
+          cannot assign a resource group that you create for an external component to a role. See
               <codeph><xref href="./CREATE_RESOURCE_GROUP.xml#topic1" type="topic" format="dita"
             /></codeph> for additional information.  </li>
         <li id="av137061"><b>WITH <varname>option</varname></b> — Changes many of the role
@@ -105,7 +106,8 @@ ALTER ROLE <varname>name</varname> [ [WITH] <varname>option</varname> [ ... ] ]<
             <codeph>NONE</codeph> removes the role's current resource group assignment and assigns a
             default resource group based on the role's capability. <codeph>SUPERUSER</codeph> roles
             are assigned the <codeph>admin_group</codeph> resource group, while the
-              <codeph>default_group</codeph> resource group is assigned to non-admin roles. </pd>
+              <codeph>default_group</codeph> resource group is assigned to non-admin roles.</pd>
+          <pd>You cannot assign a resource group that you create for an external component to a role.</pd>
         </plentry>
         <plentry>
           <pt><varname>queue_name</varname></pt>

gpdb-doc/dita/ref_guide/sql_commands/CREATE_RESOURCE_GROUP.xml

@@ -13,23 +13,29 @@
 MEMORY_LIMIT=<varname>integer</varname>
 [ CONCURRENCY=<varname>integer</varname> ]
 [ MEMORY_SHARED_QUOTA=<varname>integer</varname> ]
-[ MEMORY_SPILL_RATIO=<varname>integer</varname> ]</codeblock>
+[ MEMORY_SPILL_RATIO=<varname>integer</varname> ]
+[ MEMORY_AUDITOR= {vmtracker | cgroup} ]</codeblock>
     </section>
     <section id="section3">
       <title>Description</title>
-      <p>Creates a new resource group for Greenplum Database resource management. A resource
-         group is assigned to one or more roles and identifies concurrent transaction, memory,
-         and CPU limits for the role when resource groups are enabled.</p>
+      <p>Creates a new resource group for Greenplum Database resource management. You can create resource groups to manage resources for roles or 
+        to manage the resources of a Greenplum Database external component such as PL/Container.</p>
+       <p>A resource
+         group that you create to manage a user role identifies concurrent transaction, memory,
+         and CPU limits for the role when resource groups are enabled. You may assign such resource groups to one or more roles.</p>
+      <p>A resource group that you create to manage the resources of a Greenplum Database external component such as PL/Container identifies the memory and CPU limits for the component when resource groups are enabled. These resource groups use cgroups to manage both CPU and memory management. Assignment of resource groups to external components is component-specific. For example, you assign a PL/Container resource group when you configure a PL/Container runtime. You cannot assign a resource group that you create for external components to a role, nor can you assign a resource group that you create for roles to an external component.</p>
       <p>You must have <codeph>SUPERUSER</codeph> privileges to create a resource group. The maximum number of resource groups allowed in your Greenplum Database cluster is 100.</p>
       <p>Greenplum Database pre-defines two default resource groups: <codeph>admin_group</codeph>
          and <codeph>default_group</codeph>. These group names, as well as the group name <codeph>none</codeph>, are reserved.</p>
       <p>
         To set appropriate limits for resource groups, the Greenplum Database administrator must
-        be familiar with the queries typically executed on the system, as well as the users/roles executing those queries.</p>
+        be familiar with the queries typically executed on the system, as well as the users/roles executing those queries and the external components they may be using, such as PL/Containers.</p>
       <p>
-        After creating a resource group, assign the group to one or more roles using the <codeph><xref
+        After creating a resource group for a role, assign the group to one or more roles using the <codeph><xref
             href="ALTER_ROLE.xml#topic1" type="topic" format="dita"/></codeph> or <codeph><xref
             href="./CREATE_ROLE.xml#topic1" type="topic" format="dita"/></codeph> commands.</p>
+      <p>
+        After you create a resource group to manage the CPU and memory resources of an external component, configure the external component to use the resource group. For example, configure the PL/Container runtime <codeph>resource_group_id</codeph>.</p>
     </section>
     <section id="section4">
       <title>Parameters</title>
@@ -42,8 +48,8 @@ MEMORY_LIMIT=<varname>integer</varname>
         </plentry>
         <plentry>
           <pt>CONCURRENCY <varname>integer</varname></pt>
-          <pd>The maximum number of concurrent transactions, including active and idle transactions, that are permitted for this resource group. The <codeph>CONCURRENCY</codeph> value must be an integer in the range [0 .. <codeph>max_connections</codeph>]. The default <codeph>CONCURRENCY</codeph> value is 20.
-            </pd>
+          <pd>The maximum number of concurrent transactions, including active and idle transactions, that are permitted for this resource group. The <codeph>CONCURRENCY</codeph> value must be an integer in the range [0 .. <codeph>max_connections</codeph>]. The default <codeph>CONCURRENCY</codeph> value  for resource groups defined for roles is 20.</pd>
+          <pd>You must set <codeph>CONCURRENCY</codeph> to zero (0) for resource groups that you create for external components.</pd>
           <pd><note>You cannot set the <codeph>CONCURRENCY</codeph> value for the <codeph>admin_group</codeph> to zero (0).</note></pd>
         </plentry>
         <plentry>
@@ -63,6 +69,11 @@ MEMORY_LIMIT=<varname>integer</varname>
           <pt>MEMORY_SPILL_RATIO <varname>integer</varname></pt>
           <pd>The memory usage threshold for memory-intensive operators in a transaction. When the transaction reaches this threshold, it spills to disk. The minimum memory spill ratio percentage you can specify for a resource group is 0. The maximum is 100. The default <codeph>MEMORY_SPILL_RATIO</codeph> value is 20.</pd>
         </plentry>
+        <plentry>
+          <pt>MEMORY_AUDITOR {vmtracker | cgroup}</pt>
+          <pd>The memory auditor for the resource group. Greenplum Database employs virtual memory tracking for role resources and cgroup memory tracking for resources used by external components. The default <codeph>MEMORY_AUDITOR</codeph> is <codeph>vmtracker</codeph>. When you create a resource group with <codeph>vmtracker</codeph> memory auditing, Greenplum Database tracks that resource group's memory internally.</pd>
+          <pd>When you create a resource group specifying the <codeph>cgroup</codeph> <codeph>MEMORY_AUDITOR</codeph>, Greenplum Database defers the accounting of memory used by that resource group to cgroups. <codeph>CONCURRENCY</codeph> must be zero (0) for a resource group that you create for external components such as PL/Container. You cannot assign a resource group that you create for external components to a Greenplum Database role.</pd>
+        </plentry>
       </parml>
     </section>
     <section id="section5"><title>Notes</title>
@@ -75,9 +86,12 @@ MEMORY_LIMIT=<varname>integer</varname>
       <title>Examples</title>
       <p>Create a resource group with CPU and memory limit percentages of 35: </p>
       <codeblock>CREATE RESOURCE GROUP rgroup1 WITH (CPU_RATE_LIMIT=35, MEMORY_LIMIT=35);</codeblock>
-      <p>Create a resource group with a concurrent transaction limit of 30, a memory limit of 15, and a CPU limit of 25:</p>
+      <p>Create a resource group with a concurrent transaction limit of 20, a memory limit of 15, and a CPU limit of 25:</p>
       <codeblock>CREATE RESOURCE GROUP rgroup2 WITH (CONCURRENCY=20, 
   MEMORY_LIMIT=15, CPU_RATE_LIMIT=25);</codeblock>
+      <p>Create a resource group to manage PL/Container resources specifying a memory limit of 10, and a CPU limit of 10:</p>
+      <codeblock>CREATE RESOURCE GROUP plc_run1 WITH (MEMORY_LIMIT=10, CPU_RATE_LIMIT=10,
+  CONCURRENCY=0, MEMORY_AUDITOR=cgroup);</codeblock>
     </section>
     <section id="section7">
       <title>Compatibility</title>

gpdb-doc/dita/ref_guide/sql_commands/CREATE_ROLE.xml

@@ -179,7 +179,7 @@
                         having the <codeph>SUPERUSER</codeph> attribute.</pd>
                     <pd>You can assign the <codeph>default_group</codeph> resource group to any
                         role.</pd>
-                </plentry>
+                    <pd>You cannot assign a resource group that you create for an external component to a role.</pd></plentry>
                 <plentry>
                     <pt>RESOURCE QUEUE <varname>queue_name</varname></pt>
                     <pd>The name of the resource queue to which the new user-level role is to be

gpdb-doc/dita/ref_guide/sql_commands/DROP_RESOURCE_GROUP.xml

@@ -4,9 +4,9 @@
 <topic id="topic1"><title id="dc20941">DROP RESOURCE GROUP</title><body>
     <p id="sql_command_desc">Removes a resource group.</p><section id="section2"><title>Synopsis</title><codeblock id="sql_command_synopsis">DROP RESOURCE GROUP <varname>group_name</varname></codeblock></section><section id="section3"><title>Description</title><p>This command removes a resource group from Greenplum
 Database. Only a superuser
-can drop a resource group.</p><p>To drop a resource group, the group cannot be assigned to any roles,
-nor can it have any statements pending or running in the group.</p><p>You cannot drop the pre-defined <codeph>admin_group</codeph> and <codeph>default_group</codeph> resource groups.</p>
-</section><section id="section4"><title>Parameters</title><parml><plentry><pt><varname>group_name</varname></pt><pd>The name of the resource group to remove.</pd></plentry></parml></section><section id="section5"><title>Notes</title><p>You cannot submit a <codeph>DROP RESOURCE GROUP</codeph> command in an explicit transaction or sub-transaction.</p><p>Use <codeph><xref href="ALTER_ROLE.xml#topic1" type="topic" format="dita"/></codeph> to remove the resource group assigned
+can drop a resource group.</p><p>To drop a role resource group, the group cannot be assigned to any roles,
+nor can it have any statements pending or running in the group. If you drop a resource group that you created for an external component, the behavior is determined by the external component. For example, dropping a resource group that you assigned to a PL/Container runtime kills running containers in the group. </p><p>You cannot drop the pre-defined <codeph>admin_group</codeph> and <codeph>default_group</codeph> resource groups.</p>
+</section><section id="section4"><title>Parameters</title><parml><plentry><pt><varname>group_name</varname></pt><pd>The name of the resource group to remove.</pd></plentry></parml></section><section id="section5"><title>Notes</title><p>You cannot submit a <codeph>DROP RESOURCE GROUP</codeph> command in an explicit transaction or sub-transaction.</p><p>Use <codeph><xref href="ALTER_ROLE.xml#topic1" type="topic" format="dita"/></codeph> to remove a resource group assigned
         to a specific user/role.</p><p> Perform the following query to view all of the currently active
         queries for all resource groups:</p><codeblock>SELECT usename, current_query, waiting, procpid,
     rsgid, rsgname, rsgqueueduration