2021/05/24 - Amazon CloudWatch Logs - 4 updated api methods
Changes This release provides dimensions and unit support for metric filters.
{'metricFilters': {'metricTransformations': {'dimensions': {'string': 'string'},
'unit': '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'}}}
Lists the specified metric filters. You can list all of the metric filters or filter the results by log name, prefix, metric name, or metric namespace. The results are ASCII-sorted by filter name.
See also: AWS API Documentation
Request Syntax
client.describe_metric_filters(
logGroupName='string',
filterNamePrefix='string',
nextToken='string',
limit=123,
metricName='string',
metricNamespace='string'
)
string
The name of the log group.
string
The prefix to match. CloudWatch Logs uses the value you set here only if you also include the logGroupName parameter in your request.
string
The token for the next set of items to return. (You received this token from a previous call.)
integer
The maximum number of items returned. If you don't specify a value, the default is up to 50 items.
string
Filters results to include only those with the specified metric name. If you include this parameter in your request, you must also include the metricNamespace parameter.
string
Filters results to include only those in the specified namespace. If you include this parameter in your request, you must also include the metricName parameter.
dict
Response Syntax
{
'metricFilters': [
{
'filterName': 'string',
'filterPattern': 'string',
'metricTransformations': [
{
'metricName': 'string',
'metricNamespace': 'string',
'metricValue': 'string',
'defaultValue': 123.0,
'dimensions': {
'string': 'string'
},
'unit': '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'
},
],
'creationTime': 123,
'logGroupName': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
metricFilters (list) --
The metric filters.
(dict) --
Metric filters express how CloudWatch Logs would extract metric observations from ingested log events and transform them into metric data in a CloudWatch metric.
filterName (string) --
The name of the metric filter.
filterPattern (string) --
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.
metricTransformations (list) --
The metric transformations.
(dict) --
Indicates how to transform ingested log events to metric data in a CloudWatch metric.
metricName (string) --
The name of the CloudWatch metric.
metricNamespace (string) --
A custom namespace to contain your metric in CloudWatch. Use namespaces to group together metrics that are similar. For more information, see Namespaces .
metricValue (string) --
The value to publish to the CloudWatch metric when a filter pattern matches a log event.
defaultValue (float) --
(Optional) The value to emit when a filter pattern does not match a log event. This value can be null.
dimensions (dict) --
The fields to use as dimensions for the metric. One metric filter can include as many as three dimensions.
Warning
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 .
(string) --
(string) --
unit (string) --
The unit to assign to the metric. If you omit this, the unit is set as None .
creationTime (integer) --
The creation time of the metric filter, expressed as the number of milliseconds after Jan 1, 1970 00:00:00 UTC.
logGroupName (string) --
The name of the log group.
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.
{'status': {'Unknown', 'Timeout'}}
Response {'queries': {'status': {'Unknown', 'Timeout'}}}
Returns a list of CloudWatch Logs Insights queries that are scheduled, executing, or have been executed recently in this account. You can request all queries or limit it to queries of a specific log group or queries with a certain status.
See also: AWS API Documentation
Request Syntax
client.describe_queries(
logGroupName='string',
status='Scheduled'|'Running'|'Complete'|'Failed'|'Cancelled'|'Timeout'|'Unknown',
maxResults=123,
nextToken='string'
)
string
Limits the returned queries to only those for the specified log group.
string
Limits the returned queries to only those that have the specified status. Valid values are Cancelled , Complete , Failed , Running , and Scheduled .
integer
Limits the number of returned queries to the specified number.
string
The token for the next set of items to return. The token expires after 24 hours.
dict
Response Syntax
{
'queries': [
{
'queryId': 'string',
'queryString': 'string',
'status': 'Scheduled'|'Running'|'Complete'|'Failed'|'Cancelled'|'Timeout'|'Unknown',
'createTime': 123,
'logGroupName': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
queries (list) --
The list of queries that match the request.
(dict) --
Information about one CloudWatch Logs Insights query that matches the request in a DescribeQueries operation.
queryId (string) --
The unique ID number of this query.
queryString (string) --
The query string used in this query.
status (string) --
The status of this query. Possible values are Cancelled , Complete , Failed , Running , Scheduled , and Unknown .
createTime (integer) --
The date and time that this query was created.
logGroupName (string) --
The name of the log group scanned by this query.
nextToken (string) --
The token for the next set of items to return. The token expires after 24 hours.
{'status': {'Unknown', 'Timeout'}}
Returns the results from the specified query.
Only the fields requested in the query are returned, along with a @ptr field, which is the identifier for the log record. You can use the value of @ptr in a GetLogRecord operation to get the full log record.
GetQueryResults does not start a query execution. To run a query, use StartQuery .
If the value of the Status field in the output is Running , this operation returns only partial results. If you see a value of Scheduled or Running for the status, you can retry the operation later to see the final results.
See also: AWS API Documentation
Request Syntax
client.get_query_results(
queryId='string'
)
string
[REQUIRED]
The ID number of the query.
dict
Response Syntax
{
'results': [
[
{
'field': 'string',
'value': 'string'
},
],
],
'statistics': {
'recordsMatched': 123.0,
'recordsScanned': 123.0,
'bytesScanned': 123.0
},
'status': 'Scheduled'|'Running'|'Complete'|'Failed'|'Cancelled'|'Timeout'|'Unknown'
}
Response Structure
(dict) --
results (list) --
The log events that matched the query criteria during the most recent time it ran.
The results value is an array of arrays. Each log event is one object in the top-level array. Each of these log event objects is an array of field /value pairs.
(list) --
(dict) --
Contains one field from one log event returned by a CloudWatch Logs Insights query, along with the value of that field.
For more information about the fields that are generated by CloudWatch logs, see Supported Logs and Discovered Fields .
field (string) --
The log event field.
value (string) --
The value of this field.
statistics (dict) --
Includes the number of log events scanned by the query, the number of log events that matched the query criteria, and the total number of bytes in the log events that were scanned. These values reflect the full raw results of the query.
recordsMatched (float) --
The number of log events that matched the query string.
recordsScanned (float) --
The total number of log events scanned during the query.
bytesScanned (float) --
The total number of bytes in the log events scanned during the query.
status (string) --
The status of the most recent running of the query. Possible values are Cancelled , Complete , Failed , Running , Scheduled , Timeout , and Unknown .
Queries time out after 15 minutes of execution. To avoid having your queries time out, reduce the time range being searched or partition your query into a number of queries.
{'metricTransformations': {'dimensions': {'string': 'string'},
'unit': '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'}}
Creates or updates a metric filter and associates it with the specified log group. Metric filters allow you to configure rules to extract metric data from log events ingested through PutLogEvents .
The maximum number of metric filters that can be associated with a log group is 100.
When you create a metric filter, you can also optionally assign a unit and dimensions to the metric that is created.
Warning
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 .
See also: AWS API Documentation
Request Syntax
client.put_metric_filter(
logGroupName='string',
filterName='string',
filterPattern='string',
metricTransformations=[
{
'metricName': 'string',
'metricNamespace': 'string',
'metricValue': 'string',
'defaultValue': 123.0,
'dimensions': {
'string': 'string'
},
'unit': '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'
},
]
)
string
[REQUIRED]
The name of the log group.
string
[REQUIRED]
A name for the metric filter.
string
[REQUIRED]
A filter pattern for extracting metric data out of ingested log events.
list
[REQUIRED]
A collection of information that defines how metric data gets emitted.
(dict) --
Indicates how to transform ingested log events to metric data in a CloudWatch metric.
metricName (string) -- [REQUIRED]
The name of the CloudWatch metric.
metricNamespace (string) -- [REQUIRED]
A custom namespace to contain your metric in CloudWatch. Use namespaces to group together metrics that are similar. For more information, see Namespaces .
metricValue (string) -- [REQUIRED]
The value to publish to the CloudWatch metric when a filter pattern matches a log event.
defaultValue (float) --
(Optional) The value to emit when a filter pattern does not match a log event. This value can be null.
dimensions (dict) --
The fields to use as dimensions for the metric. One metric filter can include as many as three dimensions.
Warning
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 .
(string) --
(string) --
unit (string) --
The unit to assign to the metric. If you omit this, the unit is set as None .
None