2022/10/20 - CloudWatch RUM - 7 new api methods
Changes CloudWatch RUM now supports Extended CloudWatch Metrics with Additional Dimensions
Creates or updates a destination to receive extended metrics from CloudWatch RUM. You can send extended metrics to CloudWatch or to a CloudWatch Evidently experiment.
For more information about extended metrics, see AddRumMetrics.
See also: AWS API Documentation
Request Syntax
client.put_rum_metrics_destination(
AppMonitorName='string',
Destination='CloudWatch'|'Evidently',
DestinationArn='string',
IamRoleArn='string'
)
string
[REQUIRED]
The name of the CloudWatch RUM app monitor that will send the metrics.
string
[REQUIRED]
Defines the destination to send the metrics to. Valid values are CloudWatch and Evidently . If you specify Evidently , you must also specify the ARN of the CloudWatchEvidently experiment that is to be the destination and an IAM role that has permission to write to the experiment.
string
Use this parameter only if Destination is Evidently . This parameter specifies the ARN of the Evidently experiment that will receive the extended metrics.
string
This parameter is required if Destination is Evidently . If Destination is CloudWatch , do not use this parameter.
This parameter specifies the ARN of an IAM role that RUM will assume to write to the Evidently experiment that you are sending metrics to. This role must have permission to write to that experiment.
dict
Response Syntax
{}
Response Structure
(dict) --
Specifies the extended metrics that you want a CloudWatch RUM app monitor to send to a destination. Valid destinations include CloudWatch and Evidently.
By default, RUM app monitors send some metrics to CloudWatch. These default metrics are listed in CloudWatch metrics that you can collect with CloudWatch RUM.
If you also send extended metrics, you can send metrics to Evidently as well as CloudWatch, and you can also optionally send the metrics with additional dimensions. The valid dimension names for the additional dimensions are BrowserName , CountryCode , DeviceType , FileType , OSName , and PageId . For more information, see Extended metrics that you can send to CloudWatch and CloudWatch Evidently.
The maximum number of metric definitions that you can specify in one BatchCreateRumMetricDefinitions operation is 200.
<p>The maximum number of metric definitions that one destination can contain is 2000.</p> <p>Extended metrics sent are charged as CloudWatch custom metrics. Each combination of additional dimension name and dimension value counts as a custom metric. For more information, see <a href="https://aws.amazon.com/cloudwatch/pricing/">Amazon CloudWatch Pricing</a>.</p> <p>You must have already created a destination for the metrics before you send them. For more information, see <a href="https://docs.aws.amazon.com/cloudwatchrum/latest/APIReference/API_PutRumMetricsDestination.html">PutRumMetricsDestination</a>.</p> <p>If some metric definitions specified in a <code>BatchCreateRumMetricDefinitions</code> operations are not valid, those metric definitions fail and return errors, but all valid metric definitions in the same operation still succeed.</p>
See also: AWS API Documentation
Request Syntax
client.batch_create_rum_metric_definitions(
AppMonitorName='string',
Destination='CloudWatch'|'Evidently',
DestinationArn='string',
MetricDefinitions=[
{
'DimensionKeys': {
'string': 'string'
},
'EventPattern': 'string',
'Name': 'string',
'UnitLabel': 'string',
'ValueKey': 'string'
},
]
)
string
[REQUIRED]
The name of the CloudWatch RUM app monitor that is to send the metrics.
string
[REQUIRED]
The destination to send the metrics to. Valid values are CloudWatch and Evidently . If you specify Evidently , you must also specify the ARN of the CloudWatchEvidently experiment that will receive the metrics and an IAM role that has permission to write to the experiment.
string
This parameter is required if Destination is Evidently . If Destination is CloudWatch , do not use this parameter.
This parameter specifies the ARN of the Evidently experiment that is to receive the metrics. You must have already defined this experiment as a valid destination. For more information, see PutRumMetricsDestination.
list
[REQUIRED]
An array of structures which define the metrics that you want to send.
(dict) --
Use this structure to define one extended metric that RUM will send to CloudWatch or CloudWatch Evidently. For more information, see Additional metrics that you can send to CloudWatch and CloudWatch Evidently.
Only certain combinations of values for Name , ValueKey , and EventPattern are valid. In addition to what is displayed in the list below, the EventPattern can also include information used by the DimensionKeys field.
If Name is PerformanceNavigationDuration , then ValueKey must be event_details.duration and the EventPattern must include {"event_type":["com.amazon.rum.performance_navigation_event"]}
If Name is PerformanceResourceDuration , then ValueKey must be event_details.duration and the EventPattern must include {"event_type":["com.amazon.rum.performance_resource_event"]}
If Name is NavigationSatisfiedTransaction , then ValueKey must be null and the EventPattern must include { "event_type": ["com.amazon.rum.performance_navigation_event"], "event_details": { "duration": [{ "numeric": [">",2000] }] } }
If Name is NavigationToleratedTransaction , then ValueKey must be null and the EventPattern must include { "event_type": ["com.amazon.rum.performance_navigation_event"], "event_details": { "duration": [{ "numeric": [">=",2000,"<"8000] }] } }
If Name is NavigationFrustratedTransaction , then ValueKey must be null and the EventPattern must include { "event_type": ["com.amazon.rum.performance_navigation_event"], "event_details": { "duration": [{ "numeric": [">=",8000] }] } }
If Name is WebVitalsCumulativeLayoutShift , then ValueKey must be event_details.value and the EventPattern must include {"event_type":["com.amazon.rum.cumulative_layout_shift_event"]}
If Name is WebVitalsFirstInputDelay , then ValueKey must be event_details.value and the EventPattern must include {"event_type":["com.amazon.rum.first_input_delay_event"]}
If Name is WebVitalsLargestContentfulPaint , then ValueKey must be event_details.value and the EventPattern must include {"event_type":["com.amazon.rum.largest_contentful_paint_event"]}
If Name is JsErrorCount , then ValueKey must be null and the EventPattern must include {"event_type":["com.amazon.rum.js_error_event"]}
If Name is HttpErrorCount , then ValueKey must be null and the EventPattern must include {"event_type":["com.amazon.rum.http_event"]}
If Name is SessionCount , then ValueKey must be null and the EventPattern must include {"event_type":["com.amazon.rum.session_start_event"]}
DimensionKeys (dict) --
Use this field only if you are sending the metric to CloudWatch.
This field is a map of field paths to dimension names. It defines the dimensions to associate with this metric in CloudWatch. Valid values for the entries in this field are the following:
"metadata.pageId": "PageId"
"metadata.browserName": "BrowserName"
"metadata.deviceType": "DeviceType"
"metadata.osName": "OSName"
"metadata.countryCode": "CountryCode"
"event_details.fileType": "FileType"
<p> All dimensions listed in this field must also be included in <code>EventPattern</code>.</p>
(string) --
(string) --
EventPattern (string) --
The pattern that defines the metric, specified as a JSON object. RUM checks events that happen in a user's session against the pattern, and events that match the pattern are sent to the metric destination.
When you define extended metrics, the metric definition is not valid if EventPattern is omitted.
Example event patterns:
'{ "event_type": ["com.amazon.rum.js_error_event"], "metadata": { "browserName": [ "Chrome", "Safari" ], } }'
'{ "event_type": ["com.amazon.rum.performance_navigation_event"], "metadata": { "browserName": [ "Chrome", "Firefox" ] }, "event_details": { "duration": [{ "numeric": [ "<", 2000 ] }] } }'
'{ "event_type": ["com.amazon.rum.performance_navigation_event"], "metadata": { "browserName": [ "Chrome", "Safari" ], "countryCode": [ "US" ] }, "event_details": { "duration": [{ "numeric": [ ">=", 2000, "<", 8000 ] }] } }'
If the metrics destination' is CloudWatch and the event also matches a value in DimensionKeys , then the metric is published with the specified dimensions.
Name (string) -- [REQUIRED]
The name for the metric that is defined in this structure. Valid values are the following:
PerformanceNavigationDuration
PerformanceResourceDuration
NavigationSatisfiedTransaction
NavigationToleratedTransaction
NavigationFrustratedTransaction
WebVitalsCumulativeLayoutShift
WebVitalsFirstInputDelay
WebVitalsLargestContentfulPaint
JsErrorCount
HttpErrorCount
SessionCount
UnitLabel (string) --
The CloudWatch metric unit to use for this metric. If you omit this field, the metric is recorded with no unit.
ValueKey (string) --
The field within the event object that the metric value is sourced from.
If you omit this field, a hardcoded value of 1 is pushed as the metric value. This is useful if you just want to count the number of events that the filter catches.
If this metric is sent to CloudWatch Evidently, this field will be passed to Evidently raw and Evidently will handle data extraction from the event.
dict
Response Syntax
{
'Errors': [
{
'ErrorCode': 'string',
'ErrorMessage': 'string',
'MetricDefinition': {
'DimensionKeys': {
'string': 'string'
},
'EventPattern': 'string',
'Name': 'string',
'UnitLabel': 'string',
'ValueKey': 'string'
}
},
],
'MetricDefinitions': [
{
'DimensionKeys': {
'string': 'string'
},
'EventPattern': 'string',
'MetricDefinitionId': 'string',
'Name': 'string',
'UnitLabel': 'string',
'ValueKey': 'string'
},
]
}
Response Structure
(dict) --
Errors (list) --
An array of error objects, if the operation caused any errors.
(dict) --
A structure that defines one error caused by a BatchCreateRumMetricsDefinitions operation.
ErrorCode (string) --
The error code.
ErrorMessage (string) --
The error message for this metric definition.
MetricDefinition (dict) --
The metric definition that caused this error.
DimensionKeys (dict) --
Use this field only if you are sending the metric to CloudWatch.
This field is a map of field paths to dimension names. It defines the dimensions to associate with this metric in CloudWatch. Valid values for the entries in this field are the following:
"metadata.pageId": "PageId"
"metadata.browserName": "BrowserName"
"metadata.deviceType": "DeviceType"
"metadata.osName": "OSName"
"metadata.countryCode": "CountryCode"
"event_details.fileType": "FileType"
<p> All dimensions listed in this field must also be included in <code>EventPattern</code>.</p>
(string) --
(string) --
EventPattern (string) --
The pattern that defines the metric, specified as a JSON object. RUM checks events that happen in a user's session against the pattern, and events that match the pattern are sent to the metric destination.
When you define extended metrics, the metric definition is not valid if EventPattern is omitted.
Example event patterns:
'{ "event_type": ["com.amazon.rum.js_error_event"], "metadata": { "browserName": [ "Chrome", "Safari" ], } }'
'{ "event_type": ["com.amazon.rum.performance_navigation_event"], "metadata": { "browserName": [ "Chrome", "Firefox" ] }, "event_details": { "duration": [{ "numeric": [ "<", 2000 ] }] } }'
'{ "event_type": ["com.amazon.rum.performance_navigation_event"], "metadata": { "browserName": [ "Chrome", "Safari" ], "countryCode": [ "US" ] }, "event_details": { "duration": [{ "numeric": [ ">=", 2000, "<", 8000 ] }] } }'
If the metrics destination' is CloudWatch and the event also matches a value in DimensionKeys , then the metric is published with the specified dimensions.
Name (string) --
The name for the metric that is defined in this structure. Valid values are the following:
PerformanceNavigationDuration
PerformanceResourceDuration
NavigationSatisfiedTransaction
NavigationToleratedTransaction
NavigationFrustratedTransaction
WebVitalsCumulativeLayoutShift
WebVitalsFirstInputDelay
WebVitalsLargestContentfulPaint
JsErrorCount
HttpErrorCount
SessionCount
UnitLabel (string) --
The CloudWatch metric unit to use for this metric. If you omit this field, the metric is recorded with no unit.
ValueKey (string) --
The field within the event object that the metric value is sourced from.
If you omit this field, a hardcoded value of 1 is pushed as the metric value. This is useful if you just want to count the number of events that the filter catches.
If this metric is sent to CloudWatch Evidently, this field will be passed to Evidently raw and Evidently will handle data extraction from the event.
MetricDefinitions (list) --
An array of structures that define the extended metrics.
(dict) --
A structure that displays the definition of one extended metric that RUM sends to CloudWatch or CloudWatch Evidently. For more information, see Additional metrics that you can send to CloudWatch and CloudWatch Evidently.
DimensionKeys (dict) --
This field is a map of field paths to dimension names. It defines the dimensions to associate with this metric in CloudWatch The value of this field is used only if the metric destination is CloudWatch . If the metric destination is Evidently , the value of DimensionKeys is ignored.
(string) --
(string) --
EventPattern (string) --
The pattern that defines the metric. RUM checks events that happen in a user's session against the pattern, and events that match the pattern are sent to the metric destination.
If the metrics destination is CloudWatch and the event also matches a value in DimensionKeys , then the metric is published with the specified dimensions.
MetricDefinitionId (string) --
The ID of this metric definition.
Name (string) --
The name of the metric that is defined in this structure.
UnitLabel (string) --
Use this field only if you are sending this metric to CloudWatch. It defines the CloudWatch metric unit that this metric is measured in.
ValueKey (string) --
The field within the event object that the metric value is sourced from.
Returns a list of destinations that you have created to receive RUM extended metrics, for the specified app monitor.
For more information about extended metrics, see AddRumMetrics.
See also: AWS API Documentation
Request Syntax
client.list_rum_metrics_destinations(
AppMonitorName='string',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The name of the app monitor associated with the destinations that you want to retrieve.
integer
The maximum number of results to return in one operation. The default is 50. The maximum that you can specify is 100.
To retrieve the remaining results, make another call with the returned NextToken value.
string
Use the token returned by the previous operation to request the next page of results.
dict
Response Syntax
{
'Destinations': [
{
'Destination': 'CloudWatch'|'Evidently',
'DestinationArn': 'string',
'IamRoleArn': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Destinations (list) --
The list of CloudWatch RUM extended metrics destinations associated with the app monitor that you specified.
(dict) --
A structure that displays information about one destination that CloudWatch RUM sends extended metrics to.
Destination (string) --
Specifies whether the destination is CloudWatch or Evidently .
DestinationArn (string) --
If the destination is Evidently , this specifies the ARN of the Evidently experiment that receives the metrics.
IamRoleArn (string) --
This field appears only when the destination is Evidently . It specifies the ARN of the IAM role that is used to write to the Evidently experiment that receives the metrics.
NextToken (string) --
A token that you can use in a subsequent operation to retrieve the next set of results.
Deletes a destination for CloudWatch RUM extended metrics, so that the specified app monitor stops sending extended metrics to that destination.
See also: AWS API Documentation
Request Syntax
client.delete_rum_metrics_destination(
AppMonitorName='string',
Destination='CloudWatch'|'Evidently',
DestinationArn='string'
)
string
[REQUIRED]
The name of the app monitor that is sending metrics to the destination that you want to delete.
string
[REQUIRED]
The type of destination to delete. Valid values are CloudWatch and Evidently .
string
This parameter is required if Destination is Evidently . If Destination is CloudWatch , do not use this parameter. This parameter specifies the ARN of the Evidently experiment that corresponds to the destination to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
Modifies one existing metric definition for CloudWatch RUM extended metrics. For more information about extended metrics, see BatchCreateRumMetricsDefinitions.
See also: AWS API Documentation
Request Syntax
client.update_rum_metric_definition(
AppMonitorName='string',
Destination='CloudWatch'|'Evidently',
DestinationArn='string',
MetricDefinition={
'DimensionKeys': {
'string': 'string'
},
'EventPattern': 'string',
'Name': 'string',
'UnitLabel': 'string',
'ValueKey': 'string'
},
MetricDefinitionId='string'
)
string
[REQUIRED]
The name of the CloudWatch RUM app monitor that sends these metrics.
string
[REQUIRED]
The destination to send the metrics to. Valid values are CloudWatch and Evidently . If you specify Evidently , you must also specify the ARN of the CloudWatchEvidently experiment that will receive the metrics and an IAM role that has permission to write to the experiment.
string
This parameter is required if Destination is Evidently . If Destination is CloudWatch , do not use this parameter.
This parameter specifies the ARN of the Evidently experiment that is to receive the metrics. You must have already defined this experiment as a valid destination. For more information, see PutRumMetricsDestination.
dict
[REQUIRED]
A structure that contains the new definition that you want to use for this metric.
DimensionKeys (dict) --
Use this field only if you are sending the metric to CloudWatch.
This field is a map of field paths to dimension names. It defines the dimensions to associate with this metric in CloudWatch. Valid values for the entries in this field are the following:
"metadata.pageId": "PageId"
"metadata.browserName": "BrowserName"
"metadata.deviceType": "DeviceType"
"metadata.osName": "OSName"
"metadata.countryCode": "CountryCode"
"event_details.fileType": "FileType"
<p> All dimensions listed in this field must also be included in <code>EventPattern</code>.</p>
(string) --
(string) --
EventPattern (string) --
The pattern that defines the metric, specified as a JSON object. RUM checks events that happen in a user's session against the pattern, and events that match the pattern are sent to the metric destination.
When you define extended metrics, the metric definition is not valid if EventPattern is omitted.
Example event patterns:
'{ "event_type": ["com.amazon.rum.js_error_event"], "metadata": { "browserName": [ "Chrome", "Safari" ], } }'
'{ "event_type": ["com.amazon.rum.performance_navigation_event"], "metadata": { "browserName": [ "Chrome", "Firefox" ] }, "event_details": { "duration": [{ "numeric": [ "<", 2000 ] }] } }'
'{ "event_type": ["com.amazon.rum.performance_navigation_event"], "metadata": { "browserName": [ "Chrome", "Safari" ], "countryCode": [ "US" ] }, "event_details": { "duration": [{ "numeric": [ ">=", 2000, "<", 8000 ] }] } }'
If the metrics destination' is CloudWatch and the event also matches a value in DimensionKeys , then the metric is published with the specified dimensions.
Name (string) -- [REQUIRED]
The name for the metric that is defined in this structure. Valid values are the following:
PerformanceNavigationDuration
PerformanceResourceDuration
NavigationSatisfiedTransaction
NavigationToleratedTransaction
NavigationFrustratedTransaction
WebVitalsCumulativeLayoutShift
WebVitalsFirstInputDelay
WebVitalsLargestContentfulPaint
JsErrorCount
HttpErrorCount
SessionCount
UnitLabel (string) --
The CloudWatch metric unit to use for this metric. If you omit this field, the metric is recorded with no unit.
ValueKey (string) --
The field within the event object that the metric value is sourced from.
If you omit this field, a hardcoded value of 1 is pushed as the metric value. This is useful if you just want to count the number of events that the filter catches.
If this metric is sent to CloudWatch Evidently, this field will be passed to Evidently raw and Evidently will handle data extraction from the event.
string
[REQUIRED]
The ID of the metric definition to update.
dict
Response Syntax
{}
Response Structure
(dict) --
Removes the specified metrics from being sent to an extended metrics destination.
If some metric definition IDs specified in a BatchDeleteRumMetricDefinitions operations are not valid, those metric definitions fail and return errors, but all valid metric definition IDs in the same operation are still deleted.
The maximum number of metric definitions that you can specify in one BatchDeleteRumMetricDefinitions operation is 200.
See also: AWS API Documentation
Request Syntax
client.batch_delete_rum_metric_definitions(
AppMonitorName='string',
Destination='CloudWatch'|'Evidently',
DestinationArn='string',
MetricDefinitionIds=[
'string',
]
)
string
[REQUIRED]
The name of the CloudWatch RUM app monitor that is sending these metrics.
string
[REQUIRED]
Defines the destination where you want to stop sending the specified metrics. Valid values are CloudWatch and Evidently . If you specify Evidently , you must also specify the ARN of the CloudWatchEvidently experiment that is to be the destination and an IAM role that has permission to write to the experiment.
string
This parameter is required if Destination is Evidently . If Destination is CloudWatch , do not use this parameter.
This parameter specifies the ARN of the Evidently experiment that was receiving the metrics that are being deleted.
list
[REQUIRED]
An array of structures which define the metrics that you want to stop sending.
(string) --
dict
Response Syntax
{
'Errors': [
{
'ErrorCode': 'string',
'ErrorMessage': 'string',
'MetricDefinitionId': 'string'
},
],
'MetricDefinitionIds': [
'string',
]
}
Response Structure
(dict) --
Errors (list) --
An array of error objects, if the operation caused any errors.
(dict) --
A structure that defines one error caused by a BatchCreateRumMetricsDefinitions operation.
ErrorCode (string) --
The error code.
ErrorMessage (string) --
The error message for this metric definition.
MetricDefinitionId (string) --
The ID of the metric definition that caused this error.
MetricDefinitionIds (list) --
The IDs of the metric definitions that were deleted.
(string) --
Retrieves the list of metrics and dimensions that a RUM app monitor is sending to a single destination.
See also: AWS API Documentation
Request Syntax
client.batch_get_rum_metric_definitions(
AppMonitorName='string',
Destination='CloudWatch'|'Evidently',
DestinationArn='string',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The name of the CloudWatch RUM app monitor that is sending the metrics.
string
[REQUIRED]
The type of destination that you want to view metrics for. Valid values are CloudWatch and Evidently .
string
This parameter is required if Destination is Evidently . If Destination is CloudWatch , do not use this parameter.
This parameter specifies the ARN of the Evidently experiment that corresponds to the destination.
integer
The maximum number of results to return in one operation. The default is 50. The maximum that you can specify is 100.
To retrieve the remaining results, make another call with the returned NextToken value.
string
Use the token returned by the previous operation to request the next page of results.
dict
Response Syntax
{
'MetricDefinitions': [
{
'DimensionKeys': {
'string': 'string'
},
'EventPattern': 'string',
'MetricDefinitionId': 'string',
'Name': 'string',
'UnitLabel': 'string',
'ValueKey': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
MetricDefinitions (list) --
An array of structures that display information about the metrics that are sent by the specified app monitor to the specified destination.
(dict) --
A structure that displays the definition of one extended metric that RUM sends to CloudWatch or CloudWatch Evidently. For more information, see Additional metrics that you can send to CloudWatch and CloudWatch Evidently.
DimensionKeys (dict) --
This field is a map of field paths to dimension names. It defines the dimensions to associate with this metric in CloudWatch The value of this field is used only if the metric destination is CloudWatch . If the metric destination is Evidently , the value of DimensionKeys is ignored.
(string) --
(string) --
EventPattern (string) --
The pattern that defines the metric. RUM checks events that happen in a user's session against the pattern, and events that match the pattern are sent to the metric destination.
If the metrics destination is CloudWatch and the event also matches a value in DimensionKeys , then the metric is published with the specified dimensions.
MetricDefinitionId (string) --
The ID of this metric definition.
Name (string) --
The name of the metric that is defined in this structure.
UnitLabel (string) --
Use this field only if you are sending this metric to CloudWatch. It defines the CloudWatch metric unit that this metric is measured in.
ValueKey (string) --
The field within the event object that the metric value is sourced from.
NextToken (string) --
A token that you can use in a subsequent operation to retrieve the next set of results.