Skip to content

Commit d3f17b8

Browse files
author
awstools
committed
feat(client-xray): AWS X-Ray Features: Support Sampling Rate Boost On Anomaly
1 parent 6f9b4a6 commit d3f17b8

10 files changed

+235
-9
lines changed

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,10 @@ export interface CreateSamplingRuleCommandOutput extends CreateSamplingRuleResul
5858
* Attributes: { // AttributeMap
5959
* "<keys>": "STRING_VALUE",
6060
* },
61+
* SamplingRateBoost: { // SamplingRateBoost
62+
* MaxRate: Number("double"), // required
63+
* CooldownWindowMinutes: Number("int"), // required
64+
* },
6165
* },
6266
* Tags: [ // TagList
6367
* { // Tag
@@ -86,6 +90,10 @@ export interface CreateSamplingRuleCommandOutput extends CreateSamplingRuleResul
8690
* // Attributes: { // AttributeMap
8791
* // "<keys>": "STRING_VALUE",
8892
* // },
93+
* // SamplingRateBoost: { // SamplingRateBoost
94+
* // MaxRate: Number("double"), // required
95+
* // CooldownWindowMinutes: Number("int"), // required
96+
* // },
8997
* // },
9098
* // CreatedAt: new Date("TIMESTAMP"),
9199
* // ModifiedAt: new Date("TIMESTAMP"),

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ export interface DeleteSamplingRuleCommandOutput extends DeleteSamplingRuleResul
5959
* // Attributes: { // AttributeMap
6060
* // "<keys>": "STRING_VALUE",
6161
* // },
62+
* // SamplingRateBoost: { // SamplingRateBoost
63+
* // MaxRate: Number("double"), // required
64+
* // CooldownWindowMinutes: Number("int"), // required
65+
* // },
6266
* // },
6367
* // CreatedAt: new Date("TIMESTAMP"),
6468
* // ModifiedAt: new Date("TIMESTAMP"),

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ export interface GetSamplingRulesCommandOutput extends GetSamplingRulesResult, _
5959
* // Attributes: { // AttributeMap
6060
* // "<keys>": "STRING_VALUE",
6161
* // },
62+
* // SamplingRateBoost: { // SamplingRateBoost
63+
* // MaxRate: Number("double"), // required
64+
* // CooldownWindowMinutes: Number("int"), // required
65+
* // },
6266
* // },
6367
* // CreatedAt: new Date("TIMESTAMP"),
6468
* // ModifiedAt: new Date("TIMESTAMP"),

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,16 @@ export interface GetSamplingTargetsCommandOutput extends GetSamplingTargetsResul
4747
* BorrowCount: Number("int"),
4848
* },
4949
* ],
50+
* SamplingBoostStatisticsDocuments: [ // SamplingBoostStatisticsDocumentList
51+
* { // SamplingBoostStatisticsDocument
52+
* RuleName: "STRING_VALUE", // required
53+
* ServiceName: "STRING_VALUE", // required
54+
* Timestamp: new Date("TIMESTAMP"), // required
55+
* AnomalyCount: Number("int"), // required
56+
* TotalCount: Number("int"), // required
57+
* SampledAnomalyCount: Number("int"), // required
58+
* },
59+
* ],
5060
* };
5161
* const command = new GetSamplingTargetsCommand(input);
5262
* const response = await client.send(command);
@@ -58,6 +68,10 @@ export interface GetSamplingTargetsCommandOutput extends GetSamplingTargetsResul
5868
* // ReservoirQuota: Number("int"),
5969
* // ReservoirQuotaTTL: new Date("TIMESTAMP"),
6070
* // Interval: Number("int"),
71+
* // SamplingBoost: { // SamplingBoost
72+
* // BoostRate: Number("double"), // required
73+
* // BoostRateTTL: new Date("TIMESTAMP"), // required
74+
* // },
6175
* // },
6276
* // ],
6377
* // LastRuleModification: new Date("TIMESTAMP"),
@@ -68,6 +82,13 @@ export interface GetSamplingTargetsCommandOutput extends GetSamplingTargetsResul
6882
* // Message: "STRING_VALUE",
6983
* // },
7084
* // ],
85+
* // UnprocessedBoostStatistics: [
86+
* // {
87+
* // RuleName: "STRING_VALUE",
88+
* // ErrorCode: "STRING_VALUE",
89+
* // Message: "STRING_VALUE",
90+
* // },
91+
* // ],
7192
* // };
7293
*
7394
* ```

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export interface GetTraceSegmentDestinationCommandOutput extends GetTraceSegment
2929

3030
/**
3131
* <p>
32-
* 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>.
32+
* 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>.
3333
* </p>
3434
* @example
3535
* Use a bare-bones client and the command you need to make an API call.

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,11 @@ export interface ListRetrievedTracesCommandOutput extends ListRetrievedTracesRes
3131
* <p>
3232
* 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>.
3333
* </p>
34-
* <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>
34+
* <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>
3535
* <p>
3636
* 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>
37-
* <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>
38-
* <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>
37+
* <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>
38+
* <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>
3939
* @example
4040
* Use a bare-bones client and the command you need to make an API call.
4141
* ```javascript

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export interface StartTraceRetrievalCommandOutput extends StartTraceRetrievalRes
2929

3030
/**
3131
* <p>
32-
* 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>.
32+
* 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>.
3333
* </p>
3434
* <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>
3535
* <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‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,10 @@ export interface UpdateSamplingRuleCommandOutput extends UpdateSamplingRuleResul
5151
* Attributes: { // AttributeMap
5252
* "<keys>": "STRING_VALUE",
5353
* },
54+
* SamplingRateBoost: { // SamplingRateBoost
55+
* MaxRate: Number("double"), // required
56+
* CooldownWindowMinutes: Number("int"), // required
57+
* },
5458
* },
5559
* };
5660
* const command = new UpdateSamplingRuleCommand(input);
@@ -73,6 +77,10 @@ export interface UpdateSamplingRuleCommandOutput extends UpdateSamplingRuleResul
7377
* // Attributes: { // AttributeMap
7478
* // "<keys>": "STRING_VALUE",
7579
* // },
80+
* // SamplingRateBoost: { // SamplingRateBoost
81+
* // MaxRate: Number("double"), // required
82+
* // CooldownWindowMinutes: Number("int"), // required
83+
* // },
7684
* // },
7785
* // CreatedAt: new Date("TIMESTAMP"),
7886
* // ModifiedAt: new Date("TIMESTAMP"),

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

Lines changed: 118 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -224,8 +224,7 @@ export interface Trace {
224224
Id?: string | undefined;
225225

226226
/**
227-
* <p>The length of time in seconds between the start time of the root segment and the end
228-
* time of the last segment that completed.</p>
227+
* <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>
229228
* @public
230229
*/
231230
Duration?: number | undefined;
@@ -532,6 +531,26 @@ export interface CreateGroupResult {
532531
Group?: Group | undefined;
533532
}
534533

534+
/**
535+
* <p>Enable temporary sampling rate increases when you detect anomalies to improve visibility.</p>
536+
* @public
537+
*/
538+
export interface SamplingRateBoost {
539+
/**
540+
* <p>Defines max temporary sampling rate to apply when a boost is triggered.
541+
* Calculated boost rate by X-Ray will be less than or equal to this max rate.</p>
542+
* @public
543+
*/
544+
MaxRate: number | undefined;
545+
546+
/**
547+
* <p>Sets the time window (in minutes) in which only one sampling rate boost can be triggered.
548+
* After a boost occurs, no further boosts are allowed until the next window.</p>
549+
* @public
550+
*/
551+
CooldownWindowMinutes: number | undefined;
552+
}
553+
535554
/**
536555
* <p>A sampling rule that services use to decide whether to instrument a request. Rule
537556
* fields can match properties of the service, or properties of a request. The service can ignore
@@ -618,6 +637,13 @@ export interface SamplingRule {
618637
* @public
619638
*/
620639
Attributes?: Record<string, string> | undefined;
640+
641+
/**
642+
* <p>Specifies the multiplier applied to the base sampling rate.
643+
* This boost allows you to temporarily increase sampling without changing the rule's configuration.</p>
644+
* @public
645+
*/
646+
SamplingRateBoost?: SamplingRateBoost | undefined;
621647
}
622648

623649
/**
@@ -2172,6 +2198,50 @@ export interface GetSamplingStatisticSummariesResult {
21722198
NextToken?: string | undefined;
21732199
}
21742200

2201+
/**
2202+
* <p>Request anomaly stats for a single rule from a service. Results are for the last 10
2203+
* seconds unless the service has been assigned a longer reporting interval after a previous call
2204+
* to <a href="https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html">GetSamplingTargets</a>.</p>
2205+
* @public
2206+
*/
2207+
export interface SamplingBoostStatisticsDocument {
2208+
/**
2209+
* <p>The name of the sampling rule.</p>
2210+
* @public
2211+
*/
2212+
RuleName: string | undefined;
2213+
2214+
/**
2215+
* <p>Matches the <code>name</code> that the service uses to identify itself in segments.</p>
2216+
* @public
2217+
*/
2218+
ServiceName: string | undefined;
2219+
2220+
/**
2221+
* <p>The current time.</p>
2222+
* @public
2223+
*/
2224+
Timestamp: Date | undefined;
2225+
2226+
/**
2227+
* <p>The number of requests with anomaly.</p>
2228+
* @public
2229+
*/
2230+
AnomalyCount: number | undefined;
2231+
2232+
/**
2233+
* <p>The number of requests that associated to the rule.</p>
2234+
* @public
2235+
*/
2236+
TotalCount: number | undefined;
2237+
2238+
/**
2239+
* <p>The number of requests with anomaly recorded.</p>
2240+
* @public
2241+
*/
2242+
SampledAnomalyCount: number | undefined;
2243+
}
2244+
21752245
/**
21762246
* <p>Request sampling results for a single rule from a service. Results are for the last 10
21772247
* seconds unless the service has been assigned a longer reporting interval after a previous call
@@ -2225,6 +2295,31 @@ export interface GetSamplingTargetsRequest {
22252295
* @public
22262296
*/
22272297
SamplingStatisticsDocuments: SamplingStatisticsDocument[] | undefined;
2298+
2299+
/**
2300+
* <p>Information about rules that the service is using to boost sampling rate.</p>
2301+
* @public
2302+
*/
2303+
SamplingBoostStatisticsDocuments?: SamplingBoostStatisticsDocument[] | undefined;
2304+
}
2305+
2306+
/**
2307+
* <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
2308+
* <a href="https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html">GetSamplingTargets</a>.</p>
2309+
* @public
2310+
*/
2311+
export interface SamplingBoost {
2312+
/**
2313+
* <p>The calculated sampling boost rate for this service </p>
2314+
* @public
2315+
*/
2316+
BoostRate: number | undefined;
2317+
2318+
/**
2319+
* <p>When the sampling boost expires.</p>
2320+
* @public
2321+
*/
2322+
BoostRateTTL: Date | undefined;
22282323
}
22292324

22302325
/**
@@ -2265,6 +2360,12 @@ export interface SamplingTargetDocument {
22652360
* @public
22662361
*/
22672362
Interval?: number | undefined;
2363+
2364+
/**
2365+
* <p>The sampling boost that X-Ray allocated for this service.</p>
2366+
* @public
2367+
*/
2368+
SamplingBoost?: SamplingBoost | undefined;
22682369
}
22692370

22702371
/**
@@ -2316,6 +2417,13 @@ export interface GetSamplingTargetsResult {
23162417
* @public
23172418
*/
23182419
UnprocessedStatistics?: UnprocessedStatistics[] | undefined;
2420+
2421+
/**
2422+
* <p>Information about <a href="https://docs.aws.amazon.com/xray/latest/api/API_SamplingBoostStatisticsDocument.html">SamplingBoostStatisticsDocument</a> that X-Ray could not
2423+
* process.</p>
2424+
* @public
2425+
*/
2426+
UnprocessedBoostStatistics?: UnprocessedStatistics[] | undefined;
23192427
}
23202428

23212429
/**
@@ -3086,8 +3194,7 @@ export interface TraceSummary {
30863194
StartTime?: Date | undefined;
30873195

30883196
/**
3089-
* <p>The length of time in seconds between the start time of the root segment and the end
3090-
* time of the last segment that completed.</p>
3197+
* <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>
30913198
* @public
30923199
*/
30933200
Duration?: number | undefined;
@@ -4183,6 +4290,13 @@ export interface SamplingRuleUpdate {
41834290
* @public
41844291
*/
41854292
Attributes?: Record<string, string> | undefined;
4293+
4294+
/**
4295+
* <p>Specifies the multiplier applied to the base sampling rate.
4296+
* This boost allows you to temporarily increase sampling without changing the rule's configuration.</p>
4297+
* @public
4298+
*/
4299+
SamplingRateBoost?: SamplingRateBoost | undefined;
41864300
}
41874301

41884302
/**

0 commit comments

Comments
 (0)