2026/11/05 - Amazon CloudWatch Logs - 4 updated api methods
Changes Adds account-level retention policies with dry run preview and the Essentials log group class to Amazon CloudWatch Logs
{'logGroupClass': {'ESSENTIALS'}}
Creates a log group with the specified name. You can create up to 1,000,000 log groups per Region per account.
You must use the following guidelines when naming a log group:
Log group names must be unique within a Region for an Amazon Web Services account.
Log group names can be between 1 and 512 characters long.
Log group names consist of the following characters: a-z, A-Z, 0-9, '_' (underscore), '-' (hyphen), '/' (forward slash), '.' (period), and '#' (number sign)
Log group names can't start with the string aws/
When you create a log group, by default the log events in the log group do not expire. To set a retention policy so that events expire and are deleted after a specified time, use PutRetentionPolicy.
If you associate an KMS key with the log group, ingested data is encrypted using the KMS key. This association is stored as long as the data encrypted with the KMS key is still within CloudWatch Logs. This enables CloudWatch Logs to decrypt this data whenever it is requested.
If you attempt to associate a KMS key with the log group but the KMS key does not exist or the KMS key is disabled, you receive an InvalidParameterException error.
See also: AWS API Documentation
Request Syntax
client.create_log_group(
logGroupName='string',
kmsKeyId='string',
tags={
'string': 'string'
},
logGroupClass='STANDARD'|'INFREQUENT_ACCESS'|'DELIVERY'|'ESSENTIALS',
deletionProtectionEnabled=True|False
)
string
[REQUIRED]
A name for the log group.
string
The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data. For more information, see Amazon Resource Names.
dict
The key-value pairs to use for the tags.
You can grant users access to certain log groups while preventing them from accessing other log groups. To do so, tag your groups and use IAM policies that refer to those tags. To assign tags when you create a log group, you must have either the logs:TagResource or logs:TagLogGroup permission. For more information about tagging, see Tagging Amazon Web Services resources. For more information about using tags to control access, see Controlling access to Amazon Web Services resources using tags.
(string) --
(string) --
string
Use this parameter to specify the log group class for this log group. There are four classes:
The Standard log class supports all CloudWatch Logs features.
The Infrequent Access log class supports a subset of CloudWatch Logs features and incurs lower costs.
The Essentials log class supports a subset of CloudWatch Logs features and incurs lower costs.
Use the Delivery log class only for delivering Lambda logs to store in Amazon S3 or Amazon Data Firehose. Log events in log groups in the Delivery class are kept in CloudWatch Logs for only one day. This log class doesn't offer rich CloudWatch Logs capabilities such as CloudWatch Logs Insights queries.
If you omit this parameter, the default of STANDARD is used.
For details about the features supported by each class, see Log classes
boolean
Use this parameter to enable deletion protection for the new log group. When enabled on a log group, deletion protection blocks all deletion operations until it is explicitly disabled. By default log groups are created without deletion protection enabled.
None
{'logGroupClass': {'ESSENTIALS'}}
Response {'logGroups': {'logGroupClass': {'ESSENTIALS'}}}
Returns information about log groups, including data sources that ingest into each log group. You can return all your log groups or filter the results by prefix. The results are ASCII-sorted by log group name.
If an account-level retention policy applies to a log group, retentionInDays shows the retention period from that policy, and retentionPolicyName shows the name of the policy.
CloudWatch Logs doesn't support IAM policies that control access to the DescribeLogGroups action by using the aws:ResourceTag/key-name condition key. Other CloudWatch Logs actions do support the use of the aws:ResourceTag/key-name condition key to control access. For more information about using tags to control access, see Controlling access to Amazon Web Services resources using tags.
If you are using CloudWatch cross-account observability, you can use this operation in a monitoring account and view data from the linked source accounts. For more information, see CloudWatch cross-account observability.
See also: AWS API Documentation
Request Syntax
client.describe_log_groups(
accountIdentifiers=[
'string',
],
logGroupNamePrefix='string',
logGroupNamePattern='string',
nextToken='string',
limit=123,
includeLinkedAccounts=True|False,
logGroupClass='STANDARD'|'INFREQUENT_ACCESS'|'DELIVERY'|'ESSENTIALS',
logGroupIdentifiers=[
'string',
]
)
list
When includeLinkedAccounts is set to true, use this parameter to specify the list of accounts to search. You can specify as many as 20 account IDs in the array.
(string) --
string
The prefix to match.
string
If you specify a string for this parameter, the operation returns only log groups that have names that match the string based on a case-sensitive substring search. For example, if you specify DataLogs, log groups named DataLogs, aws/DataLogs, and GroupDataLogs would match, but datalogs, Data/log/s and Groupdata would not match.
If you specify logGroupNamePattern in your request, then only arn, creationTime, and logGroupName are included in the response.
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.
boolean
If you are using a monitoring account, set this to true to have the operation return log groups in the accounts listed in accountIdentifiers.
If this parameter is set to true and accountIdentifiers contains a null value, the operation returns all log groups in the monitoring account and all log groups in all source accounts that are linked to the monitoring account.
The default for this parameter is false.
string
Use this parameter to limit the results to only those log groups in the specified log group class. If you omit this parameter, log groups of all classes can be returned.
If you specify either INFREQUENT_ACCESS or ESSENTIALS, the results include log groups in both the Infrequent Access and Essentials log classes.
Specifies the log group class for this log group. There are four classes:
The Standard log class supports all CloudWatch Logs features.
The Infrequent Access log class supports a subset of CloudWatch Logs features and incurs lower costs.
The Essentials log class supports a subset of CloudWatch Logs features and incurs lower costs.
Use the Delivery log class only for delivering Lambda logs to store in Amazon S3 or Amazon Data Firehose. Log events in log groups in the Delivery class are kept in CloudWatch Logs for only one day. This log class doesn't offer rich CloudWatch Logs capabilities such as CloudWatch Logs Insights queries.
For details about the features supported by each class, see Log classes
list
Use this array to filter the list of log groups returned. If you specify this parameter, the only other filter that you can choose to specify is includeLinkedAccounts.
If you are using this operation in a monitoring account, you can specify the ARNs of log groups in source accounts and in the monitoring account itself. If you are using this operation in an account that is not a cross-account monitoring account, you can specify only log group names in the same account as the operation.
(string) --
dict
Response Syntax
{
'logGroups': [
{
'logGroupName': 'string',
'creationTime': 123,
'retentionInDays': 123,
'metricFilterCount': 123,
'arn': 'string',
'storedBytes': 123,
'kmsKeyId': 'string',
'dataProtectionStatus': 'ACTIVATED'|'DELETED'|'ARCHIVED'|'DISABLED',
'inheritedProperties': [
'ACCOUNT_DATA_PROTECTION',
],
'logGroupClass': 'STANDARD'|'INFREQUENT_ACCESS'|'DELIVERY'|'ESSENTIALS',
'logGroupArn': 'string',
'deletionProtectionEnabled': True|False,
'bearerTokenAuthenticationEnabled': True|False,
'retentionPolicyName': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
logGroups (list) --
An array of structures, where each structure contains the information about one log group.
(dict) --
Represents a log group.
logGroupName (string) --
The name of the log group.
creationTime (integer) --
The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
retentionInDays (integer) --
The number of days to retain the log events in the specified log group. Possible values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, and 3653.
To set a log group so that its log events do not expire, use DeleteRetentionPolicy.
metricFilterCount (integer) --
The number of metric filters.
arn (string) --
The Amazon Resource Name (ARN) of the log group. This version of the ARN includes a trailing :* after the log group name.
Use this version to refer to the ARN in IAM policies when specifying permissions for most API actions. The exception is when specifying permissions for TagResource, UntagResource, and ListTagsForResource. The permissions for those three actions require the ARN version that doesn't include a trailing :*.
storedBytes (integer) --
The number of bytes stored.
kmsKeyId (string) --
The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data.
dataProtectionStatus (string) --
Displays whether this log group has a protection policy, or whether it had one in the past. For more information, see PutDataProtectionPolicy.
inheritedProperties (list) --
Displays all the properties that this log group has inherited from account-level settings.
(string) --
logGroupClass (string) --
This specifies the log group class for this log group. There are four classes:
The Standard log class supports all CloudWatch Logs features.
The Infrequent Access log class supports a subset of CloudWatch Logs features and incurs lower costs.
The Essentials log class supports a subset of CloudWatch Logs features and incurs lower costs.
Use the Delivery log class only for delivering Lambda logs to store in Amazon S3 or Amazon Data Firehose. Log events in log groups in the Delivery class are kept in CloudWatch Logs for only one day. This log class doesn't offer rich CloudWatch Logs capabilities such as CloudWatch Logs Insights queries.
For details about the features supported by the Standard, Infrequent Access, and Essentials classes, see Log classes
logGroupArn (string) --
The Amazon Resource Name (ARN) of the log group. This version of the ARN doesn't include a trailing :* after the log group name.
Use this version to refer to the ARN in the following situations:
In the logGroupIdentifier input field in many CloudWatch Logs APIs.
In the resourceArn field in tagging APIs
In IAM policies, when specifying permissions for TagResource, UntagResource, and ListTagsForResource.
deletionProtectionEnabled (boolean) --
Indicates whether deletion protection is enabled for this log group. When enabled, deletion protection blocks all deletion operations until it is explicitly disabled.
bearerTokenAuthenticationEnabled (boolean) --
Indicates whether bearer token authentication is enabled for this log group. When enabled, bearer token authentication is allowed on operations until it is explicitly disabled.
retentionPolicyName (string) --
The name of the account-level retention policy that determines the retention period of this log group. This field is returned only when an account-level retention policy applies to the log group. When it is returned, retentionInDays shows the retention period from that policy instead of the retention period set on the log group. If the policy specifies that log events never expire, retentionInDays is not returned.
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.
{'logGroupClass': {'ESSENTIALS'}}
Returns an aggregate summary of all log groups in the Region grouped by specified data source characteristics. Supports optional filtering by log group class, name patterns, and data sources. If you perform this action in a monitoring account, you can also return aggregated summaries of log groups from source accounts that are linked to the monitoring account. For more information about using cross-account observability to set up monitoring accounts and source accounts, see CloudWatch cross-account observability.
The operation aggregates log groups by data source name and type and optionally format, providing counts of log groups that share these characteristics. The operation paginates results. By default, it returns up to 50 results and includes a token to retrieve more results.
See also: AWS API Documentation
Request Syntax
client.list_aggregate_log_group_summaries(
accountIdentifiers=[
'string',
],
includeLinkedAccounts=True|False,
logGroupClass='STANDARD'|'INFREQUENT_ACCESS'|'DELIVERY'|'ESSENTIALS',
logGroupNamePattern='string',
dataSources=[
{
'name': 'string',
'type': 'string'
},
],
groupBy='DATA_SOURCE_NAME_TYPE_AND_FORMAT'|'DATA_SOURCE_NAME_AND_TYPE',
nextToken='string',
limit=123
)
list
When includeLinkedAccounts is set to true, use this parameter to specify the list of accounts to search. You can specify as many as 20 account IDs in the array.
(string) --
boolean
If you are using a monitoring account, set this to true to have the operation return log groups in the accounts listed in accountIdentifiers.
If this parameter is set to true and accountIdentifiers contains a null value, the operation returns all log groups in the monitoring account and all log groups in all source accounts that are linked to the monitoring account.
The default for this parameter is false.
string
Filters the results by log group class to include only log groups of the specified class.
string
Use this parameter to limit the returned log groups to only those with names that match the pattern that you specify. This parameter is a regular expression that can match prefixes and substrings, and supports wildcard matching and matching multiple patterns, as in the following examples.
Use ^ to match log group names by prefix.
For a substring match, specify the string to match. All matches are case sensitive
To match multiple patterns, separate them with a | as in the example ^/aws/lambda|discovery
You can specify as many as five different regular expression patterns in this field, each of which must be between 3 and 24 characters. You can include the ^ symbol as many as five times, and include the | symbol as many as four times.
list
Filters the results by data source characteristics to include only log groups associated with the specified data sources.
(dict) --
Filter criteria for data sources, used to specify which data sources to include in operations based on name and type.
name (string) -- [REQUIRED]
The name pattern to filter data sources by.
type (string) --
The type pattern to filter data sources by.
string
[REQUIRED]
Specifies how to group the log groups in the summary.
string
The token for the next set of items to return. The token expires after 24 hours.
integer
The maximum number of aggregated summaries to return. If you omit this parameter, the default is up to 50 aggregated summaries.
dict
Response Syntax
{
'aggregateLogGroupSummaries': [
{
'logGroupCount': 123,
'groupingIdentifiers': [
{
'key': 'string',
'value': 'string'
},
]
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
aggregateLogGroupSummaries (list) --
The list of aggregate log group summaries grouped by the specified data source characteristics.
(dict) --
Contains an aggregate summary of log groups grouped by data source characteristics, including the count of log groups and their grouping identifiers.
logGroupCount (integer) --
The number of log groups in this aggregate summary group.
groupingIdentifiers (list) --
An array of key-value pairs that identify the data source characteristics used to group the log groups.
The size and content of this array depends on the groupBy parameter specified in the request.
(dict) --
A key-value pair that identifies how log groups are grouped in aggregate summaries.
key (string) --
The key that identifies the grouping characteristic. The format of the key uses dot notation. Examples are, dataSource.Name, dataSource.Type, and dataSource.Format.
value (string) --
The value associated with the grouping characteristic. Examples are amazon_vpc, flow, and OCSF.
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.
{'logGroupClass': {'ESSENTIALS'}}
Response {'logGroups': {'logGroupClass': {'ESSENTIALS'}}}
Returns a list of log groups in the Region in your account. If you are performing this action in a monitoring account, you can choose to also return log groups from source accounts that are linked to the monitoring account. For more information about using cross-account observability to set up monitoring accounts and source accounts, see CloudWatch cross-account observability.
You can optionally filter the results by log group class, log group name pattern, field indexes, data sources, field index names, or log group tags. If you specify more than one filter type, the results include log groups that satisfy all filters.
This operation is paginated. By default, your first use of this operation returns 50 results, and includes a token to use in a subsequent operation to return more results.
See also: AWS API Documentation
Request Syntax
client.list_log_groups(
logGroupNamePattern='string',
logGroupClass='STANDARD'|'INFREQUENT_ACCESS'|'DELIVERY'|'ESSENTIALS',
includeLinkedAccounts=True|False,
accountIdentifiers=[
'string',
],
nextToken='string',
limit=123,
dataSources=[
{
'name': 'string',
'type': 'string'
},
],
fieldIndexNames=[
'string',
],
logGroupTags=[
{
'key': 'string',
'values': [
'string',
]
},
]
)
string
Use this parameter to limit the returned log groups to only those with names that match the pattern that you specify. This parameter is a regular expression that can match prefixes and substrings, and supports wildcard matching and matching multiple patterns, as in the following examples.
Use ^ to match log group names by prefix.
For a substring match, specify the string to match. All matches are case sensitive
To match multiple patterns, separate them with a | as in the example ^/aws/lambda|discovery
You can specify as many as five different regular expression patterns in this field, each of which must be between 3 and 24 characters. You can include the ^ symbol as many as five times, and include the | symbol as many as four times.
string
Use this parameter to limit the results to only those log groups in the specified log group class. If you omit this parameter, log groups of all classes can be returned.
boolean
If you are using a monitoring account, set this to true to have the operation return log groups in the accounts listed in accountIdentifiers.
If this parameter is set to true and accountIdentifiers contains a null value, the operation returns all log groups in the monitoring account and all log groups in all source accounts that are linked to the monitoring account.
The default for this parameter is false.
list
When includeLinkedAccounts is set to true, use this parameter to specify the list of accounts to search. You can specify as many as 20 account IDs in the array.
(string) --
string
The token for the next set of items to return. The token expires after 24 hours.
integer
The maximum number of log groups to return. If you omit this parameter, the default is up to 50 log groups.
list
An array of data source filters to filter log groups by their associated data sources. You can filter by data source name, type, or both. Multiple filters within the same dimension are combined with OR logic, while filters across different dimensions are combined with AND logic.
(dict) --
Filter criteria for data sources, used to specify which data sources to include in operations based on name and type.
name (string) -- [REQUIRED]
The name pattern to filter data sources by.
type (string) --
The type pattern to filter data sources by.
list
An array of field index names to filter log groups that have specific field indexes. Only log groups containing all specified field indexes are returned. You can specify 1 to 20 field index names, each with 1 to 512 characters.
(string) --
list
An array of tag filters to return only log groups that have specific tags. Multiple filters are combined with AND logic.
(dict) --
A tag filter that specifies a tag key and optional tag values for filtering log groups by tags.
key (string) -- [REQUIRED]
The tag key to filter on.
values (list) --
An optional list of tag values to filter on.
If you specify a filter that contains more than one value for a key, the response returns log groups that match any of the specified values for that key.
If you don't specify values, the response returns all log groups that are tagged with that key, with any or no value.
Use * for wildcard matching. For example, prod* matches values that start with prod.
Use ! as a prefix for negation. For example, !prod matches values that are not prod.
Exact matching and negation are case-sensitive. Wildcard matching is case-insensitive.
(string) --
dict
Response Syntax
{
'logGroups': [
{
'logGroupName': 'string',
'logGroupArn': 'string',
'logGroupClass': 'STANDARD'|'INFREQUENT_ACCESS'|'DELIVERY'|'ESSENTIALS'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
logGroups (list) --
An array of structures, where each structure contains the information about one log group.
(dict) --
This structure contains information about one log group in your account.
logGroupName (string) --
The name of the log group.
logGroupArn (string) --
The Amazon Resource Name (ARN) of the log group.
logGroupClass (string) --
The log group class for this log group. For details about the features supported by each log group class, see Log classes
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.