com.kdgregory.logback.aws

Class JsonAccessLayout

java.lang.Object

ch.qos.logback.core.spi.ContextAwareBase

ch.qos.logback.core.LayoutBase<E>

com.kdgregory.logback.aws.internal.AbstractJsonLayout<ch.qos.logback.access.spi.IAccessEvent>

com.kdgregory.logback.aws.JsonAccessLayout

All Implemented Interfaces:

ch.qos.logback.core.Layout<ch.qos.logback.access.spi.IAccessEvent>, ch.qos.logback.core.spi.ContextAware, ch.qos.logback.core.spi.LifeCycle

public class JsonAccessLayout
extends AbstractJsonLayout<ch.qos.logback.access.spi.IAccessEvent>

Formats an IAccessEvent as a JSON string, with additional parameters.

The JSON object always contains the following properties. Most come from the event, but some are extracted from the request itself (which is provided by the event).

• timestamp: the date/time that the message was logged, in ISO-8601 UTC format.
• hostname: the name of the host running the app-server, extracted from RuntimeMxBean (may not be available on all platforms).
• processId: the process ID of the app-server.
• thread: the name of the thread that processed the request.
• elapsedTime: the elapsed time for request processing, in milliseconds.
• protocol: the name and version of the request protocol (eg, "HTTP/1.1").
• requestMethod: the HTTP request method (eg, "GET").
• requestURI: the requested resource, excluding host, port, or query string.
• statusCode: the response status code.
• bytesSent: the number of bytes (content-length) of the response.
• remoteIP: the IP address of the originating server.
• forwardedFor: the value of the X-Forwarded-For header, if it exists. Used to identify source IP when running behind a load balancer.

The following properties are potentially expensive to compute, may leak secrets, or significantly increase the size of the generated JSON, so will only appear if specifically enabled:

• instanceId: the EC2 instance ID of the machine where the logger is running. WARNING: do not enable this elsewhere, as the operation to retrieve this value may take a long time (and return nothing).
• cookies: a list of cookie objects, with all attributes (name, value, domain, max age, &c). These are subject to whitelisting and blacklisting via includeCookies and excludeCookies.
• parameters: the request parameters, if any. These are subject to whitelisting and blacklisting via includeParameters and excludeParameters.
• queryString: the query string, if any.
• remoteHost: the remote hostname. This may involve a DNS lookup.
• requestHeaders: the request headers. These are subject to whitelisting and blacklisting via includeHeaders and excludeHeaders.
• responseHeaders: the response headers. These are subject to whitelisting and blacklisting via includeHeaders and excludeHeaders.
• server: the destination server name. This is normally extracted from the Host request header, but may involve a DNS lookup (see J2EE docs for more info).
• sessionId: the session ID. This may not be available, which will trigger an ignored exception on retrieval.
• user: the remote user, if one exists.

Lastly, you can define a set of user tags, which are written as a child object with the key tags. These are intended to provide program-level information, in the case where multiple programs send their logs to the same stream. They are set as a single comma-separate string, which may contain substitution values (example: appserver-name=Fribble,startedAt={startupTimestamp}).

WARNING: you should not rely on the order in which elements are output. Any apparent ordering is an implementation artifact and subject to change without notice.

Field Summary

Fields inherited from class ch.qos.logback.core.LayoutBase

started

Fields inherited from class ch.qos.logback.core.spi.ContextAwareBase

context

Constructor Summary

Constructors

Constructor and Description
JsonAccessLayout()

Method Summary

Modifier and Type	Method and Description
String	doLayout(ch.qos.logback.access.spi.IAccessEvent event)
boolean	getEnableCookies()
boolean	getEnableParameters()
boolean	getEnableQueryString()
boolean	getEnableRemoteHost()
boolean	getEnableRemoteUser()
boolean	getEnableRequestHeaders()
boolean	getEnableResponseHeaders()
boolean	getEnableServer()
boolean	getEnableSessionId()
String	getExcludeCookies()
String	getExcludeHeaders()
String	getExcludeParameters()
String	getIncludeCookies()
String	getIncludeHeaders()
String	getIncludeParameters()
void	setEnableCookies(boolean value) Enables storing request cookies in the output.
void	setEnableParameters(boolean value) Enables storing request parameters in the output.
void	setEnableQueryString(boolean value) Enables storing the unparsed request query string in the output.
void	setEnableRemoteHost(boolean value) Optionally enables looking up the hostname of the remote host.
void	setEnableRemoteUser(boolean value) Enables retrieving the remote user's name, if it's known.
void	setEnableRequestHeaders(boolean value) Enables storing request headers in the output.
void	setEnableResponseHeaders(boolean value) Enables storing request headers in the output.
void	setEnableServer(boolean value) Optionally enables inserting the hostname of the destination server, taken from the HTTP request.
void	setEnableSessionId(boolean value) Optionally enables storing the session ID in the result.
void	setExcludeCookies(String value) Sets the list of cookies that will be explicitly excluded from the output.
void	setExcludeHeaders(String value) Sets the list of headers that will be explicitly excluded from the output.
void	setExcludeParameters(String value) Sets the list of parameters that will be explicitly excluded from the output.
void	setIncludeCookies(String value) Sets the list of cookies that will be included in the output.
void	setIncludeHeaders(String value) Sets the list of headers that will be included in the output.
void	setIncludeParameters(String value) Sets the list of parameters that will be included in the output.

Methods inherited from class com.kdgregory.logback.aws.internal.AbstractJsonLayout

addCommonAttributesAndConvert, getAppendNewlines, getEnableAccountId, getEnableHostname, getEnableInstanceId, getTags, setAppendNewlines, setEnableAccountId, setEnableHostname, setEnableInstanceId, setTags, start, stop

Methods inherited from class ch.qos.logback.core.LayoutBase

getContentType, getContext, getFileFooter, getFileHeader, getPresentationFooter, getPresentationHeader, isStarted, setContext, setFileFooter, setFileHeader, setPresentationFooter, setPresentationHeader

Methods inherited from class ch.qos.logback.core.spi.ContextAwareBase

addError, addError, addInfo, addInfo, addStatus, addWarn, addWarn, getDeclaredOrigin, getStatusManager

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ch.qos.logback.core.spi.ContextAware

addError, addError, addInfo, addInfo, addStatus, addWarn, addWarn

Constructor Detail

JsonAccessLayout

public JsonAccessLayout()

Method Detail

setEnableServer

public void setEnableServer(boolean value)

Optionally enables inserting the hostname of the destination server, taken from the HTTP request.

getEnableServer

public boolean getEnableServer()

setEnableRemoteHost

public void setEnableRemoteHost(boolean value)

Optionally enables looking up the hostname of the remote host. This is likely to be an expensive operation.

getEnableRemoteHost

public boolean getEnableRemoteHost()

setEnableRemoteUser

public void setEnableRemoteUser(boolean value)

Enables retrieving the remote user's name, if it's known.

getEnableRemoteUser

public boolean getEnableRemoteUser()

setEnableSessionId

public void setEnableSessionId(boolean value)

Optionally enables storing the session ID in the result.

getEnableSessionId

public boolean getEnableSessionId()

setEnableRequestHeaders

public void setEnableRequestHeaders(boolean value)

Enables storing request headers in the output. This must be used along with either includeHeaders or excludeHeaders to avoid accidentally leaking secrets.

getEnableRequestHeaders

public boolean getEnableRequestHeaders()

setEnableResponseHeaders

public void setEnableResponseHeaders(boolean value)

Enables storing request headers in the output. This must be used along with either includeHeaders and excludeHeaders to avoid accidentally leaking secrets.

getEnableResponseHeaders

public boolean getEnableResponseHeaders()

setIncludeHeaders

public void setIncludeHeaders(String value)

Sets the list of headers that will be included in the output. This is a comma-separated list of names or the special value "*". If given a list of names, only those names will be included; "*" includes all headers. Note that excludeHeaders still applies; even if a header is explicitly whitelisted it may still be omitted.

getIncludeHeaders

public String getIncludeHeaders()

setExcludeHeaders

public void setExcludeHeaders(String value)

Sets the list of headers that will be explicitly excluded from the output. This is a comma-separated list of names, and takes precedence over includeHeaders.

getExcludeHeaders

public String getExcludeHeaders()

setEnableParameters

public void setEnableParameters(boolean value)

Enables storing request parameters in the output. This must be used along with either includeParameters and excludeParameters to avoid accidentally leaking secrets.

getEnableParameters

public boolean getEnableParameters()

setIncludeParameters

public void setIncludeParameters(String value)

Sets the list of parameters that will be included in the output. This is a comma-separated list of names, or the special value "*". If given a list of names, only those names will be included; "*" includes all parameters. Note that excludeParameters still applies; even if a parameter is explicitly whitelisted it may still be omitted.

getIncludeParameters

public String getIncludeParameters()

setExcludeParameters

public void setExcludeParameters(String value)

Sets the list of parameters that will be explicitly excluded from the output. This is a comma-separated list of names, and takes precedence over includeParameters.

getExcludeParameters

public String getExcludeParameters()

setEnableCookies

public void setEnableCookies(boolean value)

Enables storing request cookies in the output. You must also configure, includeCookies and (optionally) excludeCookies to avoid accidentally leaking secrets.

getEnableCookies

public boolean getEnableCookies()

setIncludeCookies

public void setIncludeCookies(String value)

Sets the list of cookies that will be included in the output. This is a comma-separated list of names, or the special value "*". If given a list of names, only those names will be included; "*" includes all cookies. Note that excludeCookies takes precedence; even if a cookie is explicitly whitelisted it may still be omitted.

getIncludeCookies

public String getIncludeCookies()

setExcludeCookies

public void setExcludeCookies(String value)

Sets the list of cookies that will be explicitly excluded from the output. This is a comma-separated list of names, and takes precedence over includeCookies.

getExcludeCookies

public String getExcludeCookies()

setEnableQueryString

public void setEnableQueryString(boolean value)

Enables storing the unparsed request query string in the output. This is not as useful as storing the request parameters, and may leak secrets.

getEnableQueryString

public boolean getEnableQueryString()

doLayout

public String doLayout(ch.qos.logback.access.spi.IAccessEvent event)