master
yaml 611 lines 27.3 KB
Raw
1 plugin_name: go.d.plugin
2 modules:
3 - meta:
4 id: collector-go.d.plugin-web_log
5 plugin_name: go.d.plugin
6 module_name: web_log
7 monitored_instance:
8 name: Web server log files
9 link: ""
10 categories:
11 - data-collection.web-servers-and-proxies
12 icon_filename: webservers.svg
13 keywords:
14 - webserver
15 - apache
16 - httpd
17 - nginx
18 - lighttpd
19 - logs
20 info_provided_to_referring_integrations:
21 description: ""
22 related_resources:
23 integrations:
24 list: []
25 overview:
26 data_collection:
27 metrics_description: |
28 This collector monitors web servers by parsing their log files.
29 method_description: ""
30 default_behavior:
31 auto_detection:
32 description: |
33 It automatically detects log files of web servers running on localhost.
34 limits:
35 description: ""
36 performance_impact:
37 description: ""
38 additional_permissions:
39 description: ""
40 multi_instance: true
41 supported_platforms:
42 include: []
43 exclude: []
44 setup:
45 prerequisites:
46 list: []
47 configuration:
48 file:
49 name: go.d/web_log.conf
50 options:
51 description: |
52 Weblog is aware of how to parse and interpret the following fields (**known fields**):
53
54 > [nginx](https://nginx.org/en/docs/varindex.html)
55 >
56 > [apache](https://httpd.apache.org/docs/current/mod/mod_log_config.html)
57
58 | nginx | apache | description |
59 |-------------------------|----------|------------------------------------------------------------------------------------------|
60 | $host ($http_host) | %v | Name of the server which accepted a request. |
61 | $server_port | %p | Port of the server which accepted a request. |
62 | $scheme | - | Request scheme. "http" or "https". |
63 | $remote_addr | %a (%h) | Client address. |
64 | $request | %r | Full original request line. The line is "$request_method $request_uri $server_protocol". |
65 | $request_method | %m | Request method. Usually "GET" or "POST". |
66 | $request_uri | %U | Full original request URI. |
67 | $server_protocol | %H | Request protocol. Usually "HTTP/1.0", "HTTP/1.1", or "HTTP/2.0". |
68 | $status | %s (%>s) | Response status code. |
69 | $request_length | %I | Bytes received from a client, including request and headers. |
70 | $bytes_sent | %O | Bytes sent to a client, including request and headers. |
71 | $body_bytes_sent | %B (%b) | Bytes sent to a client, not counting the response header. |
72 | $request_time | %D | Request processing time. |
73 | $upstream_response_time | - | Time spent on receiving the response from the upstream server. |
74 | $ssl_protocol | - | Protocol of an established SSL connection. |
75 | $ssl_cipher | - | String of ciphers used for an established SSL connection. |
76
77 Notes:
78
79 - Apache `%h` logs the IP address if [HostnameLookups](https://httpd.apache.org/docs/2.4/mod/core.html#hostnamelookups) is Off. The web log collector counts hostnames as IPv4 addresses. We recommend either to disable HostnameLookups or use `%a` instead of `%h`.
80 - Since httpd 2.0, unlike 1.3, the `%b` and `%B` format strings do not represent the number of bytes sent to the client, but simply the size in bytes of the HTTP response. It will differ, for instance, if the connection is aborted, or if SSL is used. The `%O` format provided by [`mod_logio`](https://httpd.apache.org/docs/2.4/mod/mod_logio.html) will log the actual number of bytes sent over the network.
81 - To get `%I` and `%O` working you need to enable `mod_logio` on Apache.
82 - NGINX logs URI with query parameters, Apache doesnt.
83 - `$request` is parsed into `$request_method`, `$request_uri` and `$server_protocol`. If you have `$request` in your log format, there is no sense to have others.
84 - Don't use both `$bytes_sent` and `$body_bytes_sent` (`%O` and `%B` or `%b`). The module does not distinguish between these parameters.
85 folding:
86 title: Config options
87 enabled: true
88 list:
89 - name: update_every
90 description: Data collection frequency.
91 default_value: 1
92 required: false
93 group: Collection
94 - name: autodetection_retry
95 description: Recheck interval in seconds. Zero means no recheck will be scheduled.
96 default_value: 0
97 required: false
98 group: Collection
99
100 - name: path
101 description: Path to the web server log file.
102 default_value: ""
103 required: true
104 group: Target
105 - name: exclude_path
106 description: Path to exclude.
107 default_value: "*.gz"
108 required: false
109 group: Target
110
111 - name: url_patterns
112 description: List of URL patterns.
113 default_value: "[]"
114 required: false
115 group: Customization
116 detailed_description: |
117 "URL pattern" scope metrics will be collected for each URL pattern.
118
119 Option syntax:
120
121 ```yaml
122 url_patterns:
123 - name: name1
124 match: pattern1
125 - name: name2
126 match: pattern2
127 ```
128
129 Examples:
130
131 ```yaml
132 url_patterns:
133 - name: api
134 match: '* /api/*'
135 - name: api_versioned
136 match: '~ ^/api/v[0-9]+/.*'
137 - name: health_endpoint
138 match: '= /health'
139 - name: not_static_css
140 match: '!* *.css'
141 ```
142
143 Pattern values use the [matcher library](/src/go/pkg/matcher/README.md#supported-format) syntax:
144
145 - `=` — string (exact match)
146 - `*` — glob patterns
147 - `~` — regular expressions
148 - `!` — negates either short syntax (`!* ...`) or long syntax (`!simple_patterns:...`)
149 - `simple_patterns` — simple patterns (long syntax only)
150
151 Patterns are matched against the full original request URI (`$request_uri`).
152 - name: url_patterns.name
153 description: Used as a dimension name.
154 default_value: ""
155 required: true
156 group: Customization
157 - name: url_patterns.match
158 description: Used to match against full original request URI. Match syntax in [matcher](/src/go/pkg/matcher/README.md#supported-format).
159 default_value: ""
160 required: true
161 group: Customization
162
163 - name: log_type
164 description: Log parser type.
165 default_value: auto
166 required: false
167 group: Parser
168 detailed_description: |
169 Weblog supports 5 different log parsers:
170
171 | Parser type | Description |
172 |-------------|-------------------------------------------|
173 | auto | Use CSV and auto-detect format |
174 | csv | A comma-separated values |
175 | json | [JSON](https://www.json.org/json-en.html) |
176 | ltsv | [LTSV](http://ltsv.org/) |
177 | regexp | Regular expression with named groups |
178
179 Syntax:
180
181 ```yaml
182 log_type: auto
183 ```
184
185 If `log_type` parameter set to `auto` (which is default), weblog will try to auto-detect appropriate log parser and log format using the last line of the log file.
186
187 - checks if format is `CSV` (using regexp).
188 - checks if format is `JSON` (using regexp).
189 - assumes format is `CSV` and tries to find appropriate `CSV` log format using predefined list of formats. It tries to parse the line using each of them in the following order (the first one matches is used later):
190
191 ```sh
192 $host:$server_port $remote_addr - - [$time_local] "$request" $status $body_bytes_sent - - $request_length $request_time $upstream_response_time
193 $host:$server_port $remote_addr - - [$time_local] "$request" $status $body_bytes_sent - - $request_length $request_time
194 $host:$server_port $remote_addr - - [$time_local] "$request" $status $body_bytes_sent $request_length $request_time $upstream_response_time
195 $host:$server_port $remote_addr - - [$time_local] "$request" $status $body_bytes_sent $request_length $request_time
196 $host:$server_port $remote_addr - - [$time_local] "$request" $status $body_bytes_sent
197 $remote_addr - - [$time_local] "$request" $status $body_bytes_sent - - $request_length $request_time $upstream_response_time
198 $remote_addr - - [$time_local] "$request" $status $body_bytes_sent - - $request_length $request_time
199 $remote_addr - - [$time_local] "$request" $status $body_bytes_sent $request_length $request_time $upstream_response_time
200 $remote_addr - - [$time_local] "$request" $status $body_bytes_sent $request_length $request_time
201 $remote_addr - - [$time_local] "$request" $status $body_bytes_sent
202 ```
203
204 If you're using the default Apache/NGINX log format, auto-detect will work for you. If it doesn't work you need to set the format manually.
205 - name: csv_config
206 description: CSV log parser config.
207 default_value: ""
208 required: false
209 group: Parser
210 - name: csv_config.delimiter
211 description: CSV field delimiter.
212 default_value: ","
213 required: false
214 group: Parser
215 - name: csv_config.format
216 description: CSV log format.
217 default_value: ""
218 required: false
219 group: Parser
220 - name: ltsv_config
221 description: LTSV log parser config.
222 default_value: ""
223 required: false
224 group: Parser
225 - name: ltsv_config.field_delimiter
226 description: LTSV field delimiter.
227 default_value: "\\t"
228 required: false
229 group: Parser
230 - name: ltsv_config.value_delimiter
231 description: LTSV value delimiter.
232 default_value: ":"
233 required: false
234 group: Parser
235 - name: ltsv_config.mapping
236 description: LTSV fields mapping to **known fields**.
237 default_value: ""
238 required: true
239 group: Parser
240 detailed_description: |
241 The mapping is a dictionary where the key is a field, as in logs, and the value is the corresponding **known field**.
242
243 > **Note**: don't use `$` and `%` prefixes for mapped field names.
244
245 ```yaml
246 log_type: ltsv
247 ltsv_config:
248 mapping:
249 label1: field1
250 label2: field2
251 ```
252 - name: json_config
253 description: JSON log parser config.
254 default_value: ""
255 required: false
256 group: Parser
257 - name: json_config.mapping
258 description: JSON fields mapping to **known fields**.
259 default_value: ""
260 required: true
261 group: Parser
262 detailed_description: |
263 The mapping is a dictionary where the key is a field, as in logs, and the value is the corresponding **known field**.
264
265 > **Note**: don't use `$` and `%` prefixes for mapped field names.
266
267 ```yaml
268 log_type: json
269 json_config:
270 mapping:
271 label1: field1
272 label2: field2
273 ```
274 - name: regexp_config
275 description: RegExp log parser config.
276 default_value: ""
277 required: false
278 group: Parser
279 - name: regexp_config.pattern
280 description: RegExp pattern with named groups.
281 default_value: ""
282 required: true
283 group: Parser
284 detailed_description: |
285 Use pattern with subexpressions names. These names should be **known fields**.
286
287 > **Note**: don't use `$` and `%` prefixes for mapped field names.
288
289 Syntax:
290
291 ```yaml
292 log_type: regexp
293 regexp_config:
294 pattern: PATTERN
295 ```
296 examples:
297 folding:
298 title: Config
299 enabled: true
300 list: []
301 troubleshooting:
302 problems:
303 list:
304 - name: High percentage of unparsed log lines (web_log_1m_unmatched alert)
305 description: |
306 This alert indicates that more than 1% of log lines could not be parsed by the web_log collector over the last minute.
307
308 **Common causes:**
309 - Custom log format not matching any of the predefined formats
310 - Log format has changed on the web server
311 - Using a non-standard log format without proper configuration
312
313 **Diagnostic steps:**
314
315 1. Run the collector in debug mode to see unparsed lines:
316 ```bash
317 cd /usr/libexec/netdata/plugins.d/
318 sudo -u netdata -s
319 ./go.d.plugin -d -m web_log
320 ```
321
322 2. Check the debug output for lines marked as unmatched to understand what format they have.
323
324 **Resolution:**
325
326 - If using a custom log format, configure `log_type` and the appropriate parser config:
327 - For CSV formats: set `log_type: csv` and configure `csv_config.format` to match your log format
328 - For custom patterns: set `log_type: regexp` and configure `regexp_config.pattern` with a regex containing named groups matching the known fields
329 - For JSON logs: set `log_type: json` and configure `json_config.mapping`
330 - For LTSV logs: set `log_type: ltsv` and configure `ltsv_config.mapping`
331 - name: Unmatched lines due to non-standard log fields or extra columns
332 description: |
333 Persistent unmatched entries appear even with auto-detection enabled.
334
335 **Cause:**
336 The log format includes fields not in the known-fields list (for example, custom headers, upstream timing, or unique IDs), preventing CSV auto-detection from matching any predefined format.
337
338 **Resolution:**
339 Set `log_type: csv` explicitly and specify `csv_config.format` using the known field variables that match the log's column order. Alternatively, use `log_type: regexp` with a `regexp_config.pattern` that captures only the known fields and ignores extras.
340 - name: Suppressing the alert for known benign unmatched lines
341 description: |
342 The web_log_1m_unmatched alert fires continuously but the unmatched lines are intentional (for example, health check logs in a different format).
343
344 **Resolution:**
345 Customize the alert threshold in `health.d/web_log.conf` by copying the web_log_1m_unmatched template and adjusting the warn condition, or silence notifications via Netdata Cloud alert configuration.
346 alerts:
347 - name: web_log_1m_unmatched
348 metric: web_log.excluded_requests
349 info: percentage of unparsed log lines over the last minute
350 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
351 - name: web_log_1m_requests
352 metric: web_log.type_requests
353 info: "ratio of successful HTTP requests over the last minute (1xx, 2xx, 304, 401)"
354 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
355 - name: web_log_1m_redirects
356 metric: web_log.type_requests
357 info: "ratio of redirection HTTP requests over the last minute (3xx except 304)"
358 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
359 - name: web_log_1m_bad_requests
360 metric: web_log.type_requests
361 info: "ratio of client error HTTP requests over the last minute (4xx except 401)"
362 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
363 - name: web_log_1m_internal_errors
364 metric: web_log.type_requests
365 info: "ratio of server error HTTP requests over the last minute (5xx)"
366 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
367 - name: web_log_web_slow
368 metric: web_log.request_processing_time
369 info: average HTTP response time over the last 1 minute
370 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
371 - name: web_log_5m_requests_ratio
372 metric: web_log.type_requests
373 info: ratio of successful HTTP requests over over the last 5 minutes, compared with the previous 5 minutes
374 link: https://github.com/netdata/netdata/blob/master/src/health/health.d/web_log.conf
375 metrics:
376 folding:
377 title: Metrics
378 enabled: false
379 description: ""
380 availability: []
381 scopes:
382 - name: global
383 description: These metrics refer to the entire monitored application.
384 labels: []
385 metrics:
386 - name: web_log.requests
387 description: Total Requests
388 unit: requests/s
389 chart_type: line
390 dimensions:
391 - name: requests
392 - name: web_log.excluded_requests
393 description: Excluded Requests
394 unit: requests/s
395 chart_type: stacked
396 dimensions:
397 - name: unmatched
398 - name: web_log.type_requests
399 description: Requests By Type
400 unit: requests/s
401 chart_type: stacked
402 dimensions:
403 - name: success
404 - name: bad
405 - name: redirect
406 - name: error
407 - name: web_log.status_code_class_responses
408 description: Responses By Status Code Class
409 unit: responses/s
410 chart_type: stacked
411 dimensions:
412 - name: 1xx
413 - name: 2xx
414 - name: 3xx
415 - name: 4xx
416 - name: 5xx
417 - name: web_log.status_code_class_1xx_responses
418 description: Informational Responses By Status Code
419 unit: responses/s
420 chart_type: stacked
421 dimensions:
422 - name: a dimension per 1xx code
423 - name: web_log.status_code_class_2xx_responses
424 description: Successful Responses By Status Code
425 unit: responses/s
426 chart_type: stacked
427 dimensions:
428 - name: a dimension per 2xx code
429 - name: web_log.status_code_class_3xx_responses
430 description: Redirects Responses By Status Code
431 unit: responses/s
432 chart_type: stacked
433 dimensions:
434 - name: a dimension per 3xx code
435 - name: web_log.status_code_class_4xx_responses
436 description: Client Errors Responses By Status Code
437 unit: responses/s
438 chart_type: stacked
439 dimensions:
440 - name: a dimension per 4xx code
441 - name: web_log.status_code_class_5xx_responses
442 description: Server Errors Responses By Status Code
443 unit: responses/s
444 chart_type: stacked
445 dimensions:
446 - name: a dimension per 5xx code
447 - name: web_log.bandwidth
448 description: Bandwidth
449 unit: kilobits/s
450 chart_type: area
451 dimensions:
452 - name: received
453 - name: sent
454 - name: web_log.request_processing_time
455 description: Request Processing Time
456 unit: milliseconds
457 chart_type: line
458 dimensions:
459 - name: min
460 - name: max
461 - name: avg
462 - name: web_log.requests_processing_time_histogram
463 description: Requests Processing Time Histogram
464 unit: requests/s
465 chart_type: line
466 dimensions:
467 - name: a dimension per bucket
468 - name: web_log.upstream_response_time
469 description: Upstream Response Time
470 unit: milliseconds
471 chart_type: line
472 dimensions:
473 - name: min
474 - name: max
475 - name: avg
476 - name: web_log.upstream_responses_time_histogram
477 description: Upstream Responses Time Histogram
478 unit: requests/s
479 chart_type: line
480 dimensions:
481 - name: a dimension per bucket
482 - name: web_log.current_poll_uniq_clients
483 description: Current Poll Unique Clients
484 unit: clients
485 chart_type: stacked
486 dimensions:
487 - name: ipv4
488 - name: ipv6
489 - name: web_log.vhost_requests
490 description: Requests By Vhost
491 unit: requests/s
492 chart_type: stacked
493 dimensions:
494 - name: a dimension per vhost
495 - name: web_log.port_requests
496 description: Requests By Port
497 unit: requests/s
498 chart_type: stacked
499 dimensions:
500 - name: a dimension per port
501 - name: web_log.scheme_requests
502 description: Requests By Scheme
503 unit: requests/s
504 chart_type: stacked
505 dimensions:
506 - name: http
507 - name: https
508 - name: web_log.http_method_requests
509 description: Requests By HTTP Method
510 unit: requests/s
511 chart_type: stacked
512 dimensions:
513 - name: a dimension per HTTP method
514 - name: web_log.http_version_requests
515 description: Requests By HTTP Version
516 unit: requests/s
517 chart_type: stacked
518 dimensions:
519 - name: a dimension per HTTP version
520 - name: web_log.ip_proto_requests
521 description: Requests By IP Protocol
522 unit: requests/s
523 chart_type: stacked
524 dimensions:
525 - name: ipv4
526 - name: ipv6
527 - name: web_log.ssl_proto_requests
528 description: Requests By SSL Connection Protocol
529 unit: requests/s
530 chart_type: stacked
531 dimensions:
532 - name: a dimension per SSL protocol
533 - name: web_log.ssl_cipher_suite_requests
534 description: Requests By SSL Connection Cipher Suite
535 unit: requests/s
536 chart_type: stacked
537 dimensions:
538 - name: a dimension per SSL cipher suite
539 - name: web_log.url_pattern_requests
540 description: URL Field Requests By Pattern
541 unit: requests/s
542 chart_type: stacked
543 dimensions:
544 - name: a dimension per URL pattern
545 - name: web_log.custom_field_pattern_requests
546 description: Custom Field Requests By Pattern
547 unit: requests/s
548 chart_type: stacked
549 dimensions:
550 - name: a dimension per custom field pattern
551 - name: custom time field
552 description: TBD
553 labels: []
554 metrics:
555 - name: web_log.custom_time_field_summary
556 description: Custom Time Field Summary
557 unit: milliseconds
558 chart_type: line
559 dimensions:
560 - name: min
561 - name: max
562 - name: avg
563 - name: web_log.custom_time_field_histogram
564 description: Custom Time Field Histogram
565 unit: observations
566 chart_type: line
567 dimensions:
568 - name: a dimension per bucket
569 - name: custom numeric field
570 description: TBD
571 labels: []
572 metrics:
573 - name: web_log.custom_numeric_field_{{field_name}}_summary
574 description: Custom Numeric Field Summary
575 unit: '{{units}}'
576 chart_type: line
577 dimensions:
578 - name: min
579 - name: max
580 - name: avg
581 - name: URL pattern
582 description: TBD
583 labels: []
584 metrics:
585 - name: web_log.url_pattern_status_code_responses
586 description: Responses By Status Code
587 unit: responses/s
588 chart_type: line
589 dimensions:
590 - name: a dimension per pattern
591 - name: web_log.url_pattern_http_method_requests
592 description: Requests By HTTP Method
593 unit: requests/s
594 chart_type: line
595 dimensions:
596 - name: a dimension per HTTP method
597 - name: web_log.url_pattern_bandwidth
598 description: Bandwidth
599 unit: kilobits/s
600 chart_type: area
601 dimensions:
602 - name: received
603 - name: sent
604 - name: web_log.url_pattern_request_processing_time
605 description: Request Processing Time
606 unit: milliseconds
607 chart_type: line
608 dimensions:
609 - name: min
610 - name: max
611 - name: avg