Skip to content

Commit 13177b4

Browse files
bakerboy448bakerboy448
authored
docs: expand logWatch documentation (#35)
* docs: expand logWatch documentation with config syntax and examples - Add configuration section with all options explained - Add complete [[watch_file]] block examples for *arr apps - Add examples for Kometa, Nginx, Rustic - Add pattern reference tables - Add troubleshooting section - Based on community patterns from production configs * docs: logWatch use UI format with explanations --------- Co-authored-by: bakerboy448 <bakerboy448@users.noreply.github.com>
1 parent be213da commit 13177b4

File tree

1 file changed

+288
-15
lines changed

1 file changed

+288
-15
lines changed

‎docs/pages/integrations/logWatch.md‎

Lines changed: 288 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,295 @@
11
# Log Watcher
22

3-
aka File Watcher
3+
The Log Watcher (aka File Watcher) allows the Notifiarr Client to monitor log files for lines matching regular expressions. This is similar to `tail -f file | grep pattern` - you get notifications when log files contain new lines matching your patterns.
44

5-
This allows the Notifiarr Client to watch (log) files for lines matching a regular expression. This is similar to tail -f file | grep string and allows you to send notifications when, for instance, a log file has a new line written that matches a regular expression.
5+
## Configuration
66

7-
***Coming Soon***
8-
!!! info
9-
If creating a skip expression that contains `'` replace the apostrophe with `.?`
7+
Add a new Log Watcher entry in the Notifiarr Client UI under **Configuration** > **Log Watch**.
108

11-
## Regular Expressions & Skip Expressions
9+
### Fields
1210

13-
Below are community suggested expressions
11+
| Field | Required | Default | Description |
12+
|-------|----------|---------|-------------|
13+
| **Path** | Yes | - | Full path to the log file to watch |
14+
| **Regex** | Yes | - | Regular expression to match - matching lines trigger notifications |
15+
| **Skip** | No | *empty* | Regular expression for lines to ignore (even if they match Regex) |
16+
| **Poll** | No | `false` | Use polling instead of inotify (useful for network mounts) |
17+
| **Pipe** | No | `false` | Treat path as a named pipe (FIFO) instead of a file |
18+
| **Must Exist** | No | `false` | Fail if the file doesn't exist at startup |
19+
| **Log Match** | No | `true` | Log matched lines to notifiarr debug log |
1420

15-
| App | Regular Expression | Skip Expression | Regular Explanation | Skip Explanation |
16-
| --- | ------------------ | --------------- | ------------------- | ---------------- |
17-
| Radarr | `(?i)(\|warn\||\|error\||^\[v5.+\])` | `(?i)Movie with IMDBId|It will not be added|Invalid date found|Validation failed|An unhandled exception has occurred while executing the request.|HttpClient error` | Notify on all Warnings, Errors, and Stack Traces (Version Number) | Skip movie add errors. Skip Indexer Feed invalid date Errors. Skip Errors saying there was an Error |
18-
| Sonarr | `(?i)(\|warn\||\|error\||^\[v4.+\])` | `(?i)Invalid date found|Validation failed|An unhandled exception has occurred while executing the request.|Unable to find exact quality|HttpClient error` | Notify on all Warnings, Errors, and Stack Traces (Version Number) | Skip Indexer Feed invalid date Errors. Skip Errors saying there was an Error. Skip unknown quality errors. |
19-
| Prowlarr | `(?i)(\|warn\||\|error\||^\[v1.+\])` | `(?i)Validation failed|An unhandled exception has occurred while executing the request|[?:CinemaZ|PrivateHD](.a-z0-9/=&?: )+404\.NotFound|HttpClient error` | Notify on all Warnings, Errors, and Stack Traces (Version Number) | Skip Errors saying there was an error. Skip Cinemaz/PrivateHD 404 (NotFound Errors) |
20-
| Readarr | `(?i)(\|warn\||\|error\||^\[v1.+\])` | `(?i)Validation failed|An unhandled exception has occurred while executing the request.|HttpClient error` | Notify on all Warnings, Errors, and Stack Traces (Version Number) | Skip Errors saying there was an error. |
21-
| Lidarr | `(?i)(\|warn\||\|error\||^\[v2.+\])` | `(?i)Validation failed|An unhandled exception has occurred while executing the request.|HttpClient error` | Notify on all Warnings, Errors, and Stack Traces (Version Number) | Skip Errors saying there was an error. |
22-
| PMM | `(?i)(\[ERROR\])` | `(?i)(Convert Error:|ID not found|TVDb Error: Name not found|Plex Error: No Items found in Plex|Trakt Error: No TVDb ID found for|TMDb Error: No Movie found for TMDb ID)` | Notify on Errors | Exclude common errors of unable to find/map ids or Plex searches returning no items. |
21+
!!! tip "Regex Tips"
22+
- Use `(?i)` at the start for case-insensitive matching
23+
- Use `|` to match multiple patterns: `error|warn|fatal`
24+
- Escape special characters: `\[`, `\.`, `\|`
25+
- If your skip expression contains `'`, replace it with `.?`
26+
27+
## Community Patterns
28+
29+
### *arr Applications
30+
31+
These patterns catch warnings, errors, and stack traces while filtering common noise.
32+
33+
---
34+
35+
#### Radarr
36+
37+
**Path:**
38+
```text
39+
/var/log/radarr/radarr.debug.txt
40+
```
41+
42+
**Regex:**
43+
```text
44+
(?i)(\|warn\||\|error\||^\[v[0-9].+\]|database is locked)
45+
```
46+
47+
??? info "Why this regex?"
48+
- `(?i)` - Case-insensitive matching for all patterns
49+
- `\|warn\|` - Matches `|Warn|` log level delimiter in *arr logs
50+
- `\|error\|` - Matches `|Error|` log level delimiter
51+
- `^\[v[0-9].+\]` - Matches stack traces that start with any version header (v4, v5, v6, etc.)
52+
- `database is locked` - SQLite locking issues that indicate problems
53+
54+
**Skip:**
55+
```text
56+
(?i)Download client failed to add torrent|Movie with IMDBId|It will not be added|Invalid date found|Validation failed|An unhandled exception has occurred while executing the request.|HttpClient error|TaskManager failed while processing|Task Error|Name does not resolve|429.TooManyRequests
57+
```
58+
59+
??? info "Why skip these?"
60+
- `Download client failed to add torrent` - Usually duplicate detection, not a real error
61+
- `Movie with IMDBId` / `It will not be added` - Informational about skipped movies
62+
- `Invalid date found` - Common indexer feed parsing noise
63+
- `Validation failed` - API validation errors (usually user input issues)
64+
- `An unhandled exception...` - Generic wrapper, the actual error is elsewhere
65+
- `HttpClient error` - Transient network issues that resolve themselves
66+
- `TaskManager failed` / `Task Error` - Background task noise
67+
- `Name does not resolve` - DNS failures that are usually transient
68+
- `429.TooManyRequests` - Rate limiting (expected behavior)
69+
70+
---
71+
72+
#### Sonarr
73+
74+
**Path:**
75+
```text
76+
/var/log/sonarr/sonarr.debug.txt
77+
```
78+
79+
**Regex:**
80+
```text
81+
(?i)(\|warn\||\|error\||^\[v[0-9].+\]|database is locked)
82+
```
83+
84+
??? info "Why this regex?"
85+
- Same pattern as Radarr - matches warnings, errors, stack traces, and database locks
86+
87+
**Skip:**
88+
```text
89+
(?i)Download client failed to add torrent|Invalid date found|Validation failed|An unhandled exception has occurred while executing the request.|Unable to find exact quality|HttpClient error|TaskManager failed while processing|Task Error|Name does not resolve|InvalidDateException|429.TooManyRequests
90+
```
91+
92+
??? info "Why skip these?"
93+
- Same reasons as Radarr, plus:
94+
- `Unable to find exact quality` - Quality parsing noise from release names
95+
- `InvalidDateException` - Date parsing errors from indexers
96+
97+
---
98+
99+
#### Prowlarr
100+
101+
**Path:**
102+
```text
103+
/var/log/prowlarr/prowlarr.debug.txt
104+
```
105+
106+
**Regex:**
107+
```text
108+
(?i)(\|warn\||\|error\||^\[v[0-9].+\])
109+
```
110+
111+
**Skip:**
112+
```text
113+
(?i)Validation failed|An unhandled exception has occurred while executing the request|(?:CinemaZ|PrivateHD)[.a-z0-9/=&?: ]+404\.NotFound|HttpClient error|System.Net.CookieException|TaskManager failed while processing|Task Error|Name does not resolve|NzbDrone.Common.Http.HttpException: HTTP request failed|Retrying in
114+
```
115+
116+
??? info "Why skip these?"
117+
- `(?:CinemaZ|PrivateHD)...404` - Known indexers that return 404 for certain searches
118+
- `System.Net.CookieException` - Cookie handling issues that don't affect functionality
119+
- `HTTP request failed` / `Retrying in` - Transient errors with automatic retry
120+
121+
---
122+
123+
#### Readarr
124+
125+
**Path:**
126+
```text
127+
/var/log/readarr/readarr.debug.txt
128+
```
129+
130+
**Regex:**
131+
```text
132+
(?i)(\|warn\||\|error\||^\[v[0-9].+\])
133+
```
134+
135+
**Skip:**
136+
```text
137+
(?i)Validation failed|An unhandled exception has occurred while executing the request.|HttpClient error
138+
```
139+
140+
---
141+
142+
#### Lidarr
143+
144+
**Path:**
145+
```text
146+
/var/log/lidarr/lidarr.debug.txt
147+
```
148+
149+
**Regex:**
150+
```text
151+
(?i)(\|warn\||\|error\||^\[v[0-9].+\])
152+
```
153+
154+
**Skip:**
155+
```text
156+
(?i)Validation failed|An unhandled exception has occurred while executing the request.|HttpClient error
157+
```
158+
159+
---
160+
161+
### Other Applications
162+
163+
#### Kometa (formerly Plex Meta Manager)
164+
165+
**Path:**
166+
```text
167+
/var/log/kometa/meta.log
168+
```
169+
170+
**Regex:**
171+
```text
172+
(?i)(\[ERROR\]|\[CRITICAL\])
173+
```
174+
175+
??? info "Why this regex?"
176+
- Kometa uses `[ERROR]` and `[CRITICAL]` log level markers
177+
- Only matches actual errors, not warnings (which are often informational)
178+
179+
**Skip:**
180+
```text
181+
(?i)Convert Error:|ID not found|TVDb Error: Name not found|Plex Error: No Items found in Plex|Trakt Error: No TVDb ID found for|TMDb Error: No Movie found for TMDb ID
182+
```
183+
184+
??? info "Why skip these?"
185+
- `Convert Error` - Image conversion issues that don't affect functionality
186+
- `ID not found` / `Name not found` - Missing metadata that can't be fixed
187+
- `No Items found in Plex` - Empty collections (expected for new libraries)
188+
- `No TVDb ID found` / `No Movie found` - External service lookup failures
189+
190+
---
191+
192+
#### Nginx Error Log
193+
194+
**Path:**
195+
```text
196+
/var/log/nginx/error.log
197+
```
198+
199+
**Regex:**
200+
```text
201+
(?i)(emerg|alert|crit|\[error\].*upstream.*failed|502|503|504|connect\(\) failed|no live upstreams)
202+
```
203+
204+
??? info "Why this regex?"
205+
- `emerg|alert|crit` - Nginx severity levels for serious issues
206+
- `\[error\].*upstream.*failed` - Backend connection failures
207+
- `502|503|504` - Gateway errors indicating backend problems
208+
- `connect\(\) failed` - Can't reach upstream servers
209+
- `no live upstreams` - All backends are down
210+
211+
**Skip:**
212+
```text
213+
(?i)(client closed connection|upstream timed out.*reading response header|recv\(\) failed|connection reset by peer|SSL_do_handshake)
214+
```
215+
216+
??? info "Why skip these?"
217+
- `client closed connection` - User navigated away or closed browser
218+
- `upstream timed out` - Often caused by slow backends, not errors
219+
- `recv\(\) failed` / `connection reset` - Network glitches
220+
- `SSL_do_handshake` - SSL negotiation failures from bots/scanners
221+
222+
---
223+
224+
#### Rustic Backup
225+
226+
**Path:**
227+
```text
228+
/var/log/rustic/rustic.log
229+
```
230+
231+
**Regex:**
232+
```text
233+
(\[ERROR\]|\[WARN\]|starting to backup|successfully saved|backup of.*done)
234+
```
235+
236+
??? info "Why this regex?"
237+
- `\[ERROR\]|\[WARN\]` - Actual problems with backups
238+
- `starting to backup` - Notification that backup started
239+
- `successfully saved|backup of.*done` - Confirmation backup completed
240+
241+
**Skip:**
242+
```text
243+
(?i)(flush_task.*graceful shutdown|Requesting graceful shutdown|read_end_buffer_size|write_end_buffer_size|repository opendal.*password is correct)
244+
```
245+
246+
??? info "Why skip these?"
247+
- `graceful shutdown` - Normal shutdown messages
248+
- `buffer_size` - Configuration warnings that don't affect functionality
249+
- `password is correct` - Informational message, not an error
250+
251+
---
252+
253+
## Pattern Reference
254+
255+
### Common *arr Log Patterns
256+
257+
| Pattern | Matches |
258+
|---------|---------|
259+
| `\|warn\|` | Warning log level in *arr format: `2024-01-30 12:00:00.000\|Warn\|...` |
260+
| `\|error\|` | Error log level in *arr format |
261+
| `^\[v[0-9].+\]` | Stack traces that start with any version header (e.g., `[v5.0.0.1234]`) |
262+
| `database is locked` | SQLite concurrency issues |
263+
264+
### Common Skip Patterns
265+
266+
| Pattern | Reason to Skip |
267+
|---------|---------------|
268+
| `Invalid date found` | Indexer feed parsing - benign noise |
269+
| `Validation failed` | User input issues, not system errors |
270+
| `HttpClient error` | Transient network issues that auto-resolve |
271+
| `429.TooManyRequests` | Rate limiting - expected behavior |
272+
| `Name does not resolve` | DNS failures - usually transient |
273+
| `Download client failed to add torrent` | Usually duplicate detection |
274+
275+
## Troubleshooting
276+
277+
### File Not Being Watched
278+
279+
1. Verify the path exists: `ls -la /path/to/log`
280+
2. Check file permissions - notifiarr user must have read access
281+
3. Try enabling **Poll** for network-mounted files
282+
4. Check notifiarr logs: `journalctl -u notifiarr | grep -i watch`
283+
284+
### Too Many Notifications
285+
286+
1. Add patterns to **Skip** for false positives
287+
2. Use more specific **Regex** patterns
288+
3. Consider watching `.debug.txt` instead of `.txt` for less verbose logs
289+
290+
### No Notifications
291+
292+
1. Test your regex at [regex101.com](https://regex101.com/) with Go flavor
293+
2. Verify the watcher is not disabled
294+
3. Check that lines actually match with: `tail -f /path/to/log | grep -E 'your-regex'`
295+
4. Review notifiarr debug log for "watch" entries

0 commit comments

Comments
 (0)