Github user srowen commented on a diff in the pull request: https://github.com/apache/spark/pull/14731#discussion_r95058662 --- Diff: docs/streaming-programming-guide.md --- @@ -630,35 +630,106 @@ which creates a DStream from text data received over a TCP socket connection. Besides sockets, the StreamingContext API provides methods for creating DStreams from files as input sources. -- **File Streams:** For reading data from files on any file system compatible with the HDFS API (that is, HDFS, S3, NFS, etc.), a DStream can be created as: +#### File Streams +{:.no_toc} + +For reading data from files on any file system compatible with the HDFS API (that is, HDFS, S3, NFS, etc.), a DStream can be created as +via `StreamingContext.fileStream[KeyClass, ValueClass, InputFormatClass]`. + +File streams do not require running a receiver, hence does not require allocating cores. - <div class="codetabs"> - <div data-lang="scala" markdown="1"> - streamingContext.fileStream[KeyClass, ValueClass, InputFormatClass](dataDirectory) - </div> - <div data-lang="java" markdown="1"> - streamingContext.fileStream<KeyClass, ValueClass, InputFormatClass>(dataDirectory); - </div> - <div data-lang="python" markdown="1"> - streamingContext.textFileStream(dataDirectory) - </div> - </div> +For simple text files, the easiest method is `StreamingContext.textFileStream(dataDirectory)`. - Spark Streaming will monitor the directory `dataDirectory` and process any files created in that directory (files written in nested directories not supported). Note that +<div class="codetabs"> +<div data-lang="scala" markdown="1"> - + The files must have the same data format. - + The files must be created in the `dataDirectory` by atomically *moving* or *renaming* them into - the data directory. - + Once moved, the files must not be changed. So if the files are being continuously appended, the new data will not be read. +{% highlight scala %} +streamingContext.fileStream[KeyClass, ValueClass, InputFormatClass](dataDirectory) +{% endhighlight %} +For text files + +{% highlight scala %} +streamingContext.textFileStream(dataDirectory) +{% endhighlight %} +</div> - For simple text files, there is an easier method `streamingContext.textFileStream(dataDirectory)`. And file streams do not require running a receiver, hence does not require allocating cores. +<div data-lang="java" markdown="1"> +{% highlight java %} +streamingContext.fileStream<KeyClass, ValueClass, InputFormatClass>(dataDirectory); +{% endhighlight %} +For text files - <span class="badge" style="background-color: grey">Python API</span> `fileStream` is not available in the Python API, only `textFileStream` is available. +{% highlight java %} +streamingContext.textFileStream(dataDirectory); +{% endhighlight %} +</div> -- **Streams based on Custom Receivers:** DStreams can be created with data streams received through custom receivers. See the [Custom Receiver +<div data-lang="python" markdown="1"> +`fileStream` is not available in the Python API; only `textFileStream` is available. +{% highlight python %} +streamingContext.textFileStream(dataDirectory) +{% endhighlight %} +</div> + +</div> + +##### How Directories are Monitored +{:.no_toc} + +Spark Streaming will monitor the directory `dataDirectory` and process any files created in that directory. + + * A simple directory can be monitored, such as `hdfs://namenode:8040/logs/`. + All files directly under such a path will be processed as they are discovered. + + A [POSIX glob pattern](http://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_02) can be supplied, such as + `hdfs://namenode:8040/logs/2017/*`. + Here, the DStream will consist of all files in the directories + matching the pattern. + That is: it is a pattern of directories, not of files in directories. + + All files must be in the same data format. + * A file is considered part of a time period based on its modification time, + not its creation time. + + Once processed, changes to a file within the current window will not cause the file to be reread. + That is: *updates are ignored*. + + The more files under a directory, the longer it will take to + scan for changes âeven if no files have been modified. + * If a wildcard is used to identify directories, such as `hdfs://namenode:8040/logs/2016-*`, + renaming an entire directory to match the path will add the directory to the list of + monitored directories. Only the files in the directory whose modification time is + within the current window will be included in the stream. + + Calling `FileSystem.setTimes()` to fix the timestamp is a way to have the file picked + up in a later window, even if its contents have not changed. + + +##### Streaming to FileSystems vs Object stores +{:.no_toc} + +"Full" Filesystems such as HDFS tend to set the modification time on their files as soon --- End diff -- Is the message of this section: Write new data to a file outside the monitored directory, and then move it into that directory after it's closed. Otherwise, if writing directly to a file in the monitored directory, it may be processed while it's being written to. However: if you are working with an object store like S3, this approach still works correctly but may be slow because a rename can be a copy. In some cases it's OK to write directly into the destination directory because the object store won't expose the file until it's done. If so I think this could be a little more direct, telling users what they need to know to use this correctly. It seems like renaming is always at least correct. I think that if different advice applies for S3, that should also be called out by name, or else I'm left wondering unnecessarily whether this applies to the most commonly-used store, S3.
--- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- --------------------------------------------------------------------- To unsubscribe, e-mail: reviews-unsubscr...@spark.apache.org For additional commands, e-mail: reviews-h...@spark.apache.org