point out that disabling shard-by-all-labels has down-sides (#4452)

Signed-off-by: Mauro Stettler <[email protected]>

Author: replay

docs/configuration/arguments.md

@@ -142,6 +142,8 @@ The ingester query API was improved over time, but defaults to the old behaviour
 
    **Upgrade notes**: As this flag also makes all queries always read from all ingesters, the upgrade path is pretty trivial; just enable the flag. When you do enable it, you'll see a spike in the number of active series as the writes are "reshuffled" amongst the ingesters, but over the next stale period all the old series will be flushed, and you should end up with much better load balancing. With this flag enabled in the queriers, reads will always catch all the data from all ingesters.
 
+   **Warning**: disabling this flag can lead to a much less balanced distribution of load among the ingesters.
+
 - `-distributor.extra-query-delay`
    This is used by a component with an embedded distributor (Querier and Ruler) to control how long to wait until sending more than the minimum amount of queries needed for a successful response.
 

docs/guides/zone-replication.md

@@ -30,7 +30,7 @@ The Cortex time-series replication is used to hold multiple (typically 3) replic
 
 The `-distributor.shard-by-all-labels` setting has an impact on read availability. When enabled, a metric is sharded across all ingesters and querier needs to fetch series from all ingesters while, when disabled, a metric is sharded only across `<replication factor>` ingesters.
 
-In the event of a large outage impacting ingesters in more than 1 zone, when `-distributor.shard-by-all-labels=true` all queries will fail, while when disabled some queries may still succeed if the ingesters holding the required metric are not impacted by the outage.
+In the event of a large outage impacting ingesters in more than 1 zone, when `-distributor.shard-by-all-labels=true` all queries will fail, while when disabled some queries may still succeed if the ingesters holding the required metric are not impacted by the outage. To learn more about this flag, please refer to [distributor arguments](../configuration/arguments.md#distributor).
 
 ## Store-gateways: blocks replication