From 1108100af759aff7f0ac1dda3ba3a61e7e8287f9 Mon Sep 17 00:00:00 2001 From: Gabe Henkes Date: Fri, 15 Jan 2016 16:56:36 -0600 Subject: [PATCH] Update documentation and tests --- docs/source/manual/configuration.rst | 36 +++++++++-------- .../AsyncAccessEventAppenderFactory.java | 9 +++++ .../jetty/DropwizardRequestLayout.java | 20 ---------- .../jetty/LogbackAccessRequestLayout.java | 21 ++++++++++ ...tLog.java => LogbackAccessRequestLog.java} | 4 +- .../jetty/LogbackAccessRequestLogFactory.java | 40 ++++++------------- .../jetty/LogbackAccessRequestLayoutTest.java | 21 ++++++++++ ....java => LogbackAccessRequestLogTest.java} | 4 +- .../logging/AbstractAppenderFactory.java | 13 ++++++ .../dropwizard/logging/AppenderFactory.java | 8 +++- .../logging/AsyncAppenderFactory.java | 9 +++++ .../AsyncLoggingEventAppenderFactory.java | 8 ++++ .../logging/SyslogAppenderFactory.java | 4 +- .../logging/filter/FilterFactory.java | 9 +++++ .../logging/filter/NullFilterFactory.java | 10 +++++ .../filter/ThresholdFilterFactory.java | 9 +++++ 16 files changed, 155 insertions(+), 70 deletions(-) delete mode 100644 dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLayout.java create mode 100644 dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLayout.java rename dropwizard-jetty/src/main/java/io/dropwizard/jetty/{DropwizardRequestLog.java => LogbackAccessRequestLog.java} (72%) create mode 100644 dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLayoutTest.java rename dropwizard-jetty/src/test/java/io/dropwizard/jetty/{DropwizardRequestLogTest.java => LogbackAccessRequestLogTest.java} (95%) diff --git a/docs/source/manual/configuration.rst b/docs/source/manual/configuration.rst index 6e7e7f8fd84..12a678e280d 100644 --- a/docs/source/manual/configuration.rst +++ b/docs/source/manual/configuration.rst @@ -69,7 +69,7 @@ GZip .. code-block:: yaml server: - gzip: + gzip: bufferSize: 8KiB @@ -105,13 +105,15 @@ Request Log .. code-block:: yaml server: - requestLog: - timeZone: UTC + requestLog: + - type: SLF4J + timeZone: UTC ====================== ================ =========== Name Default Description ====================== ================ =========== +type SLF4J The request log type. SLF4J or Logback-Access. timeZone UTC The time zone to which request timestamps will be converted. appenders console appender The set of AppenderFactory appenders to which requests will be logged. *TODO* See logging/appender refs for more info @@ -224,7 +226,7 @@ Name Default Description applicationConnectors An `HTTP connector`_ A set of :ref:`connectors ` which will listening on port 8080. handle application requests. adminConnectors An `HTTP connector`_ An `HTTP connector`_ listening on port 8081. - listening on port 8081. A set of :ref:`connectors ` which will + listening on port 8081. A set of :ref:`connectors ` which will handle admin requests. adminMinThreads 1 The minimum number of threads to use for admin requests. adminMaxThreads 64 The maximum number of threads to use for admin requests. @@ -246,7 +248,7 @@ HTTP ---- .. code-block:: yaml - + # Extending from the default server configuration server: applicationConnectors: @@ -300,7 +302,7 @@ idleTimeout 30 seconds The maximum idle time for a connect or when waiting for a new message to be sent on a connection. This value is interpreted as the maximum time between some progress being made on the connection. So if a single byte is read or written, then the timeout is reset. -minBufferPoolSize 64 bytes The minimum size of the buffer pool. +minBufferPoolSize 64 bytes The minimum size of the buffer pool. bufferPoolIncrement 1KiB The increment by which the buffer pool should be increased. maxBufferPoolSize 64KiB The maximum size of the buffer pool. acceptorThreads # of CPUs/2 The number of worker threads dedicated to accepting connections. @@ -327,7 +329,7 @@ HTTPS Extends the attributes that are available to the :ref:`HTTP connector ` .. code-block:: yaml - + # Extending from the default server configuration server: applicationConnectors: @@ -337,14 +339,14 @@ Extends the attributes that are available to the :ref:`HTTP connector crlPath: /path/to/file enableCRLDP: false @@ -395,8 +397,8 @@ excludedProtocols (none) A list of protocols (e.g., supportedCipherSuites (none) A list of cipher suites (e.g., ``TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256``) which are supported. All other cipher suites will be refused excludedCipherSuites (none) A list of cipher suites (e.g., ``TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256``) which - are excluded. These cipher suites will be refused and exclusion takes higher - precedence than inclusion, such that if a cipher suite is listed in + are excluded. These cipher suites will be refused and exclusion takes higher + precedence than inclusion, such that if a cipher suite is listed in ``supportedCipherSuites`` and ``excludedCipherSuites``, the cipher suite will be excluded. To verify that the proper cipher suites are being whitelisted and blacklisted, it is recommended to use the tool `sslyze`_. @@ -550,6 +552,7 @@ Name Default Description type REQUIRED The appender type. Must be ``console``. threshold ALL The lowest level of events to print to the console. timeZone UTC The time zone to which event timestamps will be converted. + Will be ignored if a logFormat is supplied. target stdout The name of the standard stream to which events will be written. Can be ``stdout`` or ``stderr``. logFormat default The Logback pattern with which events will be formatted. See @@ -588,10 +591,11 @@ threshold ALL The lowest level of events to write to archive true Whether or not to archive old events in separate files. archivedLogFilenamePattern (none) Required if ``archive`` is ``true``. The filename pattern for archived files. ``%d`` is replaced with the date in ``yyyy-MM-dd`` form, - and the fact that it ends with ``.gz`` indicates the file will be gzipped as it's archived. + and the fact that it ends with ``.gz`` indicates the file will be gzipped as it's archived. Likewise, filename patterns which end in ``.zip`` will be filled as they are archived. archivedFileCount 5 The number of archived files to keep. Must be between ``1`` and ``50``. timeZone UTC The time zone to which event timestamps will be converted. + Will be ignored if a logFormat is supplied. logFormat default The Logback pattern with which events will be formatted. See the Logback_ documentation for details. ============================ =========== ================================================================================================== @@ -802,11 +806,11 @@ Name Default Description ====================== =============== ==================================================================================================== host localhost The hostname (or group) of the Ganglia server(s) to report to. port 8649 The port of the Ganglia server(s) to report to. -mode unicast The UDP addressing mode to announce the metrics with. One of ``unicast`` +mode unicast The UDP addressing mode to announce the metrics with. One of ``unicast`` or ``multicast``. ttl 1 The time-to-live of the UDP packets for the announced metrics. uuid (none) The UUID to tag announced metrics with. -spoof (none) The hostname and port to use instead of this nodes for the announced metrics. +spoof (none) The hostname and port to use instead of this nodes for the announced metrics. In the format ``hostname:port``. tmax 60 The tmax value to announce metrics with. dmax 0 The dmax value to announce metrics with. @@ -993,7 +997,7 @@ TLS Name Default Description =========================== ================= ============================================================================================================================ protocol TLSv1.2 The default protocol the client will attempt to use during the SSL Handshake. - See + See `here `_ for more information. verifyHostname true Whether to verify the hostname of the server against the hostname presented in the server certificate. keyStorePath (none) The path to the Java key store which contains the client certificate and private key. diff --git a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/AsyncAccessEventAppenderFactory.java b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/AsyncAccessEventAppenderFactory.java index 41e8af61d9d..7e1201b0c3f 100644 --- a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/AsyncAccessEventAppenderFactory.java +++ b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/AsyncAccessEventAppenderFactory.java @@ -4,7 +4,16 @@ import ch.qos.logback.core.AsyncAppenderBase; import io.dropwizard.logging.AsyncAppenderFactory; +/** + * An implementation of {@link AsyncAppenderFactory} for {@link IAccessEvent}. + */ public class AsyncAccessEventAppenderFactory implements AsyncAppenderFactory { + + /** + * Creates an {@link AsyncAppenderFactory} of type {@link IAccessEvent} that prepares events + * for deferred processing + * @return the {@link AsyncAppenderFactory} + */ @Override public AsyncAppenderBase build() { return new AsyncAppenderBase() { diff --git a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLayout.java b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLayout.java deleted file mode 100644 index 6ea81e5d925..00000000000 --- a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLayout.java +++ /dev/null @@ -1,20 +0,0 @@ -package io.dropwizard.jetty; - -import ch.qos.logback.access.PatternLayout; -import ch.qos.logback.core.Context; - -/** - * A base layout for Dropwizard request logs. - *
    - *
  • Disables pattern headers.
    • - *
- */ -public class DropwizardRequestLayout extends PatternLayout { - - public DropwizardRequestLayout(Context context, String pattern) { - setOutputPatternAsHeader(false); - - setPattern(pattern); - setContext(context); - } -} diff --git a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLayout.java b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLayout.java new file mode 100644 index 00000000000..a0af79a292b --- /dev/null +++ b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLayout.java @@ -0,0 +1,21 @@ +package io.dropwizard.jetty; + +import ch.qos.logback.access.PatternLayout; +import ch.qos.logback.core.Context; + +/** + * A base layout for Logback Access request logs. + *
    + *
  • Extends {@link PatternLayout}.
    • + *
  • Disables pattern headers.
    • + *
+ */ +public class LogbackAccessRequestLayout extends PatternLayout { + + public LogbackAccessRequestLayout(Context context, String pattern) { + setOutputPatternAsHeader(false); + + setPattern(pattern); + setContext(context); + } +} diff --git a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLog.java b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLog.java similarity index 72% rename from dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLog.java rename to dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLog.java index dceee8b0e97..d4bb8d150f4 100644 --- a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/DropwizardRequestLog.java +++ b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLog.java @@ -6,9 +6,9 @@ * The Dropwizard request log uses logback-access, but we override it to remove the requirement for logback-access.xml * based configuration. */ -public class DropwizardRequestLog extends RequestLogImpl { +public class LogbackAccessRequestLog extends RequestLogImpl { @Override public void configure() { - setName("DropwizardRequestLog"); + setName("LogbackAccessRequestLog"); } } diff --git a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLogFactory.java b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLogFactory.java index 458da1901b8..80aa8dfda90 100644 --- a/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLogFactory.java +++ b/dropwizard-jetty/src/main/java/io/dropwizard/jetty/LogbackAccessRequestLogFactory.java @@ -1,8 +1,5 @@ package io.dropwizard.jetty; -import java.util.Optional; -import java.util.TimeZone; - import javax.validation.Valid; import javax.validation.constraints.NotNull; @@ -26,31 +23,20 @@ import io.dropwizard.logging.filter.NullFilterFactory; /** - * A factory for creating {@link RequestLog} instances. + * A factory for creating {@link LogbackAccessRequestLog} instances. *

* Configuration Parameters: * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * *
NameDefaultDescription
{@code timeZone}UTCThe time zone to which request timestamps will be converted, if using the default {@code logFormat}.
{@code logFormat}HTTP [%t{dd/MMM/yyyy:HH:mm:ss Z,UTC}] %h %l %u "%r" %s %b "%i{Referer}" "%i{User-Agent}"The Logback pattern with which events will be formatted. See - * the Logback documentation for details.
{@code appenders}a default {@link ConsoleAppenderFactory console} appenderThe set of {@link AppenderFactory appenders} to which requests will be logged.
NameDefaultDescription
{@code appenders}a default {@link ConsoleAppenderFactory console} appenderThe set of {@link AppenderFactory appenders} to which requests will be logged.
*/ @JsonTypeName("logback-access") @@ -83,13 +69,13 @@ public RequestLog build(String name) { final LoggerContext context = logger.getLoggerContext(); - final DropwizardRequestLog requestLog = new DropwizardRequestLog(); + final LogbackAccessRequestLog requestLog = new LogbackAccessRequestLog(); final FilterFactory thresholdFilterFactory = new NullFilterFactory<>(); final AsyncAppenderFactory asyncAppenderFactory = new AsyncAccessEventAppenderFactory(); for (AppenderFactory output : appenders) { - final Layout layout = new DropwizardRequestLayout(context, output.getLogFormat()); + final Layout layout = new LogbackAccessRequestLayout(context, output.getLogFormat()); layout.start(); requestLog.addAppender(output.build(context, name, layout, thresholdFilterFactory, asyncAppenderFactory)); } diff --git a/dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLayoutTest.java b/dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLayoutTest.java new file mode 100644 index 00000000000..dca0fda7d4f --- /dev/null +++ b/dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLayoutTest.java @@ -0,0 +1,21 @@ +package io.dropwizard.jetty; + +import ch.qos.logback.core.Context; +import org.junit.Test; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.Mockito.mock; + +public class LogbackAccessRequestLayoutTest { + + @Test + public void outputPatternAsHeaderIsFalse() { + final Context context = mock(Context.class); + final String pattern = "pattern"; + final LogbackAccessRequestLayout layout = new LogbackAccessRequestLayout(context, pattern); + + assertThat(layout.isOutputPatternAsHeader()).isFalse(); + assertThat(layout.getContext()).isEqualTo(context); + assertThat(layout.getPattern()).isEqualTo(pattern); + } +} diff --git a/dropwizard-jetty/src/test/java/io/dropwizard/jetty/DropwizardRequestLogTest.java b/dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLogTest.java similarity index 95% rename from dropwizard-jetty/src/test/java/io/dropwizard/jetty/DropwizardRequestLogTest.java rename to dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLogTest.java index 40635f7d164..4f28005151e 100644 --- a/dropwizard-jetty/src/test/java/io/dropwizard/jetty/DropwizardRequestLogTest.java +++ b/dropwizard-jetty/src/test/java/io/dropwizard/jetty/LogbackAccessRequestLogTest.java @@ -19,11 +19,11 @@ import ch.qos.logback.access.spi.IAccessEvent; import ch.qos.logback.core.Appender; -public class DropwizardRequestLogTest { +public class LogbackAccessRequestLogTest { @SuppressWarnings("unchecked") private final Appender appender = mock(Appender.class); - private final DropwizardRequestLog requestLog = new DropwizardRequestLog(); + private final LogbackAccessRequestLog requestLog = new LogbackAccessRequestLog(); private final Request request = mock(Request.class); private final Response response = mock(Response.class); diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/AbstractAppenderFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/AbstractAppenderFactory.java index 6a0e4997f8f..2d0291d9a27 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/AbstractAppenderFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/AbstractAppenderFactory.java @@ -33,6 +33,19 @@ * The minimum event level the appender will handle. * * + * {@code logFormat} + * (none) + * An appender-specific log format. + * + * + * {@code timeZone} + * {@code UTC} + * + * The time zone to which event timestamps will be converted. + * Ignored if logFormat is supplied. + * + * + * * {@code queueSize} * {@link AsyncAppenderBase} * The maximum capacity of the blocking queue. diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/AppenderFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/AppenderFactory.java index 149e106131c..1f9ade50a0d 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/AppenderFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/AppenderFactory.java @@ -25,11 +25,14 @@ @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") public interface AppenderFactory extends Discoverable { /** - * Given a Logback context, an application name, and a layout, build a new appender. + * Given a Logback context, an application name, a layout, + * a thresholdFilterFactory, and an asyncAppenderFactory build a new appender. * * @param context the Logback context * @param applicationName the application name * @param layout the layout for logging + * @param thresholdFilterFactory the factory for the threshold filter + * @param asyncAppenderFactory the factory for the async appender * @return a new, started {@link Appender} */ Appender build(LoggerContext context, @@ -38,5 +41,8 @@ Appender build(LoggerContext context, FilterFactory thresholdFilterFactory, AsyncAppenderFactory asyncAppenderFactory); + /** + * @return the log format of this AppenderFactory + */ String getLogFormat(); } diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncAppenderFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncAppenderFactory.java index d7f620201d6..3173c9c6724 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncAppenderFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncAppenderFactory.java @@ -2,6 +2,15 @@ import ch.qos.logback.core.AsyncAppenderBase; +/** + * Factory used to create an {@link AsyncAppenderBase} of type E + * @param The type of log event + */ public interface AsyncAppenderFactory { + + /** + * Creates an {@link AsyncAppenderBase} of type E + * @return a new {@link AsyncAppenderBase} + */ AsyncAppenderBase build(); } diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncLoggingEventAppenderFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncLoggingEventAppenderFactory.java index 7033bf034b2..d5786c86845 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncLoggingEventAppenderFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/AsyncLoggingEventAppenderFactory.java @@ -4,7 +4,15 @@ import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.AsyncAppenderBase; +/** + * An implementation of {@link AsyncAppenderFactory} for {@link ILoggingEvent}. + */ public class AsyncLoggingEventAppenderFactory implements AsyncAppenderFactory { + + /** + * Creates an {@link AsyncAppenderFactory} of type {@link ILoggingEvent} + * @return the {@link AsyncAppenderFactory} + */ @Override public AsyncAppenderBase build() { return new AsyncAppender(); diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/SyslogAppenderFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/SyslogAppenderFactory.java index c9d28eb5d33..75277274ea4 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/SyslogAppenderFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/SyslogAppenderFactory.java @@ -132,8 +132,8 @@ public enum Facility { /** * Returns the Logback pattern with which events will be formatted. */ - @JsonProperty @Override + @JsonProperty public String getLogFormat() { return logFormat; } @@ -141,8 +141,8 @@ public String getLogFormat() { /** * Sets the Logback pattern with which events will be formatted. */ - @JsonProperty @Override + @JsonProperty public void setLogFormat(String logFormat) { this.logFormat = logFormat; } diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/FilterFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/FilterFactory.java index 54954d84d08..73dd7d2b451 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/FilterFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/FilterFactory.java @@ -3,6 +3,15 @@ import ch.qos.logback.classic.Level; import ch.qos.logback.core.filter.Filter; +/** + * An interface for building Logback {@link Filter Filters} + * @param The type of log event + */ public interface FilterFactory { + + /** + * Creates a {@link Filter} of type E + * @return a new {@link Filter} + */ Filter build(Level threshold); } diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/NullFilterFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/NullFilterFactory.java index 75c4d089fdf..e80ce0a5e56 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/NullFilterFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/NullFilterFactory.java @@ -4,7 +4,17 @@ import ch.qos.logback.core.filter.Filter; import ch.qos.logback.core.spi.FilterReply; +/** + * Factory for building a logback {@link Filter} that will always defer to the next Filter. + * @param The type of log event + */ public class NullFilterFactory implements FilterFactory { + + /** + * Creates a {@link Filter} that will always defer to the next Filter in the chain, if any. + * @param threshold the parameter is ignored + * @return a {@link Filter} with a {@link Filter#decide(Object)} method that will always return {@link FilterReply#NEUTRAL}. + */ @Override public Filter build(Level threshold) { return new Filter() { diff --git a/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/ThresholdFilterFactory.java b/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/ThresholdFilterFactory.java index b623d6df4a0..494589fba37 100644 --- a/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/ThresholdFilterFactory.java +++ b/dropwizard-logging/src/main/java/io/dropwizard/logging/filter/ThresholdFilterFactory.java @@ -5,7 +5,16 @@ import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.filter.Filter; +/** + * Factory that creates a {@link Filter} of type {@link ILoggingEvent} + */ public class ThresholdFilterFactory implements FilterFactory { + + /** + * Creates and starts a {@link Filter} that for the given threshold. + * @param threshold The minimum event level for this filter. + * @return a new, started {@link Filter} + */ @Override public Filter build(Level threshold) { final ThresholdFilter filter = new ThresholdFilter();