Merge pull request #1693 from cortexproject/periodic-table-docs

Add documentation for periodic table dates

Author: csmarchbanks

README.md

@@ -21,12 +21,15 @@ Cortex is a primarily used as a [remote write](https://prometheus.io/docs/operat
 
 ## Documentation
 
-Read the [getting started guide](docs/getting_started.md) if you're new to the project.
+Read the [getting started guide](docs/getting_started.md) if you're new to the
+project. Before deploying Cortex with a permanent storage backend you
+should read:
+1. [An overview of Cortex's architecture](docs/architecture.md)
+1. [A general guide to running Cortex](docs/running.md)
+1. [Information regarding configuring Cortex](docs/arguments.md)
 
 For a guide to contributing to Cortex, see the [contributor guidelines](CONTRIBUTING.md).
 
-You can also read [an overview of Cortex's architecture](docs/architecture.md) and [information about configuring Cortex](docs/arguments.md).
-
 ## Further reading
 
 To learn more about Cortex, consult the following documents & talks:

docs/running.md

@@ -47,7 +47,20 @@ replica and be unconcerned, as we still have two copies of the data
 left for redundancy. This is configurable: you can run with more
 redundancy or less, depending on your risk appetite.
 
-### Index schema
+### Schema
+
+#### Schema periodic table
+
+The periodic table from argument (`-dynamodb.periodic-table.from=<date>` if
+using command line flags, the `from` field for the first schema entry if using
+YAML) should be set to the date the oldest metrics you will be sending to
+Cortex. Generally that means set it to the date you are first deploying this
+instance. If you use an example date from years ago table-manager will create
+hundreds of tables. You can also avoid creating too many tables by setting a
+reasonable retention in the table-manager
+(`-table-manager.retention-period=<duration>`).
+
+#### Schema version
 
 Choose schema version 9 in most cases; version 10 if you expect
 hundreds of thousands of timeseries under a single name.  Anything