@Plugin(name="CloudWatchAppender",
category="Core",
elementType="appender")
public class CloudWatchAppender
extends AbstractAppender<CloudWatchWriterConfig,CloudWatchAppenderConfig,CloudWatchWriterStatistics,CloudWatchWriterStatisticsMXBean>
This appender supports the following configuration parameters:
| logGroup | Name of the CloudWatch log group where messages are sent; may use
substitutions. If this group doesn't exist it will be created.
You typically assign a single log group to an application, and then use multiple log streams for instances of that application. There is no default value. If you do not configure the log group, the appender will be disabled and will report its misconfiguration. |
|---|---|
| logStream | Name of the CloudWatch log stream where messages are sent; may use
substitutions. If this stream doesn't exist it will be created.
You typically create a separate log stream for each instance of the application.
Default value is |
| retentionPeriod | (optional) Specifies a retention period for created CloudWatch log groups. If omitted, messages are retained forever. Note that values are restricted; see AWS API doc. |
| dedicatedWriter | If true (the default), the appender assumes that it is the only thing writing to the log stream, and does not fetch a sequence token before each write. This improves performance and reduces the likelihood of throttling when there are a large number of processes (as long as they write to different streams). If you need to have multiple appenders writing to the same stream, set this to false. |
| synchronous | If true, the appender will operate in synchronous mode: calls to
append() execute on the caller's thread, and will not return until
writer has attempted to send a batch (errors may still result in
messages being requeued for the next batch). This negates the benefits
of message batching, and should only be used in cases (like AWS Lambda)
where background thread processing is not guaranteed.
Note: setting |
| batchDelay | The time, in milliseconds, that the writer will wait to accumulate
messages for a batch.
The writer attempts to gather multiple logging messages into a batch, to reduce communication with the service. The batch delay controls the time that a message will remain in-memory while the writer builds this batch. In a low-volume environment it will be the main determinant of when the batch is sent; in a high volume environment it's likely that the maximum request size will be reached before the delay elapses. The default value is 2000, which is rather arbitrarily chosen. If the appender is in synchronous mode, this setting is ignored. |
| truncateOversizeMessages | If true (the default), oversize messages are truncated to
the maximum length permitted by CloudWatch Logs. If false
they are discarded. In either case, the oversized message is reported
to the Log4J debug log.
|
| discardThreshold | The number of unsent messages that will trigger message discard. A
high value is useful when network connectivity is intermittent and/or
overall AWS communication is causing throttling. However, a value that
is too high may cause out-of-memory errors.
The default, 10,000, is based on the assumptions that (1) each message will be 1k or less, and (2) any app that uses remote logging can afford 10MB. |
| discardAction | The action to take when the number of unsent messages exceeds the
discard threshold. Values are "none" (retain all messages), "oldest"
(discard oldest messages), and "newest" (discard most recent messages).
The default is "oldest". Attempting to set an incorrect value will throw a configuration error. |
| assumedRole | Specifies role name or ARN that will be assumed by this appender. Useful for cross-account logging. If the appender does not have permission to assume this role, initialization will fail. |
| clientFactory | The fully-qualified name of a static method to create the correct AWS
client, which will be called instead of the writer's internal client
factory. This is useful if you need non-default configuration, such as
using a proxy server.
The passed string is of the form |
| clientRegion | Specifies a non-default service region. This setting is ignored if you use a client factory. |
| clientEndpoint | Specifies a non-default service endpoint. Typically used when running in a VPC, when the normal endpoint is not available. |
| initializationTimeout | Milliseconds to wait for appender to initialize. If this timeout expires, the appender will shut down its writer thread and discard any future log events. The only reason to change this is if you're deploying to a high- contention environment (and even then, the default of 60 seconds should be more than enough). |
| useShutdownHook | This exists for consistency with other appenders but ignored; Log4J2 provides its own shutdown hooks. |
| Modifier and Type | Class and Description |
|---|---|
static class |
CloudWatchAppender.CloudWatchAppenderBuilder |
| Modifier and Type | Field and Description |
|---|---|
protected Integer |
retentionPeriod |
appenderConfig, appenderStats, discardAction, internalLogger, layoutCharset, threadFactory, writer, writerFactory| Modifier | Constructor and Description |
|---|---|
protected |
CloudWatchAppender(String name,
CloudWatchAppenderConfig config,
InternalLogger internalLogger) |
| Modifier and Type | Method and Description |
|---|---|
protected CloudWatchWriterConfig |
generateWriterConfig()
Called as part of initialization.
|
static CloudWatchAppender.CloudWatchAppenderBuilder |
newBuilder() |
append, getAppenderStatistics, getConfig, registerStatisticsBean, start, stop, stop, unregisterStatisticsBeanerror, error, error, getHandler, getLayout, getName, ignoreExceptions, parseInt, setHandler, toStringaddFilter, getFilter, hasFilter, isFiltered, removeFilter, stopequalsImpl, getState, getStatusLogger, hashCodeImpl, initialize, isInitialized, isStarted, isStarting, isStopped, isStopping, setStarted, setStarting, setState, setStopped, setStopping, stopprotected Integer retentionPeriod
protected CloudWatchAppender(String name, CloudWatchAppenderConfig config, InternalLogger internalLogger)
@PluginBuilderFactory public static CloudWatchAppender.CloudWatchAppenderBuilder newBuilder()
protected CloudWatchWriterConfig generateWriterConfig()
AbstractAppenderCopyright © 2022. All rights reserved.