Added a FAQ topic on disk full conditions

filebeat/docs/faq.asciidoc

@@ -111,5 +111,22 @@ Filebeat uses a newline character to detect the end of an event. If lines are ad
 harvested, a newline character is required after the last line, or Filebeat will not read the last line of
 the file.
 
+[float]
+[[faq-deleted-files-are-not-freed]]
+=== Filebeat keeps open file handlers of deleted files for a long time?
+
+In the default behaviour, Filebeat opens the files and keeps them open until it
+reaches the end of them.  In situations when the configured output is blocked
+(e.g. Elasticsearch or Logstash is unavailable) for a long time, this can cause
+Filebeat to keep file handlers to files that were deleted from the file system
+in the mean time. As long as Filebeat keeps the deleted files open, the
+operating system doesn't free up the space on disk, which can lead to increase
+disk utilisation or even out of disk situations.
+
+To mitigate this issue, you can set the <<close-timeout>> setting to `5m`. This
+will ensure every file handler is closed once every 5 minutes, regardless of
+whether it reached EOF or not.
+
+
 include::../../libbeat/docs/faq-limit-bandwidth.asciidoc[]
 include::../../libbeat/docs/shared-faq.asciidoc[]

filebeat/docs/filebeat-options.asciidoc

@@ -291,12 +291,12 @@ WARNING: Only use this option if you understand that data loss is a potential si
 
 When this option is enabled, Filebeat gives every harvester a predefined lifetime. Regardless of where the reader is in the file, reading will stop after the `close_timeout` period has elapsed. This option can be useful for older log files when you want to spend only a predefined amount of time on the files.  While `close_timeout` will close the file after the predefined timeout, if the file is still being updated, the prospector will start a new harvester again per the defined `scan_frequency`. And the close_timeout for this harvester will start again with the countdown for the timeout.
 
+This option is particularly useful in case the output is blocked, which makes Filebeat keep open file handlers even for files that were deleted from the disk. Setting `close_timeout` to `5m` ensures that the files are periodically closed so they can be freed up by the operating system.
+
 If you set `close_timeout` to equal `ignore_older`, the file will not be picked up if it's modified while the harvester is closed. This combination of settings normally leads to data loss, and the complete file is not sent.
 
 When you use `close_timeout` for logs that contain multiline events, the harvester might stop in the middle of a multiline event, which means that only parts of the event will be sent. If the harvester is started again and the file still exists, only the second part of the event will be sent.
 
-The `close_timeout` setting won't apply if your output is stalled and no further events can be sent. At least one event must be sent after `close_timeout` elapses so the harvester can be closed after sending the event.
-
 This option is set to 0 by default which means it is disabled.