feat(client-xray): AWS X-Ray Features: Support Sampling Rate Boost On Anomaly

Author: awstools

clients/client-xray/src/commands/CreateSamplingRuleCommand.ts

@@ -58,6 +58,10 @@ export interface CreateSamplingRuleCommandOutput extends CreateSamplingRuleResul
  *     Attributes: { // AttributeMap
  *       "<keys>": "STRING_VALUE",
  *     },
+ *     SamplingRateBoost: { // SamplingRateBoost
+ *       MaxRate: Number("double"), // required
+ *       CooldownWindowMinutes: Number("int"), // required
+ *     },
  *   },
  *   Tags: [ // TagList
  *     { // Tag
@@ -86,6 +90,10 @@ export interface CreateSamplingRuleCommandOutput extends CreateSamplingRuleResul
  * //       Attributes: { // AttributeMap
  * //         "<keys>": "STRING_VALUE",
  * //       },
+ * //       SamplingRateBoost: { // SamplingRateBoost
+ * //         MaxRate: Number("double"), // required
+ * //         CooldownWindowMinutes: Number("int"), // required
+ * //       },
  * //     },
  * //     CreatedAt: new Date("TIMESTAMP"),
  * //     ModifiedAt: new Date("TIMESTAMP"),

clients/client-xray/src/commands/DeleteSamplingRuleCommand.ts

@@ -59,6 +59,10 @@ export interface DeleteSamplingRuleCommandOutput extends DeleteSamplingRuleResul
  * //       Attributes: { // AttributeMap
  * //         "<keys>": "STRING_VALUE",
  * //       },
+ * //       SamplingRateBoost: { // SamplingRateBoost
+ * //         MaxRate: Number("double"), // required
+ * //         CooldownWindowMinutes: Number("int"), // required
+ * //       },
  * //     },
  * //     CreatedAt: new Date("TIMESTAMP"),
  * //     ModifiedAt: new Date("TIMESTAMP"),

clients/client-xray/src/commands/GetSamplingRulesCommand.ts

@@ -59,6 +59,10 @@ export interface GetSamplingRulesCommandOutput extends GetSamplingRulesResult, _
  * //         Attributes: { // AttributeMap
  * //           "<keys>": "STRING_VALUE",
  * //         },
+ * //         SamplingRateBoost: { // SamplingRateBoost
+ * //           MaxRate: Number("double"), // required
+ * //           CooldownWindowMinutes: Number("int"), // required
+ * //         },
  * //       },
  * //       CreatedAt: new Date("TIMESTAMP"),
  * //       ModifiedAt: new Date("TIMESTAMP"),

clients/client-xray/src/commands/GetSamplingTargetsCommand.ts

@@ -47,6 +47,16 @@ export interface GetSamplingTargetsCommandOutput extends GetSamplingTargetsResul
  *       BorrowCount: Number("int"),
  *     },
  *   ],
+ *   SamplingBoostStatisticsDocuments: [ // SamplingBoostStatisticsDocumentList
+ *     { // SamplingBoostStatisticsDocument
+ *       RuleName: "STRING_VALUE", // required
+ *       ServiceName: "STRING_VALUE", // required
+ *       Timestamp: new Date("TIMESTAMP"), // required
+ *       AnomalyCount: Number("int"), // required
+ *       TotalCount: Number("int"), // required
+ *       SampledAnomalyCount: Number("int"), // required
+ *     },
+ *   ],
  * };
  * const command = new GetSamplingTargetsCommand(input);
  * const response = await client.send(command);
@@ -58,6 +68,10 @@ export interface GetSamplingTargetsCommandOutput extends GetSamplingTargetsResul
  * //       ReservoirQuota: Number("int"),
  * //       ReservoirQuotaTTL: new Date("TIMESTAMP"),
  * //       Interval: Number("int"),
+ * //       SamplingBoost: { // SamplingBoost
+ * //         BoostRate: Number("double"), // required
+ * //         BoostRateTTL: new Date("TIMESTAMP"), // required
+ * //       },
  * //     },
  * //   ],
  * //   LastRuleModification: new Date("TIMESTAMP"),
@@ -68,6 +82,13 @@ export interface GetSamplingTargetsCommandOutput extends GetSamplingTargetsResul
  * //       Message: "STRING_VALUE",
  * //     },
  * //   ],
+ * //   UnprocessedBoostStatistics: [
+ * //     {
+ * //       RuleName: "STRING_VALUE",
+ * //       ErrorCode: "STRING_VALUE",
+ * //       Message: "STRING_VALUE",
+ * //     },
+ * //   ],
  * // };
  *
  * ```

clients/client-xray/src/commands/GetTraceSegmentDestinationCommand.ts

@@ -29,7 +29,7 @@ export interface GetTraceSegmentDestinationCommandOutput extends GetTraceSegment
 
 /**
  * <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>.
+ *   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>
  * @example
  * Use a bare-bones client and the command you need to make an API call.

clients/client-xray/src/commands/ListRetrievedTracesCommand.ts

@@ -31,11 +31,11 @@ export interface ListRetrievedTracesCommandOutput extends ListRetrievedTracesRes
  * <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>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 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>
+ *          <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>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript

clients/client-xray/src/commands/StartTraceRetrievalCommand.ts

@@ -29,7 +29,7 @@ export interface StartTraceRetrievalCommandOutput extends StartTraceRetrievalRes
 
 /**
  * <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>.
+ *   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>

clients/client-xray/src/commands/UpdateSamplingRuleCommand.ts

@@ -51,6 +51,10 @@ export interface UpdateSamplingRuleCommandOutput extends UpdateSamplingRuleResul
  *     Attributes: { // AttributeMap
  *       "<keys>": "STRING_VALUE",
  *     },
+ *     SamplingRateBoost: { // SamplingRateBoost
+ *       MaxRate: Number("double"), // required
+ *       CooldownWindowMinutes: Number("int"), // required
+ *     },
  *   },
  * };
  * const command = new UpdateSamplingRuleCommand(input);
@@ -73,6 +77,10 @@ export interface UpdateSamplingRuleCommandOutput extends UpdateSamplingRuleResul
  * //       Attributes: { // AttributeMap
  * //         "<keys>": "STRING_VALUE",
  * //       },
+ * //       SamplingRateBoost: { // SamplingRateBoost
+ * //         MaxRate: Number("double"), // required
+ * //         CooldownWindowMinutes: Number("int"), // required
+ * //       },
  * //     },
  * //     CreatedAt: new Date("TIMESTAMP"),
  * //     ModifiedAt: new Date("TIMESTAMP"),

clients/client-xray/src/models/models_0.ts

@@ -224,8 +224,7 @@ export interface Trace {
   Id?: string | undefined;
 
   /**
-   * <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>
+   * <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>
    * @public
    */
   Duration?: number | undefined;
@@ -532,6 +531,26 @@ export interface CreateGroupResult {
   Group?: Group | undefined;
 }
 
+/**
+ * <p>Enable temporary sampling rate increases when you detect anomalies to improve visibility.</p>
+ * @public
+ */
+export interface SamplingRateBoost {
+  /**
+   * <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>
+   * @public
+   */
+  MaxRate: number | undefined;
+
+  /**
+   * <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>
+   * @public
+   */
+  CooldownWindowMinutes: number | undefined;
+}
+
 /**
  * <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
@@ -618,6 +637,13 @@ export interface SamplingRule {
    * @public
    */
   Attributes?: Record<string, string> | undefined;
+
+  /**
+   * <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>
+   * @public
+   */
+  SamplingRateBoost?: SamplingRateBoost | undefined;
 }
 
 /**
@@ -2172,6 +2198,50 @@ export interface GetSamplingStatisticSummariesResult {
   NextToken?: string | undefined;
 }
 
+/**
+ * <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>
+ * @public
+ */
+export interface SamplingBoostStatisticsDocument {
+  /**
+   * <p>The name of the sampling rule.</p>
+   * @public
+   */
+  RuleName: string | undefined;
+
+  /**
+   * <p>Matches the <code>name</code> that the service uses to identify itself in segments.</p>
+   * @public
+   */
+  ServiceName: string | undefined;
+
+  /**
+   * <p>The current time.</p>
+   * @public
+   */
+  Timestamp: Date | undefined;
+
+  /**
+   * <p>The number of requests with anomaly.</p>
+   * @public
+   */
+  AnomalyCount: number | undefined;
+
+  /**
+   * <p>The number of requests that associated to the rule.</p>
+   * @public
+   */
+  TotalCount: number | undefined;
+
+  /**
+   * <p>The number of requests with anomaly recorded.</p>
+   * @public
+   */
+  SampledAnomalyCount: number | undefined;
+}
+
 /**
  * <p>Request sampling results 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
@@ -2225,6 +2295,31 @@ export interface GetSamplingTargetsRequest {
    * @public
    */
   SamplingStatisticsDocuments: SamplingStatisticsDocument[] | undefined;
+
+  /**
+   * <p>Information about rules that the service is using to boost sampling rate.</p>
+   * @public
+   */
+  SamplingBoostStatisticsDocuments?: SamplingBoostStatisticsDocument[] | undefined;
+}
+
+/**
+ * <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>
+ * @public
+ */
+export interface SamplingBoost {
+  /**
+   * <p>The calculated sampling boost rate for this service </p>
+   * @public
+   */
+  BoostRate: number | undefined;
+
+  /**
+   * <p>When the sampling boost expires.</p>
+   * @public
+   */
+  BoostRateTTL: Date | undefined;
 }
 
 /**
@@ -2265,6 +2360,12 @@ export interface SamplingTargetDocument {
    * @public
    */
   Interval?: number | undefined;
+
+  /**
+   * <p>The sampling boost that X-Ray allocated for this service.</p>
+   * @public
+   */
+  SamplingBoost?: SamplingBoost | undefined;
 }
 
 /**
@@ -2316,6 +2417,13 @@ export interface GetSamplingTargetsResult {
    * @public
    */
   UnprocessedStatistics?: UnprocessedStatistics[] | undefined;
+
+  /**
+   * <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>
+   * @public
+   */
+  UnprocessedBoostStatistics?: UnprocessedStatistics[] | undefined;
 }
 
 /**
@@ -3086,8 +3194,7 @@ export interface TraceSummary {
   StartTime?: Date | undefined;
 
   /**
-   * <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>
+   * <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>
    * @public
    */
   Duration?: number | undefined;
@@ -4183,6 +4290,13 @@ export interface SamplingRuleUpdate {
    * @public
    */
   Attributes?: Record<string, string> | undefined;
+
+  /**
+   * <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>
+   * @public
+   */
+  SamplingRateBoost?: SamplingRateBoost | undefined;
 }
 
 /**