Skip to content

Commit 0caf822

Browse files
dalexandrovdalexandrov
authored
Ported Access Log documentation to 4.x (#5054)
1 parent d9b638c commit 0caf822

File tree

3 files changed

+153
-106
lines changed

3 files changed

+153
-106
lines changed

‎docs/includes/server/access-log-config-common.adoc

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
///////////////////////////////////////////////////////////////////////////////
2+
3+
Copyright (c) 2022 Oracle and/or its affiliates.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
17+
///////////////////////////////////////////////////////////////////////////////
18+
19+
ifndef::rootdir[:rootdir: {docdir}/../..]
20+
:description: Access Log Config
21+
:keywords: helidon, webserver, access, log
22+
23+
24+
== Configuration Options
25+
26+
The following configuration options can be defined:
27+
28+
[cols="2,2,2,5", role="flex, sm10"]
29+
|===
30+
|Config key |Default value |Builder method |Description
31+
32+
|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled
33+
|`logger-name` |`io.helidon.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries
34+
|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output,
35+
when `helidon` is defined, the Helidon log format (see below) is used.
36+
Can be configured to explicitly define log entries (see below as well)
37+
|`exclude-paths`|N/A|`excludePaths(List<String>)` | List of path patterns to exclude from access log. Path pattern syntax is as
38+
defined in `io.helidon.webserver.PathMatcher`. Can be used to exclude
39+
paths such as `/health` or `/metrics` to avoid cluttering log.
40+
41+
|===
42+
43+
== Supported Log Formats
44+
45+
=== Supported Log Entries
46+
47+
The following log entries are supported in Helidon:
48+
49+
[cols="2,2,5",role="flex, sm7"]
50+
|===
51+
|Config format |Class (to use with builder) |Description
52+
53+
|%h |`HostLogEntry` |IP address of the remote host
54+
|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon
55+
|%u |`UserLogEntry` |The username of logged-in user (when Security is used)
56+
|%t |`TimestampLogEntry` |The current timestamp
57+
|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version)
58+
|%s |`StatusLogEntry` |The HTTP status returned to the client
59+
|%b |`SizeLogEntry` |The response entity size (if available)
60+
|%D |`TimeTakenLogEntry` |The time taken in microseconds
61+
|%T |`TimeTakenLogEntry` |The time taken in seconds
62+
|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write
63+
multiple headers)
64+
|===
65+
66+
Currently we only support the entries defined above, with NO support for free text.
67+
68+
=== Helidon Log Format
69+
When format is set to `helidon`, the format used is:
70+
71+
`"%h %u %t %r %s %b %D"`
72+
73+
The entries logged:
74+
75+
1. IP Address
76+
2. Username of a logged-in user
77+
3. Timestamp
78+
4. Request Line
79+
5. HTTP Status code
80+
6. Entity size
81+
7. Time taken (microseconds)
82+
83+
Access log example:
84+
85+
[source, listing]
86+
----
87+
192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53
88+
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658
89+
0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21
90+
0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0
91+
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0
92+
----

‎docs/mp/server.adoc

+31
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,37 @@ include::{rootdir}/config/io_helidon_reactive_webserver_WebServer.adoc[leveloffs
111111
112112
== Examples
113113
114+
=== Access Log
115+
116+
Access logging in Helidon is done by a dedicated module that can be
117+
added to Maven and configured.
118+
119+
To enable Access logging add the following dependency to project's `pom.xml`:
120+
121+
[source,xml]
122+
----
123+
<dependency>
124+
<groupId>io.helidon.microprofile</groupId>
125+
<artifactId>helidon-microprofile-access-log</artifactId>
126+
</dependency>
127+
----
128+
129+
=== Configuring Access Log in a configuration file
130+
131+
Access log can be configured as follows:
132+
133+
[source, properties]
134+
.Access Log configuration file
135+
----
136+
server.port=8080
137+
server.host=0.0.0.0
138+
server.access-log.format=helidon
139+
----
140+
141+
All options shown above are also available programmatically when using builder.
142+
143+
include::{rootdir}/includes/server/access-log-config-common.adoc[leveloffset=+1]
144+
114145
=== Configuring TLS
115146
116147
Helidon MP also supports custom TLS configuration.

‎docs/se/webserver.adoc

+30-106
Original file line numberDiff line numberDiff line change
@@ -822,6 +822,16 @@ in the order it is registered with WebServer routing.
822822
This implies that if you register it last and another `Service` or
823823
`Handler` finishes the request, the service will not be invoked.
824824
825+
To enable Access logging add the following dependency to project's `pom.xml`:
826+
827+
[source,xml]
828+
----
829+
<dependency>
830+
<groupId>io.helidon.webserver</groupId>
831+
<artifactId>helidon-webserver-access-log</artifactId>
832+
</dependency>
833+
----
834+
825835
826836
=== Configuring Access Log in your code
827837
@@ -851,120 +861,34 @@ server:
851861
852862
All options shown above are also available programmatically when using builder.
853863
854-
=== Configuration options
855-
856-
The following configuration options can be defined:
857-
858-
[cols="2,2,2,5", role="flex, sm10"]
859-
|===
860-
|Config key |Default value |Builder method |Description
861-
862-
|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled
863-
|`logger-name` |`io.helidon.reactive.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries
864-
|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output,
865-
when `helidon` is defined, the Helidon log format (see below) is used.
866-
Can be configured to explicitly define log entries (see below as well)
867-
|`exclude-paths`|N/A|`excludePaths(List<String>)` | List of path patterns to exclude from access log. Path pattern syntax is as
868-
defined in `io.helidon.reactive.webserver.PathMatcher`. Can be used to exclude
869-
paths such as `/health` or `/metrics` to avoid cluttering log.
870-
871-
|===
872864
873-
=== Supported Log Formats
865+
include::{rootdir}/includes/server/access-log-config-common.adoc[leveloffset=+1]
874866
875-
==== Supported Log Entries
876-
877-
The following log entries are supported in Helidon:
878-
879-
[cols="2,2,5",role="flex, sm7"]
880-
|===
881-
|Config format |Class (to use with builder) |Description
882-
883-
|%h |`HostLogEntry` |IP address of the remote host
884-
|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon
885-
|%u |`UserLogEntry` |The username of logged-in user (when Security is used)
886-
|%t |`TimestampLogEntry` |The current timestamp
887-
|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version)
888-
|%s |`StatusLogEntry` |The HTTP status returned to the client
889-
|%b |`SizeLogEntry` |The response entity size (if available)
890-
|%D |`TimeTakenLogEntry` |The time taken in microseconds
891-
|%T |`TimeTakenLogEntry` |The time taken in seconds
892-
|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write
893-
multiple headers)
894-
|===
895-
896-
Currently we only support the entries defined above, with NO support for free text.
897-
898-
==== Helidon Log Format
899-
When format is set to `helidon`, the format used is:
900-
901-
`"%h %u %t %r %s %b %D"`
902-
903-
The entries logged:
904-
905-
1. IP Address
906-
2. Username of a logged-in user
907-
3. Timestamp
908-
4. Request Line
909-
5. HTTP Status code
910-
6. Entity size
911-
7. Time taken (microseconds)
912-
913-
Access log example:
914-
915-
[source, listing]
916-
----
917-
192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53
918-
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658
919-
0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21
920-
0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0
921-
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0
922-
----
867+
== TLS Configuration
923868
924-
==== Common Log Format
925-
When format is set to `common`, the format used is:
926-
927-
`"%h %l %u %t %r %s %b"`
928-
929-
The entries logged:
930-
931-
1. IP Address
932-
2. Client identity
933-
3. Username of a logged-in user
934-
4. Timestamp
935-
5. Request Line
936-
6. HTTP Status code
937-
7. Entity size
938-
939-
Access log example:
940-
941-
[source, listing]
942-
----
943-
192.168.0.104 - - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53
944-
0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658
945-
0:0:0:0:0:0:0:1 - jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21
946-
0:0:0:0:0:0:0:1 - jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0
947-
0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0
948-
----
949-
950-
=== Configuring Access Log with Java util logging
869+
Configure TLS either programmatically, or by the Helidon configuration framework.
951870
952-
To support a separate file for Access log entries, Helidon provides a custom
953-
log handler, that extends the `FileHandler`.
871+
=== Configuring TLS in your code
954872
955-
To log to a file `access.log` with appending records after restart, you can use the
956-
following configuration in `logging.properties`:
873+
To configure TLS in WebServer programmatically create your keystore configuration and pass it to the WebServer builder.
957874
958-
[source, properties]
959-
.Logging configuration file
875+
[source,java]
960876
----
961-
io.helidon.reactive.webserver.accesslog.AccessLogHandler.level=INFO
962-
io.helidon.reactive.webserver.accesslog.AccessLogHandler.pattern=access.log
963-
io.helidon.reactive.webserver.accesslog.AccessLogHandler.append=true
877+
KeyConfig keyConfig = KeyConfig.keystoreBuilder()
878+
//Whether this keystore is also trust store
879+
.trustStore()
880+
//Keystore location/name
881+
.keystore(Resource.create("keystore.p12"))
882+
//Password to the keystore
883+
.keystorePassphrase("password")
884+
.build();
964885
965-
io.helidon.reactive.webserver.AccessLog.level=INFO
966-
io.helidon.reactive.webserver.AccessLog.useParentHandlers=false
967-
io.helidon.reactive.webserver.AccessLog.handlers=io.helidon.reactive.webserver.accesslog.AccessLogHandler
886+
WebServer.builder()
887+
.tls(WebServerTls.builder()
888+
.trust(keyConfig)
889+
.privateKey(keyConfig)
890+
.build())
891+
.build();
968892
----
969893
970894
== TLS configuration

0 commit comments

Comments
 (0)