docs(client-pi): Clarifies how aggregation works for GetResourceMetri…

…cs in the Performance Insights API.
aws · Apr 23, 2024 · f542ac3 · f542ac3
1 parent 39a8983
commit f542ac3
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 11 deletions.
diff --git a/clients/client-pi/src/commands/GetResourceMetricsCommand.ts b/clients/client-pi/src/commands/GetResourceMetricsCommand.ts
@@ -28,8 +28,8 @@ export interface GetResourceMetricsCommandOutput extends GetResourceMetricsRespo
 
 /**
  * <p>Retrieve Performance Insights metrics for a set of data sources over a time period. You can provide
- *       specific dimension groups and dimensions, and provide aggregation and filtering criteria for
- *       each group.</p>
+ *           specific dimension groups and dimensions, and provide filtering criteria for each group. You must specify an aggregate function for
+ *           each metric.</p>
  *          <note>
  *             <p>Each response element returns a maximum of 500 bytes. For larger elements, such as SQL statements,
  *                only the first 500 bytes are returned.</p>

diff --git a/clients/client-pi/src/models/models_0.ts b/clients/client-pi/src/models/models_0.ts
@@ -1244,8 +1244,11 @@ export interface GetResourceMetadataResponse {
 }
 
 /**
- * <p>A single query to be processed. You must provide the metric to query. If no other
- *       parameters are specified, Performance Insights returns all data points for the specified metric. Optionally, you can
+ * <p>A single query to be processed. You must provide the metric to query and append an aggregate function to the metric.
+ *             For example, to find the average for the metric <code>db.load</code>
+ *             you must use <code>db.load.avg</code>. Valid values for aggregate functions include <code>.avg</code>, <code>.min</code>,
+ *             <code>.max</code>, and <code>.sum</code>.
+ *             If no other parameters are specified, Performance Insights returns all data points for the specified metric. Optionally, you can
  *       request that the data points be aggregated by dimension group (<code>GroupBy</code>), and return only
  *           those data points that match your criteria (<code>Filter</code>).</p>
  * @public
@@ -1268,6 +1271,10 @@ export interface MetricQuery {
    *                <p>The counter metrics listed in <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS">Performance Insights
    *                         operating system counters</a> in the <i>Amazon Aurora User Guide</i>.</p>
    *             </li>
+   *             <li>
+   *                <p>The counter metrics listed in <a href="https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS">Performance Insights
+   *                     operating system counters</a> in the <i>Amazon RDS User Guide</i>.</p>
+   *             </li>
    *          </ul>
    *          <p>If the number of active sessions is less than an internal Performance Insights threshold, <code>db.load.avg</code> and <code>db.sampledload.avg</code> are the same
    *             value. If the number of active sessions is greater than the internal threshold, Performance Insights samples the active sessions, with <code>db.load.avg</code> showing the
@@ -1348,8 +1355,10 @@ export interface GetResourceMetricsRequest {
   Identifier: string | undefined;
 
   /**
-   * <p>An array of one or more queries to perform. Each query must specify a Performance Insights metric, and can optionally specify aggregation and filtering
-   *             criteria.</p>
+   * <p>An array of one or more queries to perform. Each query must specify a Performance Insights metric and specify an aggregate function, and you can provide filtering
+   *             criteria. You must append the aggregate function to the metric. For example, to find the average for the metric <code>db.load</code>
+   *             you must use <code>db.load.avg</code>. Valid values for aggregate functions include <code>.avg</code>, <code>.min</code>,
+   *             <code>.max</code>, and <code>.sum</code>.</p>
    * @public
    */
   MetricQueries: MetricQuery[] | undefined;
@@ -1447,6 +1456,10 @@ export interface ResponseResourceMetricKey {
    *                <p>The counter metrics listed in <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS">Performance Insights
    *                         operating system counters</a> in the <i>Amazon Aurora User Guide</i>.</p>
    *             </li>
+   *             <li>
+   *                <p>The counter metrics listed in <a href="https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS">Performance Insights
+   *                     operating system counters</a> in the <i>Amazon RDS User Guide</i>.</p>
+   *             </li>
    *          </ul>
    *          <p>If the number of active sessions is less than an internal Performance Insights threshold, <code>db.load.avg</code> and
    *           <code>db.sampledload.avg</code> are the same value. If the number of active sessions is greater than the

diff --git a/codegen/sdk-codegen/aws-models/pi.json b/codegen/sdk-codegen/aws-models/pi.json
@@ -1096,7 +1096,7 @@
         }
       ],
       "traits": {
-        "smithy.api#documentation": "<p>Retrieve Performance Insights metrics for a set of data sources over a time period. You can provide\n      specific dimension groups and dimensions, and provide aggregation and filtering criteria for\n      each group.</p>\n         <note>\n            <p>Each response element returns a maximum of 500 bytes. For larger elements, such as SQL statements, \n               only the first 500 bytes are returned.</p>\n         </note>",
+        "smithy.api#documentation": "<p>Retrieve Performance Insights metrics for a set of data sources over a time period. You can provide\n          specific dimension groups and dimensions, and provide filtering criteria for each group. You must specify an aggregate function for\n          each metric.</p>\n         <note>\n            <p>Each response element returns a maximum of 500 bytes. For larger elements, such as SQL statements, \n               only the first 500 bytes are returned.</p>\n         </note>",
         "smithy.api#paginated": {
           "inputToken": "NextToken",
           "outputToken": "NextToken",
@@ -1124,7 +1124,7 @@
         "MetricQueries": {
           "target": "com.amazonaws.pi#MetricQueryList",
           "traits": {
-            "smithy.api#documentation": "<p>An array of one or more queries to perform. Each query must specify a Performance Insights metric, and can optionally specify aggregation and filtering\n            criteria.</p>",
+            "smithy.api#documentation": "<p>An array of one or more queries to perform. Each query must specify a Performance Insights metric and specify an aggregate function, and you can provide filtering\n            criteria. You must append the aggregate function to the metric. For example, to find the average for the metric <code>db.load</code> \n            you must use <code>db.load.avg</code>. Valid values for aggregate functions include <code>.avg</code>, <code>.min</code>, \n            <code>.max</code>, and <code>.sum</code>.</p>",
             "smithy.api#required": {}
           }
         },
@@ -1742,7 +1742,7 @@
         "Metric": {
           "target": "com.amazonaws.pi#RequestString",
           "traits": {
-            "smithy.api#documentation": "<p>The name of a Performance Insights metric to be measured.</p>\n         <p>Valid values for <code>Metric</code> are:</p>\n         <ul>\n            <li>\n               <p>\n                  <code>db.load.avg</code> - A scaled representation of the number of active sessions for the \n                    database engine.</p>\n            </li>\n            <li>\n               <p>\n                  <code>db.sampledload.avg</code> - The raw number of active sessions for the database engine.</p>\n            </li>\n            <li>\n               <p>The counter metrics listed in <a href=\"https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS\">Performance Insights\n                        operating system counters</a> in the <i>Amazon Aurora User Guide</i>.</p>\n            </li>\n         </ul>\n         <p>If the number of active sessions is less than an internal Performance Insights threshold, <code>db.load.avg</code> and <code>db.sampledload.avg</code> are the same\n            value. If the number of active sessions is greater than the internal threshold, Performance Insights samples the active sessions, with <code>db.load.avg</code> showing the\n            scaled values, <code>db.sampledload.avg</code> showing the raw values, and <code>db.sampledload.avg</code> less than\n                <code>db.load.avg</code>. For most use cases, you can query <code>db.load.avg</code> only.</p>",
+            "smithy.api#documentation": "<p>The name of a Performance Insights metric to be measured.</p>\n         <p>Valid values for <code>Metric</code> are:</p>\n         <ul>\n            <li>\n               <p>\n                  <code>db.load.avg</code> - A scaled representation of the number of active sessions for the \n                    database engine.</p>\n            </li>\n            <li>\n               <p>\n                  <code>db.sampledload.avg</code> - The raw number of active sessions for the database engine.</p>\n            </li>\n            <li>\n               <p>The counter metrics listed in <a href=\"https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS\">Performance Insights\n                        operating system counters</a> in the <i>Amazon Aurora User Guide</i>.</p>\n            </li>\n            <li>\n               <p>The counter metrics listed in <a href=\"https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS\">Performance Insights\n                    operating system counters</a> in the <i>Amazon RDS User Guide</i>.</p>\n            </li>\n         </ul>\n         <p>If the number of active sessions is less than an internal Performance Insights threshold, <code>db.load.avg</code> and <code>db.sampledload.avg</code> are the same\n            value. If the number of active sessions is greater than the internal threshold, Performance Insights samples the active sessions, with <code>db.load.avg</code> showing the\n            scaled values, <code>db.sampledload.avg</code> showing the raw values, and <code>db.sampledload.avg</code> less than\n                <code>db.load.avg</code>. For most use cases, you can query <code>db.load.avg</code> only.</p>",
             "smithy.api#required": {}
           }
         },
@@ -1760,7 +1760,7 @@
         }
       },
       "traits": {
-        "smithy.api#documentation": "<p>A single query to be processed. You must provide the metric to query. If no other\n      parameters are specified, Performance Insights returns all data points for the specified metric. Optionally, you can\n      request that the data points be aggregated by dimension group (<code>GroupBy</code>), and return only \n          those data points that match your criteria (<code>Filter</code>).</p>"
+        "smithy.api#documentation": "<p>A single query to be processed. You must provide the metric to query and append an aggregate function to the metric.\n            For example, to find the average for the metric <code>db.load</code> \n            you must use <code>db.load.avg</code>. Valid values for aggregate functions include <code>.avg</code>, <code>.min</code>, \n            <code>.max</code>, and <code>.sum</code>.\n            If no other parameters are specified, Performance Insights returns all data points for the specified metric. Optionally, you can\n      request that the data points be aggregated by dimension group (<code>GroupBy</code>), and return only \n          those data points that match your criteria (<code>Filter</code>).</p>"
       }
     },
     "com.amazonaws.pi#MetricQueryFilterMap": {
@@ -2944,7 +2944,7 @@
         "Metric": {
           "target": "com.amazonaws.pi#String",
           "traits": {
-            "smithy.api#documentation": "<p>The name of a Performance Insights metric to be measured.</p>\n         <p>Valid values for <code>Metric</code> are:</p>\n         <ul>\n            <li>\n               <p>\n                  <code>db.load.avg</code> - A scaled representation of the number of active sessions for the database engine.</p>\n            </li>\n            <li>\n               <p>\n                  <code>db.sampledload.avg</code> - The raw number of active sessions for the database engine.</p>\n            </li>\n            <li>\n               <p>The counter metrics listed in <a href=\"https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS\">Performance Insights\n                        operating system counters</a> in the <i>Amazon Aurora User Guide</i>.</p>\n            </li>\n         </ul>\n         <p>If the number of active sessions is less than an internal Performance Insights threshold, <code>db.load.avg</code> and \n          <code>db.sampledload.avg</code> are the same value. If the number of active sessions is greater than the \n          internal threshold, Performance Insights samples the active sessions, with <code>db.load.avg</code> showing the scaled values, \n          <code>db.sampledload.avg</code> showing the raw values, and <code>db.sampledload.avg</code> less \n          than <code>db.load.avg</code>. For most use cases, you can query <code>db.load.avg</code> only.\n      </p>",
+            "smithy.api#documentation": "<p>The name of a Performance Insights metric to be measured.</p>\n         <p>Valid values for <code>Metric</code> are:</p>\n         <ul>\n            <li>\n               <p>\n                  <code>db.load.avg</code> - A scaled representation of the number of active sessions for the database engine.</p>\n            </li>\n            <li>\n               <p>\n                  <code>db.sampledload.avg</code> - The raw number of active sessions for the database engine.</p>\n            </li>\n            <li>\n               <p>The counter metrics listed in <a href=\"https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS\">Performance Insights\n                        operating system counters</a> in the <i>Amazon Aurora User Guide</i>.</p>\n            </li>\n            <li>\n               <p>The counter metrics listed in <a href=\"https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_PerfInsights_Counters.html#USER_PerfInsights_Counters.OS\">Performance Insights\n                    operating system counters</a> in the <i>Amazon RDS User Guide</i>.</p>\n            </li>\n         </ul>\n         <p>If the number of active sessions is less than an internal Performance Insights threshold, <code>db.load.avg</code> and \n          <code>db.sampledload.avg</code> are the same value. If the number of active sessions is greater than the \n          internal threshold, Performance Insights samples the active sessions, with <code>db.load.avg</code> showing the scaled values, \n          <code>db.sampledload.avg</code> showing the raw values, and <code>db.sampledload.avg</code> less \n          than <code>db.load.avg</code>. For most use cases, you can query <code>db.load.avg</code> only.\n      </p>",
             "smithy.api#required": {}
           }
         },