Docs: revise multi-tenancy prose (#6355)

* Docs: revise multi-tenancy prose

* Update multi-tenancy docs using review comments

Author: KMiller-Grafana

docs/sources/configuration/_index.md

@@ -315,7 +315,7 @@ The `querier` block configures the Loki Querier.
 # CLI flag: -querier.query-ingester-only
 [query_ingester_only: <boolean> | default = false]
 
-# Allow queries for multiple tenants.
+# When true, allow queries to span multiple tenants.
 # CLI flag: -querier.multi-tenant-queries-enabled
 [multi_tenant_queries_enabled: <boolean> | default = false]
 

docs/sources/operations/multi-tenancy.md

@@ -12,24 +12,39 @@ Tenant IDs can be any alphanumeric string that fits within the Go HTTP header
 limit (1MB). Operators are recommended to use a reasonable limit for uniquely
 identifying tenants; 20 bytes is usually enough.
 
-To run in multi-tenant mode, Loki should be started with `auth_enabled: true`.
+Loki defaults to running in multi-tenant mode.
+Multi-tenant mode is set in the configuration with `auth_enabled: true`.
 
-Loki can be run in "single-tenant" mode where the `X-Scope-OrgID` header is not
-required. In single-tenant mode, the tenant ID defaults to `fake`.
+When configured with `auth_enabled: false`, Loki uses a single tenant.
+The `X-Scope-OrgID` header is not required in Loki API requests.
+The single tenant ID will be the string `fake`.
 
 ## Multi-tenant Queries
 
-If run in multi-tenant mode, queries that gather results from multiple tenants can be enabled with
-the `multi_tenant_queries_enabled: true` configuration option in the querier. Once enabled, multiple
-tenant IDs can be defined in the HTTP header `X-Scope-OrgID` by concatenating them
-with `|`. For instance a query for tenant A and B can set `X-Scope-OrgID: A|B`.
+In multi-tenant mode, queries may gather results from multiple tenants.
+Set the querier configuration option `multi_tenant_queries_enabled: true` to enable queries across tenants.
+The query API request defines the tenants.
+Specify multiple tenants
+in the query request HTTP header `X-Scope-OrgID` by separating the tenant IDs with the pipe character (`|`).
+For example, a query for tenants `A` and `B` requires the header `X-Scope-OrgID: A|B`.
 
-Only query endpoints support multi-tenant calls. Calls to `GET /loki/api/v1/tail`
-and `POST /loki/api/v1/push` will return an HTTP 400 error if more than one tenant
-is defined in the HTTP header.
+Only query endpoints support multi-tenant calls.
+Calls to `GET /loki/api/v1/tail` and `POST /loki/api/v1/push` will return an HTTP 400 error if more than one tenant is defined in the HTTP header.
 
-Instant and range queries support label filtering on the tenant IDs. For example
-`{app="foo", __tenant_id__=~"a.+"} | logfmt` will return results for all tenants
-whose ID start with `a`. Tenant ID filtering in stages is not supported; `{app="foo"} | __tenant_id__="1" | logfmt` will not work.
+Instant and range queries support label filtering using tenant IDs.
+For example, the query
 
-In case the label `__tenant_id__` is already present in a log stream it is prepended with `original_`.
+```
+{app="foo", __tenant_id__=~"a.+"} | logfmt
+```
+will return results for all tenants
+that have a tenant ID that begins with the character `a`.
+
+If the label `__tenant_id__` is already present in a log stream, it is prepended with the string `original_`.
+
+Tenant ID filtering in stages is not supported.
+An example of a query that will _not_ work:
+
+```
+{app="foo"} | __tenant_id__="1" | logfmt
+```