diff --git a/docs/concepts/data_model.md b/docs/concepts/data_model.md index 6fa583b0..0a3af509 100644 --- a/docs/concepts/data_model.md +++ b/docs/concepts/data_model.md @@ -17,9 +17,9 @@ Every time series is uniquely identified by its metric name and optional key-val ***Metric names:*** -* Metric names SHOULD specify the general feature of a system that is measured (e.g. `http_requests_total` - the total number of HTTP requests received). +* Metric names SHOULD specify the general feature of a system that is measured (e.g. `http_requests_total` - the total number of HTTP requests received). * Metric names MAY use any UTF-8 characters. -* Metric names SHOULD match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*` for the best experience and compatibility (see the warning below). Metric names outside of that set will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8.md#querying)). +* Metric names SHOULD match the regex `[a-zA-Z_:][a-zA-Z0-9_:]*` for the best experience and compatibility (see the warning below). Metric names outside of that set will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8#querying)). NOTE: Colons (':') are reserved for user-defined recording rules. They SHOULD NOT be used by exporters or direct instrumentation. @@ -27,13 +27,13 @@ NOTE: Colons (':') are reserved for user-defined recording rules. They SHOULD NO Labels let you capture different instances of the same metric name. For example: all HTTP requests that used the method `POST` to the `/api/tracks` handler. We refer to this as Prometheus's "dimensional data model". The query language allows filtering and aggregation based on these dimensions. The change of any label's value, including adding or removing labels, will create a new time series. -* Label names MAY use any UTF-8 characters. +* Label names MAY use any UTF-8 characters. * Label names beginning with `__` (two underscores) MUST be reserved for internal Prometheus use. -* Label names SHOULD match the regex `[a-zA-Z_][a-zA-Z0-9_]*` for the best experience and compatibility (see the warning below). Label names outside of that regex will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8.md#querying)). +* Label names SHOULD match the regex `[a-zA-Z_][a-zA-Z0-9_]*` for the best experience and compatibility (see the warning below). Label names outside of that regex will require quoting e.g. when used in PromQL (see the [UTF-8 guide](../guides/utf8#querying)). * Label values MAY contain any UTF-8 characters. * Labels with an empty label value are considered equivalent to labels that do not exist. -WARNING: The [UTF-8](../guides/utf8.md) support for metric and label names was added relatively recently in Prometheus v3.0.0. It might take time for the wider ecosystem (downstream PromQL compatible projects and vendors, tooling, third-party instrumentation, collectors, etc.) to adopt new quoting mechanisms, relaxed validation etc. For the best compatibility it's recommended to stick to the recommended ("SHOULD") character set. +WARNING: The [UTF-8](../guides/utf8) support for metric and label names was added relatively recently in Prometheus v3.0.0. It might take time for the wider ecosystem (downstream PromQL compatible projects and vendors, tooling, third-party instrumentation, collectors, etc.) to adopt new quoting mechanisms, relaxed validation etc. For the best compatibility it's recommended to stick to the recommended ("SHOULD") character set. INFO: See also the [best practices for naming metrics and labels](/docs/practices/naming/). diff --git a/docs/specs/native_histograms.md b/docs/specs/native_histograms.md index 4d91e3ca..1726a0ae 100644 --- a/docs/specs/native_histograms.md +++ b/docs/specs/native_histograms.md @@ -1,6 +1,6 @@ --- title: Native Histograms [EXPERIMENTAL] -sort_rank: 2 +sort_rank: 1 --- # Native Histograms diff --git a/docs/specs/om/index.md b/docs/specs/om/index.md index 8cab4af1..7a121d6d 100644 --- a/docs/specs/om/index.md +++ b/docs/specs/om/index.md @@ -1,4 +1,4 @@ --- title: "OpenMetrics" -sort_rank: 3 +sort_rank: 2 --- diff --git a/docs/specs/om/open_metrics_spec.md b/docs/specs/om/open_metrics_spec.md index 8ed717aa..15cc996e 100644 --- a/docs/specs/om/open_metrics_spec.md +++ b/docs/specs/om/open_metrics_spec.md @@ -1,7 +1,7 @@ --- -title: "1.0" -title_prefix: "OpenMetrics 1.0" -sort_rank: 5 +title: "OpenMetrics 1.0" +nav_title: "1.0" +sort_rank: 1 author: - role: editor @@ -391,9 +391,9 @@ UTF-8 MUST be used. Byte order markers (BOMs) MUST NOT be used. As an important The content type MUST be: -``` +``` application/openmetrics-text; version=1.0.0; charset=utf-8 -``` +``` Line endings MUST be signalled with line feed (\n) and MUST NOT contain carriage returns (\r). Expositions MUST end with EOF and SHOULD end with `EOF\n`. diff --git a/docs/specs/om/open_metrics_spec_2_0.md b/docs/specs/om/open_metrics_spec_2_0.md index bc8b9838..6b2a9997 100644 --- a/docs/specs/om/open_metrics_spec_2_0.md +++ b/docs/specs/om/open_metrics_spec_2_0.md @@ -1,9 +1,9 @@ --- -title: "2.0" -title_prefix: "OpenMetrics 2.0" -sort_rank: 10 +title: "OpenMetrics 2.0" +nav_title: "2.0" +sort_rank: 2 -is_hidden: true +hide_in_nav: true author: - role: editor @@ -393,9 +393,9 @@ UTF-8 MUST be used. Byte order markers (BOMs) MUST NOT be used. As an important The content type MUST be: -``` +``` application/openmetrics-text; version=1.0.0; charset=utf-8 -``` +``` Line endings MUST be signalled with line feed (\n) and MUST NOT contain carriage returns (\r). Expositions MUST end with EOF and SHOULD end with `EOF\n`. diff --git a/docs/specs/prw/index.md b/docs/specs/prw/index.md index 3a800945..0e87c7f8 100644 --- a/docs/specs/prw/index.md +++ b/docs/specs/prw/index.md @@ -1,4 +1,4 @@ --- title: "Remote Write" -sort_rank: 4 +sort_rank: 3 --- diff --git a/docs/specs/prw/remote_write_spec.md b/docs/specs/prw/remote_write_spec.md index 18cedc01..7a9fd20b 100644 --- a/docs/specs/prw/remote_write_spec.md +++ b/docs/specs/prw/remote_write_spec.md @@ -1,7 +1,7 @@ --- -title: "1.0" -title_prefix: "Remote Write 1.0" -sort_rank: 5 +title: "Remote Write 1.0" +nav_title: "1.0" +sort_rank: 1 --- # Prometheus Remote-Write Specification @@ -16,7 +16,7 @@ The remote write specification is intended to document the standard for how Prom The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). -> NOTE: This specification has a 2.0 version available, see [here](./remote_write_spec_2_0.md). +> NOTE: This specification has a 2.0 version available, see [here](./remote_write_spec_2_0). ## Introduction ### Background @@ -158,7 +158,7 @@ This document does not intend to explain all the features required for a fully P **HTTP Path** The path for HTTP handler can be anything - and MUST be provided by the sender. Generally we expect the whole URL to be specified in config. -**Persistence** It is recommended that Prometheus Remote Write compatible senders should persistently buffer sample data in the event of outages in the receiver. +**Persistence** It is recommended that Prometheus Remote Write compatible senders should persistently buffer sample data in the event of outages in the receiver. **Authentication & Encryption** as remote write uses HTTP, we consider authentication & encryption to be a transport-layer problem. Senders and receivers should support all the usual suspects (Basic auth, TLS etc) and are free to add potentially custom authentication options. Support for custom authentication in the Prometheus remote write sender and eventual agent should not be assumed, but we will endeavour to support common and widely used auth protocols, where feasible. diff --git a/docs/specs/prw/remote_write_spec_2_0.md b/docs/specs/prw/remote_write_spec_2_0.md index d224ad2c..9df7bb5b 100644 --- a/docs/specs/prw/remote_write_spec_2_0.md +++ b/docs/specs/prw/remote_write_spec_2_0.md @@ -1,7 +1,7 @@ --- -title: "2.0 [EXPERIMENTAL]" -title_prefix: "Remote Write 2.0" -sort_rank: 4 +title: "Remote Write 2.0 [EXPERIMENTAL]" +nav_title: "2.0" +sort_rank: 2 --- # Prometheus Remote-Write Specification @@ -60,7 +60,7 @@ Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-p --> The protobuf serialization MUST use either of the following Protobuf Messages: -* The `prometheus.WriteRequest` introduced in [the Remote-Write 1.0 specification](./remote_write_spec.md#protocol). As of 2.0, this message is deprecated. It SHOULD be used only for compatibility reasons. Senders and Receivers MAY NOT support the `prometheus.WriteRequest`. +* The `prometheus.WriteRequest` introduced in [the Remote-Write 1.0 specification](./remote_write_spec#protocol). As of 2.0, this message is deprecated. It SHOULD be used only for compatibility reasons. Senders and Receivers MAY NOT support the `prometheus.WriteRequest`. * The `io.prometheus.write.v2.Request` introduced in this specification and defined [below](#protobuf-message). Senders and Receivers SHOULD use this message when possible. Senders and Receivers MUST support the `io.prometheus.write.v2.Request`. Protobuf Message MUST use binary Wire Format. Then, MUST be compressed with [Google’s Snappy](https://github.com/google/snappy). Snappy's [block format](https://github.com/google/snappy/blob/2c94e11145f0b7b184b831577c93e5a41c4c0346/format_description.txt) MUST be used -- [the framed format](https://github.com/google/snappy/blob/2c94e11145f0b7b184b831577c93e5a41c4c0346/framing_format.txt) MUST NOT be used. @@ -448,11 +448,11 @@ Rationales: https://github.com/prometheus/proposals/blob/alexg/remote-write-20-p ## Out of Scope -The same as in [1.0](./remote_write_spec.md#out-of-scope). +The same as in [1.0](./remote_write_spec#out-of-scope). ## Future Plans -This section contains speculative plans that are not considered part of protocol specification yet but are mentioned here for completeness. Note that 2.0 specification completed [2 of 3 future plans in the 1.0](./remote_write_spec.md#future-plans). +This section contains speculative plans that are not considered part of protocol specification yet but are mentioned here for completeness. Note that 2.0 specification completed [2 of 3 future plans in the 1.0](./remote_write_spec#future-plans). * **Transactionality** There is still no transactionality defined for 2.0 specification, mostly because it makes a scalable Sender implementation difficult. Prometheus Sender aims at being "transactional" - i.e. to never expose a partially scraped target to a query. We intend to do the same with Remote-Write -- for instance, in the future we would like to "align" Remote-Write with scrapes, perhaps such that all the samples, metadata and exemplars for a single scrape are sent in a single Remote-Write request. @@ -467,7 +467,7 @@ This section contains speculative plans that are not considered part of protocol ### FAQ **Why did you not use gRPC?** -Because the 1.0 protocol does not use gRPC, breaking it would increase friction in the adoption. See 1.0 [reason](./remote_write_spec.md#faq). +Because the 1.0 protocol does not use gRPC, breaking it would increase friction in the adoption. See 1.0 [reason](./remote_write_spec#faq). **Why not stream protobuf messages?** If you use persistent HTTP/1.1 connections, they are pretty close to streaming. Of course, headers have to be re-sent, but that is less expensive than a new TCP set up. @@ -481,4 +481,4 @@ Samples must be in-order _for a given series_. However, even if a Receiver does **What are the differences between Remote-Write 2.0 and OpenTelemetry's OTLP protocol?** [OpenTelemetry OTLP](https://github.com/open-telemetry/opentelemetry-proto/blob/a05597bff803d3d9405fcdd1e1fb1f42bed4eb7a/docs/specification.md) is a protocol for transporting of telemetry data (such as metrics, logs, traces and profiles) between telemetry sources, intermediate nodes and telemetry backends. The recommended transport involves gRPC with protobuf, but HTTP with protobuf or JSON are also described. It was designed from scratch with the intent to support a variety of different observability signals, data types and extra information. For [metrics](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/metrics/v1/metrics.proto) that means additional non-identifying labels, flags, temporal aggregations types, resource or scoped metrics, schema URLs and more. OTLP also requires [the semantic convention](https://opentelemetry.io/docs/concepts/semantic-conventions/) to be used. -Remote-Write was designed for simplicity, efficiency and organic growth. The first version was officially released in 2023, when already [dozens of battle-tested adopters in the CNCF ecosystem](./remote_write_spec.md#compatible-senders-and-receivers) had been using this protocol for years. Remote-Write 2.0 iterates on the previous protocol by adding a few new elements (metadata, exemplars, created timestamp and native histograms) and string interning. Remote-Write 2.0 is always stateless, focuses only on metrics and is opinionated; as such it is scoped down to elements that the Prometheus community considers enough to have a robust metric solution. The intention is to ensure the Remote-Write is a stable protocol that is cheaper and simpler to adopt and use than the alternatives in the observability ecosystem. +Remote-Write was designed for simplicity, efficiency and organic growth. The first version was officially released in 2023, when already [dozens of battle-tested adopters in the CNCF ecosystem](./remote_write_spec#compatible-senders-and-receivers) had been using this protocol for years. Remote-Write 2.0 iterates on the previous protocol by adding a few new elements (metadata, exemplars, created timestamp and native histograms) and string interning. Remote-Write 2.0 is always stateless, focuses only on metrics and is opinionated; as such it is scoped down to elements that the Prometheus community considers enough to have a robust metric solution. The intention is to ensure the Remote-Write is a stable protocol that is cheaper and simpler to adopt and use than the alternatives in the observability ecosystem. diff --git a/scripts/fetch-repo-docs.ts b/scripts/fetch-repo-docs.ts index 7bba60d0..cb238f7a 100644 --- a/scripts/fetch-repo-docs.ts +++ b/scripts/fetch-repo-docs.ts @@ -201,7 +201,12 @@ const fetchRepoDocs = async ({ console.log("Found Markdown file:", filePath); const { - data: { title, nav_title: navTitle, sort_rank: sortRank }, + data: { + title, + nav_title: navTitle, + sort_rank: sortRank, + hide_in_nav: hideInNav, + }, } = matter(fs.readFileSync(file, "utf-8")); if (!title) { @@ -234,6 +239,7 @@ const fetchRepoDocs = async ({ title, navTitle, sortRank: sortRank ?? 0, + hideInNav, children: [], }; @@ -277,7 +283,13 @@ for (const sourceConfig of docsConfig.localMarkdownSources) { const filePath = path.relative(docsDir, file); const { - data: { title, sort_rank: sortRank, nav_icon: navIcon }, + data: { + title, + nav_title: navTitle, + sort_rank: sortRank, + nav_icon: navIcon, + hide_in_nav: hideInNav, + }, } = matter(fs.readFileSync(file, "utf-8")); if (!title) { throw new Error(`Missing title in ${file}`); @@ -301,8 +313,10 @@ for (const sourceConfig of docsConfig.localMarkdownSources) { slug, filePath: file, title, + navTitle, sortRank: sortRank ?? 0, navIcon, + hideInNav, children: [], }; } diff --git a/src/app/docs/layout.tsx b/src/app/docs/layout.tsx index d510f6d8..f8015162 100644 --- a/src/app/docs/layout.tsx +++ b/src/app/docs/layout.tsx @@ -93,6 +93,10 @@ function buildRecursiveNav( : null; const shownChildren = doc.children.filter((child) => { + if (child.hideInNav) { + return false; + } + // Always show unversioned local docs in the nav. if (child.type === "local-doc") { return true; @@ -135,7 +139,7 @@ function buildRecursiveNav( defaultOpened={active || undefined} key={doc.slug} href="#required-for-focus" - label={doc.title} + label={doc.navTitle ?? doc.title} // We offset the children, but we do it manually via a mix of margin and padding // to position the left-hand-side border on the first level correctly. childrenOffset={0} @@ -207,7 +211,7 @@ function buildRecursiveNav( variant="light" component={Link} key={doc.slug} - label={doc.title} + label={doc.navTitle ?? doc.title} href={`/docs/${doc.slug}`} style={{ borderRadius: 2.5 }} /> @@ -282,7 +286,6 @@ export default function DocsLayout({ } } - // TODO: Handle hideInNav. const nav = buildRecursiveNav(getDocsRoots(), pageSlug, router); return (