Skip to content

Commit ded5216

Browse files
himeshsiriwardanahimeshsiriwardana
authored
Merge pull request #5953 from himeshsiriwardana/access-log-routing
Added docs on routing access logs to log4j2
2 parents a6ab0d9 + 4d6fc72 commit ded5216

7 files changed

Lines changed: 436 additions & 27 deletions

File tree

‎.vale/styles/WSO2-IAM/TooWordy.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,12 +133,9 @@ tokens:
133133
- it seems that
134134
- it was
135135
- magnitude
136-
- maximum
137136
- methodology
138137
- minimize
139-
- minimum
140138
- modify
141-
- monitor
142139
- necessitate
143140
- nevertheless
144141
- not certain

‎.vale/styles/config/vocabularies/vocab/accept.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,9 @@ backchannel
5757
frontchannel
5858
URL
5959
timeframe
60+
appender
61+
appenders
62+
servlet
6063
[Aa]pprovers?
6164
server_version
6265
[Uu]serstore

‎en/identity-server/6.1.0/docs/deploy/monitor/http-access-logging.md‎

Lines changed: 101 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,18 @@ information such as the persons who access it, how many hits
55
it received, what the errors are, etc. This information is useful for
66
troubleshooting errors. WSO2 Identity Server can enable access logs for the
77
HTTP servlet transport. This servlet transport works on `9443`/`9763` ports,
8-
and it receives admin/operation requests. Therefore, access logs for the
8+
and it receives admin/operation requests. So, access logs for the
99
servlet transport is useful for analysing operational/admin-level access
1010
details.
1111

12-
### Configuring access logs for the HTTP servlet transport
12+
## Configuring access logs for the HTTP servlet transport
1313

1414
In the Identity Server 5.9.0 only the access log pattern is configurable.
1515

16-
1. Open the `<IS_HOME>/repository/conf/deployment.toml`
16+
1. Open the `<IS_HOME>/repository/conf/deployment.toml`
1717
file.
1818

19-
2. Add the following configuration.
19+
2. Add the following configuration.
2020

2121
``` toml
2222
[http_access_log]
@@ -75,16 +75,98 @@ In the Identity Server 5.9.0 only the access log pattern is configurable.
7575
</tbody>
7676
</table>
7777

78-
3. Restart the server. According to the configurations, a log
78+
3. Restart the server. According to the configurations, a log
7979
file named
80-
` http_access.{DATE}.log ` is
81-
created by default inside the `<IS_HOME>/repository/logs ` directory. The
80+
`http_access.{DATE}.log` is
81+
created by default inside the `<IS_HOME>/repository/logs` directory. The
8282
log is rotated on a daily basis.
8383

84+
## Routing access logs to the Log4j2 logger
85+
86+
By default, HTTP access logs write to a separate `http_access.log` file using the Tomcat Access Log Valve. WSO2 Identity Server also supports routing HTTP access logs through the Log4j2 logger, which gives you full control over where those logs go.
87+
88+
To enable Log4j2-based access logging, set `useLogger = true` in `<IS_HOME>/repository/conf/deployment.toml`:
89+
90+
```toml
91+
[http_access_log]
92+
useLogger = true
93+
```
94+
95+
After enabling this, update `<IS_HOME>/repository/conf/log4j2.properties` to add the HTTP access log appender and logger.
96+
97+
### Route to a dedicated rolling log file
98+
99+
If you want to keep HTTP access logs in their own file, separate from other server logs, you can route them to a rolling log file that rotates on a schedule and rolls over when it reaches a configured size. To do so,
100+
101+
1. Add `HTTP_ACCESS` to the `appenders` list:
102+
103+
```properties
104+
appenders = CARBON_CONSOLE, CARBON_LOGFILE, AUDIT_LOGFILE, ATOMIKOS_LOGFILE, CARBON_TRACE_LOGFILE, DELETE_EVENT_LOGFILE, TRANSACTION_LOGFILE, HTTP_ACCESS
105+
```
106+
107+
2. Add `HTTP_ACCESS` to the `loggers` list:
108+
109+
```properties
110+
loggers = HTTP_ACCESS, AUDIT_LOG, trace-messages, ...
111+
```
112+
113+
3. Add the appender and logger configuration:
114+
115+
```properties
116+
logger.HTTP_ACCESS.name = HTTP_ACCESS
117+
logger.HTTP_ACCESS.level = INFO
118+
logger.HTTP_ACCESS.appenderRef.HTTP_ACCESS.ref = HTTP_ACCESS
119+
logger.HTTP_ACCESS.additivity = false
120+
121+
appender.HTTP_ACCESS.type = RollingFile
122+
appender.HTTP_ACCESS.name = HTTP_ACCESS
123+
appender.HTTP_ACCESS.fileName = ${sys:carbon.home}/repository/logs/http_access.log
124+
appender.HTTP_ACCESS.filePattern = ${sys:carbon.home}/repository/logs/http_access-%d {MM-dd-yyyy}.log
125+
appender.HTTP_ACCESS.layout.type = PatternLayout
126+
appender.HTTP_ACCESS.layout.pattern = [%X{Correlation-ID}] %mm%n
127+
appender.HTTP_ACCESS.policies.type = Policies
128+
appender.HTTP_ACCESS.policies.time.type = TimeBasedTriggeringPolicy
129+
appender.HTTP_ACCESS.policies.time.interval = 1
130+
appender.HTTP_ACCESS.policies.time.modulate = true
131+
appender.HTTP_ACCESS.policies.size.type = SizeBasedTriggeringPolicy
132+
appender.HTTP_ACCESS.policies.size.size = 10MB
133+
appender.HTTP_ACCESS.strategy.type = DefaultRolloverStrategy
134+
appender.HTTP_ACCESS.strategy.max = 20
135+
appender.HTTP_ACCESS.filter.threshold.type = ThresholdFilter
136+
appender.HTTP_ACCESS.filter.threshold.level = INFO
137+
```
138+
139+
### Route to standard output
140+
141+
In Kubernetes environments, logs are typically collected from standard output rather than files. To make HTTP access logs part of that flow, route them to the console alongside all other server logs. To do so,
142+
143+
1. Set `appenders` to `CARBON_CONSOLE` only:
144+
145+
```properties
146+
appenders = CARBON_CONSOLE
147+
```
148+
149+
2. Add `HTTP_ACCESS` to the `loggers` list:
150+
151+
```properties
152+
loggers = HTTP_ACCESS, AUDIT_LOG, trace-messages, ...
153+
```
154+
155+
3. Add the logger configuration:
156+
157+
```properties
158+
logger.HTTP_ACCESS.name = HTTP_ACCESS
159+
logger.HTTP_ACCESS.level = INFO
160+
logger.HTTP_ACCESS.appenderRef.HTTP_ACCESS.ref = CARBON_CONSOLE
161+
logger.HTTP_ACCESS.additivity = false
162+
```
163+
164+
You can define other logging patterns and targets for the `HTTP_ACCESS` logger using standard Log4j2 configuration. See the [Log4j2 documentation](https://logging.apache.org/log4j/2.x/manual/configuration.html) for available options.
165+
84166
### Customizing access logs by pattern
85167

86168
Given below are a few sample configurations for customizing the
87-
` pattern ` attribute:
169+
`pattern` attribute:
88170

89171
#### Example 1: Logging request headers
90172

@@ -98,14 +180,14 @@ The configuration is as follows:
98180
This sample configuration logs the Content-type,
99181
Accept and Accept-encoding headers of every request coming to the
100182
server. For example, in the following example, we use the
101-
` RequestInfoExample ` to send the HTTP request:
183+
`RequestInfoExample` to send the HTTP request:
102184

103185
``` java
104186
GET http://<IP>:<PORT>/example/servlets/servlet/RequestInfoExample?abc=xyz
105187
```
106188

107189
The following log entry is recorded in the
108-
` http_access.{DATE}.log ` file.
190+
`http_access.{DATE}.log` file.
109191

110192
``` java
111193
text/plain; charset=utf-8 */* gzip,deflate,sdch
@@ -120,9 +202,8 @@ The configuration is as follows:
120202
pattern = "%{Content-Type}o %{Content-Length}o %{Date}o %{Server}o"
121203
```
122204
123-
The a bove configuration sample logs the ` Content-type `
124-
, ` Content-Length `, ` Date, ` and
125-
` Server ` headers of every response coming from the
205+
The above configuration sample logs the `Content-type`,
206+
`Content-Length`, `Date`, and `Server` headers of every response coming from the
126207
server as follows:
127208
128209
``` java
@@ -149,11 +230,11 @@ server as follows:
149230
150231
#### Example 4: Logging URL encoded parameters
151232
152-
You cannot use the ` AccessLogValve ` to log URL encoded
233+
You cannot use the `AccessLogValve` to log URL encoded
153234
parameters. However, you can use the
154-
` ExtendedAccessLogValve ` attribute for this purpose. In
155-
this example only two values (namely, ` className `, and
156-
` pattern ` ) are modified from the previous
235+
`ExtendedAccessLogValve` attribute for this purpose. In
236+
this example only two values (namely, `className`, and
237+
`pattern`) are modified from the previous
157238
configuration. Hence this will be added as a new valve.
158239
159240
The configuration is as follows:
@@ -168,8 +249,8 @@ pattern="x-P(param1) x-P(param2)"
168249
```
169250
170251
Send the POST request together with the URL encoded values such as
171-
` param1 ` = ` value1 ` and
172-
` param2 ` = ` value2 ` as follows:
252+
`param1` = `value1` and
253+
`param2` = `value2` as follows:
173254
174255
``` java
175256
POST http://<IP>:<PORT>/example/servlets/servlet/RequestInfoExample
@@ -179,4 +260,4 @@ The above sample configuration logs the following:
179260
180261
``` java
181262
'value1' 'value2'
182-
```
263+
```

‎en/identity-server/7.0.0/docs/deploy/monitor/http-access-logging.md‎

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,88 @@ To configure access logs for HTTP servlet transport:
5858

5959
3. Restart the server. According to the configurations, a log file named `http_access.{DATE}.log` is created by default inside the `<IS_HOME>/repository/logs` directory. The log is rotated daily.
6060

61+
## Routing access logs to the Log4j2 logger
62+
63+
By default, HTTP access logs write to a separate `http_access.log` file using the Tomcat Access Log Valve. WSO2 Identity Server also supports routing HTTP access logs through the Log4j2 logger, which gives you full control over where those logs go.
64+
65+
To enable Log4j2-based access logging, set `useLogger = true` in `<IS_HOME>/repository/conf/deployment.toml`:
66+
67+
```toml
68+
[http_access_log]
69+
useLogger = true
70+
```
71+
72+
After enabling this, update `<IS_HOME>/repository/conf/log4j2.properties` to add the HTTP access log appender and logger.
73+
74+
### Route to a dedicated rolling log file
75+
76+
If you want to keep HTTP access logs in their own file, separate from other server logs, you can route them to a rolling log file that rotates on a schedule and rolls over when it reaches a configured size. To do so,
77+
78+
1. Add `HTTP_ACCESS` to the `appenders` list:
79+
80+
```properties
81+
appenders = CARBON_CONSOLE, CARBON_LOGFILE, AUDIT_LOGFILE, ATOMIKOS_LOGFILE, CARBON_TRACE_LOGFILE, DELETE_EVENT_LOGFILE, TRANSACTION_LOGFILE, HTTP_ACCESS
82+
```
83+
84+
2. Add `HTTP_ACCESS` to the `loggers` list:
85+
86+
```properties
87+
loggers = HTTP_ACCESS, AUDIT_LOG, trace-messages, ...
88+
```
89+
90+
3. Add the appender and logger configuration:
91+
92+
```properties
93+
logger.HTTP_ACCESS.name = HTTP_ACCESS
94+
logger.HTTP_ACCESS.level = INFO
95+
logger.HTTP_ACCESS.appenderRef.HTTP_ACCESS.ref = HTTP_ACCESS
96+
logger.HTTP_ACCESS.additivity = false
97+
98+
appender.HTTP_ACCESS.type = RollingFile
99+
appender.HTTP_ACCESS.name = HTTP_ACCESS
100+
appender.HTTP_ACCESS.fileName = ${sys:carbon.home}/repository/logs/http_access.log
101+
appender.HTTP_ACCESS.filePattern = ${sys:carbon.home}/repository/logs/http_access-%d{MM-dd-yyyy}.log
102+
appender.HTTP_ACCESS.layout.type = PatternLayout
103+
appender.HTTP_ACCESS.layout.pattern = [%X{Correlation-ID}] %mm%n
104+
appender.HTTP_ACCESS.policies.type = Policies
105+
appender.HTTP_ACCESS.policies.time.type = TimeBasedTriggeringPolicy
106+
appender.HTTP_ACCESS.policies.time.interval = 1
107+
appender.HTTP_ACCESS.policies.time.modulate = true
108+
appender.HTTP_ACCESS.policies.size.type = SizeBasedTriggeringPolicy
109+
appender.HTTP_ACCESS.policies.size.size = 10MB
110+
appender.HTTP_ACCESS.strategy.type = DefaultRolloverStrategy
111+
appender.HTTP_ACCESS.strategy.max = 20
112+
appender.HTTP_ACCESS.filter.threshold.type = ThresholdFilter
113+
appender.HTTP_ACCESS.filter.threshold.level = INFO
114+
```
115+
116+
### Route to standard output
117+
118+
In Kubernetes environments, logs are typically collected from standard output rather than files. To make HTTP access logs part of that flow, route them to the console alongside all other server logs. To do so,
119+
120+
1. Set `appenders` to `CARBON_CONSOLE` only:
121+
122+
```properties
123+
appenders = CARBON_CONSOLE
124+
```
125+
126+
2. Add `HTTP_ACCESS` to the `loggers` list:
127+
128+
```properties
129+
loggers = HTTP_ACCESS, AUDIT_LOG, trace-messages, ...
130+
```
131+
132+
3. Add the logger configuration:
133+
134+
```properties
135+
logger.HTTP_ACCESS.name = HTTP_ACCESS
136+
logger.HTTP_ACCESS.level = INFO
137+
logger.HTTP_ACCESS.appenderRef.HTTP_ACCESS.ref = CARBON_CONSOLE
138+
logger.HTTP_ACCESS.additivity = false
139+
```
140+
141+
You can define other logging patterns and targets for the `HTTP_ACCESS` logger using standard Log4j2 configuration. See the [Log4j2 documentation](https://logging.apache.org/log4j/2.x/manual/configuration.html) for available options.
142+
61143
### Customizing access logs by pattern
62144

63145
Given below are a few sample configurations for customizing the `pattern` attribute:
@@ -138,4 +220,4 @@ The above sample configuration logs the following:
138220
139221
``` java
140222
'value1' 'value2'
141-
```
223+
```

0 commit comments

Comments
 (0)