CloudWatchLogs / Client / start_live_tail

start_live_tail#

CloudWatchLogs.Client.start_live_tail(**kwargs)#

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.

Warning

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.

Request Syntax

response = client.start_live_tail(
    logGroupIdentifiers=[
        'string',
    ],
    logStreamNames=[
        'string',
    ],
    logStreamNamePrefixes=[
        'string',
    ],
    logEventFilterPattern='string'
)

Parameters:

logGroupIdentifiers (list) –
[REQUIRED]

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 (*).

Note
You can include up to 10 log groups.
- (string) –
logStreamNames (list) –
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.

Note
You can specify this parameter only if you specify only one log group in logGroupIdentifiers.
- (string) –
logStreamNamePrefixes (list) –
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.

Note
You can specify this parameter only if you specify only one log group in logGroupIdentifiers.
- (string) –
logEventFilterPattern (string) –
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.

Return type:

dict

Returns:

The response of this operation contains an EventStream member. When iterated the EventStream will yield events based on the structure below, where only one of the top level keys will be present for any given event.

Response Syntax

{
    'responseStream': EventStream({
        'sessionStart': {
            'requestId': 'string',
            'sessionId': 'string',
            'logGroupIdentifiers': [
                'string',
            ],
            'logStreamNames': [
                'string',
            ],
            'logStreamNamePrefixes': [
                'string',
            ],
            'logEventFilterPattern': 'string'
        },
        'sessionUpdate': {
            'sessionMetadata': {
                'sampled': True|False
            },
            'sessionResults': [
                {
                    'logStreamName': 'string',
                    'logGroupIdentifier': 'string',
                    'message': 'string',
                    'timestamp': 123,
                    'ingestionTime': 123
                },
            ]
        },
        'SessionTimeoutException': {
            'message': 'string'
        },
        'SessionStreamingException': {
            'message': 'string'
        }
    })
}

Response Structure

(dict) –
- responseStream (EventStream) –
  
  An object that includes the stream returned by your request. It can include both log events and exceptions.
  - sessionStart (dict) –
    
    This object contains information about this Live Tail session, including the log groups included and the log stream filters, if any.
    - requestId (string) –
      
      The unique ID generated by CloudWatch Logs to identify this Live Tail session request.
    - sessionId (string) –
      
      The unique ID generated by CloudWatch Logs to identify this Live Tail session.
    - logGroupIdentifiers (list) –
      
      An array of the names and ARNs of the log groups included in this Live Tail session.
      - (string) –
    - logStreamNames (list) –
      
      If your StartLiveTail operation request included a logStreamNames parameter that filtered the session to only include certain log streams, these streams are listed here.
      - (string) –
    - logStreamNamePrefixes (list) –
      
      If your StartLiveTail operation request included a logStreamNamePrefixes parameter that filtered the session to only include log streams that have names that start with certain prefixes, these prefixes are listed here.
      - (string) –
    - logEventFilterPattern (string) –
      
      An optional pattern to filter the results to include only log events that match the pattern. For example, a filter pattern of error 404 displays only log events that include both error and 404.
      
      For more information about filter pattern syntax, see Filter and Pattern Syntax.
  - sessionUpdate (dict) –
    
    This object contains the log events and session metadata.
    - sessionMetadata (dict) –
      
      This object contains the session metadata for a Live Tail session.
      - sampled (boolean) –
        
        If this is true, then more than 500 log events matched the request for this update, and the sessionResults includes a sample of 500 of those events.
        
        If this is false, then 500 or fewer log events matched the request for this update, so no sampling was necessary. In this case, the sessionResults array includes all log events that matched your request during this time.
    - sessionResults (list) –
      
      An array, where each member of the array includes the information for one log event in the Live Tail session.
      
      A sessionResults array 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 sessionUpdate structure.
      - (dict) –
        
        This object contains the information for one log event returned in a Live Tail stream.
        
        logStreamName (string) –
        
        The name of the log stream that ingested this log event.
        
        logGroupIdentifier (string) –
        
        The name or ARN of the log group that ingested this log event.
        
        message (string) –
        
        The log event message text.
        
        timestamp (integer) –
        
        The timestamp specifying when this log event was created.
        
        ingestionTime (integer) –
        
        The timestamp specifying when this log event was ingested into the log group.
  - SessionTimeoutException (dict) –
    
    This exception is returned in the stream when the Live Tail session times out. Live Tail sessions time out after three hours.
    - message (string) –
  - SessionStreamingException (dict) –
    
    This exception is returned if an unknown error occurs.
    - message (string) –

Exceptions

CloudWatchLogs.Client.exceptions.AccessDeniedException
CloudWatchLogs.Client.exceptions.InvalidParameterException
CloudWatchLogs.Client.exceptions.ResourceNotFoundException
CloudWatchLogs.Client.exceptions.LimitExceededException
CloudWatchLogs.Client.exceptions.InvalidOperationException