4184 logging for an MP app (#4903)

* Access log documentation fix * Minor reference fix * Common parts extracted (access log config)
helidon-io · Sep 20, 2022 · 84123e8 · 84123e8
1 parent 0455440
commit 84123e8
Show file tree

Hide file tree

Showing 3 changed files with 134 additions and 114 deletions.
diff --git a/docs/includes/server/access-log-config-common.adoc 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<String>)` | 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
@@ -111,6 +111,37 @@ include::{rootdir}/config/io_helidon_webserver_WebServer.adoc[leveloffset=+1,tag
 
 == 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]
+----
+<dependency>
+    <groupId>io.helidon.microprofile</groupId>
+    <artifactId>helidon-microprofile-access-log</artifactId>
+</dependency>
+----
+
+=== 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.
+
+include::{rootdir}/includes/server/access-log-config-common.adoc[leveloffset=+1]
+
 === Configuring TLS
 
 Helidon MP also supports custom TLS configuration.

diff --git 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]
+----
+<dependency>
+    <groupId>io.helidon.webserver</groupId>
+    <artifactId>helidon-webserver-access-log</artifactId>
+</dependency>
+----
+
 
 === Configuring Access Log in your code
 
@@ -843,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<String>)` | 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