com.amazonaws.services.logs.AWSLogs Maven / Gradle / Ivy
/*
* Copyright 2010-2014 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.services.logs;
import com.amazonaws.*;
import com.amazonaws.regions.*;
import com.amazonaws.services.logs.model.*;
/**
* Interface for accessing AWSLogs.
* Amazon CloudWatch Logs Service API Reference
* This is the Amazon CloudWatch Logs API Reference . Amazon
* CloudWatch Logs is a managed service for real time monitoring and
* archival of application logs. This guide provides detailed information
* about Amazon CloudWatch Logs actions, data types, parameters, and
* errors. For detailed information about Amazon CloudWatch Logs features
* and their associated API calls, go to the
* Amazon CloudWatch Logs Developer Guide
* .
*
*
* Use the following links to get started using the Amazon CloudWatch
* Logs API Reference :
*
*
*
* -
* Actions
* : An alphabetical list of all Amazon CloudWatch Logs actions.
* -
* Data Types
* : An alphabetical list of all Amazon CloudWatch Logs data types.
* -
* Common Parameters
* : Parameters that all Query actions can use.
* -
* Common Errors
* : Client and server errors that all actions can return.
* -
* Regions and Endpoints
* : Itemized regions and endpoints for all AWS products.
*
*
*
* In addition to using the Amazon CloudWatch Logs API, you can also use
* the following SDKs and third-party libraries to access Amazon
* CloudWatch Logs programmatically.
*
*
*
* -
* AWS SDK for Java Documentation
*
* -
* AWS SDK for .NET Documentation
*
* -
* AWS SDK for PHP Documentation
*
* -
* AWS SDK for Ruby Documentation
*
*
*
*
* Developers in the AWS developer community also provide their own
* libraries, which you can find at the following AWS developer centers:
*
*
*
* -
* AWS Java Developer Center
*
* -
* AWS PHP Developer Center
*
* -
* AWS Python Developer Center
*
* -
* AWS Ruby Developer Center
*
* -
* AWS Windows and .NET Developer Center
*
*
*
*/
public interface AWSLogs {
/**
* Overrides the default endpoint for this client ("https://logs.us-east-1.amazonaws.com").
* Callers can use this method to control which AWS region they want to work with.
*
* Callers can pass in just the endpoint (ex: "logs.us-east-1.amazonaws.com") or a full
* URL, including the protocol (ex: "https://logs.us-east-1.amazonaws.com"). If the
* protocol is not specified here, the default protocol from this client's
* {@link ClientConfiguration} will be used, which by default is HTTPS.
*
* For more information on using AWS regions with the AWS SDK for Java, and
* a complete list of all available endpoints for all AWS services, see:
*
* http://developer.amazonwebservices.com/connect/entry.jspa?externalID=3912
*
* This method is not threadsafe. An endpoint should be configured when the
* client is created and before any service requests are made. Changing it
* afterwards creates inevitable race conditions for any service requests in
* transit or retrying.
*
* @param endpoint
* The endpoint (ex: "logs.us-east-1.amazonaws.com") or a full URL,
* including the protocol (ex: "https://logs.us-east-1.amazonaws.com") of
* the region specific AWS endpoint this client will communicate
* with.
*
* @throws IllegalArgumentException
* If any problems are detected with the specified endpoint.
*/
public void setEndpoint(String endpoint) throws java.lang.IllegalArgumentException;
/**
* An alternative to {@link AWSLogs#setEndpoint(String)}, sets the
* regional endpoint for this client's service calls. Callers can use this
* method to control which AWS region they want to work with.
*
* By default, all service endpoints in all regions use the https protocol.
* To use http instead, specify it in the {@link ClientConfiguration}
* supplied at construction.
*
* This method is not threadsafe. A region should be configured when the
* client is created and before any service requests are made. Changing it
* afterwards creates inevitable race conditions for any service requests in
* transit or retrying.
*
* @param region
* The region this client will communicate with. See
* {@link Region#getRegion(com.amazonaws.regions.Regions)} for
* accessing a given region.
* @throws java.lang.IllegalArgumentException
* If the given region is null, or if this service isn't
* available in the given region. See
* {@link Region#isServiceSupported(String)}
* @see Region#getRegion(com.amazonaws.regions.Regions)
* @see Region#createClient(Class, com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration)
*/
public void setRegion(Region region) throws java.lang.IllegalArgumentException;
/**
*
* Sets the retention of the specified log group. A retention policy
* allows you to configure the number of days you want to retain log
* events in the specified log group.
*
*
* @param putRetentionPolicyRequest Container for the necessary
* parameters to execute the PutRetentionPolicy service method on
* AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void putRetentionPolicy(PutRetentionPolicyRequest putRetentionPolicyRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns all the metrics filters associated with the specified log
* group. The list returned in the response is ASCII-sorted by filter
* name.
*
*
* By default, this operation returns up to 50 metric filters. If there
* are more metric filters to list, the response would contain a
* nextToken value in the response body. You can also limit
* the number of metric filters returned in the response by specifying
* the limit parameter in the request.
*
*
* @param describeMetricFiltersRequest Container for the necessary
* parameters to execute the DescribeMetricFilters service method on
* AWSLogs.
*
* @return The response from the DescribeMetricFilters service method, as
* returned by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeMetricFiltersResult describeMetricFilters(DescribeMetricFiltersRequest describeMetricFiltersRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns all the log streams that are associated with the specified
* log group. The list returned in the response is ASCII-sorted by log
* stream name.
*
*
* By default, this operation returns up to 50 log streams. If there are
* more log streams to list, the response would contain a
* nextToken value in the response body. You can also limit
* the number of log streams returned in the response by specifying the
* limit parameter in the request.
*
*
* @param describeLogStreamsRequest Container for the necessary
* parameters to execute the DescribeLogStreams service method on
* AWSLogs.
*
* @return The response from the DescribeLogStreams service method, as
* returned by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeLogStreamsResult describeLogStreams(DescribeLogStreamsRequest describeLogStreamsRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes the log group with the specified name and permanently deletes
* all the archived log events associated with it.
*
*
* @param deleteLogGroupRequest Container for the necessary parameters to
* execute the DeleteLogGroup service method on AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void deleteLogGroup(DeleteLogGroupRequest deleteLogGroupRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Creates a new log group with the specified name. The name of the log
* group must be unique within a region for an AWS account. You can
* create up to 500 log groups per account.
*
*
* You must use the following guidelines when naming a log group:
*
* - Log group names can be between 1 and 512 characters long.
* - Allowed characters are a-z, A-Z, 0-9, '_' (underscore), '-'
* (hyphen), '/' (forward slash), and '.' (period).
*
*
*
*
*
* @param createLogGroupRequest Container for the necessary parameters to
* execute the CreateLogGroup service method on AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceAlreadyExistsException
* @throws LimitExceededException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void createLogGroup(CreateLogGroupRequest createLogGroupRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Creates or updates a metric filter and associates it with the
* specified log group. Metric filters allow you to configure rules to
* extract metric data from log events ingested through
* PutLogEvents requests.
*
*
* @param putMetricFilterRequest Container for the necessary parameters
* to execute the PutMetricFilter service method on AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceNotFoundException
* @throws LimitExceededException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void putMetricFilter(PutMetricFilterRequest putMetricFilterRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes a metric filter associated with the specified log group.
*
*
* @param deleteMetricFilterRequest Container for the necessary
* parameters to execute the DeleteMetricFilter service method on
* AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void deleteMetricFilter(DeleteMetricFilterRequest deleteMetricFilterRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Tests the filter pattern of a metric filter against a sample of log
* event messages. You can use this operation to validate the correctness
* of a metric filter pattern.
*
*
* @param testMetricFilterRequest Container for the necessary parameters
* to execute the TestMetricFilter service method on AWSLogs.
*
* @return The response from the TestMetricFilter service method, as
* returned by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public TestMetricFilterResult testMetricFilter(TestMetricFilterRequest testMetricFilterRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Uploads a batch of log events to the specified log stream.
*
*
* Every PutLogEvents request must include the
* sequenceToken obtained from the response of the previous
* request. An upload in a newly created log stream does not require a
* sequenceToken .
*
*
* The batch of events must satisfy the following constraints:
*
* - The maximum batch size is 32,768 bytes, and this size is
* calculated as the sum of all event messages in UTF-8, plus 26 bytes
* for each log event.
* - None of the log events in the batch can be more than 2 hours in
* the future.
* - None of the log events in the batch can be older than 14 days or
* the retention period of the log group.
* - The log events in the batch must be in chronological ordered by
* their
timestamp .
* - The maximum number of log events in a batch is 1,000.
*
*
*
*
*
* @param putLogEventsRequest Container for the necessary parameters to
* execute the PutLogEvents service method on AWSLogs.
*
* @return The response from the PutLogEvents service method, as returned
* by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws InvalidSequenceTokenException
* @throws DataAlreadyAcceptedException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public PutLogEventsResult putLogEvents(PutLogEventsRequest putLogEventsRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes the retention policy of the specified log group. Log events
* would not expire if they belong to log groups without a retention
* policy.
*
*
* @param deleteRetentionPolicyRequest Container for the necessary
* parameters to execute the DeleteRetentionPolicy service method on
* AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void deleteRetentionPolicy(DeleteRetentionPolicyRequest deleteRetentionPolicyRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Retrieves log events from the specified log stream. You can provide
* an optional time range to filter the results on the event
* timestamp .
*
*
* By default, this operation returns as much log events as can fit in a
* response size of 1MB, up to 10,000 log events. The response will
* always include a nextForwardToken and a
* nextBackwardToken in the response body. You can use any
* of these tokens in subsequent GetLogEvents requests to
* paginate through events in either forward or backward direction. You
* can also limit the number of log events returned in the response by
* specifying the limit parameter in the request.
*
*
* @param getLogEventsRequest Container for the necessary parameters to
* execute the GetLogEvents service method on AWSLogs.
*
* @return The response from the GetLogEvents service method, as returned
* by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public GetLogEventsResult getLogEvents(GetLogEventsRequest getLogEventsRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Creates a new log stream in the specified log group. The name of the
* log stream must be unique within the log group. There is no limit on
* the number of log streams that can exist in a log group.
*
*
* You must use the following guidelines when naming a log stream:
*
* - Log stream names can be between 1 and 512 characters long.
* - The ':' colon character is not allowed.
*
*
*
*
*
* @param createLogStreamRequest Container for the necessary parameters
* to execute the CreateLogStream service method on AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws ResourceNotFoundException
* @throws ResourceAlreadyExistsException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void createLogStream(CreateLogStreamRequest createLogStreamRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Deletes a log stream and permanently deletes all the archived log
* events associated with it.
*
*
* @param deleteLogStreamRequest Container for the necessary parameters
* to execute the DeleteLogStream service method on AWSLogs.
*
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
* @throws OperationAbortedException
* @throws ResourceNotFoundException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public void deleteLogStream(DeleteLogStreamRequest deleteLogStreamRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns all the log groups that are associated with the AWS account
* making the request. The list returned in the response is ASCII-sorted
* by log group name.
*
*
* By default, this operation returns up to 50 log groups. If there are
* more log groups to list, the response would contain a
* nextToken value in the response body. You can also limit
* the number of log groups returned in the response by specifying the
* limit parameter in the request.
*
*
* @param describeLogGroupsRequest Container for the necessary parameters
* to execute the DescribeLogGroups service method on AWSLogs.
*
* @return The response from the DescribeLogGroups service method, as
* returned by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeLogGroupsResult describeLogGroups(DescribeLogGroupsRequest describeLogGroupsRequest)
throws AmazonServiceException, AmazonClientException;
/**
*
* Returns all the log groups that are associated with the AWS account
* making the request. The list returned in the response is ASCII-sorted
* by log group name.
*
*
* By default, this operation returns up to 50 log groups. If there are
* more log groups to list, the response would contain a
* nextToken value in the response body. You can also limit
* the number of log groups returned in the response by specifying the
* limit parameter in the request.
*
*
* @return The response from the DescribeLogGroups service method, as
* returned by AWSLogs.
*
* @throws ServiceUnavailableException
* @throws InvalidParameterException
*
* @throws AmazonClientException
* If any internal errors are encountered inside the client while
* attempting to make the request or handle the response. For example
* if a network connection is not available.
* @throws AmazonServiceException
* If an error response is returned by AWSLogs indicating
* either a problem with the data in the request, or a server side issue.
*/
public DescribeLogGroupsResult describeLogGroups() throws AmazonServiceException, AmazonClientException;
/**
* Shuts down this client object, releasing any resources that might be held
* open. This is an optional method, and callers are not expected to call
* it, but can if they want to explicitly release any open resources. Once a
* client has been shutdown, it should not be used to make any more
* requests.
*/
public void shutdown();
/**
* Returns additional metadata for a previously executed successful request, typically used for
* debugging issues where a service isn't acting as expected. This data isn't considered part
* of the result data returned by an operation, so it's available through this separate,
* diagnostic interface.
*
* Response metadata is only cached for a limited period of time, so if you need to access
* this extra diagnostic information for an executed request, you should use this method
* to retrieve it as soon as possible after executing a request.
*
* @param request
* The originally executed request.
*
* @return The response metadata for the specified request, or null if none
* is available.
*/
public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
}