Amazon CloudWatch Logs

Retrieves log events, optionally filtered by a filter pattern from the specified log group. You can provide an optional time range to filter the results on the event timestamp. You can limit the streams searched to an explicit list of logStreamNames.

By default, this operation returns as much matching log events as can fit in a response size of 1MB, up to 10,000 log events, or all the events found within a time-bounded scan window. If the response includes a nextToken, then there is more data to search, and the search can be resumed with a new request providing the nextToken. The response will contain a list of searchedLogStreams that contains information about which streams were searched in the request and whether they have been searched completely or require further pagination. The limit parameter in the request. can be used to specify the maximum number of events to return in a page.

Request Syntax

client.filter_log_events(
    logGroupName='string',
    logStreamNames=[
        'string',
    ],
    startTime=123,
    endTime=123,
    filterPattern='string',
    nextToken='string',
    limit=123,
    interleaved=True|False
)

type logGroupName:

string

param logGroupName:

[REQUIRED]

The name of the log group to query

type logStreamNames:

list

param logStreamNames:

Optional list of log stream names within the specified log group to search. Defaults to all the log streams in the log group.

• (string) --

type startTime:

integer

param startTime:

A unix timestamp indicating the start time of the range for the request. If provided, events with a timestamp prior to this time will not be returned.

type endTime:

integer

param endTime:

A unix timestamp indicating the end time of the range for the request. If provided, events with a timestamp later than this time will not be returned.

type filterPattern:

string

param filterPattern:

A valid CloudWatch Logs filter pattern to use for filtering the response. If not provided, all the events are matched.

type nextToken:

string

param nextToken:

A pagination token obtained from a FilterLogEvents response to continue paginating the FilterLogEvents results.

type limit:

integer

param limit:

The maximum number of events to return in a page of results. Default is 10,000 events.

type interleaved:

boolean

param interleaved:

If provided, the API will make a best effort to provide responses that contain events from multiple log streams within the log group interleaved in a single response. If not provided, all the matched log events in the first log stream will be searched first, then those in the next log stream, etc.

rtype:

dict

returns:

Response Syntax

{
    'events': [
        {
            'logStreamName': 'string',
            'timestamp': 123,
            'message': 'string',
            'ingestionTime': 123,
            'eventId': 'string'
        },
    ],
    'searchedLogStreams': [
        {
            'logStreamName': 'string',
            'searchedCompletely': True|False
        },
    ],
    'nextToken': 'string'
}

Response Structure

• (dict) --

  • events (list) --

    A list of FilteredLogEvent objects representing the matched events from the request.

    • (dict) -- Represents a matched event from a FilterLogEvents request.

      • logStreamName (string) -- The name of the log stream this event belongs to.

      • timestamp (integer) -- A point in time expressed as the number milliseconds since Jan 1, 1970 00:00:00 UTC.

      • message (string) --

      • ingestionTime (integer) -- A point in time expressed as the number milliseconds since Jan 1, 1970 00:00:00 UTC.

      • eventId (string) -- A unique identifier for this event.

  • searchedLogStreams (list) --

    A list of SearchedLogStream objects indicating which log streams have been searched in this request and whether each has been searched completely or still has more to be paginated.

    • (dict) -- An object indicating the search status of a log stream in a FilterLogEvents request.

      • logStreamName (string) -- The name of the log stream.

      • searchedCompletely (boolean) -- Indicates whether all the events in this log stream were searched or more data exists to search by paginating further.

  • nextToken (string) --

    A pagination token obtained from a FilterLogEvents response to continue paginating the FilterLogEvents results.