Skip to main content

trails

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

Overview​

Nametrails
TypeResource
Idaws.cloudtrail.trails

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
trail_listarrayThe list of trail objects. Trail objects with string values are only returned if values for the objects exist in a trail's configuration. For example, SNSTopicName and SNSTopicARN are only returned in results if a trail is configured to send SNS notifications. Similarly, KMSKeyId only appears in results if a trail's log files are encrypted with KMS customer managed keys.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_trailsselectregionRetrieves settings for one or more trails associated with the current Region for your account.
create_trailinsertregion, S3BucketNameCreates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket.
update_trailupdateregionUpdates trail settings that control what events you are logging, and how to handle log files. Changes to a trail do not require stopping the CloudTrail service. Use this action to designate an existing bucket for log delivery. If the existing bucket has previously been a target for CloudTrail log files, an IAM policy exists for the bucket. UpdateTrail must be called from the Region in which the trail was created; otherwise, an InvalidHomeRegionException is thrown.
delete_traildeleteregionDeletes a trail. This operation must be called from the Region in which the trail was created. DeleteTrail cannot be called on the shadow trails (replicated trails in other Regions) of a trail that is enabled in all Regions. While deleting a CloudTrail trail is an irreversible action, CloudTrail does not delete log files in the Amazon S3 bucket for that trail, the Amazon S3 bucket itself, or the CloudWatchlog group to which the trail delivers events. Deleting a multi-Region trail will stop logging of events in all Amazon Web Services Regions enabled in your Amazon Web Services account. Deleting a single-Region trail will stop logging of events in that Region only. It will not stop logging of events in other Regions even if the trails in those other Regions have identical names to the deleted trail. For information about account closure and deletion of CloudTrail trails, see https:​//docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-account-closure.html.
get_trailexecregionReturns settings information for a specified trail.
list_trailsexecregionLists trails that are in the current account.

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.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Retrieves settings for one or more trails associated with the current Region for your account.

SELECT
trail_list
FROM aws.cloudtrail.trails
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates a trail that specifies the settings for delivery of log data to an Amazon S3 bucket.

INSERT INTO aws.cloudtrail.trails (
Name,
S3BucketName,
S3KeyPrefix,
SnsTopicName,
IncludeGlobalServiceEvents,
IsMultiRegionTrail,
EnableLogFileValidation,
CloudWatchLogsLogGroupArn,
CloudWatchLogsRoleArn,
KmsKeyId,
IsOrganizationTrail,
TagsList,
region
)
SELECT 
'{{ Name }}',
'{{ S3BucketName }}' /* required */,
'{{ S3KeyPrefix }}',
'{{ SnsTopicName }}',
{{ IncludeGlobalServiceEvents }},
{{ IsMultiRegionTrail }},
{{ EnableLogFileValidation }},
'{{ CloudWatchLogsLogGroupArn }}',
'{{ CloudWatchLogsRoleArn }}',
'{{ KmsKeyId }}',
{{ IsOrganizationTrail }},
'{{ TagsList }}',
'{{ region }}'
RETURNING
cloud_watch_logs_log_group_arn,
cloud_watch_logs_role_arn,
include_global_service_events,
is_multi_region_trail,
is_organization_trail,
kms_key_id,
log_file_validation_enabled,
name,
s3_bucket_name,
s3_key_prefix,
sns_topic_arn,
sns_topic_name,
trail_arn
;

UPDATE examples​

Updates trail settings that control what events you are logging, and how to handle log files. Changes to a trail do not require stopping the CloudTrail service. Use this action to designate an existing bucket for log delivery. If the existing bucket has previously been a target for CloudTrail log files, an IAM policy exists for the bucket. UpdateTrail must be called from the Region in which the trail was created; otherwise, an InvalidHomeRegionException is thrown.

UPDATE aws.cloudtrail.trails
SET 
Name = '{{ Name }}',
S3BucketName = '{{ S3BucketName }}',
S3KeyPrefix = '{{ S3KeyPrefix }}',
SnsTopicName = '{{ SnsTopicName }}',
IncludeGlobalServiceEvents = {{ IncludeGlobalServiceEvents }},
IsMultiRegionTrail = {{ IsMultiRegionTrail }},
EnableLogFileValidation = {{ EnableLogFileValidation }},
CloudWatchLogsLogGroupArn = '{{ CloudWatchLogsLogGroupArn }}',
CloudWatchLogsRoleArn = '{{ CloudWatchLogsRoleArn }}',
KmsKeyId = '{{ KmsKeyId }}',
IsOrganizationTrail = {{ IsOrganizationTrail }}
WHERE 
region = '{{ region }}' --required
RETURNING
cloud_watch_logs_log_group_arn,
cloud_watch_logs_role_arn,
include_global_service_events,
is_multi_region_trail,
is_organization_trail,
kms_key_id,
log_file_validation_enabled,
name,
s3_bucket_name,
s3_key_prefix,
sns_topic_arn,
sns_topic_name,
trail_arn;

DELETE examples​

Deletes a trail. This operation must be called from the Region in which the trail was created. DeleteTrail cannot be called on the shadow trails (replicated trails in other Regions) of a trail that is enabled in all Regions. While deleting a CloudTrail trail is an irreversible action, CloudTrail does not delete log files in the Amazon S3 bucket for that trail, the Amazon S3 bucket itself, or the CloudWatchlog group to which the trail delivers events. Deleting a multi-Region trail will stop logging of events in all Amazon Web Services Regions enabled in your Amazon Web Services account. Deleting a single-Region trail will stop logging of events in that Region only. It will not stop logging of events in other Regions even if the trails in those other Regions have identical names to the deleted trail. For information about account closure and deletion of CloudTrail trails, see https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-account-closure.html.

DELETE FROM aws.cloudtrail.trails
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Returns settings information for a specified trail.

EXEC aws.cloudtrail.trails.get_trail 
@region='{{ region }}' --required 
@@json=
'{
"Name": "{{ Name }}"
}'
;
Last updated on