You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Expand logging documentation with configuration details
Document Log4j2 configuration structure (appenders, pattern layout,
log rotation), harvester logging via routing appender, all available
logger modules, JSON logging sample output, custom log configuration
creation, REST API endpoints, and troubleshooting tips.
Also fix the log level preset list to match actual configuration
files (PROD, INDEX, DEV, TEST, JSON — there is no SEARCH preset).
The configuration file configures for each debug level at what severity messages will be logged.
45
+
**`log4j2.xml`** (PROD), **`log4j2-dev.xml`** (DEV), **`log4j2-index.xml`**(INDEX),**`log4j2-json.xml`** (JSON) and **`log4j2-test.xml`** (TEST).
46
+
Each configuration file defines which log levels apply to each logger module.
47
47
48
48
The file used is determined by the log level set in the *Admin* → *Settings* page.
49
49
50
+
### Configuration structure
51
+
52
+
Each Log4j2 configuration file defines three appenders:
53
+
54
+
-**Console** — writes to `SYSTEM_OUT` (stdout).
55
+
-**RollingFile** (`File`) — writes to `geonetwork.log` in the log directory.
56
+
-**Harvester** — a routing appender that writes to per-harvester log files (see [Harvester logging](#harvester-logging)).
57
+
58
+
The default `PatternLayout` format used by the Console and RollingFile appenders is:
59
+
60
+
```
61
+
%date{ISO8601} %-5level [%logger] - %message%n
62
+
```
63
+
64
+
Which produces output like:
65
+
66
+
```
67
+
2024-06-15T10:23:45,123 INFO [geonetwork.harvester] - Starting harvester run
68
+
```
69
+
70
+
### Log file rotation
71
+
72
+
The `RollingFile` appender uses size-based rotation:
73
+
74
+
- Maximum file size: **10 MB** per log file.
75
+
- Up to **3 backup files** are kept, named `geonetwork.log-1.log`, `geonetwork.log-2.log`, `geonetwork.log-3.log`.
76
+
- When the current log file exceeds 10 MB, it is rolled over and the oldest backup is deleted.
77
+
78
+
### Auto-discovery of configuration files
79
+
80
+
GeoNetwork scans `/WEB-INF/classes` for files matching the regex `log4j2(-(.*?))?.xml`. Any file that matches this pattern is automatically made available in the *Admin* → *Settings* log level dropdown. The matched group (e.g. `dev` from `log4j2-dev.xml`) is uppercased to form the display name. The base `log4j2.xml` without a suffix is displayed as **PROD**.
81
+
82
+
## Harvester logging
83
+
84
+
Harvester logs are written to separate files via a **Routing** appender. Each harvester gets its own log file, dynamically named based on the harvester's thread context (`ctx:logfile` and `ctx:harvester`).
85
+
86
+
- The log file name is determined at runtime from the harvester context.
87
+
- If no specific context is set, logs go to `harvester_default.log` in the log directory.
88
+
- Harvester log files use the `PatternLayout` with timezone-aware timestamps:
- Even when JSON logging is enabled, harvester logs continue to use plain-text `PatternLayout` since they are consumed separately from the main log file.
93
+
94
+
## Logger modules
95
+
96
+
The Log4j2 configuration files define logger categories that administrators can adjust. Each log level preset (PROD, INDEX, DEV, etc.) sets these loggers to different levels.
97
+
98
+
### GeoNetwork loggers
99
+
100
+
The main GeoNetwork logger `geonetwork` controls the base level for all GeoNetwork modules. Submodule loggers inherit from it unless explicitly configured:
101
+
102
+
| Logger | Description |
103
+
|--------|-------------|
104
+
| `geonetwork.accessmanager` | Access control and permissions |
Each preset adjusts logger levels differently. As a general guide:
149
+
150
+
- **PROD** — most GeoNetwork loggers at `error`, third-party at `error`. Minimal output.
151
+
- **INDEX** — similar to PROD, but `geonetwork.search` at `warn` and `geonetwork.harvest-man` at `info` for indexation monitoring.
152
+
- **DEV** — most GeoNetwork loggers at `debug`, Spring/Hibernate at `debug`. Very verbose.
153
+
- **TEST** — simplified configuration with fewer logger categories, root level at `warn`.
154
+
- **JSON** — same logger levels as PROD, but output format is JSON (see below).
155
+
50
156
## JSON logging
51
157
52
158
The **JSON** log level uses `log4j2-json.xml` which replaces the default `PatternLayout` with Log4j2's `JsonTemplateLayout`. This produces structured JSON output on both the console and the rolling log file, making it suitable for ingestion by log aggregation tools such as the ELK stack (Elasticsearch, Logstash, Kibana).
@@ -59,6 +165,97 @@ Each log event is output as a JSON object with the following fields:
59
165
- `message` — the log message
60
166
- `exception` — stack trace, if present
61
167
168
+
A sample JSON log line:
169
+
170
+
```json
171
+
{"@timestamp":"2024-06-15T10:23:45.123+0000","level":"ERROR","loggerName":"geonetwork.index","message":"Failed to index record abc-123","exception":null}
172
+
```
173
+
62
174
To activate JSON logging, go to *Admin* → *Settings* and select **JSON** from the log level dropdown.
63
175
64
-
The `JsonTemplateLayout` is provided by the `log4j-layout-template-json` library which is included in GeoNetwork's dependencies. Harvester logs continue to use plain-text `PatternLayout` as they are consumed separately.
176
+
The `JsonTemplateLayout` is provided by the `log4j-layout-template-json` library which is included in GeoNetwork's dependencies. The event template is embedded inline in the `log4j2-json.xml` configuration file and can be customized directly to add or modify fields.
177
+
178
+
Harvester logs continue to use plain-text `PatternLayout` as they are consumed separately.
179
+
180
+
For log ingestion, you can point **Filebeat** or **Logstash** directly at the `geonetwork.log` file when JSON mode is enabled, since each line is a self-contained JSON object.
181
+
182
+
## Custom log configurations
183
+
184
+
You can create your own log level preset by adding a new configuration file to `/WEB-INF/classes/`:
185
+
186
+
1. Copy an existing configuration (e.g. `log4j2.xml`) as a starting point.
187
+
2. Name the new file following the pattern `log4j2-<name>.xml` (e.g. `log4j2-debug-search.xml`).
188
+
3. Adjust the logger levels as needed.
189
+
4. Restart GeoNetwork (or wait for the configuration to be reloaded).
190
+
191
+
The new configuration will automatically appear in the *Admin* → *Settings* log level dropdown as **`<NAME>`** (uppercased from the filename suffix, e.g. `DEBUG-SEARCH`).
192
+
193
+
## Log REST API
194
+
195
+
GeoNetwork provides REST endpoints for managing and viewing logs. All endpoints require **Administrator** role.
196
+
197
+
### List available log configurations
198
+
199
+
```
200
+
GET /{portal}/api/site/logging
201
+
```
202
+
203
+
Returns a JSON array of available log configuration files:
204
+
205
+
```json
206
+
[
207
+
{"name": "PROD", "file": "log4j2.xml"},
208
+
{"name": "DEV", "file": "log4j2-dev.xml"},
209
+
{"name": "INDEX", "file": "log4j2-index.xml"},
210
+
{"name": "JSON", "file": "log4j2-json.xml"},
211
+
{"name": "TEST", "file": "log4j2-test.xml"}
212
+
]
213
+
```
214
+
215
+
### Get recent log activity
216
+
217
+
```
218
+
GET /{portal}/api/site/logging/activity?lines={n}
219
+
```
220
+
221
+
Returns the last *n* lines from the log file as plain text. Default is **2000** lines; maximum is **20000**.
222
+
223
+
### Download log file as ZIP
224
+
225
+
```
226
+
GET /{portal}/api/site/logging/activity/zip
227
+
```
228
+
229
+
Downloads the current log file as a ZIP archive, named `catalog-log-<timestamp>.zip`.
230
+
231
+
## Troubleshooting
232
+
233
+
### Enable Log4j2 internal status logging
234
+
235
+
If log output is not appearing as expected, enable Log4j2's internal status logger to diagnose configuration problems. Set the `status` attribute on the `<Configuration>` element:
236
+
237
+
```xml
238
+
<Configurationstatus="trace"dest="out">
239
+
```
240
+
241
+
Alternatively, set the system property at startup:
This will output Log4j2's internal messages to the console, helping identify issues with appender configuration, missing files, or pattern errors.
248
+
249
+
### XSL transformation errors
250
+
251
+
XSL transformation errors are not written to `geonetwork.log`. They are written to **`catalina.out`** (when using Tomcat). Check this file if you suspect issues with metadata formatting or schema processing.
252
+
253
+
### Temporarily increase logging for a specific module
254
+
255
+
To debug a specific subsystem without increasing the global log level, edit the active Log4j2 configuration file and change only the target logger. For example, to debug search issues while keeping everything else at `error`:
256
+
257
+
```xml
258
+
<Loggername="geonetwork.search"level="debug"/>
259
+
```
260
+
261
+
Then switch to a different log configuration and back in *Admin* → *Settings* to reload, or restart GeoNetwork. Remember to revert the change after debugging.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments