From 8d1bd1f7e7fb4cc4cffe8b993edc58a90b7748ed Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Fri, 16 Sep 2022 12:00:43 +0300 Subject: [PATCH 1/3] Access log documentation fix --- docs/mp/server.adoc | 146 ++++++++++++++++++++++++++++++++++++++++- docs/se/webserver.adoc | 10 +++ 2 files changed, 155 insertions(+), 1 deletion(-) diff --git a/docs/mp/server.adoc b/docs/mp/server.adoc index e5e22288e90..be9adaf665b 100644 --- a/docs/mp/server.adoc +++ b/docs/mp/server.adoc @@ -109,7 +109,151 @@ In this example, the configuration is in a file, and it includes Helidon configu include::{rootdir}/config/io_helidon_webserver_WebServer.adoc[leveloffset=+1,tag=config] -== Examples + +== Access Log + +Access logging in Helidon is done by a dedicated module that can be +added to Maven and configured. + +To enable Access logging add the following dependency to project's `pom.xml`: + +[source,xml] +---- + + io.helidon.microprofile + helidon-microprofile-access-log + +---- + +=== Configuring Access Log in a configuration file + +Access log can be configured as follows: + +[source, properties] +.Access Log configuration file +---- +server.port=8080 +server.host=0.0.0.0 +server.access-log.format=helidon +---- + +All options shown above are also available programmatically when using builder. + +=== Configuration Options + +The following configuration options can be defined: + +[cols="2,2,2,5", role="flex, sm10"] +|=== +|Config key |Default value |Builder method |Description + +|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled +|`logger-name` |`io.helidon.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries +|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output, +when `helidon` is defined, the Helidon log format (see below) is used. +Can be configured to explicitly define log entries (see below as well) +|`exclude-paths`|N/A|`excludePaths(List)` | List of path patterns to exclude from access log. Path pattern syntax is as +defined in `io.helidon.webserver.PathMatcher`. Can be used to exclude +paths such as `/health` or `/metrics` to avoid cluttering log. + +|=== + +=== Supported Log Formats + +==== Supported Log Entries + +The following log entries are supported in Helidon: + +[cols="2,2,5",role="flex, sm7"] +|=== +|Config format |Class (to use with builder) |Description + +|%h |`HostLogEntry` |IP address of the remote host +|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon +|%u |`UserLogEntry` |The username of logged-in user (when Security is used) +|%t |`TimestampLogEntry` |The current timestamp +|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version) +|%s |`StatusLogEntry` |The HTTP status returned to the client +|%b |`SizeLogEntry` |The response entity size (if available) +|%D |`TimeTakenLogEntry` |The time taken in microseconds +|%T |`TimeTakenLogEntry` |The time taken in seconds +|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write +multiple headers) +|=== + +Currently we only support the entries defined above, with NO support for free text. + +==== Helidon Log Format +When format is set to `helidon`, the format used is: + +`"%h %u %t %r %s %b %D"` + +The entries logged: + +1. IP Address +2. Username of a logged-in user +3. Timestamp +4. Request Line +5. HTTP Status code +6. Entity size +7. Time taken (microseconds) + +Access log example: + +[source, listing] +---- +192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 +0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 +0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 +0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 +0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 +---- + +==== Common Log Format +When format is set to `common`, the format used is: + +`"%h %l %u %t %r %s %b"` + +The entries logged: + +1. IP Address +2. Client identity +3. Username of a logged-in user +4. Timestamp +5. Request Line +6. HTTP Status code +7. Entity size + +Access log example: + +[source, listing] +---- +192.168.0.104 - - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 +0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 +0:0:0:0:0:0:0:1 - jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 +0:0:0:0:0:0:0:1 - jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 +0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 +---- + +=== Configuring Access Log with Java util logging + +To support a separate file for Access log entries, Helidon provides a custom +log handler, that extends the `FileHandler`. + +To log to a file `access.log` with appending records after restart, you can use the +following configuration in `logging.properties`: + +[source, properties] +.Logging configuration file +---- +io.helidon.webserver.accesslog.AccessLogHandler.level=INFO +io.helidon.webserver.accesslog.AccessLogHandler.pattern=access.log +io.helidon.webserver.accesslog.AccessLogHandler.append=true + +io.helidon.webserver.AccessLog.level=INFO +io.helidon.webserver.AccessLog.useParentHandlers=false +io.helidon.webserver.AccessLog.handlers=io.helidon.webserver.accesslog.AccessLogHandler +---- === Configuring TLS diff --git a/docs/se/webserver.adoc b/docs/se/webserver.adoc index 43df966d970..48b543691bb 100644 --- a/docs/se/webserver.adoc +++ b/docs/se/webserver.adoc @@ -814,6 +814,16 @@ in the order it is registered with WebServer routing. This implies that if you register it last and another `Service` or `Handler` finishes the request, the service will not be invoked. +To enable Access logging add the following dependency to project's `pom.xml`: + +[source,xml] +---- + + io.helidon.webserver + helidon-webserver-access-log + +---- + === Configuring Access Log in your code From 22790777b8d4ede2d522b554b3bf86e93bf388c5 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Mon, 19 Sep 2022 11:32:39 +0300 Subject: [PATCH 2/3] Minor reference fix --- docs/mp/server.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/mp/server.adoc b/docs/mp/server.adoc index be9adaf665b..065177a0bed 100644 --- a/docs/mp/server.adoc +++ b/docs/mp/server.adoc @@ -109,8 +109,9 @@ In this example, the configuration is in a file, and it includes Helidon configu include::{rootdir}/config/io_helidon_webserver_WebServer.adoc[leveloffset=+1,tag=config] +== Examples -== Access Log +=== Access Log Access logging in Helidon is done by a dedicated module that can be added to Maven and configured. From dd425b5085d89b4c693103adebca1c0caeddcd32 Mon Sep 17 00:00:00 2001 From: Dmitry Aleksandrov Date: Tue, 20 Sep 2022 16:29:43 +0300 Subject: [PATCH 3/3] Common parts extracted (access log config) --- .../server/access-log-config-common.adoc | 92 ++++++++++++++ docs/mp/server.adoc | 116 +----------------- docs/se/webserver.adoc | 115 +---------------- 3 files changed, 94 insertions(+), 229 deletions(-) create mode 100644 docs/includes/server/access-log-config-common.adoc diff --git a/docs/includes/server/access-log-config-common.adoc b/docs/includes/server/access-log-config-common.adoc new file mode 100644 index 00000000000..69687da67a4 --- /dev/null +++ b/docs/includes/server/access-log-config-common.adoc @@ -0,0 +1,92 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2022 Oracle and/or its affiliates. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +/////////////////////////////////////////////////////////////////////////////// + +ifndef::rootdir[:rootdir: {docdir}/../..] +:description: Access Log Config +:keywords: helidon, webserver, access, log + + +== Configuration Options + +The following configuration options can be defined: + +[cols="2,2,2,5", role="flex, sm10"] +|=== +|Config key |Default value |Builder method |Description + +|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled +|`logger-name` |`io.helidon.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries +|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output, +when `helidon` is defined, the Helidon log format (see below) is used. +Can be configured to explicitly define log entries (see below as well) +|`exclude-paths`|N/A|`excludePaths(List)` | List of path patterns to exclude from access log. Path pattern syntax is as +defined in `io.helidon.webserver.PathMatcher`. Can be used to exclude +paths such as `/health` or `/metrics` to avoid cluttering log. + +|=== + +== Supported Log Formats + +=== Supported Log Entries + +The following log entries are supported in Helidon: + +[cols="2,2,5",role="flex, sm7"] +|=== +|Config format |Class (to use with builder) |Description + +|%h |`HostLogEntry` |IP address of the remote host +|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon +|%u |`UserLogEntry` |The username of logged-in user (when Security is used) +|%t |`TimestampLogEntry` |The current timestamp +|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version) +|%s |`StatusLogEntry` |The HTTP status returned to the client +|%b |`SizeLogEntry` |The response entity size (if available) +|%D |`TimeTakenLogEntry` |The time taken in microseconds +|%T |`TimeTakenLogEntry` |The time taken in seconds +|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write +multiple headers) +|=== + +Currently we only support the entries defined above, with NO support for free text. + +=== Helidon Log Format +When format is set to `helidon`, the format used is: + +`"%h %u %t %r %s %b %D"` + +The entries logged: + +1. IP Address +2. Username of a logged-in user +3. Timestamp +4. Request Line +5. HTTP Status code +6. Entity size +7. Time taken (microseconds) + +Access log example: + +[source, listing] +---- +192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 +0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 +0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 +0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 +0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 +---- diff --git a/docs/mp/server.adoc b/docs/mp/server.adoc index 065177a0bed..e7de1ce2587 100644 --- a/docs/mp/server.adoc +++ b/docs/mp/server.adoc @@ -140,121 +140,7 @@ server.access-log.format=helidon All options shown above are also available programmatically when using builder. -=== Configuration Options - -The following configuration options can be defined: - -[cols="2,2,2,5", role="flex, sm10"] -|=== -|Config key |Default value |Builder method |Description - -|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled -|`logger-name` |`io.helidon.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries -|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output, -when `helidon` is defined, the Helidon log format (see below) is used. -Can be configured to explicitly define log entries (see below as well) -|`exclude-paths`|N/A|`excludePaths(List)` | List of path patterns to exclude from access log. Path pattern syntax is as -defined in `io.helidon.webserver.PathMatcher`. Can be used to exclude -paths such as `/health` or `/metrics` to avoid cluttering log. - -|=== - -=== Supported Log Formats - -==== Supported Log Entries - -The following log entries are supported in Helidon: - -[cols="2,2,5",role="flex, sm7"] -|=== -|Config format |Class (to use with builder) |Description - -|%h |`HostLogEntry` |IP address of the remote host -|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon -|%u |`UserLogEntry` |The username of logged-in user (when Security is used) -|%t |`TimestampLogEntry` |The current timestamp -|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version) -|%s |`StatusLogEntry` |The HTTP status returned to the client -|%b |`SizeLogEntry` |The response entity size (if available) -|%D |`TimeTakenLogEntry` |The time taken in microseconds -|%T |`TimeTakenLogEntry` |The time taken in seconds -|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write -multiple headers) -|=== - -Currently we only support the entries defined above, with NO support for free text. - -==== Helidon Log Format -When format is set to `helidon`, the format used is: - -`"%h %u %t %r %s %b %D"` - -The entries logged: - -1. IP Address -2. Username of a logged-in user -3. Timestamp -4. Request Line -5. HTTP Status code -6. Entity size -7. Time taken (microseconds) - -Access log example: - -[source, listing] ----- -192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 -0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 -0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 -0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 -0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 ----- - -==== Common Log Format -When format is set to `common`, the format used is: - -`"%h %l %u %t %r %s %b"` - -The entries logged: - -1. IP Address -2. Client identity -3. Username of a logged-in user -4. Timestamp -5. Request Line -6. HTTP Status code -7. Entity size - -Access log example: - -[source, listing] ----- -192.168.0.104 - - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 -0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 -0:0:0:0:0:0:0:1 - jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 -0:0:0:0:0:0:0:1 - jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 -0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 ----- - -=== Configuring Access Log with Java util logging - -To support a separate file for Access log entries, Helidon provides a custom -log handler, that extends the `FileHandler`. - -To log to a file `access.log` with appending records after restart, you can use the -following configuration in `logging.properties`: - -[source, properties] -.Logging configuration file ----- -io.helidon.webserver.accesslog.AccessLogHandler.level=INFO -io.helidon.webserver.accesslog.AccessLogHandler.pattern=access.log -io.helidon.webserver.accesslog.AccessLogHandler.append=true - -io.helidon.webserver.AccessLog.level=INFO -io.helidon.webserver.AccessLog.useParentHandlers=false -io.helidon.webserver.AccessLog.handlers=io.helidon.webserver.accesslog.AccessLogHandler ----- +include::{rootdir}/includes/server/access-log-config-common.adoc[leveloffset=+1] === Configuring TLS diff --git a/docs/se/webserver.adoc b/docs/se/webserver.adoc index 48b543691bb..909e5fa81f2 100644 --- a/docs/se/webserver.adoc +++ b/docs/se/webserver.adoc @@ -853,121 +853,8 @@ server: All options shown above are also available programmatically when using builder. -=== Configuration Options - -The following configuration options can be defined: - -[cols="2,2,2,5", role="flex, sm10"] -|=== -|Config key |Default value |Builder method |Description - -|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled -|`logger-name` |`io.helidon.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries -|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output, -when `helidon` is defined, the Helidon log format (see below) is used. -Can be configured to explicitly define log entries (see below as well) -|`exclude-paths`|N/A|`excludePaths(List)` | List of path patterns to exclude from access log. Path pattern syntax is as -defined in `io.helidon.webserver.PathMatcher`. Can be used to exclude -paths such as `/health` or `/metrics` to avoid cluttering log. - -|=== - -=== Supported Log Formats - -==== Supported Log Entries - -The following log entries are supported in Helidon: - -[cols="2,2,5",role="flex, sm7"] -|=== -|Config format |Class (to use with builder) |Description - -|%h |`HostLogEntry` |IP address of the remote host -|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon -|%u |`UserLogEntry` |The username of logged-in user (when Security is used) -|%t |`TimestampLogEntry` |The current timestamp -|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version) -|%s |`StatusLogEntry` |The HTTP status returned to the client -|%b |`SizeLogEntry` |The response entity size (if available) -|%D |`TimeTakenLogEntry` |The time taken in microseconds -|%T |`TimeTakenLogEntry` |The time taken in seconds -|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write -multiple headers) -|=== - -Currently we only support the entries defined above, with NO support for free text. - -==== Helidon Log Format -When format is set to `helidon`, the format used is: - -`"%h %u %t %r %s %b %D"` - -The entries logged: - -1. IP Address -2. Username of a logged-in user -3. Timestamp -4. Request Line -5. HTTP Status code -6. Entity size -7. Time taken (microseconds) -Access log example: - -[source, listing] ----- -192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 -0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 -0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 -0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 -0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 ----- - -==== Common Log Format -When format is set to `common`, the format used is: - -`"%h %l %u %t %r %s %b"` - -The entries logged: - -1. IP Address -2. Client identity -3. Username of a logged-in user -4. Timestamp -5. Request Line -6. HTTP Status code -7. Entity size - -Access log example: - -[source, listing] ----- -192.168.0.104 - - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53 -0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658 -0:0:0:0:0:0:0:1 - jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21 -0:0:0:0:0:0:0:1 - jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0 -0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0 ----- - -=== Configuring Access Log with Java util logging - -To support a separate file for Access log entries, Helidon provides a custom -log handler, that extends the `FileHandler`. - -To log to a file `access.log` with appending records after restart, you can use the -following configuration in `logging.properties`: - -[source, properties] -.Logging configuration file ----- -io.helidon.webserver.accesslog.AccessLogHandler.level=INFO -io.helidon.webserver.accesslog.AccessLogHandler.pattern=access.log -io.helidon.webserver.accesslog.AccessLogHandler.append=true - -io.helidon.webserver.AccessLog.level=INFO -io.helidon.webserver.AccessLog.useParentHandlers=false -io.helidon.webserver.AccessLog.handlers=io.helidon.webserver.accesslog.AccessLogHandler ----- +include::{rootdir}/includes/server/access-log-config-common.adoc[leveloffset=+1] == TLS Configuration