Starts a Live Tail streaming session for one or more log groups. A Live Tail session returns a stream of log events that have been recently ingested in the log groups. For more information, see Use Live Tail to view logs in near real time.
The response to this operation is a response stream, over which the server sends live log events and the client receives them.
The following objects are sent over the stream:
-
A single LiveTailSessionStart object is sent at the start of the session.
-
Every second, a LiveTailSessionUpdate object is sent. Each of these objects contains an array of the actual log events.
If no new log events were ingested in the past second, the LiveTailSessionUpdate object will contain an empty array.
The array of log events contained in a LiveTailSessionUpdate can include as many as 500 log events. If the number of log events matching the request exceeds 500 per second, the log events are sampled down to 500 log events to be included in each LiveTailSessionUpdate object.
If your client consumes the log events slower than the server produces them, CloudWatch Logs buffers up to 10 LiveTailSessionUpdate events or 5000 log events, after which it starts dropping the oldest events.
-
A SessionStreamingException object is returned if an unknown error occurs on the server side.
-
A SessionTimeoutException object is returned when the session times out, after it has been kept open for three hours.
The StartLiveTail API routes requests using SDK host prefix injection. SDK versions released before April 1, 2026 route to streaming-logs.Region.amazonaws.com, which does not support VPC endpoints. SDK versions released on or after April 1, 2026 route to stream-logs.Region.amazonaws.com, which supports VPC endpoints. To set up a VPC endpoint for this API, see Creating a VPC endpoint for CloudWatch Logs .
You can end a session before it times out by closing the session stream or by closing the client that is receiving the stream. The session also ends if the established connection between the client and the server breaks.
For examples of using an SDK to start a Live Tail session, see Start a Live Tail session using an Amazon Web Services SDK.
Parameters:
-
log_group_identifiers
(StartLiveTailLogGroupIdentifiers)
–
An array where each item in the array is a log group to include in the Live Tail session.
Specify each log group by its ARN.
If you specify an ARN, the ARN can't end with an asterisk (*).
You can include up to 10 log groups.
-
log_stream_names
(Optional[InputLogStreamNames], default:
None
)
–
If you specify this parameter, then only log events in the log streams that you specify here are included in the Live Tail session.
If you specify this field, you can't also specify the logStreamNamePrefixes field.
You can specify this parameter only if you specify only one log group in logGroupIdentifiers.
-
log_stream_name_prefixes
(Optional[InputLogStreamNames], default:
None
)
–
If you specify this parameter, then only log events in the log streams that have names that start with the prefixes that you specify here are included in the Live Tail session.
If you specify this field, you can't also specify the logStreamNames field.
You can specify this parameter only if you specify only one log group in logGroupIdentifiers.
-
log_event_filter_pattern
(Optional[FilterPattern], default:
None
)
–
An optional pattern to use to filter the results to include only log events that match the pattern. For example, a filter pattern of error 404 causes only log events that include both error and 404 to be included in the Live Tail stream.
Regular expression filter patterns are supported.
For more information about filter pattern syntax, see Filter and Pattern Syntax.
Raises:
Source code in docs_src/capo_cloudwatch_logs/_services/cloud_watch_logs.py
| def start_live_tail(
self,
log_group_identifiers: "capo_cloudwatch_logs.types.start_live_tail_log_group_identifiers.StartLiveTailLogGroupIdentifiers",
*,
config_overrides: Optional[CloudWatchLogsClientConfig] = None,
log_stream_names: Optional[
"capo_cloudwatch_logs.types.input_log_stream_names.InputLogStreamNames"
] = None,
log_stream_name_prefixes: Optional[
"capo_cloudwatch_logs.types.input_log_stream_names.InputLogStreamNames"
] = None,
log_event_filter_pattern: Optional[
"capo_cloudwatch_logs.types.filter_pattern.FilterPattern"
] = None,
) -> "capo_cloudwatch_logs.types.start_live_tail_response.StartLiveTailResponse":
"""<p>Starts a Live Tail streaming session for one or more log groups. A Live Tail session returns a stream of log events that have been recently ingested in the log groups. For more information, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs_LiveTail.html">Use Live Tail to view logs in near real time</a>. </p> <p>The response to this operation is a response stream, over which the server sends live log events and the client receives them.</p> <p>The following objects are sent over the stream:</p> <ul> <li> <p>A single <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_LiveTailSessionStart.html">LiveTailSessionStart</a> object is sent at the start of the session.</p> </li> <li> <p>Every second, a <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_LiveTailSessionUpdate.html">LiveTailSessionUpdate</a> object is sent. Each of these objects contains an array of the actual log events.</p> <p>If no new log events were ingested in the past second, the <code>LiveTailSessionUpdate</code> object will contain an empty array.</p> <p>The array of log events contained in a <code>LiveTailSessionUpdate</code> can include as many as 500 log events. If the number of log events matching the request exceeds 500 per second, the log events are sampled down to 500 log events to be included in each <code>LiveTailSessionUpdate</code> object.</p> <p>If your client consumes the log events slower than the server produces them, CloudWatch Logs buffers up to 10 <code>LiveTailSessionUpdate</code> events or 5000 log events, after which it starts dropping the oldest events.</p> </li> <li> <p>A <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartLiveTailResponseStream.html#CWL-Type-StartLiveTailResponseStream-SessionStreamingException">SessionStreamingException</a> object is returned if an unknown error occurs on the server side.</p> </li> <li> <p>A <a href="https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartLiveTailResponseStream.html#CWL-Type-StartLiveTailResponseStream-SessionTimeoutException">SessionTimeoutException</a> object is returned when the session times out, after it has been kept open for three hours.</p> </li> </ul> <note> <p>The <code>StartLiveTail</code> API routes requests using SDK host prefix injection. SDK versions released before April 1, 2026 route to <code>streaming-logs.<i>Region</i>.amazonaws.com</code>, which does not support VPC endpoints. SDK versions released on or after April 1, 2026 route to <code>stream-logs.<i>Region</i>.amazonaws.com</code>, which supports VPC endpoints. To set up a VPC endpoint for this API, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html#create-VPC-endpoint-for-CloudWatchLogs">Creating a VPC endpoint for CloudWatch Logs </a>.</p> </note> <important> <p>You can end a session before it times out by closing the session stream or by closing the client that is receiving the stream. The session also ends if the established connection between the client and the server breaks.</p> </important> <p>For examples of using an SDK to start a Live Tail session, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/example_cloudwatch-logs_StartLiveTail_section.html"> Start a Live Tail session using an Amazon Web Services SDK</a>.</p>
Args:
log_group_identifiers: <p>An array where each item in the array is a log group to include in the Live Tail session.</p> <p>Specify each log group by its ARN. </p> <p>If you specify an ARN, the ARN can't end with an asterisk (*).</p> <note> <p> You can include up to 10 log groups.</p> </note>
log_stream_names: <p>If you specify this parameter, then only log events in the log streams that you specify here are included in the Live Tail session.</p> <p>If you specify this field, you can't also specify the <code>logStreamNamePrefixes</code> field.</p> <note> <p>You can specify this parameter only if you specify only one log group in <code>logGroupIdentifiers</code>.</p> </note>
log_stream_name_prefixes: <p>If you specify this parameter, then only log events in the log streams that have names that start with the prefixes that you specify here are included in the Live Tail session.</p> <p>If you specify this field, you can't also specify the <code>logStreamNames</code> field.</p> <note> <p>You can specify this parameter only if you specify only one log group in <code>logGroupIdentifiers</code>.</p> </note>
log_event_filter_pattern: <p>An optional pattern to use to filter the results to include only log events that match the pattern. For example, a filter pattern of <code>error 404</code> causes only log events that include both <code>error</code> and <code>404</code> to be included in the Live Tail stream.</p> <p>Regular expression filter patterns are supported.</p> <p>For more information about filter pattern syntax, see <a href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html">Filter and Pattern Syntax</a>.</p>
Raises:
capo_cloudwatch_logs.errors.access_denied_exception.AccessDeniedException: <p>You don't have sufficient permissions to perform this action.</p>
capo_cloudwatch_logs.errors.invalid_operation_exception.InvalidOperationException: <p>The operation is not valid on the specified resource.</p>
capo_cloudwatch_logs.errors.invalid_parameter_exception.InvalidParameterException: <p>A parameter is specified incorrectly.</p>
capo_cloudwatch_logs.errors.limit_exceeded_exception.LimitExceededException: <p>You have reached the maximum number of resources that can be created.</p>
capo_cloudwatch_logs.errors.resource_not_found_exception.ResourceNotFoundException: <p>The specified resource does not exist.</p>
capo_cloudwatch_logs.errors.UnknownServiceError: The service returned an error code this client does not model.
"""
def _handler(
req: "OperationRequest[capo_cloudwatch_logs.types.start_live_tail_request.StartLiveTailRequest]",
) -> OperationResponse[
"capo_cloudwatch_logs.types.start_live_tail_response.StartLiveTailResponse"
]:
import capo_cloudwatch_logs._operations.logs_20140328.start_live_tail
output, http_response = (
capo_cloudwatch_logs._operations.logs_20140328.start_live_tail.start_live_tail(
req.options, req.input
)
)
return OperationResponse(output=output, response=http_response)
def _redact_output(
output: "capo_cloudwatch_logs.types.start_live_tail_response.StartLiveTailResponse",
) -> dict[str, Any]:
import capo_cloudwatch_logs.types.start_live_tail_response
return capo_cloudwatch_logs.types.start_live_tail_response.redact_sensitive(
output
)
interceptors_, options_ = self.operation_options(
config_overrides,
OperationLogging("StartLiveTail", redact_output=_redact_output),
)
input_: capo_cloudwatch_logs.types.start_live_tail_request.StartLiveTailRequest = {
"log_group_identifiers": log_group_identifiers
}
if log_stream_names is not None:
input_["log_stream_names"] = log_stream_names
if log_stream_name_prefixes is not None:
input_["log_stream_name_prefixes"] = log_stream_name_prefixes
if log_event_filter_pattern is not None:
input_["log_event_filter_pattern"] = log_event_filter_pattern
response = execute_pipeline(
OperationRequest(input=input_, options=options_),
handler=_handler,
interceptors=list(interceptors_),
)
return response.output
|