2025/09/16 - Amazon CloudWatch Logs - 4 updated api methods
Changes Cloudwatch Logs added support for 2 new API parameters in metric and subscription filter APIs to filter log events based on system field values and emit system field values as dimensions and send them to customer destination as additional metadata.
{'metricFilters': {'emitSystemFieldDimensions': ['string'],
'fieldSelectionCriteria': 'string'}}
Lists the specified metric filters. You can list all of the metric filters or filter the results by log name, prefix, metric name, or metric namespace. The results are ASCII-sorted by filter name.
See also: AWS API Documentation
Request Syntax
client.describe_metric_filters(
logGroupName='string',
filterNamePrefix='string',
nextToken='string',
limit=123,
metricName='string',
metricNamespace='string'
)
string
The name of the log group.
string
The prefix to match. CloudWatch Logs uses the value that you set here only if you also include the logGroupName parameter in your request.
string
The token for the next set of items to return. (You received this token from a previous call.)
integer
The maximum number of items returned. If you don't specify a value, the default is up to 50 items.
string
Filters results to include only those with the specified metric name. If you include this parameter in your request, you must also include the metricNamespace parameter.
string
Filters results to include only those in the specified namespace. If you include this parameter in your request, you must also include the metricName parameter.
dict
Response Syntax
{
'metricFilters': [
{
'filterName': 'string',
'filterPattern': 'string',
'metricTransformations': [
{
'metricName': 'string',
'metricNamespace': 'string',
'metricValue': 'string',
'defaultValue': 123.0,
'dimensions': {
'string': 'string'
},
'unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|'Gigabytes'|'Terabytes'|'Bits'|'Kilobits'|'Megabits'|'Gigabits'|'Terabits'|'Percent'|'Count'|'Bytes/Second'|'Kilobytes/Second'|'Megabytes/Second'|'Gigabytes/Second'|'Terabytes/Second'|'Bits/Second'|'Kilobits/Second'|'Megabits/Second'|'Gigabits/Second'|'Terabits/Second'|'Count/Second'|'None'
},
],
'creationTime': 123,
'logGroupName': 'string',
'applyOnTransformedLogs': True|False,
'fieldSelectionCriteria': 'string',
'emitSystemFieldDimensions': [
'string',
]
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
metricFilters (list) --
The metric filters.
(dict) --
Metric filters express how CloudWatch Logs would extract metric observations from ingested log events and transform them into metric data in a CloudWatch metric.
filterName (string) --
The name of the metric filter.
filterPattern (string) --
A symbolic description of how CloudWatch Logs should interpret the data in each log event. For example, a log event can contain timestamps, IP addresses, strings, and so on. You use the filter pattern to specify what to look for in the log event message.
metricTransformations (list) --
The metric transformations.
(dict) --
Indicates how to transform ingested log events to metric data in a CloudWatch metric.
metricName (string) --
The name of the CloudWatch metric.
metricNamespace (string) --
A custom namespace to contain your metric in CloudWatch. Use namespaces to group together metrics that are similar. For more information, see Namespaces.
metricValue (string) --
The value to publish to the CloudWatch metric when a filter pattern matches a log event.
defaultValue (float) --
(Optional) The value to emit when a filter pattern does not match a log event. This value can be null.
dimensions (dict) --
The fields to use as dimensions for the metric. One metric filter can include as many as three dimensions.
(string) --
(string) --
unit (string) --
The unit to assign to the metric. If you omit this, the unit is set as None.
creationTime (integer) --
The creation time of the metric filter, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
logGroupName (string) --
The name of the log group.
applyOnTransformedLogs (boolean) --
This parameter is valid only for log groups that have an active log transformer. For more information about log transformers, see PutTransformer.
If this value is true, the metric filter is applied on the transformed version of the log events instead of the original ingested log events.
fieldSelectionCriteria (string) --
The filter expression that specifies which log events are processed by this metric filter based on system fields. Returns the fieldSelectionCriteria value if it was specified when the metric filter was created.
emitSystemFieldDimensions (list) --
The list of system fields that are emitted as additional dimensions in the generated metrics. Returns the emitSystemFieldDimensions value if it was specified when the metric filter was created.
(string) --
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.
{'subscriptionFilters': {'emitSystemFields': ['string'],
'fieldSelectionCriteria': 'string'}}
Lists the subscription filters for the specified log group. You can list all the subscription filters or filter the results by prefix. The results are ASCII-sorted by filter name.
See also: AWS API Documentation
Request Syntax
client.describe_subscription_filters(
logGroupName='string',
filterNamePrefix='string',
nextToken='string',
limit=123
)
string
[REQUIRED]
The name of the log group.
string
The prefix to match. If you don't specify a value, no prefix filter is applied.
string
The token for the next set of items to return. (You received this token from a previous call.)
integer
The maximum number of items returned. If you don't specify a value, the default is up to 50 items.
dict
Response Syntax
{
'subscriptionFilters': [
{
'filterName': 'string',
'logGroupName': 'string',
'filterPattern': 'string',
'destinationArn': 'string',
'roleArn': 'string',
'distribution': 'Random'|'ByLogStream',
'applyOnTransformedLogs': True|False,
'creationTime': 123,
'fieldSelectionCriteria': 'string',
'emitSystemFields': [
'string',
]
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
subscriptionFilters (list) --
The subscription filters.
(dict) --
Represents a subscription filter.
filterName (string) --
The name of the subscription filter.
logGroupName (string) --
The name of the log group.
filterPattern (string) --
A symbolic description of how CloudWatch Logs should interpret the data in each log event. For example, a log event can contain timestamps, IP addresses, strings, and so on. You use the filter pattern to specify what to look for in the log event message.
destinationArn (string) --
The Amazon Resource Name (ARN) of the destination.
roleArn (string) --
distribution (string) --
The method used to distribute log data to the destination, which can be either random or grouped by log stream.
applyOnTransformedLogs (boolean) --
This parameter is valid only for log groups that have an active log transformer. For more information about log transformers, see PutTransformer.
If this value is true, the subscription filter is applied on the transformed version of the log events instead of the original ingested log events.
creationTime (integer) --
The creation time of the subscription filter, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
fieldSelectionCriteria (string) --
The filter expression that specifies which log events are processed by this subscription filter based on system fields. Returns the fieldSelectionCriteria value if it was specified when the subscription filter was created.
emitSystemFields (list) --
The list of system fields that are included in the log events sent to the subscription destination. Returns the emitSystemFields value if it was specified when the subscription filter was created.
(string) --
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.
{'emitSystemFieldDimensions': ['string'], 'fieldSelectionCriteria': 'string'}
Creates or updates a metric filter and associates it with the specified log group. With metric filters, you can configure rules to extract metric data from log events ingested through PutLogEvents.
The maximum number of metric filters that can be associated with a log group is 100.
Using regular expressions in filter patterns is supported. For these filters, there is a quota of two regular expression patterns within a single filter pattern. There is also a quota of five regular expression patterns per log group. For more information about using regular expressions in filter patterns, see Filter pattern syntax for metric filters, subscription filters, filter log events, and Live Tail.
When you create a metric filter, you can also optionally assign a unit and dimensions to the metric that is created.
See also: AWS API Documentation
Request Syntax
client.put_metric_filter(
logGroupName='string',
filterName='string',
filterPattern='string',
metricTransformations=[
{
'metricName': 'string',
'metricNamespace': 'string',
'metricValue': 'string',
'defaultValue': 123.0,
'dimensions': {
'string': 'string'
},
'unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|'Gigabytes'|'Terabytes'|'Bits'|'Kilobits'|'Megabits'|'Gigabits'|'Terabits'|'Percent'|'Count'|'Bytes/Second'|'Kilobytes/Second'|'Megabytes/Second'|'Gigabytes/Second'|'Terabytes/Second'|'Bits/Second'|'Kilobits/Second'|'Megabits/Second'|'Gigabits/Second'|'Terabits/Second'|'Count/Second'|'None'
},
],
applyOnTransformedLogs=True|False,
fieldSelectionCriteria='string',
emitSystemFieldDimensions=[
'string',
]
)
string
[REQUIRED]
The name of the log group.
string
[REQUIRED]
A name for the metric filter.
string
[REQUIRED]
A filter pattern for extracting metric data out of ingested log events.
list
[REQUIRED]
A collection of information that defines how metric data gets emitted.
(dict) --
Indicates how to transform ingested log events to metric data in a CloudWatch metric.
metricName (string) -- [REQUIRED]
The name of the CloudWatch metric.
metricNamespace (string) -- [REQUIRED]
A custom namespace to contain your metric in CloudWatch. Use namespaces to group together metrics that are similar. For more information, see Namespaces.
metricValue (string) -- [REQUIRED]
The value to publish to the CloudWatch metric when a filter pattern matches a log event.
defaultValue (float) --
(Optional) The value to emit when a filter pattern does not match a log event. This value can be null.
dimensions (dict) --
The fields to use as dimensions for the metric. One metric filter can include as many as three dimensions.
(string) --
(string) --
unit (string) --
The unit to assign to the metric. If you omit this, the unit is set as None.
boolean
This parameter is valid only for log groups that have an active log transformer. For more information about log transformers, see PutTransformer.
If the log group uses either a log-group level or account-level transformer, and you specify true, the metric filter will be applied on the transformed version of the log events instead of the original ingested log events.
string
A filter expression that specifies which log events should be processed by this metric filter based on system fields such as source account and source region. Uses selection criteria syntax with operators like =, !=, AND, OR, IN, NOT IN. Example: @aws.region = "us-east-1" or @aws.account IN ["123456789012", "987654321098"]. Maximum length: 2000 characters.
list
A list of system fields to emit as additional dimensions in the generated metrics. Valid values are @aws.account and @aws.region. These dimensions help identify the source of centralized log data and count toward the total dimension limit for metric filters.
(string) --
None
{'emitSystemFields': ['string'], 'fieldSelectionCriteria': 'string'}
Creates or updates a subscription filter and associates it with the specified log group. With subscription filters, you can subscribe to a real-time stream of log events ingested through PutLogEvents and have them delivered to a specific destination. When log events are sent to the receiving service, they are Base64 encoded and compressed with the GZIP format.
The following destinations are supported for subscription filters:
An Amazon Kinesis data stream belonging to the same account as the subscription filter, for same-account delivery.
A logical destination created with PutDestination that belongs to a different account, for cross-account delivery. We currently support Kinesis Data Streams and Firehose as logical destinations.
An Amazon Kinesis Data Firehose delivery stream that belongs to the same account as the subscription filter, for same-account delivery.
An Lambda function that belongs to the same account as the subscription filter, for same-account delivery.
Each log group can have up to two subscription filters associated with it. If you are updating an existing filter, you must specify the correct name in filterName.
Using regular expressions in filter patterns is supported. For these filters, there is a quotas of quota of two regular expression patterns within a single filter pattern. There is also a quota of five regular expression patterns per log group. For more information about using regular expressions in filter patterns, see Filter pattern syntax for metric filters, subscription filters, filter log events, and Live Tail.
To perform a PutSubscriptionFilter operation for any destination except a Lambda function, you must also have the iam:PassRole permission.
See also: AWS API Documentation
Request Syntax
client.put_subscription_filter(
logGroupName='string',
filterName='string',
filterPattern='string',
destinationArn='string',
roleArn='string',
distribution='Random'|'ByLogStream',
applyOnTransformedLogs=True|False,
fieldSelectionCriteria='string',
emitSystemFields=[
'string',
]
)
string
[REQUIRED]
The name of the log group.
string
[REQUIRED]
A name for the subscription filter. If you are updating an existing filter, you must specify the correct name in filterName. To find the name of the filter currently associated with a log group, use DescribeSubscriptionFilters.
string
[REQUIRED]
A filter pattern for subscribing to a filtered stream of log events.
string
[REQUIRED]
The ARN of the destination to deliver matching log events to. Currently, the supported destinations are:
An Amazon Kinesis stream belonging to the same account as the subscription filter, for same-account delivery.
A logical destination (specified using an ARN) belonging to a different account, for cross-account delivery. If you're setting up a cross-account subscription, the destination must have an IAM policy associated with it. The IAM policy must allow the sender to send logs to the destination. For more information, see PutDestinationPolicy.
A Kinesis Data Firehose delivery stream belonging to the same account as the subscription filter, for same-account delivery.
A Lambda function belonging to the same account as the subscription filter, for same-account delivery.
string
The ARN of an IAM role that grants CloudWatch Logs permissions to deliver ingested log events to the destination stream. You don't need to provide the ARN when you are working with a logical destination for cross-account delivery.
string
The method used to distribute log data to the destination. By default, log data is grouped by log stream, but the grouping can be set to random for a more even distribution. This property is only applicable when the destination is an Amazon Kinesis data stream.
boolean
This parameter is valid only for log groups that have an active log transformer. For more information about log transformers, see PutTransformer.
If the log group uses either a log-group level or account-level transformer, and you specify true, the subscription filter will be applied on the transformed version of the log events instead of the original ingested log events.
string
A filter expression that specifies which log events should be processed by this subscription filter based on system fields such as source account and source region. Uses selection criteria syntax with operators like =, !=, AND, OR, IN, NOT IN. Example: @aws.region NOT IN ["cn-north-1"] or @aws.account = "123456789012" AND @aws.region = "us-east-1". Maximum length: 2000 characters.
list
A list of system fields to include in the log events sent to the subscription destination. Valid values are @aws.account and @aws.region. These fields provide source information for centralized log data in the forwarded payload.
(string) --
None