Docs: Make identification of experimental items consistent and more o…

…bvious. (#3911)

docs/sources/api/_index.md

@@ -242,18 +242,18 @@ accepts the following query parameters in the URL:
 - `start`: The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago.
 - `end`: The end time for the query as a nanosecond Unix epoch. Defaults to now.
 - `step`: Query resolution step width in `duration` format or float number of seconds. `duration` refers to Prometheus duration strings of the form `[0-9]+[smhdwy]`. For example, 5m refers to a duration of 5 minutes. Defaults to a dynamic value based on `start` and `end`.  Only applies to query types which produce a matrix response.
-- `interval`: **Experimental, See Below** Only return entries at (or greater than) the specified interval, can be a `duration` format or float number of seconds. Only applies to queries which produce a stream response.
+- `interval`: <span style="background-color:#f3f973;">This parameter is experimental; see the explanation under Step versus Interval.</span> Only return entries at (or greater than) the specified interval, can be a `duration` format or float number of seconds. Only applies to queries which produce a stream response.
 - `direction`: Determines the sort order of logs. Supported values are `forward` or `backward`. Defaults to `backward.`
 
 In microservices mode, `/loki/api/v1/query_range` is exposed by the querier and the frontend.
 
-##### Step vs Interval
+##### Step versus Interval
 
 Use the `step` parameter when making metric queries to Loki, or queries which return a matrix response.  It is evaluated in exactly the same way Prometheus evaluates `step`.  First the query will be evaluated at `start` and then evaluated again at `start + step` and again at `start + step + step` until `end` is reached.  The result will be a matrix of the query result evaluated at each step.
 
 Use the `interval` parameter when making log queries to Loki, or queries which return a stream response. It is evaluated by returning a log entry at `start`, then the next entry will be returned an entry with timestampe >= `start + interval`, and again at `start + interval + interval` and so on until `end` is reached.  It does not fill missing entries.
 
-**Note about the experimental nature of interval** This flag may be removed in the future, if so it will likely be in favor of a LogQL expression to perform similar behavior, however that is uncertain at this time.  [Issue 1779](https://github.com/grafana/loki/issues/1779) was created to track the discussion, if you are using `interval` please go add your use case and thoughts to that issue.
+<span style="background-color:#f3f973;">Note about the experimental nature of the interval parameter:</span> This flag may be removed in the future, if so it will likely be in favor of a LogQL expression to perform similar behavior, however that is uncertain at this time.  [Issue 1779](https://github.com/grafana/loki/issues/1779) was created to track the discussion, if you are using `interval` please go add your use case and thoughts to that issue.
 
 
 
@@ -955,14 +955,14 @@ Displays a web page with the ruler hash ring status, including the state, health
 
 ### List rule groups
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 GET /loki/api/v1/rules
 ```
 
 List all rules configured for the authenticated tenant. This endpoint returns a YAML dictionary with all the rule groups for each namespace and `200` status code on success.
 
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
-
 #### Example response
 
 ```yaml
@@ -1003,14 +1003,14 @@ _This experimental endpoint is disabled by default and can be enabled via the `-
 
 ### Get rule groups by namespace
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 GET /loki/api/v1/rules/{namespace}
 ```
 
 Returns the rule groups defined for a given namespace.
 
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
-
 #### Example response
 
 ```yaml
@@ -1028,24 +1028,24 @@ rules:
 
 ### Get rule group
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 GET /loki/api/v1/rules/{namespace}/{groupName}
 ```
 
 Returns the rule group matching the request namespace and group name.
 
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
-
 ### Set rule group
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 POST /loki/api/v1/rules/{namespace}
 ```
 
 Creates or updates a rule group. This endpoint expects a request with `Content-Type: application/yaml` header and the rules **YAML** definition in the request body, and returns `202` on success.
 
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
-
 #### Example request
 
 Request headers:
@@ -1077,16 +1077,18 @@ Deletes a rule group by namespace and group name. This endpoints returns `202` o
 
 ### Delete namespace
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 DELETE /loki/api/v1/rules/{namespace}
 ```
 
 Deletes all the rule groups in a namespace (including the namespace itself). This endpoint returns `202` on success.
 
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
-
 ### List rules
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 GET /prometheus/api/v1/rules
 ```
@@ -1095,16 +1097,14 @@ Prometheus-compatible rules endpoint to list alerting and recording rules that a
 
 For more information, refer to the [Prometheus rules](https://prometheus.io/docs/prometheus/latest/querying/api/#rules) documentation.
 
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
-
 ### List alerts
 
+<span style="background-color:#f3f973;">This experimental endpoint is disabled by default and can be enabled via the -experimental.ruler.enable-api CLI flag or the YAML config option.</span>
+
 ```
 GET /prometheus/api/v1/alerts
 ```
 
 Prometheus-compatible rules endpoint to list all active alerts.
 
-_For more information, please check out the Prometheus [alerts](https://prometheus.io/docs/prometheus/latest/querying/api/#alerts) documentation._
-
-_This experimental endpoint is disabled by default and can be enabled via the `-experimental.ruler.enable-api` CLI flag (or its respective YAML config option)._
+For more information, please check out the Prometheus [alerts](https://prometheus.io/docs/prometheus/latest/querying/api/#alerts) documentation.

docs/sources/configuration/_index.md

@@ -352,6 +352,8 @@ results_cache:
 
 The `ruler_config` configures the Loki ruler.
 
+<span style="background-color:#f3f973;">The Ruler API is experimental.</span>
+
 ```yaml
 # URL of alerts return path.
 # CLI flag: -ruler.external.url
@@ -1462,6 +1464,8 @@ to wait before saving them to the backing store.
 The `cache_config` block configures how Loki will cache requests, chunks, and
 the index to a backing cache store.
 
+<span style="background-color:#f3f973;">The memcached configuration variable addresses is experimental.</span>
+
 ```yaml
 # Enable in-memory cache.
 # CLI flag: -<prefix>.cache.enable-fifocache
@@ -1507,7 +1511,7 @@ memcached_client:
   # CLI flag: -<prefix>.memcached.service
   [service: <string> | default = "memcached"]
 
-  # EXPERIMENTAL: Comma separated addresses list in DNS Service Discovery format:
+  # (Experimental) Comma-separated addresses list in DNS Service Discovery format:
   # https://cortexmetrics.io/docs/configuration/arguments/#dns-service-discovery
   # CLI flag: -<prefix>.memcached.addresses
   [addresses: <string> | default = ""]
@@ -1653,6 +1657,8 @@ chunks:
 The `compactor_config` block configures the compactor component. This component periodically
 compacts index shards to more performant forms.
 
+<span style="background-color:#f3f973;">Retention through the Compactor is experimental.</span>
+
 ```yaml
 # Directory where files can be downloaded for compaction.
 [working_directory: <string>]

docs/sources/logql/_index.md

@@ -280,6 +280,8 @@ will get those labels extracted:
 
 ##### Pattern
 
+<span style="background-color:#f3f973;">The pattern parser is a beta feature.</span>
+
 The pattern parser allows the explicit extraction of fields from log lines by defining a pattern expression (`| pattern "<pattern-expression>"`). The expression matches the structure of a log line.
 
 Consider this NGINX log line.

docs/sources/operations/storage/logs-deletion.md

@@ -4,7 +4,7 @@ weight: 60
 ---
 # Log Entry Deletion
 
-_This feature is experimental. It is only supported for the BoltDB Shipper index store._
+<span style="background-color:#f3f973;">Log entry deletion is experimental. It is only supported for the BoltDB Shipper index store.</span>
 
 Loki supports the deletion of log entries from specified streams.
 Log entries that fall within a specified time window are those that will be deleted.
@@ -88,4 +88,4 @@ Sample form of a cURL command:
 curl -X POST \
   '<compactor_addr>/loki/api/admin/cancel_delete_request?request_id=<request_id>' \
   -H 'x-scope-orgid: <tenant-id>'
-```
+```

docs/sources/operations/storage/retention.md

@@ -8,7 +8,8 @@ Retention in Loki is achieved either through the [Table Manager](#table-manager)
 
 Retention through the [Table Manager](../table-manager/) is achieved by relying on the object store TTL feature, and will work for both [boltdb-shipper](../boltdb-shipper) store and chunk/index store. However retention through the [Compactor](../boltdb-shipper#compactor) is supported only with the [boltdb-shipper](../boltdb-shipper) store.
 
-The [Compactor](#Compactor) retention will become the default and have long term support. While this retention is still **experimental**, it supports more granular retention policies on per tenant and per stream use cases.
+<span style="background-color:#f3f973;">Retention through the [Compactor](#Compactor) is experimental.</span>
+The Compactor retention will become the default and have long term support. It supports more granular retention policies on per tenant and per stream use cases.
 
 ## Compactor
 

docs/sources/storage/_index.md

@@ -50,7 +50,7 @@ As of 2.0, this is the recommended index storage type, performance is comparable
 
 ### Cassandra
 
-Cassandra can also be utilized for the index store and aside from the experimental [boltdb-shipper](../operations/storage/boltdb-shipper/), it's the only non-cloud offering that can be used for the index that's horizontally scalable and has configurable replication. It's a good candidate when you already run Cassandra, are running on-prem, or do not wish to use a managed cloud offering.
+Cassandra can also be utilized for the index store and aside from the [boltdb-shipper](../operations/storage/boltdb-shipper/), it's the only non-cloud offering that can be used for the index that's horizontally scalable and has configurable replication. It's a good candidate when you already run Cassandra, are running on-prem, or do not wish to use a managed cloud offering.
 
 ### BigTable
 
@@ -66,7 +66,7 @@ DynamoDB is susceptible to rate limiting, particularly due to overconsuming what
 
 ### BoltDB
 
-BoltDB is an embedded database on disk. It is not replicated and thus cannot be used for high availability or clustered Loki deployments, but is commonly paired with a `filesystem` chunk store for proof of concept deployments, trying out Loki, and development. There is also an experimental mode, the [boltdb-shipper](../operations/storage/boltdb-shipper/), which aims to support clustered deployments using `boltdb` as an index.
+BoltDB is an embedded database on disk. It is not replicated and thus cannot be used for high availability or clustered Loki deployments, but is commonly paired with a `filesystem` chunk store for proof of concept deployments, trying out Loki, and development. The [boltdb-shipper](../operations/storage/boltdb-shipper/) aims to support clustered deployments using `boltdb` as an index.
 
 ## Schema Configs