Custom Logback AsyncAppender

Finatra provides a custom Logback AsyncAppender in inject-logback to provide metrics about the underlying queue and discarded log events.

Usage

To use the Finatra AsyncAppender first define all appenders that will log (i.e., Console or RollingFile appenders) and wrap them in the custom AsyncAppender. For more guidance, see the Logback documentation. There are also examples that use logback.xml files.

Metrics

This AsyncAppender adds four gauges to track values at a given point in time and counters to keep track of dropped Logback events per AsyncAppender. The gauges track:

{
  "logback/appender/async-service/current_queue_size" : 0.0,
  "logback/appender/async-service/discard/threshold" : 20.0,
  "logback/appender/async-service/max_flush_time" : 0.0,
  "logback/appender/async-service/queue_size" : 256.0,
}

The counters track the number of discarded events by log level. The appender follows the standard Logback AsyncAppender functionality for discarding events with the only addition being the introduction of metrics.

Important

All the appender metrics are of Debug verbosity and thus must explicitly be enabled. See the next section for information on enabling the custom Logback AsyncAppender metrics.

Enabling Metrics

Enabling the custom Logback AsyncAppender metrics requires changing the verbosity of the metrics via a Finagle Tunable.

Users need to create a JSON file and place it in the src/main/resources folder in com/twitter/tunables/finagle/instances.json to acceptlist the Logback metrics. To acceptlist all Logback metrics the JSON file could contain the following:

{
  "tunables":
  [
     {
        "id" : "com.twitter.finagle.stats.verbose",
        "value" : "logback/*",
        "type" : "java.lang.String"
     }
  ]
}

Registry

The configuration of each AsyncAppender will be added to the registry such that it can viewed without accessing the statically defined configuration. Different AsyncAppenders will registered in the registry by their defined name.

"library" : {
  "logback" : {
    "async-service" : {
      "never_block" : "false",
      "discarding_threshold" : "20",
      "include_caller_data" : "false",
      "max_flush_time" : "0",
      "max_queue_size" : "256",
      "appenders": "console"
    }
  },
  ...
}