Skip to content

Commit 84123e8

Browse files
dalexandrovdalexandrov
authored
4184 logging for an MP app (#4903)
* Access log documentation fix * Minor reference fix * Common parts extracted (access log config)
1 parent 0455440 commit 84123e8

File tree

3 files changed

+134
-114
lines changed

3 files changed

+134
-114
lines changed

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

Lines changed: 92 additions & 0 deletions
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‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,37 @@ include::{rootdir}/config/io_helidon_webserver_WebServer.adoc[leveloffset=+1,tag
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‎

Lines changed: 11 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -814,6 +814,16 @@ in the order it is registered with WebServer routing.
814814
This implies that if you register it last and another `Service` or
815815
`Handler` finishes the request, the service will not be invoked.
816816
817+
To enable Access logging add the following dependency to project's `pom.xml`:
818+
819+
[source,xml]
820+
----
821+
<dependency>
822+
<groupId>io.helidon.webserver</groupId>
823+
<artifactId>helidon-webserver-access-log</artifactId>
824+
</dependency>
825+
----
826+
817827
818828
=== Configuring Access Log in your code
819829
@@ -843,121 +853,8 @@ server:
843853
844854
All options shown above are also available programmatically when using builder.
845855
846-
=== Configuration Options
847-
848-
The following configuration options can be defined:
849-
850-
[cols="2,2,2,5", role="flex, sm10"]
851-
|===
852-
|Config key |Default value |Builder method |Description
853-
854-
|`enabled` |`true` |`enabled(boolean)` |When this option is set to `false`, access logging will be disabled
855-
|`logger-name` |`io.helidon.webserver.AccessLog` |`loggerName(String)` |Name of the logger to use when writing log entries
856-
|`format` |`helidon` |`helidonLogFormat()`, `commonLogFormat()`, `add(AccessLogEntry entry)` |Configuration of access log output,
857-
when `helidon` is defined, the Helidon log format (see below) is used.
858-
Can be configured to explicitly define log entries (see below as well)
859-
|`exclude-paths`|N/A|`excludePaths(List<String>)` | List of path patterns to exclude from access log. Path pattern syntax is as
860-
defined in `io.helidon.webserver.PathMatcher`. Can be used to exclude
861-
paths such as `/health` or `/metrics` to avoid cluttering log.
862-
863-
|===
864-
865-
=== Supported Log Formats
866-
867-
==== Supported Log Entries
868-
869-
The following log entries are supported in Helidon:
870-
871-
[cols="2,2,5",role="flex, sm7"]
872-
|===
873-
|Config format |Class (to use with builder) |Description
874-
875-
|%h |`HostLogEntry` |IP address of the remote host
876-
|%l |`UserIdLogEntry` |Client identity, always undefined in Helidon
877-
|%u |`UserLogEntry` |The username of logged-in user (when Security is used)
878-
|%t |`TimestampLogEntry` |The current timestamp
879-
|%r |`RequestLineLogEntry` |The request line (method, path and HTTP version)
880-
|%s |`StatusLogEntry` |The HTTP status returned to the client
881-
|%b |`SizeLogEntry` |The response entity size (if available)
882-
|%D |`TimeTakenLogEntry` |The time taken in microseconds
883-
|%T |`TimeTakenLogEntry` |The time taken in seconds
884-
|%{`header-name`}i |`HeaderLogEntry` |Value of a header (can have multiple such specification to write
885-
multiple headers)
886-
|===
887-
888-
Currently we only support the entries defined above, with NO support for free text.
889856
890-
==== Helidon Log Format
891-
When format is set to `helidon`, the format used is:
892-
893-
`"%h %u %t %r %s %b %D"`
894-
895-
The entries logged:
896-
897-
1. IP Address
898-
2. Username of a logged-in user
899-
3. Timestamp
900-
4. Request Line
901-
5. HTTP Status code
902-
6. Entity size
903-
7. Time taken (microseconds)
904-
905-
Access log example:
906-
907-
[source, listing]
908-
----
909-
192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53
910-
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658
911-
0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21
912-
0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0
913-
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0
914-
----
915-
916-
==== Common Log Format
917-
When format is set to `common`, the format used is:
918-
919-
`"%h %l %u %t %r %s %b"`
920-
921-
The entries logged:
922-
923-
1. IP Address
924-
2. Client identity
925-
3. Username of a logged-in user
926-
4. Timestamp
927-
5. Request Line
928-
6. HTTP Status code
929-
7. Entity size
930-
931-
Access log example:
932-
933-
[source, listing]
934-
----
935-
192.168.0.104 - - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53
936-
0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658
937-
0:0:0:0:0:0:0:1 - jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21
938-
0:0:0:0:0:0:0:1 - jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0
939-
0:0:0:0:0:0:0:1 - - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0
940-
----
941-
942-
=== Configuring Access Log with Java util logging
943-
944-
To support a separate file for Access log entries, Helidon provides a custom
945-
log handler, that extends the `FileHandler`.
946-
947-
To log to a file `access.log` with appending records after restart, you can use the
948-
following configuration in `logging.properties`:
949-
950-
[source, properties]
951-
.Logging configuration file
952-
----
953-
io.helidon.webserver.accesslog.AccessLogHandler.level=INFO
954-
io.helidon.webserver.accesslog.AccessLogHandler.pattern=access.log
955-
io.helidon.webserver.accesslog.AccessLogHandler.append=true
956-
957-
io.helidon.webserver.AccessLog.level=INFO
958-
io.helidon.webserver.AccessLog.useParentHandlers=false
959-
io.helidon.webserver.AccessLog.handlers=io.helidon.webserver.accesslog.AccessLogHandler
960-
----
857+
include::{rootdir}/includes/server/access-log-config-common.adoc[leveloffset=+1]
961858
962859
== TLS Configuration
963860

0 commit comments

Comments
 (0)