com.kdgregory.logging.aws.facade

Interface CloudWatchFacade

public interface CloudWatchFacade

Exposes the CloudWatch Logs APIs used by CloudWatchLogWriter.

Instances are created by FacadeFactory, and are tied to a single writer's configuration.

All operations may throw CloudWatchFacadeException. Callers are expected to catch this exception (it's checked), and take action based on the reason code that it exposes.

Method Summary

Modifier and Type	Method and Description
void	createLogGroup() Attempts to create the configured log group.
void	createLogStream() Attempts to create the configured log stream.
String	findLogGroup() Determines whether the configured log group exists, and returns its ARN if it does.
String	findLogStream() Determines whether the configured log stream exists, returning its ARN if it does.
String	putEvents(String sequenceToken, List<LogMessage> messages) Attempts to send a batch of messages.
String	retrieveSequenceToken() If the configured stream exists, returns the sequence token needed to write to it.
void	setLogGroupRetention() Sets the retention period on the configured log group.
void	shutdown() Shuts down the underlying client.

Method Detail

findLogGroup

String findLogGroup()

Determines whether the configured log group exists, and returns its ARN if it does. Returns null if the log group doesn't exist or the call is throttled.

createLogGroup

void createLogGroup()

Attempts to create the configured log group.

Log group creation is an asynchronous operation: the group may not be available for use for several seconds afterward. You should call findLogGroup() in a loop (with delays) until it returns the group's ARN.

setLogGroupRetention

void setLogGroupRetention()

Sets the retention period on the configured log group. The configured retention period must be one of the acceptable values.

findLogStream

String findLogStream()

Determines whether the configured log stream exists, returning its ARN if it does. Returns null if the log group doesn't exist or the call is throttled.

createLogStream

void createLogStream()

Attempts to create the configured log stream.

Stream creation is an asynchronous operation: the stream may not be available for several seconds after creation. You should call retrieveSequenceToken() in a loop (with delays) until it returns a value.

retrieveSequenceToken

String retrieveSequenceToken()

If the configured stream exists, returns the sequence token needed to write to it. Returns null if the stream does not exist or the retrieve operation is thottled.

Note: if the log group does not exist, this is treated as if the stream does not exist. The log-writer must use other mechanism (eg, failed write) to determine that it needs to recreate the log group.

putEvents

String putEvents(String sequenceToken,
                 List<LogMessage> messages)

Attempts to send a batch of messages. If successful, returns the next sequence token for the stream. If unsuccessful, throws an exception that should determine caller's next steps.

Parameters:

sequenceToken - Sequence token from a prior call to this method or an explicit call to retrieveSequenceToken().

messages - The messages to send. These messages must meet all of the requirements for PutLogEvents (sorted by timestamp, and within acceptable timestamp ranges).

shutdown

void shutdown()

Shuts down the underlying client.