2018/11/27 - Amazon CloudWatch Logs - 6 new api methods
Changes Six new APIs added to support CloudWatch Logs Insights. The APIs are StartQuery, StopQuery, GetQueryResults, GetLogRecord, GetLogGroupFields, and DescribeQueries.
Stops a CloudWatch Logs Insights query that is in progress. If the query has already ended, the operation returns an error indicating that the specified query is not running.
See also: AWS API Documentation
Request Syntax
client.stop_query(
queryId='string'
)
string
[REQUIRED]
The ID number of the query to stop. If necessary, you can use DescribeQueries to find this ID number.
dict
Response Syntax
{
'success': True|False
}
Response Structure
(dict) --
success (boolean) --
This is true if the query was stopped by the StopQuery operation.
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',
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',
'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.
Returns the results from the specified query. If the query is in progress, partial results of that current execution are returned. Only the fields requested in the query are returned.
GetQueryResults does not start a query execution. To run a query, use .
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'
}
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.
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.
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 , and Unknown .
Returns a list of the fields that are included in log events in the specified log group, along with the percentage of log events that contain each field. The search is limited to a time period that you specify.
In the results, fields that start with @ are fields generated by CloudWatch Logs. For example, @timestamp is the timestamp of each log event.
The response results are sorted by the frequency percentage, starting with the highest percentage.
See also: AWS API Documentation
Request Syntax
client.get_log_group_fields(
logGroupName='string',
time=123
)
string
[REQUIRED]
The name of the log group to search.
integer
The time to set as the center of the query. If you specify time , the 8 minutes before and 8 minutes after this time are searched. If you omit time , the past 15 minutes are queried.
The time value is specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
dict
Response Syntax
{
'logGroupFields': [
{
'name': 'string',
'percent': 123
},
]
}
Response Structure
(dict) --
logGroupFields (list) --
The array of fields found in the query. Each object in the array contains the name of the field, along with the percentage of time it appeared in the log events that were queried.
(dict) --
The fields contained in log events found by a GetLogGroupFields operation, along with the percentage of queried log events in which each field appears.
name (string) --
The name of a log field.
percent (integer) --
The percentage of log events queried that contained the field.
Retrieves all the fields and values of a single log event. All fields are retrieved, even if the original query that produced the logRecordPointer retrieved only a subset of fields. Fields are returned as field name/field value pairs.
Additionally, the entire unparsed log event is returned within @message .
See also: AWS API Documentation
Request Syntax
client.get_log_record(
logRecordPointer='string'
)
string
[REQUIRED]
The pointer corresponding to the log event record you want to retrieve. You get this from the response of a GetQueryResults operation. In that response, the value of the @ptr field for a log event is the value to use as logRecordPointer to retrieve that complete log event record.
dict
Response Syntax
{
'logRecord': {
'string': 'string'
}
}
Response Structure
(dict) --
logRecord (dict) --
The requested log event, as a JSON string.
(string) --
(string) --
Schedules a query of a log group using CloudWatch Logs Insights. You specify the log group to query, the query string to use, and the time to query.
For more information, see CloudWatch Logs Insights Query Syntax .
See also: AWS API Documentation
Request Syntax
client.start_query(
logGroupName='string',
startTime=123,
endTime=123,
queryString='string',
limit=123
)
string
[REQUIRED]
The log group on which to perform the query.
integer
[REQUIRED]
The time to start the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
integer
[REQUIRED]
The time to end this query, if it is still running. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
string
[REQUIRED]
The query string to use. For more information, see CloudWatch Logs Insights Query Syntax .
integer
The maximum number of log events to return in the query. If the query string uses the fields command, only the specified fields and their values are returned.
dict
Response Syntax
{
'queryId': 'string'
}
Response Structure
(dict) --
queryId (string) --
The unique ID of the query.