StartLiveTail - Amazon CloudWatch Logs (original) (raw)

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:

Note

The StartLiveTail API routes requests tostreaming-logs._Region_.amazonaws.com using SDK host prefix injection. VPC endpoint support is not available for this API.

Important

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 AWS SDK.

Request Syntax

{
   "logEventFilterPattern": "string",
   "logGroupIdentifiers": [ "string" ],
   "logStreamNamePrefixes": [ "string" ],
   "logStreamNames": [ "string" ]
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

logEventFilterPattern

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.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

logGroupIdentifiers

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.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: [\w#+=/:,.@-]*

Required: Yes

logStreamNamePrefixes

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 inlogGroupIdentifiers.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Length Constraints: Minimum length of 1. Maximum length of 512.

Pattern: [^:*]*

Required: No

logStreamNames

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 inlogGroupIdentifiers.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Length Constraints: Minimum length of 1. Maximum length of 512.

Pattern: [^:*]*

Required: No

Response Syntax

{
   "responseStream": { 
      "sessionStart": { 
         "logEventFilterPattern": "string",
         "logGroupIdentifiers": [ "string" ],
         "logStreamNamePrefixes": [ "string" ],
         "logStreamNames": [ "string" ],
         "requestId": "string",
         "sessionId": "string"
      },
      "SessionStreamingException": { 
      },
      "SessionTimeoutException": { 
      },
      "sessionUpdate": { 
         "sessionMetadata": { 
            "sampled": boolean
         },
         "sessionResults": [ 
            { 
               "ingestionTime": number,
               "logGroupIdentifier": "string",
               "logStreamName": "string",
               "message": "string",
               "timestamp": number
            }
         ]
      }
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

responseStream

An object that includes the stream returned by your request. It can include both log events and exceptions.

Type: StartLiveTailResponseStream object

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You don't have sufficient permissions to perform this action.

HTTP Status Code: 400

InvalidOperationException

The operation is not valid on the specified resource.

HTTP Status Code: 400

InvalidParameterException

A parameter is specified incorrectly.

HTTP Status Code: 400

LimitExceededException

You have reached the maximum number of resources that can be created.

HTTP Status Code: 400

ResourceNotFoundException

The specified resource does not exist.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: