Skip to content

Latest commit

 

History

History
124 lines (98 loc) · 6.63 KB

jmx.md

File metadata and controls

124 lines (98 loc) · 6.63 KB
Raw

JMX Support

The appenders will optionally register JMX "statistics beans" with one or more MBeanServers. These beans provide information about the configuration and current operation of the log writers. See below for the description of each attribute.

jconsole mbean view

Enabling

To enable JMX reporting you must register an instance of StatisticsMBean with one or more MBeanServers. If you're using Log4J, you should register HierarchyDynamicMBean at the same time.

ManagementFactory.getPlatformMBeanServer().createMBean(
        HierarchyDynamicMBean.class.getName(),
        new ObjectName("log4j:name=Config"));

ManagementFactory.getPlatformMBeanServer().createMBean(
        StatisticsMBean.class.getName(),
        new ObjectName("log4j:name=Statistics"));

The ObjectName that you use to register these beans can be anything. I find it easier, as here, to use a namespace that's consistent with the framework I'm using.

Note: this represents a change from version 1.0 of the appenders, which would also ignore the namespace used to register StatisticsMBean and instead pick a name that organized the statistics beans under the Log4J-managed beans.

The example program, as a stand-alone application, uses the JVM's platform MBeanServer. Depending on the framework that your application uses, you may want to register with a framework-supplied server (for example, Spring provides its own server and expects you to register your JMX beans with the rest of your beans).

If your application explicitly unregisters the StatisticsMBean, then the appenders will unregister themselves from the same server(s). The appenders will also unregister themselves when closed. Normally you'd never do this: appenders only get closed when the application shuts down or is unloaded.

Classpath Isolation

Internally, the appenders library maintains the associations between StatisticMBeans, appender MBeans, and MBeanServers in statically-referenced data structures. This is necessary to avoid the inevitable race conditions between appender creation and StatisticMBean registration without creating explicit links between them.

To avoid strange JMX behavior -- for example, beans registered under one web-app but not another running in the same server -- you should load the appenders library in the same classloader as Log4J. You should do this anyway, to avoid Log4J configuration errors.

Attributes

Note: the authoritative documentation for each value is maintained as JavaDoc in the MXBean interfaces.

All log writers support the following attributes:

  • MessagesSent
    The number of messages successfully written to the destination.
  • MessagesSentLastBatch
    The number of messages successfully sent in the last batch. This number can be used to tune the batch delay for your application.
  • MessagesRequeuedLastBatch
    The number of messages that could not be sent in the last batch, and were requeued for a later batch. This should be zero. For KinesisAppender, a persistent non-zero value indicates that one or more partitions is at its limit for accepting messages. You should either increase the number of partitions, or change to a different (perhaps random) partition key.
  • MessagesDiscarded
    The number of messages that have been discarded by the writer due to queue backlog.
  • LastErrorMessage
    The last error message generated by the writer, if any. This normally contains an exception name and message, but may be a more generic error such as "initialization failure", and may not have an associated exception.
  • LastErrorTimestamp
    The time that the last writer error occurred, if any.
  • LastErrorStacktrace
    The stacktrace from the last writer error, if it involved an exception.

CloudWatchLogWriter provides the following additional attributes, defined by CloudWatchWriterStatisticsMXBean:

  • ActualLogGroupName
    The actual destination log group name, after subsitutions have been applied to the configured name.
  • ActualLogStreamName
    The actual destination log stream name, after subsitutions have been applied to the configured name.
  • WriterRaceRetries
    No longer used. Previously, the number of batches that were retried due to an invalid sequence token.
  • UnrecoveredWriterRaceRetries
    No longer used. Previously, the number of batches that were requeued due to repeated invalid sequence tokens.
  • throttledWrites: the number of times that a batch had to be retried because it was throttled. This should normally be 0. CloudWatch imposes a limit of 5 transactions per second per log stream, and an overall limit of either 800 or 1500 (depending on region) transactions per second across streams. The latter quota can be increased; the former quota cannot. If you have multiple writers to the same stream, the only solutions are to increase batch delay or use different streams (the latter is a better idea in general).

KinesisLogWriter provides the following additional attributes, defined by KinesisWriterStatisticsMXBean.

  • ActualStreamName
    The actual destination stream name, after subsitutions have been applied to the configured name.
  • throttledWrites: the number of times that an entire batch had to be retried because it was throttled. This value should be zero; if non-zero, you should increase the number of shards in the destination stream. Note that individual records in a batch may be throttled and retried; this is not tracked. You can identify individual shards that are at their limit via CloudWatch metrics.

SNSLogWriter provides the following additional attributes, defined by SNSWriterStatisticsMXBean.

  • ActualTopicName
    The actual destination topic name, after substitutions have been applied. This is set from configuration and then updated after the writer has initialized (so will be blank if you configure ARN and the writer fails to initialize).
  • ActualTopicArn
    The actual destination topic ARN, after substitutions have been applied. This is set from configuration and then updated after the writer has initialized (so will be blank if you configure by name and the writer fails to initialize).
  • ActualSubject
    The subject used for any messages, after subsitutions have been applied. Subjects are optional so this may be blank.