Skip to content

Commit baf26b4

Browse files
mkjsixmkjsix
committed
📝 Add request logging exclusion patterns to reduce log noise
1 parent f58c4b2 commit baf26b4

File tree

1 file changed

+180
-0
lines changed

1 file changed

+180
-0
lines changed

‎docs/logging.adoc

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,186 @@ logging:
7777
# - tracestate # ^^
7878
----
7979

80+
=== Request Logging Exclusion Patterns (v8.7.0+)
81+
82+
Starting from RESTHeart v8.7.0, you can exclude specific request paths from being logged to reduce log noise from health checks, monitoring endpoints, and other frequent automated requests.
83+
84+
==== Configuration
85+
86+
Add the `requests-log-exclude-patterns` array to your logging configuration. Optionally configure the `requests-log-exclude-interval` to control how often excluded requests are logged:
87+
88+
[source,yml]
89+
----
90+
logging:
91+
log-level: INFO
92+
log-to-console: true
93+
requests-log-mode: 1
94+
95+
# Request path patterns to exclude from logging
96+
requests-log-exclude-patterns:
97+
- "/ping" # Exact match for load balancer health checks
98+
- "/health" # Exact match for health endpoint
99+
- "/_ping" # Exact match for internal ping
100+
- "/monitoring/*" # Wildcard: excludes all paths starting with /monitoring/
101+
- "/api/*/status" # Wildcard: excludes /api/v1/status, /api/v2/status, etc.
102+
103+
# Optional: Interval in minutes for logging excluded requests (default: 10)
104+
# Logs the first excluded request, then again every 10 minutes
105+
# Set to 0 or negative to log only the first occurrence and disable further logging
106+
requests-log-exclude-interval: 10
107+
----
108+
109+
==== Pattern Types
110+
111+
===== Exact Matches
112+
113+
[source,yml]
114+
----
115+
- "/ping" # Matches exactly "/ping"
116+
- "/health" # Matches exactly "/health"
117+
----
118+
119+
===== Wildcard Patterns
120+
121+
[source,yml]
122+
----
123+
- "/monitoring/*" # Matches "/monitoring/health", "/monitoring/status", etc.
124+
- "/api/*/status" # Matches "/api/v1/status", "/api/v2/status", etc.
125+
- "/app/v*/health" # Matches "/app/v1.0/health", "/app/v2.5/health", etc.
126+
----
127+
128+
==== Use Cases
129+
130+
===== Load Balancer Health Checks
131+
132+
[source,yml]
133+
----
134+
requests-log-exclude-patterns:
135+
- "/ping"
136+
- "/health"
137+
- "/_health"
138+
----
139+
140+
===== Monitoring and Metrics Endpoints
141+
142+
[source,yml]
143+
----
144+
requests-log-exclude-patterns:
145+
- "/metrics"
146+
- "/monitoring/*"
147+
- "/actuator/*"
148+
----
149+
150+
===== API Versioning
151+
152+
[source,yml]
153+
----
154+
requests-log-exclude-patterns:
155+
- "/api/*/health" # Excludes health checks across all API versions
156+
- "/api/*/ping" # Excludes pings across all API versions
157+
----
158+
159+
==== Before and After
160+
161+
===== Before (Noisy Logs)
162+
163+
[source,log]
164+
----
165+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:34640 => status=200 elapsed=2ms contentLength=140
166+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:34641 => status=200 elapsed=1ms contentLength=140
167+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:34642 => status=200 elapsed=2ms contentLength=140
168+
INFO o.restheart.handlers.RequestLogger - POST http://10.0.1.47:8080/api/users from /10.0.2.65:34643 => status=201 elapsed=45ms contentLength=256
169+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:34644 => status=200 elapsed=1ms contentLength=140
170+
----
171+
172+
===== After (Clean Logs with Time-Based Excluded Request Logging)
173+
174+
[source,log]
175+
----
176+
INFO o.restheart.handlers.RequestLogger - First excluded request for pattern '/ping' (will log again every 10 minutes):
177+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:34640 => status=200 elapsed=2ms contentLength=140
178+
INFO o.restheart.handlers.RequestLogger - POST http://10.0.1.47:8080/api/users from /10.0.2.65:34643 => status=201 elapsed=45ms contentLength=256
179+
180+
... (all /ping requests are silently excluded for 10 minutes) ...
181+
182+
INFO o.restheart.handlers.RequestLogger - Excluded request for pattern '/ping' (last logged 10 minutes ago):
183+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:44640 => status=200 elapsed=1ms contentLength=140
184+
185+
... (all /ping requests are silently excluded for another 10 minutes) ...
186+
187+
INFO o.restheart.handlers.RequestLogger - Excluded request for pattern '/ping' (last logged 10 minutes ago):
188+
INFO o.restheart.handlers.RequestLogger - GET http://10.0.1.47:8080/ping from /10.0.2.65:54640 => status=200 elapsed=2ms contentLength=140
189+
----
190+
191+
==== Excluded Request Time-Based Logging
192+
193+
To maintain visibility into the health of excluded endpoints while reducing log noise, the system implements a time-based logging mechanism:
194+
195+
* **First occurrence**: Always logged with full request details to confirm the pattern is working
196+
* **Periodic logging**: After the configured time interval (in minutes), the next excluded request is logged with complete request information
197+
* **Full request details**: When logged, excluded requests show the same information as regular requests (method, URL, status, timing, etc.)
198+
* **Time elapsed**: Shows how long since the last excluded request was logged for this pattern
199+
200+
This provides insight into:
201+
202+
* Whether load balancer health checks are working correctly
203+
* The exact timing and response details of periodic health checks
204+
* Confirmation that monitoring endpoints are still being called regularly
205+
* Performance characteristics of excluded endpoints (response times, status codes)
206+
* The time intervals between health check activities
207+
208+
==== Configuration Edge Cases
209+
210+
===== Zero or Negative Interval Values
211+
212+
If you set `requests-log-exclude-interval` to 0 or a negative value:
213+
214+
[source,yml]
215+
----
216+
logging:
217+
requests-log-exclude-interval: 0 # Log only the first excluded request
218+
----
219+
220+
**Behavior**: Only the first excluded request for each pattern will be logged with the message "logging disabled for subsequent requests". All subsequent excluded requests will be completely silent.
221+
222+
**Use case**: When you want to confirm that exclusion patterns are working but don't want any periodic logging of excluded requests.
223+
224+
===== Empty Patterns List
225+
226+
If `requests-log-exclude-patterns` is empty or not specified:
227+
228+
[source,yml]
229+
----
230+
logging:
231+
requests-log-exclude-patterns: [] # No exclusions
232+
----
233+
234+
**Behavior**: All requests are logged normally, exactly like the original behavior.
235+
236+
===== Configuration Value Types
237+
238+
The `requests-log-exclude-interval` accepts numeric values in minutes and handles type conversion automatically:
239+
240+
[source,yml]
241+
----
242+
logging:
243+
requests-log-exclude-interval: 10 # Log every 10 minutes
244+
# or
245+
requests-log-exclude-interval: 5 # Log every 5 minutes
246+
# or
247+
requests-log-exclude-interval: 60 # Log every hour
248+
----
249+
250+
Both integer and long formats work correctly thanks to automatic type conversion in the configuration parser.
251+
252+
==== Backward Compatibility
253+
254+
This feature is fully backward compatible. If `requests-log-exclude-patterns` is not specified in your configuration, all requests will be logged as before.
255+
256+
==== Performance Impact
257+
258+
The pattern matching is performed only when request logging is enabled (`requests-log-mode > 0`). The matching uses efficient string operations and compiled regex patterns for wildcard matching. The time-based logging uses a lightweight `ConcurrentHashMap` to track last logged times per pattern, so the performance impact is minimal.
259+
80260
=== Specify a custom LogBack configuration
81261

82262
To define a different LogBack configuration, set the property `logback.configurationFile`, as follows:

0 commit comments

Comments
 (0)