log_groups

Creates, updates, deletes, gets or lists a log_groups resource.

Overview

Name	log_groups
Type	Resource
Id	aws.logs.log_groups

Fields

The following fields are returned by SELECT queries:

describe_log_groups

Name	Datatype	Description
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 :*.
bearer_token_authentication_enabled	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.
creation_time	integer (int64)	The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
data_protection_status	string	Displays whether this log group has a protection policy, or whether it had one in the past. For more information, see PutDataProtectionPolicy. (ACTIVATED, DELETED, ARCHIVED, DISABLED)
deletion_protection_enabled	boolean	Indicates whether deletion protection is enabled for this log group. When enabled, deletion protection blocks all deletion operations until it is explicitly disabled.
inherited_properties	array	Displays all the properties that this log group has inherited from account-level settings.
kms_key_id	string	The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data.
log_group_arn	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.
log_group_class	string	This specifies the log group class for this log group. There are three 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. 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 and Infrequent Access classes, see Log classes (STANDARD, INFREQUENT_ACCESS, DELIVERY)
log_group_name	string	The name of the log group. (pattern: <code>[.-_/#A-Za-z0-9]+</code>)
metric_filter_count	integer	The number of metric filters.
retention_in_days	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.
stored_bytes	integer (int64)	The number of bytes stored.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_log_groups	select	region		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. 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.
create_log_group	insert	region, logGroupName		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. CloudWatch Logs supports only symmetric KMS keys. Do not associate an asymmetric KMS key with your log group. For more information, see Using Symmetric and Asymmetric Keys.
put_bearer_token_authentication	replace	region, logGroupIdentifier, bearerTokenAuthenticationEnabled		Enables or disables bearer token authentication for the specified log group. When enabled on a log group, bearer token authentication is enabled on operations until it is explicitly disabled. For information about the parameters that are common to all actions, see Common Parameters.
put_log_group_deletion_protection	replace	region, logGroupIdentifier, deletionProtectionEnabled		Enables or disables deletion protection for the specified log group. When enabled on a log group, deletion protection blocks all deletion operations until it is explicitly disabled. For information about the parameters that are common to all actions, see Common Parameters.
put_retention_policy	replace	region, logGroupName, retentionInDays		Sets the retention of the specified log group. With a retention policy, you can configure the number of days for which to retain log events in the specified log group. CloudWatch Logs doesn't immediately delete log events when they reach their retention setting. It typically takes up to 72 hours after that before log events are deleted, but in rare situations might take longer. To illustrate, imagine that you change a log group to have a longer retention setting when it contains log events that are past the expiration date, but haven't been deleted. Those log events will take up to 72 hours to be deleted after the new retention date is reached. To make sure that log data is deleted permanently, keep a log group at its lower retention setting until 72 hours after the previous retention period ends. Alternatively, wait to change the retention setting until you confirm that the earlier log events are deleted. When log events reach their retention setting they are marked for deletion. After they are marked for deletion, they do not add to your archival storage costs anymore, even if they are not actually deleted until later. These log events marked for deletion are also not included when you use an API to retrieve the storedBytes value to see how many bytes a log group is storing.
delete_log_group	delete	region		Deletes the specified log group and permanently deletes all the archived log events associated with the log group.
delete_retention_policy	exec	region, logGroupName		Deletes the specified retention policy. Log events do not expire if they belong to log groups without a retention policy.
list_log_groups	exec	region		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.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_log_groups

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. 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.

SELECT
arn,
bearer_token_authentication_enabled,
creation_time,
data_protection_status,
deletion_protection_enabled,
inherited_properties,
kms_key_id,
log_group_arn,
log_group_class,
log_group_name,
metric_filter_count,
retention_in_days,
stored_bytes
FROM aws.logs.log_groups
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_log_group

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. CloudWatch Logs supports only symmetric KMS keys. Do not associate an asymmetric KMS key with your log group. For more information, see Using Symmetric and Asymmetric Keys.

INSERT INTO aws.logs.log_groups (
logGroupName,
kmsKeyId,
tags,
logGroupClass,
deletionProtectionEnabled,
region
)
SELECT 
'{{ logGroupName }}' /* required */,
'{{ kmsKeyId }}',
'{{ tags }}',
'{{ logGroupClass }}',
{{ deletionProtectionEnabled }},
'{{ region }}'
;

Manifest

# Description fields are for documentation purposes
- name: log_groups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the log_groups resource.
  - name: logGroupName
    value: "{{ logGroupName }}"
    description: |
      A name for the log group.
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"
    description: |
      The Amazon Resource Name (ARN) of the KMS key to use when encrypting log data. For more information, see Amazon Resource Names.
  - name: tags
    value: "{{ tags }}"
    description: |
      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.
  - name: logGroupClass
    value: "{{ logGroupClass }}"
    description: |
      Use this parameter to specify the log group class for this log group. There are three 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. 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. The value of logGroupClass can't be changed after a log group is created. For details about the features supported by each class, see Log classes
    valid_values: ['STANDARD', 'INFREQUENT_ACCESS', 'DELIVERY']
  - name: deletionProtectionEnabled
    value: {{ deletionProtectionEnabled }}
    description: |
      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.

REPLACE examples

put_bearer_token_authentication

Enables or disables bearer token authentication for the specified log group. When enabled on a log group, bearer token authentication is enabled on operations until it is explicitly disabled. For information about the parameters that are common to all actions, see Common Parameters.

REPLACE aws.logs.log_groups
SET 
logGroupIdentifier = '{{ logGroupIdentifier }}',
bearerTokenAuthenticationEnabled = {{ bearerTokenAuthenticationEnabled }}
WHERE 
region = '{{ region }}' --required
AND logGroupIdentifier = '{{ logGroupIdentifier }}' --required
AND bearerTokenAuthenticationEnabled = {{ bearerTokenAuthenticationEnabled }} --required;

put_log_group_deletion_protection

Enables or disables deletion protection for the specified log group. When enabled on a log group, deletion protection blocks all deletion operations until it is explicitly disabled. For information about the parameters that are common to all actions, see Common Parameters.

REPLACE aws.logs.log_groups
SET 
logGroupIdentifier = '{{ logGroupIdentifier }}',
deletionProtectionEnabled = {{ deletionProtectionEnabled }}
WHERE 
region = '{{ region }}' --required
AND logGroupIdentifier = '{{ logGroupIdentifier }}' --required
AND deletionProtectionEnabled = {{ deletionProtectionEnabled }} --required;

put_retention_policy

Sets the retention of the specified log group. With a retention policy, you can configure the number of days for which to retain log events in the specified log group. CloudWatch Logs doesn't immediately delete log events when they reach their retention setting. It typically takes up to 72 hours after that before log events are deleted, but in rare situations might take longer. To illustrate, imagine that you change a log group to have a longer retention setting when it contains log events that are past the expiration date, but haven't been deleted. Those log events will take up to 72 hours to be deleted after the new retention date is reached. To make sure that log data is deleted permanently, keep a log group at its lower retention setting until 72 hours after the previous retention period ends. Alternatively, wait to change the retention setting until you confirm that the earlier log events are deleted. When log events reach their retention setting they are marked for deletion. After they are marked for deletion, they do not add to your archival storage costs anymore, even if they are not actually deleted until later. These log events marked for deletion are also not included when you use an API to retrieve the storedBytes value to see how many bytes a log group is storing.

REPLACE aws.logs.log_groups
SET 
logGroupName = '{{ logGroupName }}',
retentionInDays = {{ retentionInDays }}
WHERE 
region = '{{ region }}' --required
AND logGroupName = '{{ logGroupName }}' --required
AND retentionInDays = '{{ retentionInDays }}' --required;

DELETE examples

delete_log_group

Deletes the specified log group and permanently deletes all the archived log events associated with the log group.

DELETE FROM aws.logs.log_groups
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

delete_retention_policy

Deletes the specified retention policy. Log events do not expire if they belong to log groups without a retention policy.

EXEC aws.logs.log_groups.delete_retention_policy 
@region='{{ region }}' --required 
@@json=
'{
"logGroupName": "{{ logGroupName }}"
}'
;

list_log_groups

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.

EXEC aws.logs.log_groups.list_log_groups 
@region='{{ region }}' --required 
@@json=
'{
"logGroupNamePattern": "{{ logGroupNamePattern }}", 
"logGroupClass": "{{ logGroupClass }}", 
"includeLinkedAccounts": {{ includeLinkedAccounts }}, 
"accountIdentifiers": "{{ accountIdentifiers }}", 
"nextToken": "{{ nextToken }}", 
"limit": {{ limit }}, 
"dataSources": "{{ dataSources }}", 
"fieldIndexNames": "{{ fieldIndexNames }}", 
"logGroupTags": "{{ logGroupTags }}"
}'
;