Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: Make identification of experimental items consistent and obvious #3911

Merged
merged 1 commit into from
Jul 6, 2021
Merged

Docs: Make identification of experimental items consistent and obvious #3911

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions docs/sources/api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.



Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
```
Expand All @@ -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.
8 changes: 7 additions & 1 deletion docs/sources/configuration/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 = ""]
Expand Down Expand Up @@ -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>]
Expand Down
2 changes: 2 additions & 0 deletions docs/sources/logql/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions docs/sources/operations/storage/logs-deletion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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>'
```
```
3 changes: 2 additions & 1 deletion docs/sources/operations/storage/retention.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Github markdown does not support setting the background colour for text. This would only work for docs hosted on Grafana.
People reading the docs on the Github repo would see it in plain text https://github.com/grafana/loki/blob/79ed6ffdea5d66935f6adeac4abadfcc9cce3624/docs/sources/operations/storage/retention.md

There are some suggestions there to use a diff block to highlight the text in this issue github/markup#1440

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are correct. I am only doing this for hosted docs. And, this is a temporary solution. I just wanted something quick and easily removable for the upcoming 2.3.0 release.

What do you think about using this as a temporary and partial fix until we decide if there is a more permanent way of solving what I think is a readability issue, @sandeepsukhani ?

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

Expand Down
4 changes: 2 additions & 2 deletions docs/sources/storage/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down