filter_log_events async ¶

async def filter_log_events(
    self,
    *,
    config_overrides: Optional[AsyncCloudWatchLogsClientConfig] = None,
    log_group_name: Optional[
        "capo_cloudwatch_logs.types.log_group_name.LogGroupName"
    ] = None,
    log_group_identifier: Optional[
        "capo_cloudwatch_logs.types.log_group_identifier.LogGroupIdentifier"
    ] = None,
    log_stream_names: Optional[
        "capo_cloudwatch_logs.types.input_log_stream_names.InputLogStreamNames"
    ] = None,
    log_stream_name_prefix: Optional[
        "capo_cloudwatch_logs.types.log_stream_name.LogStreamName"
    ] = None,
    start_time: Optional["capo_cloudwatch_logs.types.timestamp.Timestamp"] = None,
    end_time: Optional["capo_cloudwatch_logs.types.timestamp.Timestamp"] = None,
    filter_pattern: Optional[
        "capo_cloudwatch_logs.types.filter_pattern.FilterPattern"
    ] = None,
    next_token: Optional["capo_cloudwatch_logs.types.next_token.NextToken"] = None,
    limit: Optional["capo_cloudwatch_logs.types.events_limit.EventsLimit"] = None,
    start_from_head: Optional[
        "capo_cloudwatch_logs.types.start_from_head.StartFromHead"
    ] = None,
    interleaved: Optional[
        "capo_cloudwatch_logs.types.interleaved.Interleaved"
    ] = None,
    unmask: Optional["capo_cloudwatch_logs.types.unmask.Unmask"] = None,
) -> (
    "capo_cloudwatch_logs.types.filter_log_events_response.FilterLogEventsResponse"
):
    """<p>Lists log events from the specified log group. You can list all the log events or filter the results using one or more of the following:</p> <ul> <li> <p>A filter pattern</p> </li> <li> <p>A time range</p> </li> <li> <p>The log stream name, or a log stream name prefix that matches multiple log streams</p> </li> </ul> <p>You must have the <code>logs:FilterLogEvents</code> permission to perform this operation.</p> <p>You can specify the log group to search by using either <code>logGroupIdentifier</code> or <code>logGroupName</code>. You must include one of these two parameters, but you can't include both. </p> <p> <code>FilterLogEvents</code> is a paginated operation. Each page returned can contain up to 1 MB of log events or up to 10,000 log events. A returned page might only be partially full, or even empty. For example, if the result of a query would return 15,000 log events, the first page isn't guaranteed to have 10,000 log events even if they all fit into 1 MB.</p> <p>Partially full or empty pages don't necessarily mean that pagination is finished. If the results include a <code>nextToken</code>, there might be more log events available. You can return these additional log events by providing the nextToken in a subsequent <code>FilterLogEvents</code> operation. If the results don't include a <code>nextToken</code>, then pagination is finished. </p> <p>Specifying the <code>limit</code> parameter only guarantees that a single page doesn't return more log events than the specified limit, but it might return fewer events than the limit. This is the expected API behavior.</p> <p>The returned log events are sorted by event timestamp, the timestamp when the event was ingested by CloudWatch Logs, and the ID of the <code>PutLogEvents</code> request. By default, the events are returned in ascending timestamp order (oldest first). To return events in descending timestamp order (newest first), set the <code>startFromHead</code> parameter to <code>false</code>.</p> <p>If you are using CloudWatch cross-account observability, you can use this operation in a monitoring account and view data from the linked source accounts. For more information, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html">CloudWatch cross-account observability</a>.</p> <note> <p>If you are using <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Transformation.html">log transformation</a>, the <code>FilterLogEvents</code> operation returns only the original versions of log events, before they were transformed. To view the transformed versions, you must use a <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html">CloudWatch Logs query.</a> </p> </note>

    Args:
        log_group_name: <p>The name of the log group to search.</p> <note> <p> You must include either <code>logGroupIdentifier</code> or <code>logGroupName</code>, but not both. </p> </note>
        log_group_identifier: <p>Specify either the name or ARN of the log group to view log events from. If the log group is in a source account and you are using a monitoring account, you must use the log group ARN.</p> <note> <p> You must include either <code>logGroupIdentifier</code> or <code>logGroupName</code>, but not both. </p> </note>
        log_stream_names: <p>Filters the results to only logs from the log streams in this list.</p> <p>If you specify a value for both <code>logStreamNames</code> and <code>logStreamNamePrefix</code>, the action returns an <code>InvalidParameterException</code> error.</p>
        log_stream_name_prefix: <p>Filters the results to include only events from log streams that have names starting with this prefix.</p> <p>If you specify a value for both <code>logStreamNamePrefix</code> and <code>logStreamNames</code>, the action returns an <code>InvalidParameterException</code> error.</p>
        start_time: <p>The start of the time range, expressed as the number of milliseconds after <code>Jan 1, 1970 00:00:00 UTC</code>. Events with a timestamp before this time are not returned.</p> <note> <p>Set <code>startTime</code> explicitly to reduce the chances of empty pages in the response.</p> </note>
        end_time: <p>The end of the time range, expressed as the number of milliseconds after <code>Jan 1, 1970 00:00:00 UTC</code>. Events with a timestamp later than this time are not returned.</p>
        filter_pattern: <p>The filter pattern to use. For more information, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html">Filter and Pattern Syntax</a>.</p> <p>If not provided, all the events are matched.</p>
        next_token: <p>The token for the next set of events to return. (You received this token from a previous call.)</p>
        limit: <p>The maximum number of events to return. The default is 10,000 events.</p>
        start_from_head: <p>If the value is true, the earliest log events are returned first. If the value is false, the latest log events are returned first. The default value is true.</p> <p>The <code>startFromHead</code> parameter sets the sort direction on the first request. On subsequent requests, the <code>nextToken</code> determines the sort direction. To continue paginating in the same direction, provide the returned <code>nextToken</code>. If you provide both <code>nextToken</code> and <code>startFromHead</code>, the direction of the <code>nextToken</code> is used.</p> <note> <p>Setting <code>startFromHead</code> to <code>false</code> is supported only when <code>startTime</code> is on or after <code>Jan 1, 2024 00:00:00 UTC</code>. A request with <code>startFromHead</code> set to <code>false</code> and a <code>startTime</code> before this date returns an <code>InvalidParameterException</code>.</p> </note>
        interleaved: <p>If the value is true, the operation attempts to provide responses that contain events from multiple log streams within the log group, interleaved in a single response. If the value is false, all the matched log events in the first log stream are searched first, then those in the next log stream, and so on.</p> <p> <b>Important</b> As of June 17, 2019, this parameter is ignored and the value is assumed to be true. The response from this operation always interleaves events from multiple log streams within a log group.</p>
        unmask: <p>Specify <code>true</code> to display the log event fields with all sensitive data unmasked and visible. The default is <code>false</code>.</p> <p>To use this operation with this parameter, you must be signed into an account with the <code>logs:Unmask</code> permission.</p>

    Raises:
        capo_cloudwatch_logs.errors.invalid_parameter_exception.InvalidParameterException: <p>A parameter is specified incorrectly.</p>
        capo_cloudwatch_logs.errors.resource_not_found_exception.ResourceNotFoundException: <p>The specified resource does not exist.</p>
        capo_cloudwatch_logs.errors.service_unavailable_exception.ServiceUnavailableException: <p>The service cannot complete the request.</p>
        capo_cloudwatch_logs.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    async def _handler(
        req: "AsyncOperationRequest[capo_cloudwatch_logs.types.filter_log_events_request.FilterLogEventsRequest]",
    ) -> AsyncOperationResponse[
        "capo_cloudwatch_logs.types.filter_log_events_response.FilterLogEventsResponse"
    ]:
        import capo_cloudwatch_logs._operations.logs_20140328.filter_log_events

        (
            output,
            http_response,
        ) = await capo_cloudwatch_logs._operations.logs_20140328.filter_log_events.async_filter_log_events(
            req.options, req.input
        )
        return AsyncOperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("FilterLogEvents")
    )
    input_: capo_cloudwatch_logs.types.filter_log_events_request.FilterLogEventsRequest = {}
    if log_group_name is not None:
        input_["log_group_name"] = log_group_name
    if log_group_identifier is not None:
        input_["log_group_identifier"] = log_group_identifier
    if log_stream_names is not None:
        input_["log_stream_names"] = log_stream_names
    if log_stream_name_prefix is not None:
        input_["log_stream_name_prefix"] = log_stream_name_prefix
    if start_time is not None:
        input_["start_time"] = start_time
    if end_time is not None:
        input_["end_time"] = end_time
    if filter_pattern is not None:
        input_["filter_pattern"] = filter_pattern
    if next_token is not None:
        input_["next_token"] = next_token
    if limit is not None:
        input_["limit"] = limit
    if start_from_head is not None:
        input_["start_from_head"] = start_from_head
    if interleaved is not None:
        input_["interleaved"] = interleaved
    if unmask is not None:
        input_["unmask"] = unmask

    response = await aexecute_pipeline(
        AsyncOperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    await response.response.aclose()
    return response.output