From 13564c03efe7517841fdc4c73905b1f630bfddcc Mon Sep 17 00:00:00 2001 From: Julius Volz Date: Wed, 28 May 2025 21:37:27 +0200 Subject: [PATCH] Standardize doc page title handling See https://groups.google.com/g/prometheus-developers/c/cwL3cM66Em8 Signed-off-by: Julius Volz --- docs/command-line/prometheus.md | 3 --- docs/command-line/promtool.md | 3 --- docs/configuration/alerting_rules.md | 2 -- docs/configuration/configuration.md | 2 -- docs/configuration/https.md | 2 -- docs/configuration/recording_rules.md | 5 ++--- docs/configuration/template_examples.md | 2 -- docs/configuration/template_reference.md | 2 -- docs/configuration/unit_testing_rules.md | 4 +--- docs/feature_flags.md | 2 -- docs/federation.md | 2 -- docs/getting_started.md | 2 -- docs/http_sd.md | 7 +++---- docs/installation.md | 2 -- docs/management_api.md | 10 ++++----- docs/migration.md | 5 ++--- docs/querying/api.md | 2 -- docs/querying/basics.md | 14 ++++++------- docs/querying/examples.md | 4 +--- docs/querying/functions.md | 26 +++++++++++------------- docs/querying/operators.md | 4 +--- docs/querying/remote_read_api.md | 10 ++++----- docs/stability.md | 5 ++--- docs/storage.md | 2 -- util/documentcli/documentcli.go | 5 +---- 25 files changed, 39 insertions(+), 88 deletions(-) diff --git a/docs/command-line/prometheus.md b/docs/command-line/prometheus.md index 18a979367b..e90a7574ba 100644 --- a/docs/command-line/prometheus.md +++ b/docs/command-line/prometheus.md @@ -2,12 +2,9 @@ title: prometheus --- -# prometheus - The Prometheus monitoring server - ## Flags | Flag | Description | Default | diff --git a/docs/command-line/promtool.md b/docs/command-line/promtool.md index 3b1ca84f6b..92e0ac0030 100644 --- a/docs/command-line/promtool.md +++ b/docs/command-line/promtool.md @@ -2,12 +2,9 @@ title: promtool --- -# promtool - Tooling for the Prometheus monitoring system. - ## Flags | Flag | Description | diff --git a/docs/configuration/alerting_rules.md b/docs/configuration/alerting_rules.md index daddf71773..faffad56f2 100644 --- a/docs/configuration/alerting_rules.md +++ b/docs/configuration/alerting_rules.md @@ -3,8 +3,6 @@ title: Alerting rules sort_rank: 3 --- -# Alerting rules - Alerting rules allow you to define alert conditions based on Prometheus expression language expressions and to send notifications about firing alerts to an external service. Whenever the alert expression results in one or more diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index d1b1b752c3..58eecfa485 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -3,8 +3,6 @@ title: Configuration sort_rank: 1 --- -# Configuration - Prometheus is configured via command-line flags and a configuration file. While the command-line flags configure immutable system parameters (such as storage locations, amount of data to keep on disk and in memory, etc.), the diff --git a/docs/configuration/https.md b/docs/configuration/https.md index ba6ed0f814..9a089ca922 100644 --- a/docs/configuration/https.md +++ b/docs/configuration/https.md @@ -3,8 +3,6 @@ title: HTTPS and authentication sort_rank: 7 --- -# HTTPS and authentication - Prometheus supports basic authentication and TLS. This is **experimental** and might change in the future. diff --git a/docs/configuration/recording_rules.md b/docs/configuration/recording_rules.md index ebcb893ff5..6d668a4da3 100644 --- a/docs/configuration/recording_rules.md +++ b/docs/configuration/recording_rules.md @@ -1,10 +1,9 @@ --- -title: Recording rules +title: Defining recording rules +nav_title: Recording rules sort_rank: 2 --- -# Defining recording rules - ## Configuring rules Prometheus supports two types of rules which may be configured and then diff --git a/docs/configuration/template_examples.md b/docs/configuration/template_examples.md index 2d12fb7129..bd076b256e 100644 --- a/docs/configuration/template_examples.md +++ b/docs/configuration/template_examples.md @@ -3,8 +3,6 @@ title: Template examples sort_rank: 4 --- -# Template examples - Prometheus supports templating in the annotations and labels of alerts, as well as in served console pages. Templates have the ability to run queries against the local database, iterate over data, use conditionals, diff --git a/docs/configuration/template_reference.md b/docs/configuration/template_reference.md index 91920ae6a8..57f2606b13 100644 --- a/docs/configuration/template_reference.md +++ b/docs/configuration/template_reference.md @@ -3,8 +3,6 @@ title: Template reference sort_rank: 5 --- -# Template reference - Prometheus supports templating in the annotations and labels of alerts, as well as in served console pages. Templates have the ability to run queries against the local database, iterate over data, use conditionals, diff --git a/docs/configuration/unit_testing_rules.md b/docs/configuration/unit_testing_rules.md index ccf1961f48..7522951fdf 100644 --- a/docs/configuration/unit_testing_rules.md +++ b/docs/configuration/unit_testing_rules.md @@ -1,10 +1,8 @@ --- -title: Unit Testing for Rules +title: Unit testing for rules sort_rank: 6 --- -# Unit Testing for Rules - You can use `promtool` to test your rules. ```shell diff --git a/docs/feature_flags.md b/docs/feature_flags.md index 5a7ad75f43..ff6883e033 100644 --- a/docs/feature_flags.md +++ b/docs/feature_flags.md @@ -3,8 +3,6 @@ title: Feature flags sort_rank: 12 --- -# Feature flags - Here is a list of features that are disabled by default since they are breaking changes or are considered experimental. Their behaviour can change in future releases which will be communicated via the [release changelog](https://github.com/prometheus/prometheus/blob/main/CHANGELOG.md). diff --git a/docs/federation.md b/docs/federation.md index 3344a0ed05..580fa30874 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -3,8 +3,6 @@ title: Federation sort_rank: 6 --- -# Federation - Federation allows a Prometheus server to scrape selected time series from another Prometheus server. diff --git a/docs/getting_started.md b/docs/getting_started.md index 012c4fd240..aeba295da8 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -3,8 +3,6 @@ title: Getting started sort_rank: 1 --- -# Getting started - This guide is a "Hello World"-style tutorial which shows how to install, configure, and use a simple Prometheus instance. You will download and run Prometheus locally, configure it to scrape itself and an example application, diff --git a/docs/http_sd.md b/docs/http_sd.md index aadc488738..3bd6bada39 100644 --- a/docs/http_sd.md +++ b/docs/http_sd.md @@ -1,10 +1,9 @@ --- -title: HTTP SD +title: Writing HTTP service discovery +nav_title: HTTP SD sort_rank: 7 --- -# Writing HTTP Service Discovery - Prometheus provides a generic [HTTP Service Discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config), that enables it to discover targets over an HTTP endpoint. @@ -40,7 +39,7 @@ an empty list `[]`. Target lists are unordered. Prometheus caches target lists. If an error occurs while fetching an updated targets list, Prometheus keeps using the current targets list. The targets list -is not saved across restart. The `prometheus_sd_http_failures_total` counter +is not saved across restart. The `prometheus_sd_http_failures_total` counter metric tracks the number of refresh failures. The whole list of targets must be returned on every scrape. There is no support diff --git a/docs/installation.md b/docs/installation.md index c8e359e780..fbab67a59d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,8 +3,6 @@ title: Installation sort_rank: 2 --- -# Installation - ## Using pre-compiled binaries We provide precompiled binaries for most official Prometheus components. Check diff --git a/docs/management_api.md b/docs/management_api.md index 0b496cbaa7..ecc46fad88 100644 --- a/docs/management_api.md +++ b/docs/management_api.md @@ -3,12 +3,10 @@ title: Management API sort_rank: 8 --- -# Management API - Prometheus provides a set of management APIs to facilitate automation and integration. -### Health check +## Health check ``` GET /-/healthy @@ -18,7 +16,7 @@ HEAD /-/healthy This endpoint always returns 200 and should be used to check Prometheus health. -### Readiness check +## Readiness check ``` GET /-/ready @@ -28,7 +26,7 @@ HEAD /-/ready This endpoint returns 200 when Prometheus is ready to serve traffic (i.e. respond to queries). -### Reload +## Reload ``` PUT /-/reload @@ -40,7 +38,7 @@ This endpoint triggers a reload of the Prometheus configuration and rule files. Alternatively, a configuration reload can be triggered by sending a `SIGHUP` to the Prometheus process. -### Quit +## Quit ``` PUT /-/quit diff --git a/docs/migration.md b/docs/migration.md index e06741bcec..55e366456d 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,10 +1,9 @@ --- -title: Migration +title: Prometheus 3.0 migration guide +nav_title: Migration sort_rank: 10 --- -# Prometheus 3.0 migration guide - In line with our [stability promise](https://prometheus.io/docs/prometheus/latest/stability/), the Prometheus 3.0 release contains a number of backwards incompatible changes. This document offers guidance on migrating from Prometheus 2.x to Prometheus 3.0 and newer versions. diff --git a/docs/querying/api.md b/docs/querying/api.md index 0bfaa63b0f..a17bd1e3a2 100644 --- a/docs/querying/api.md +++ b/docs/querying/api.md @@ -3,8 +3,6 @@ title: HTTP API sort_rank: 7 --- -# HTTP API - The current stable HTTP API is reachable under `/api/v1` on a Prometheus server. Any non-breaking additions will be added under that endpoint. diff --git a/docs/querying/basics.md b/docs/querying/basics.md index 8fc86bc230..ba915854cb 100644 --- a/docs/querying/basics.md +++ b/docs/querying/basics.md @@ -4,11 +4,9 @@ nav_title: Basics sort_rank: 1 --- -# Querying Prometheus - Prometheus provides a functional query language called PromQL (Prometheus Query Language) that lets the user select and aggregate time series data in real -time. +time. When you send a query request to Prometheus, it can be an _instant query_, evaluated at one point in time, or a _range query_ at equally-spaced steps between a start and an end time. PromQL works exactly the same @@ -35,7 +33,7 @@ evaluate to one of four types: Depending on the use-case (e.g. when graphing vs. displaying the output of an expression), only some of these types are legal as the result of a -user-specified expression. +user-specified expression. For [instant queries](api.md#instant-queries), any of the above data types are allowed as the root of the expression. [Range queries](api.md#range-queries) only support scalar-typed and instant-vector-typed expressions. @@ -217,7 +215,7 @@ and would exclude: http_requests_total{environment="development"} -Multiple matchers can be used for the same label name; they all must pass for a result to be returned. +Multiple matchers can be used for the same label name; they all must pass for a result to be returned. The query: @@ -307,7 +305,7 @@ Note that this allows a query to look ahead of its evaluation time. The `@` modifier allows changing the evaluation time for individual instant and range vectors in a query. The time supplied to the `@` modifier -is a unix timestamp and described with a float literal. +is a unix timestamp and described with a float literal. For example, the following expression returns the value of `http_requests_total` at `2021-01-04T07:40:00+00:00`: @@ -403,11 +401,11 @@ as stale, then no value is returned for that time series. If new samples are subsequently ingested for that time series, they will be returned as expected. A time series will go stale when it is no longer exported, or the target no -longer exists. Such time series will disappear from graphs +longer exists. Such time series will disappear from graphs at the times of their latest collected sample, and they will not be returned in queries after they are marked stale. -Some exporters, which put their own timestamps on samples, get a different behaviour: +Some exporters, which put their own timestamps on samples, get a different behaviour: series that stop being exported take the last value for (by default) 5 minutes before disappearing. The `track_timestamps_staleness` setting can change this. diff --git a/docs/querying/examples.md b/docs/querying/examples.md index 1879a9945c..a732334a95 100644 --- a/docs/querying/examples.md +++ b/docs/querying/examples.md @@ -1,11 +1,9 @@ --- -title: Querying examples +title: Query examples nav_title: Examples sort_rank: 4 --- -# Query examples - ## Simple time series selection Return all time series with the metric `http_requests_total`: diff --git a/docs/querying/functions.md b/docs/querying/functions.md index 40cc697055..4a141b9220 100644 --- a/docs/querying/functions.md +++ b/docs/querying/functions.md @@ -4,8 +4,6 @@ nav_title: Functions sort_rank: 3 --- -# Functions - Some functions have default arguments, e.g. `year(v=vector(time()) instant-vector)`. This means that there is one argument `v` which is an instant vector, which if not provided it will default to the value of the expression @@ -121,7 +119,7 @@ of the week (in UTC) for each of those timestamps. Returned values are from 0 to 6, where 0 means Sunday etc. Histogram samples in the input vector are ignored silently. -## `day_of_year()` +## `day_of_year()` `day_of_year(v=vector(time()) instant-vector)` interpretes float samples in `v` as timestamps (number of seconds since January 1, 1970 UTC) and returns the day @@ -255,9 +253,9 @@ histogram samples: `histogram_fraction(lower scalar, upper scalar, b instant-vector)` returns the estimated fraction of observations between the provided lower and upper values -for each classic or native histogram contained in `b`. Float samples in `b` are +for each classic or native histogram contained in `b`. Float samples in `b` are considered the counts of observations in each bucket of one or more classic -histograms, while native histogram samples in `b` are treated each individually +histograms, while native histogram samples in `b` are treated each individually as a separate histogram. This works in the same way as for `histogram_quantile()`. (See there for more details.) @@ -273,7 +271,7 @@ as a typical example. For example, the following expression calculates the fraction of HTTP requests over the last hour that took 200ms or less: - + histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h])) The error of the estimation depends on the resolution of the underlying native @@ -345,7 +343,7 @@ included in the `by` clause. The following expression aggregates the 90th percentile by `job` for classic histograms: histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m]))) - + When aggregating native histograms, the expression simplifies to: histogram_quantile(0.9, sum by (job) (rate(http_request_duration_seconds[10m]))) @@ -429,7 +427,7 @@ annotation, you should find and remove the source of the invalid data. `histogram_stddev(v instant-vector)` returns the estimated standard deviation of observations for each histogram sample in `v`. For this estimation, all observations -in a bucket are assumed to have the value of the mean of the bucket boundaries. For +in a bucket are assumed to have the value of the mean of the bucket boundaries. For the zero bucket and for buckets with custom boundaries, the arithmetic mean is used. For the usual exponential buckets, the geometric mean is used. Float samples are ignored and do not show up in the returned vector. @@ -489,10 +487,10 @@ consistently on a per-second basis. _The `info` function is an experiment to improve UX around including labels from [info metrics](https://grafana.com/blog/2021/08/04/how-to-use-promql-joins-for-more-effective-queries-of-prometheus-metrics-at-scale/#info-metrics). The behavior of this function may change in future versions of Prometheus, -including its removal from PromQL. `info` has to be enabled via the +including its removal from PromQL. `info` has to be enabled via the [feature flag](../feature_flags.md#experimental-promql-functions) `--enable-feature=promql-experimental-functions`._ -`info(v instant-vector, [data-label-selector instant-vector])` finds, for each time +`info(v instant-vector, [data-label-selector instant-vector])` finds, for each time series in `v`, all info series with matching _identifying_ labels (more on this later), and adds the union of their _data_ (i.e., non-identifying) labels to the time series. The second argument `data-label-selector` is optional. @@ -509,8 +507,8 @@ function, we “logically” define info series identity in a different way than in the conventional Prometheus view.) The identifying labels of an info series are used to join it to regular (non-info) series, i.e. those series that have the same labels as the identifying labels of the info series. The data labels, which are -the ones added to the regular series by the `info` function, effectively encode -metadata key value pairs. (This implies that a change in the data labels +the ones added to the regular series by the `info` function, effectively encode +metadata key value pairs. (This implies that a change in the data labels in the conventional Prometheus view constitutes the end of one info series and the beginning of a new info series, while the “logical” view of the `info` function is that the same info series continues to exist, just with different “data”.) @@ -534,7 +532,7 @@ This query is not only verbose and hard to write, it might also run into an “i If any of the data labels of `target_info` changes, Prometheus sees that as a change of series (as alluded to above, Prometheus just has no native concept of non-identifying labels). If the old `target_info` series is not properly marked as stale (which can happen with certain ingestion paths), -the query above will fail for up to 5m (the lookback delta) because it will find a conflicting +the query above will fail for up to 5m (the lookback delta) because it will find a conflicting match with both the old and the new version of `target_info`. The `info` function not only resolves this conflict in favor of the newer series, it also simplifies the syntax @@ -565,7 +563,7 @@ restrict them by providing a `__name__` label matcher, e.g. In its current iteration, `info` defaults to considering only info series with the name `target_info`. It also assumes that the identifying info series labels are `instance` and `job`. `info` does support other info series names however, through -`__name__` label matchers. E.g., one can explicitly say to consider both +`__name__` label matchers. E.g., one can explicitly say to consider both `target_info` and `build_info` as follows: `{__name__=~"(target|build)_info"}`. However, the identifying labels always have to be `instance` and `job`. diff --git a/docs/querying/operators.md b/docs/querying/operators.md index ab36c57185..5e4f127b86 100644 --- a/docs/querying/operators.md +++ b/docs/querying/operators.md @@ -3,8 +3,6 @@ title: Operators sort_rank: 2 --- -# Operators - ## Binary operators Prometheus's query language supports basic logical and arithmetic operators. @@ -319,7 +317,7 @@ the input samples, including the original labels, are returned in the result vector. `by` and `without` are only used to bucket the input vector. Similar to `min` and `max`, they only operate on float samples, considering `NaN` values to be farthest from the top or bottom, respectively. Histogram samples in the -input vector are ignored, flagged by an info-level annotation. +input vector are ignored, flagged by an info-level annotation. If used in an instant query, `topk` and `bottomk` return series ordered by value in descending or ascending order, respectively. If used with `by` or diff --git a/docs/querying/remote_read_api.md b/docs/querying/remote_read_api.md index 76de112342..1930e1fbae 100644 --- a/docs/querying/remote_read_api.md +++ b/docs/querying/remote_read_api.md @@ -3,9 +3,7 @@ title: Remote Read API sort_rank: 7 --- -# Remote Read API - -> This is not currently considered part of the stable API and is subject to change even between non-major version releases of Prometheus. +NOTE: This is not currently considered part of the stable API and is subject to change even between non-major version releases of Prometheus. This API provides data read functionality from Prometheus. This interface expects [snappy](https://github.com/google/snappy) compression. The API definition is located [here](https://github.com/prometheus/prometheus/blob/master/prompb/remote.proto). @@ -15,12 +13,12 @@ Request are made to the following endpoint. /api/v1/read ``` -### Samples +## Samples -This returns a message that includes a list of raw samples matching the +This returns a message that includes a list of raw samples matching the requested query. -### Streamed Chunks +## Streamed Chunks These streamed chunks utilize an XOR algorithm inspired by the [Gorilla](http://www.vldb.org/pvldb/vol8/p1816-teller.pdf) compression to encode the chunks. However, it provides resolution to the millisecond instead of to the second. diff --git a/docs/stability.md b/docs/stability.md index cb30b8ad99..82974f8f70 100644 --- a/docs/stability.md +++ b/docs/stability.md @@ -1,10 +1,9 @@ --- -title: API Stability +title: API stability guarantees +nav_title: API stability sort_rank: 11 --- -# API Stability Guarantees - Prometheus promises API stability within a major version, and strives to avoid breaking changes for key features. Some features, which are cosmetic, still under development, or depend on 3rd party services, are not covered by this. diff --git a/docs/storage.md b/docs/storage.md index e04ce027bf..f472cce140 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -3,8 +3,6 @@ title: Storage sort_rank: 5 --- -# Storage - Prometheus includes a local on-disk time series database, but also optionally integrates with remote storage systems. ## Local storage diff --git a/util/documentcli/documentcli.go b/util/documentcli/documentcli.go index f324afa3d6..42d96580a8 100644 --- a/util/documentcli/documentcli.go +++ b/util/documentcli/documentcli.go @@ -58,11 +58,8 @@ func header(title, help string) []byte { title: %s --- -# %s - %s - -`, title, title, help)) +`, title, help)) } func createFlagRow(flag *kingpin.FlagModel) []string {