AWS::Logs::SubscriptionFilter
The AWS::Logs::SubscriptionFilter
resource specifies a subscription filter and associates it with the specified log
group. Subscription filters allow you to subscribe to a real-time stream of log events
and have them delivered to a specific
destination. Currently, the supported destinations are:
-
An Amazon Kinesis data stream belonging to the same account as the subscription filter, for same-account delivery.
-
A logical destination that belongs to a different account, for cross-account delivery.
-
An Amazon Kinesis Firehose delivery stream that belongs to the same account as the subscription filter, for same-account delivery.
-
An AWS Lambda function that belongs to the same account as the subscription filter, for same-account delivery.
There can be as many as two subscription filters associated with a log group.
Syntax
To declare this entity in your AWS CloudFormation template, use the following syntax:
JSON
{ "Type" : "AWS::Logs::SubscriptionFilter", "Properties" : { "DestinationArn" :
String
, "Distribution" :String
, "FilterName" :String
, "FilterPattern" :String
, "LogGroupName" :String
, "RoleArn" :String
} }
YAML
Type: AWS::Logs::SubscriptionFilter Properties: DestinationArn:
String
Distribution:String
FilterName:String
FilterPattern:String
LogGroupName:String
RoleArn:String
Properties
DestinationArn
-
The Amazon Resource Name (ARN) of the destination.
Required: Yes
Type: String
Minimum:
1
Update requires: No interruption
Distribution
-
The method used to distribute log data to the destination, which can be either random or grouped by log stream.
Required: No
Type: String
Allowed values:
Random | ByLogStream
Update requires: No interruption
FilterName
-
The name of the subscription filter.
Required: No
Type: String
Pattern:
[^:*]*
Minimum:
1
Maximum:
512
Update requires: Replacement
FilterPattern
-
The filtering expressions that restrict what gets delivered to the destination AWS resource. For more information about the filter pattern syntax, see Filter and Pattern Syntax.
Required: Yes
Type: String
Update requires: No interruption
LogGroupName
-
The log group to associate with the subscription filter. All log events that are uploaded to this log group are filtered and delivered to the specified AWS resource if the filter pattern matches the log events.
Required: Yes
Type: String
Pattern:
[\.\-_/#A-Za-z0-9]+
Minimum:
1
Maximum:
512
Update requires: Replacement
RoleArn
-
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.
Required: No
Type: String
Minimum:
1
Update requires: No interruption
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the resource name.
For more information about using the Ref
function, see Ref
.
Examples
Create a Subscription Filter
The following example sends log events that are associated with the Root
user to a Kinesis data stream.
JSON
"SubscriptionFilter" : { "Type" : "AWS::Logs::SubscriptionFilter", "Properties" : { "RoleArn" : { "Fn::GetAtt" : [ "CloudWatchIAMRole", "Arn" ] }, "LogGroupName" : { "Ref" : "LogGroup" }, "Distribution" : "Random", "FilterName" : "filterNameString", "FilterPattern" : "{$.userIdentity.type = Root}", "DestinationArn" : { "Fn::GetAtt" : [ "KinesisStream", "Arn" ] } } }
YAML
SubscriptionFilter: Type: AWS::Logs::SubscriptionFilter Properties: RoleArn: Fn::GetAtt: - "CloudWatchIAMRole" - "Arn" LogGroupName: Ref: "LogGroup" Distribution: "Random" FilterName: "filterNameString" FilterPattern: "{$.userIdentity.type = Root}" DestinationArn: Fn::GetAtt: - "KinesisStream" - "Arn"