The Amazon CloudWatch Logs API contains several data types that various actions use. This section describes each data type in detail.
Note
The order of each element in a data type structure is not guaranteed. Applications should not assume a particular order.
The following data types are supported:
• Destination (p. 149)
• ExportTask (p. 151)
• ExportTaskExecutionInfo (p. 153)
• ExportTaskStatus (p. 154)
• FilteredLogEvent (p. 155)
• InputLogEvent (p. 157)
• LogGroup (p. 158)
• LogGroupField (p. 160)
• LogStream (p. 161)
• MetricFilter (p. 163)
• MetricFilterMatchRecord (p. 165)
• MetricTransformation (p. 166)
• OutputLogEvent (p. 168)
• QueryCompileError (p. 169)
• QueryCompileErrorLocation (p. 170)
• QueryDefinition (p. 171)
• QueryInfo (p. 173)
• QueryStatistics (p. 175)
• RejectedLogEventsInfo (p. 176)
• ResourcePolicy (p. 177)
• ResultField (p. 178)
• SearchedLogStream (p. 179)
• SubscriptionFilter (p. 180)
Destination
Destination
Represents a cross-account destination that receives subscription log events.
Contents
accessPolicy
An IAM policy document that governs which AWS accounts can create subscription filters against this destination.
Type: String
Length Constraints: Minimum length of 1.
Required: No arn
The ARN of this destination.
Type: String Required: No creationTime
The creation time of the destination, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No destinationName
The name of the destination.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern: [^:*]*
Required: No roleArn
A role for impersonation, used when delivering log events to the target.
Type: String
Length Constraints: Minimum length of 1.
Required: No targetArn
The Amazon Resource Name (ARN) of the physical target where the log events are delivered (for example, a Kinesis stream).
See Also
Type: String
Length Constraints: Minimum length of 1.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ExportTask
ExportTask
Represents an export task.
Contents
destination
The name of the S3 bucket to which the log data was exported.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Required: No destinationPrefix
The prefix that was used as the start of Amazon S3 key for every object exported.
Type: String Required: No executionInfo
Execution information about the export task.
Type: ExportTaskExecutionInfo (p. 153) object Required: No
from
The start time, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. Events with a timestamp before this time are not exported.
Type: Long
Valid Range: Minimum value of 0.
Required: No logGroupName
The name of the log group from which logs data was exported.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern: [\.\-_/#A-Za-z0-9]+
Required: No status
The status of the export task.
Type: ExportTaskStatus (p. 154) object Required: No
See Also
taskId
The ID of the export task.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Required: No taskName
The name of the export task.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Required: No to
The end time, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. Events with a timestamp later than this time are not exported.
Type: Long
Valid Range: Minimum value of 0.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ExportTaskExecutionInfo
ExportTaskExecutionInfo
Represents the status of an export task.
Contents
completionTime
The completion time of the export task, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No creationTime
The creation time of the export task, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
ExportTaskStatus
ExportTaskStatus
Represents the status of an export task.
Contents
code
The status code of the export task.
Type: String
Valid Values: CANCELLED | COMPLETED | FAILED | PENDING | PENDING_CANCEL | RUNNING
Required: No message
The status message related to the status code.
Type: String Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
FilteredLogEvent
FilteredLogEvent
Represents a matched event.
Contents
eventId
The ID of the event.
Type: String Required: No ingestionTime
The time the event was ingested, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No logStreamName
The name of the log stream to which this event belongs.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern: [^:*]*
Required: No message
The data contained in the log event.
Type: String
Length Constraints: Minimum length of 1.
Required: No timestamp
The time the event occurred, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
See Also
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
InputLogEvent
InputLogEvent
Represents a log event, which is a record of activity that was recorded by the application or resource being monitored.
Contents
message
The raw event message.
Type: String
Length Constraints: Minimum length of 1.
Required: Yes timestamp
The time the event occurred, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
LogGroup
LogGroup
Represents a log group.
Contents
arn
The Amazon Resource Name (ARN) of the log group.
Type: String Required: No creationTime
The creation time of the log group, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No kmsKeyId
The Amazon Resource Name (ARN) of the CMK to use when encrypting log data.
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: No metricFilterCount
The number of metric filters.
Type: Integer Required: No retentionInDays
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, 1827, and 3653.
To set a log group to never have log events expire, use DeleteRetentionPolicy.
Type: Integer
See Also
Required: No storedBytes
The number of bytes stored.
Type: Long
Valid Range: Minimum value of 0.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
LogGroupField
LogGroupField
The fields contained in log events found by a GetLogGroupFields operation, along with the percentage of queried log events in which each field appears.
Contents
name
The name of a log field.
Type: String Required: No percent
The percentage of log events queried that contained the field.
Type: Integer
Valid Range: Minimum value of 0. Maximum value of 100.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
LogStream
LogStream
Represents a log stream, which is a sequence of log events from a single emitter of logs.
Contents
arn
The Amazon Resource Name (ARN) of the log stream.
Type: String Required: No creationTime
The creation time of the stream, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No firstEventTimestamp
The time of the first event, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No lastEventTimestamp
The time of the most recent log event in the log stream in CloudWatch Logs. This number is
expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC. The lastEventTime value updates on an eventual consistency basis. It typically updates in less than an hour from ingestion, but in rare situations might take longer.
Type: Long
Valid Range: Minimum value of 0.
Required: No lastIngestionTime
The ingestion time, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No logStreamName
The name of the log stream.
Type: String
See Also
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern: [^:*]*
Required: No storedBytes
The number of bytes stored.
Important: On June 17, 2019, this parameter was deprecated for log streams, and is always reported as zero. This change applies only to log streams. The storedBytes parameter for log groups is not affected.
Type: Long
Valid Range: Minimum value of 0.
Required: No uploadSequenceToken
The sequence token.
Type: String
Length Constraints: Minimum length of 1.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
MetricFilter
MetricFilter
Metric filters express how CloudWatch Logs would extract metric observations from ingested log events and transform them into metric data in a CloudWatch metric.
Contents
creationTime
The creation time of the metric filter, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No filterName
The name of the metric filter.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern: [^:*]*
Required: No filterPattern
A symbolic description of how CloudWatch Logs should interpret the data in each log event. For example, a log event can contain timestamps, IP addresses, strings, and so on. You use the filter pattern to specify what to look for in the log event message.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1024.
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: No metricTransformations
The metric transformations.
Type: Array of MetricTransformation (p. 166) objects Array Members: Fixed number of 1 item.
Required: No
See Also
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
MetricFilterMatchRecord
MetricFilterMatchRecord
Represents a matched event.
Contents
eventMessage
The raw event data.
Type: String
Length Constraints: Minimum length of 1.
Required: No eventNumber
The event number.
Type: Long Required: No extractedValues
The values extracted from the event data by the filter.
Type: String to string map Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
MetricTransformation
MetricTransformation
Indicates how to transform ingested log events to metric data in a CloudWatch metric.
Contents
defaultValue
(Optional) The value to emit when a filter pattern does not match a log event. This value can be null.
Type: Double Required: No dimensions
The fields to use as dimensions for the metric. One metric filter can include as many as three dimensions.
Important
Metrics extracted from log events are charged as custom metrics. To prevent unexpected high charges, do not specify high-cardinality fields such as IPAddress or requestID as dimensions. Each different value found for a dimension is treated as a separate metric and accrues charges as a separate custom metric.
To help prevent accidental high charges, Amazon disables a metric filter if it generates 1000 different name/value pairs for the dimensions that you have specified within a certain amount of time.
You can also set up a billing alarm to alert you if your charges are higher than expected. For more information, see Creating a Billing Alarm to Monitor Your Estimated AWS Charges.
Type: String to string map
Key Length Constraints: Maximum length of 255.
Value Length Constraints: Maximum length of 255.
Required: No metricName
The name of the CloudWatch metric.
Type: String
Length Constraints: Maximum length of 255.
Pattern: [^:*$]*
Required: Yes metricNamespace
A custom namespace to contain your metric in CloudWatch. Use namespaces to group together metrics that are similar. For more information, see Namespaces.
Type: String
Length Constraints: Maximum length of 255.
Pattern: [^:*$]*
Required: Yes
See Also
metricValue
The value to publish to the CloudWatch metric when a filter pattern matches a log event.
Type: String
Length Constraints: Maximum length of 100.
Required: Yes unit
The unit to assign to the metric. If you omit this, the unit is set as None.
Type: String
Valid Values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits
| Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/
Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second
| Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
OutputLogEvent
OutputLogEvent
Represents a log event.
Contents
ingestionTime
The time the event was ingested, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No message
The data contained in the log event.
Type: String
Length Constraints: Minimum length of 1.
Required: No timestamp
The time the event occurred, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
Type: Long
Valid Range: Minimum value of 0.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
QueryCompileError
QueryCompileError
Reserved.
Contents
location Reserved.
Type: QueryCompileErrorLocation (p. 170) object Required: No
message Reserved.
Type: String Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3
QueryCompileErrorLocation
QueryCompileErrorLocation
Reserved.
Contents
endCharOffset Reserved.
Type: Integer Required: No startCharOffset
Reserved.
Type: Integer Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for Ruby V3