AWS X-Ray Update: AWS X-Ray Features: Support Sampling Rate Boost On Anomaly

Author: AWS

.changes/next-release/feature-AWSXRay-3494fee.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS X-Ray",
+    "contributor": "",
+    "description": "AWS X-Ray Features: Support Sampling Rate Boost On Anomaly"
+}

services/xray/src/main/resources/codegen-resources/service-2.json

@@ -336,7 +336,7 @@
         {"shape":"InvalidRequestException"},
         {"shape":"ThrottledException"}
       ],
-      "documentation":"<p> Retrieves the current destination of data sent to <code>PutTraceSegments</code> and <i>OpenTelemetry</i> API. The Transaction Search feature requires a CloudWatchLogs destination. For more information, see <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html\">Transaction Search</a> and <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html\">OpenTelemetry</a>. </p>"
+      "documentation":"<p> Retrieves the current destination of data sent to <code>PutTraceSegments</code> and <i>OpenTelemetry protocol (OTLP)</i> endpoint. The Transaction Search feature requires a CloudWatchLogs destination. For more information, see <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html\">Transaction Search</a> and <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html\">OpenTelemetry</a>. </p>"
     },
     "GetTraceSummaries":{
       "name":"GetTraceSummaries",
@@ -379,7 +379,7 @@
         {"shape":"ThrottledException"},
         {"shape":"ResourceNotFoundException"}
       ],
-      "documentation":"<p> Retrieves a list of traces for a given <code>RetrievalToken</code> from the CloudWatch log group generated by Transaction Search. For information on what each trace returns, see <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html\">BatchGetTraces</a>. </p> <p>This API does not initiate a retrieval job. To start a trace retrieval, use <code>StartTraceRetrieval</code>, which generates the required <code>RetrievalToken</code>.</p> <p> When the <code>RetrievalStatus</code> is not <i>COMPLETE</i>, the API will return an empty response. Retry the request once the retrieval has completed to access the full list of traces.</p> <p>For cross-account observability, this API can retrieve traces from linked accounts when CloudWatch log is the destination across relevant accounts. For more details, see <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html\">CloudWatch cross-account observability</a>.</p> <p>For retrieving data from X-Ray directly as opposed to the Transaction-Search Log group, see <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html\">BatchGetTraces</a>.</p>"
+      "documentation":"<p> Retrieves a list of traces for a given <code>RetrievalToken</code> from the CloudWatch log group generated by Transaction Search. For information on what each trace returns, see <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html\">BatchGetTraces</a>. </p> <p>This API does not initiate a retrieval process. To start a trace retrieval, use <code>StartTraceRetrieval</code>, which generates the required <code>RetrievalToken</code>.</p> <p> When the <code>RetrievalStatus</code> is not <i>COMPLETE</i>, the API will return an empty response. Retry the request once the retrieval has completed to access the full list of traces.</p> <p>For cross-account observability, this API can retrieve traces from linked accounts when CloudWatch log is set as the destination across relevant accounts. For more details, see <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html\">CloudWatch cross-account observability</a>.</p> <p>For retrieving data from X-Ray directly as opposed to the Transaction Search generated log group, see <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html\">BatchGetTraces</a>.</p>"
     },
     "ListTagsForResource":{
       "name":"ListTagsForResource",
@@ -469,7 +469,7 @@
         {"shape":"ThrottledException"},
         {"shape":"ResourceNotFoundException"}
       ],
-      "documentation":"<p> Initiates a trace retrieval process using the specified time range and for the give trace IDs on Transaction Search generated by the CloudWatch log group. For more information, see <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html\">Transaction Search</a>. </p> <p>API returns a <code>RetrievalToken</code>, which can be used with <code>ListRetrievedTraces</code> or <code>GetRetrievedTracesGraph</code> to fetch results. Retrievals will time out after 60 minutes. To execute long time ranges, consider segmenting into multiple retrievals.</p> <p>If you are using <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html\">CloudWatch cross-account observability</a>, you can use this operation in a monitoring account to retrieve data from a linked source account, as long as both accounts have transaction search enabled.</p> <p>For retrieving data from X-Ray directly as opposed to the Transaction-Search Log group, see <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html\">BatchGetTraces</a>.</p>"
+      "documentation":"<p> Initiates a trace retrieval process using the specified time range and for the given trace IDs in the Transaction Search generated CloudWatch log group. For more information, see <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html\">Transaction Search</a>. </p> <p>API returns a <code>RetrievalToken</code>, which can be used with <code>ListRetrievedTraces</code> or <code>GetRetrievedTracesGraph</code> to fetch results. Retrievals will time out after 60 minutes. To execute long time ranges, consider segmenting into multiple retrievals.</p> <p>If you are using <a href=\"https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html\">CloudWatch cross-account observability</a>, you can use this operation in a monitoring account to retrieve data from a linked source account, as long as both accounts have transaction search enabled.</p> <p>For retrieving data from X-Ray directly as opposed to the Transaction-Search Log group, see <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html\">BatchGetTraces</a>.</p>"
     },
     "TagResource":{
       "name":"TagResource",
@@ -627,6 +627,10 @@
       "type":"list",
       "member":{"shape":"AnomalousService"}
     },
+    "AnomalyCount":{
+      "type":"integer",
+      "min":0
+    },
     "AttributeKey":{
       "type":"string",
       "max":32,
@@ -738,6 +742,10 @@
       "max":24,
       "min":24
     },
+    "CooldownWindowMinutes":{
+      "type":"integer",
+      "min":0
+    },
     "CreateGroupRequest":{
       "type":"structure",
       "required":["GroupName"],
@@ -1501,6 +1509,10 @@
         "SamplingStatisticsDocuments":{
           "shape":"SamplingStatisticsDocumentList",
           "documentation":"<p>Information about rules that the service is using to sample requests.</p>"
+        },
+        "SamplingBoostStatisticsDocuments":{
+          "shape":"SamplingBoostStatisticsDocumentList",
+          "documentation":"<p>Information about rules that the service is using to boost sampling rate.</p>"
         }
       }
     },
@@ -1518,6 +1530,10 @@
         "UnprocessedStatistics":{
           "shape":"UnprocessedStatisticsList",
           "documentation":"<p>Information about <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_SamplingStatisticsDocument.html\">SamplingStatisticsDocument</a> that X-Ray could not process.</p>"
+        },
+        "UnprocessedBoostStatistics":{
+          "shape":"UnprocessedStatisticsList",
+          "documentation":"<p>Information about <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_SamplingBoostStatisticsDocument.html\">SamplingBoostStatisticsDocument</a> that X-Ray could not process.</p>"
         }
       }
     },
@@ -2281,6 +2297,11 @@
       "error":{"httpStatusCode":400},
       "exception":true
     },
+    "MaxRate":{
+      "type":"double",
+      "max":1,
+      "min":0
+    },
     "NullableBoolean":{"type":"boolean"},
     "NullableDouble":{"type":"double"},
     "NullableInteger":{"type":"integer"},
@@ -2681,10 +2702,93 @@
       "max":32,
       "min":1
     },
+    "SampledAnomalyCount":{
+      "type":"integer",
+      "min":0
+    },
     "SampledCount":{
       "type":"integer",
       "min":0
     },
+    "SamplingBoost":{
+      "type":"structure",
+      "required":[
+        "BoostRate",
+        "BoostRateTTL"
+      ],
+      "members":{
+        "BoostRate":{
+          "shape":"Double",
+          "documentation":"<p>The calculated sampling boost rate for this service </p>"
+        },
+        "BoostRateTTL":{
+          "shape":"Timestamp",
+          "documentation":"<p>When the sampling boost expires.</p>"
+        }
+      },
+      "documentation":"<p>Temporary boost sampling rate. X-Ray calculates sampling boost for each service based on the recent sampling boost stats of all services that called <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html\">GetSamplingTargets</a>.</p>"
+    },
+    "SamplingBoostStatisticsDocument":{
+      "type":"structure",
+      "required":[
+        "RuleName",
+        "ServiceName",
+        "Timestamp",
+        "AnomalyCount",
+        "TotalCount",
+        "SampledAnomalyCount"
+      ],
+      "members":{
+        "RuleName":{
+          "shape":"RuleName",
+          "documentation":"<p>The name of the sampling rule.</p>"
+        },
+        "ServiceName":{
+          "shape":"ServiceName",
+          "documentation":"<p>Matches the <code>name</code> that the service uses to identify itself in segments.</p>"
+        },
+        "Timestamp":{
+          "shape":"Timestamp",
+          "documentation":"<p>The current time.</p>"
+        },
+        "AnomalyCount":{
+          "shape":"AnomalyCount",
+          "documentation":"<p>The number of requests with anomaly.</p>"
+        },
+        "TotalCount":{
+          "shape":"TotalCount",
+          "documentation":"<p>The number of requests that associated to the rule.</p>"
+        },
+        "SampledAnomalyCount":{
+          "shape":"SampledAnomalyCount",
+          "documentation":"<p>The number of requests with anomaly recorded.</p>"
+        }
+      },
+      "documentation":"<p>Request anomaly stats for a single rule from a service. Results are for the last 10 seconds unless the service has been assigned a longer reporting interval after a previous call to <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html\">GetSamplingTargets</a>.</p>"
+    },
+    "SamplingBoostStatisticsDocumentList":{
+      "type":"list",
+      "member":{"shape":"SamplingBoostStatisticsDocument"},
+      "max":25
+    },
+    "SamplingRateBoost":{
+      "type":"structure",
+      "required":[
+        "MaxRate",
+        "CooldownWindowMinutes"
+      ],
+      "members":{
+        "MaxRate":{
+          "shape":"MaxRate",
+          "documentation":"<p>Defines max temporary sampling rate to apply when a boost is triggered. Calculated boost rate by X-Ray will be less than or equal to this max rate.</p>"
+        },
+        "CooldownWindowMinutes":{
+          "shape":"CooldownWindowMinutes",
+          "documentation":"<p>Sets the time window (in minutes) in which only one sampling rate boost can be triggered. After a boost occurs, no further boosts are allowed until the next window.</p>"
+        }
+      },
+      "documentation":"<p>Enable temporary sampling rate increases when you detect anomalies to improve visibility.</p>"
+    },
     "SamplingRule":{
       "type":"structure",
       "required":[
@@ -2751,6 +2855,10 @@
         "Attributes":{
           "shape":"AttributeMap",
           "documentation":"<p>Matches attributes derived from the request.</p>"
+        },
+        "SamplingRateBoost":{
+          "shape":"SamplingRateBoost",
+          "documentation":"<p>Specifies the multiplier applied to the base sampling rate. This boost allows you to temporarily increase sampling without changing the rule's configuration.</p>"
         }
       },
       "documentation":"<p>A sampling rule that services use to decide whether to instrument a request. Rule fields can match properties of the service, or properties of a request. The service can ignore rules that don't match its properties.</p>"
@@ -2827,6 +2935,10 @@
         "Attributes":{
           "shape":"AttributeMap",
           "documentation":"<p>Matches attributes derived from the request.</p>"
+        },
+        "SamplingRateBoost":{
+          "shape":"SamplingRateBoost",
+          "documentation":"<p>Specifies the multiplier applied to the base sampling rate. This boost allows you to temporarily increase sampling without changing the rule's configuration.</p>"
         }
       },
       "documentation":"<p>A document specifying changes to a sampling rule's configuration.</p>"
@@ -2946,6 +3058,10 @@
         "Interval":{
           "shape":"NullableInteger",
           "documentation":"<p>The number of seconds for the service to wait before getting sampling targets again.</p>"
+        },
+        "SamplingBoost":{
+          "shape":"SamplingBoost",
+          "documentation":"<p>The sampling boost that X-Ray allocated for this service.</p>"
         }
       },
       "documentation":"<p>Temporary changes to a sampling rule configuration. To meet the global sampling target for a rule, X-Ray calculates a new reservoir for each service based on the recent sampling results of all services that called <a href=\"https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html\">GetSamplingTargets</a>.</p>"
@@ -3317,6 +3433,10 @@
       "error":{"httpStatusCode":400},
       "exception":true
     },
+    "TotalCount":{
+      "type":"integer",
+      "min":0
+    },
     "Trace":{
       "type":"structure",
       "members":{
@@ -3326,7 +3446,7 @@
         },
         "Duration":{
           "shape":"NullableDouble",
-          "documentation":"<p>The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.</p>"
+          "documentation":"<p>The length of time in seconds between the start time of the earliest segment that started and the end time of the last segment that completed.</p>"
         },
         "LimitExceeded":{
           "shape":"NullableBoolean",
@@ -3415,7 +3535,7 @@
         },
         "Duration":{
           "shape":"NullableDouble",
-          "documentation":"<p>The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.</p>"
+          "documentation":"<p> The length of time in seconds between the start time of the earliest segment that started and the end time of the last segment that completed.</p>"
         },
         "ResponseTime":{
           "shape":"NullableDouble",