CreateLogGroup
Creates a log group with the specified name. You can create up to 20,000 log groups per account.
You must use the following guidelines when naming a log group:
-
Log group names must be unique within a region for an AWS 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)
When you create a log group, by default the log events in the log group never expire. To set a retention policy so that events expire and are deleted after a specified time, use PutRetentionPolicy.
If you associate a AWS Key Management Service (AWS KMS) customer master key (CMK) with the log group, ingested data is encrypted using the CMK. This association is stored as long as the data encrypted with the CMK is still within Amazon CloudWatch Logs. This enables Amazon CloudWatch Logs to decrypt this data whenever it is requested.
If you attempt to associate a CMK with the log group but the CMK does not exist or
the
CMK is disabled, you receive an InvalidParameterException
error.
CloudWatch Logs supports only symmetric CMKs. Do not associate an asymmetric CMK with your log group. For more information, see Using Symmetric and Asymmetric Keys.
Request Syntax
{
"kmsKeyId": "string
",
"logGroupName": "string
",
"tags": {
"string
" : "string
"
}
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- kmsKeyId
-
The Amazon Resource Name (ARN) of the CMK to use when encrypting log data. For more information, see Amazon Resource Names - AWS Key Management Service (AWS KMS).
Type: String
Length Constraints: Maximum length of 256.
Required: No
- logGroupName
-
The name of the log group.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[\.\-_/#A-Za-z0-9]+
Required: Yes
- tags
-
The key-value pairs to use for the tags.
Type: String to string map
Map Entries: Maximum number of 50 items.
Key Length Constraints: Minimum length of 1. Maximum length of 128.
Key Pattern:
^([\p{L}\p{Z}\p{N}_.:/=+\-@]+)$
Value Length Constraints: Maximum length of 256.
Value Pattern:
^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$
Required: No
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidParameterException
-
A parameter is specified incorrectly.
HTTP Status Code: 400
- LimitExceededException
-
You have reached the maximum number of resources that can be created.
HTTP Status Code: 400
- OperationAbortedException
-
Multiple requests to update the same resource were in conflict.
HTTP Status Code: 400
- ResourceAlreadyExistsException
-
The specified resource already exists.
HTTP Status Code: 400
- ServiceUnavailableException
-
The service cannot complete the request.
HTTP Status Code: 500
Examples
To create a log group
The following example creates a log group.
Sample Request
POST / HTTP/1.1
Host: logs.<region>.<domain>
X-Amz-Date: <DATE>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature=<Signature>
User-Agent: <UserAgentString>
Accept: application/json
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: Logs_20140328.CreateLogGroup
{
"logGroupName": "my-log-group",
"kmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/abcd1234-a123-456a-a12b-a123b456c789"
}
Sample Response
HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: