Github user steveloughran commented on a diff in the pull request: https://github.com/apache/spark/pull/14731#discussion_r95079472 --- 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 -- FWIW, I've just pulled in some people who have implemented HDFS and S3 clones to give their view of the world, [HADOOP-13946](https://issues.apache.org/jira/browse/HADOOP-13946) I think for object stores I should actually be vaguer and say "try and it and see". It looks like put ops get their TS when the PUT begins, so multipart put operations will get a TS somewhere between create() and close(). Also, @ajfabbri had to change the semantics on create() to a TS generated by the client when you are using s3guard to cache data. One troublespot here is that rename() is likely to change timestamps of files in a blobstore, meaning the files window will change from that of creation to that of the rename. That probably is something to call out, as people may need to know of it.
--- 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