Github user srowen commented on a diff in the pull request:

    https://github.com/apache/spark/pull/14731#discussion_r83491041
  
    --- Diff: docs/streaming-programming-guide.md ---
    @@ -644,17 +644,90 @@ methods for creating DStreams from files as input 
sources.
         </div>
         </div>
     
    -   Spark Streaming will monitor the directory `dataDirectory` and process 
any files created in that directory (files written in nested directories not 
supported). Note that
    +   Spark Streaming will monitor the directory `dataDirectory` and process 
any files created in that directory.
    +
    +     ++ The files must have the same data format.
    +     + A simple directory can be monitored, such as 
`hdfs://namenode:8040/logs/`.
    +       All files directly such a path will be processed as they are 
discovered.
    +     + A POSIX glob pattern can be supplied, such as
    +       `hdfs://namenode:8040/logs/2016-??-31`.
    +       Here, the DStream will consist of all files directly under those 
directories
    +       matching the regular expression.
    +       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.
    +     + Files must be created in/moved under the `dataDirectory` 
directory/directories by
    +       an atomic operation. In HDFS and similar filesystems, this can be 
done *renaming* them
    +       into the data directory from another part of the same filesystem.
    +     * 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.
    +     + 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/wildcard pattern, the longer it 
will take to
    +       scan for changes —even if no files have actually changed.
    +     + 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.
     
    -     + 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.
     
        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.
     
        <span class="badge" style="background-color: grey">Python API</span> 
`fileStream` is not available in the Python API, only      `textFileStream` is  
   available.
     
    +
    +    Special points for HDFS
    --- End diff --
    
    Does this need to start a new section in the markdown?


---
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

Reply via email to