From 90504ed63803aa17f8a9fab67bde21364f880fc2 Mon Sep 17 00:00:00 2001 From: Julius Volz Date: Fri, 9 May 2025 07:52:50 +0200 Subject: [PATCH] Initial docs site commit Signed-off-by: Julius Volz --- .gitignore | 3 + .vscode/settings.json | 3 + docs-config.ts | 34 + docs/alerting/index.md | 5 + docs/concepts/data_model.md | 71 + docs/concepts/index.md | 5 + docs/concepts/jobs_instances.md | 52 + docs/concepts/metric_types.md | 122 + docs/guides/basic-auth.md | 111 + docs/guides/cadvisor.md | 125 + docs/guides/dockerswarm.md | 230 ++ docs/guides/file-sd.md | 126 + docs/guides/go-application.md | 131 + docs/guides/index.md | 5 + docs/guides/multi-target-exporter.md | 499 +++ docs/guides/node-exporter.md | 109 + docs/guides/opentelemetry.md | 170 + docs/guides/query-log.md | 173 + docs/guides/tls-encryption.md | 80 + docs/guides/utf8.md | 122 + docs/instrumenting/clientlibs.md | 55 + docs/instrumenting/exporters.md | 354 ++ docs/instrumenting/exposition_formats.md | 182 + docs/instrumenting/index.md | 5 + docs/instrumenting/pushing.md | 27 + docs/instrumenting/writing_clientlibs.md | 408 ++ docs/instrumenting/writing_exporters.md | 534 +++ docs/introduction/comparison.md | 283 ++ docs/introduction/design-doc.md | 25 + docs/introduction/faq.md | 202 + docs/introduction/first_steps.md | 130 + docs/introduction/glossary.md | 134 + docs/introduction/index.md | 5 + docs/introduction/media.md | 59 + docs/introduction/overview.md | 92 + docs/introduction/release-cycle.md | 58 + docs/introduction/roadmap.md | 42 + docs/operating/index.md | 5 + docs/operating/integrations.md | 126 + docs/operating/security.md | 279 ++ docs/practices/alerting.md | 78 + docs/practices/consoles.md | 39 + docs/practices/histograms.md | 239 ++ docs/practices/index.md | 5 + docs/practices/instrumentation.md | 267 ++ docs/practices/naming.md | 119 + docs/practices/pushing.md | 58 + docs/practices/remote_write.md | 118 + docs/practices/rules.md | 129 + docs/prometheus/index.md | 5 + docs/specs/index.md | 5 + docs/specs/native_histograms.md | 2421 +++++++++++ docs/specs/om/index.md | 4 + docs/specs/om/open_metrics_spec.md | 1186 ++++++ docs/specs/om/open_metrics_spec_2_0.md | 1188 ++++++ docs/specs/prw/index.md | 4 + docs/specs/prw/remote_write_spec.md | 219 + docs/specs/prw/remote_write_spec_2_0.md | 484 +++ docs/tutorials/alerting_based_on_metrics.md | 86 + docs/tutorials/getting_started.md | 104 + docs/tutorials/index.md | 5 + .../instrumenting_http_server_in_go.md | 146 + docs/tutorials/understanding_metric_types.md | 100 + .../visualizing_metrics_using_grafana.md | 43 + docs/visualization/browser.md | 12 + docs/visualization/consoles.md | 176 + docs/visualization/grafana.md | 73 + docs/visualization/index.md | 5 + eslint.config.mjs | 5 + next.config.ts | 8 +- package-lock.json | 3651 ++++++++++++++++- package.json | 30 +- postcss.config.cjs | 14 + public/assets/company-logos/Amadeus.png | Bin 0 -> 38817 bytes public/assets/company-logos/Argus.png | Bin 0 -> 6132 bytes public/assets/company-logos/Boxever.png | Bin 0 -> 2228 bytes public/assets/company-logos/CoreOS.png | Bin 0 -> 2743 bytes public/assets/company-logos/Docker.png | Bin 0 -> 3364 bytes public/assets/company-logos/Ericsson.png | Bin 0 -> 6403 bytes public/assets/company-logos/Eurotech.png | Bin 0 -> 5959 bytes public/assets/company-logos/Fosdem.png | Bin 0 -> 9922 bytes public/assets/company-logos/FreshTracks.png | Bin 0 -> 6386 bytes public/assets/company-logos/Improbable.png | Bin 0 -> 1487 bytes public/assets/company-logos/Jodel.png | Bin 0 -> 2844 bytes public/assets/company-logos/JustWatch.png | Bin 0 -> 1707 bytes public/assets/company-logos/Kubermatic.png | Bin 0 -> 8654 bytes public/assets/company-logos/Kumina.png | Bin 0 -> 5938 bytes public/assets/company-logos/MOIA.png | Bin 0 -> 92103 bytes .../assets/company-logos/MavenSecurities.png | Bin 0 -> 2868 bytes public/assets/company-logos/Outbrain.png | Bin 0 -> 2064 bytes public/assets/company-logos/Qaware.png | Bin 0 -> 19284 bytes .../assets/company-logos/RobustPerception.png | Bin 0 -> 4554 bytes public/assets/company-logos/Showmax.png | Bin 0 -> 2159 bytes public/assets/company-logos/Spacenet.png | Bin 0 -> 23218 bytes public/assets/company-logos/Sysdig.png | Bin 0 -> 4139 bytes public/assets/company-logos/ayedo.png | Bin 0 -> 50368 bytes public/assets/company-logos/cesanta.png | Bin 0 -> 12988 bytes public/assets/company-logos/crononauta.png | Bin 0 -> 5519 bytes public/assets/company-logos/digitalocean.png | Bin 0 -> 1887 bytes public/assets/company-logos/ecobee.png | Bin 0 -> 3160 bytes public/assets/company-logos/giantswarm.png | Bin 0 -> 14150 bytes public/assets/company-logos/grafana.png | Bin 0 -> 23114 bytes public/assets/company-logos/mixpanel.png | Bin 0 -> 4622 bytes public/assets/company-logos/pingcap.png | Bin 0 -> 33356 bytes public/assets/company-logos/quobyte.png | Bin 0 -> 2157 bytes public/assets/company-logos/shuttlecloud.png | Bin 0 -> 7669 bytes public/assets/company-logos/soundcloud.png | Bin 0 -> 3254 bytes public/assets/company-logos/transloadit.png | Bin 0 -> 3999 bytes public/assets/company-logos/unosoft.png | Bin 0 -> 4723 bytes public/assets/company-logos/weave.png | Bin 0 -> 4233 bytes public/repo-docs-assets | 1 + scripts/fetch-repo-docs.ts | 334 ++ src/app/docs/[...slug]/page.tsx | 207 + src/app/docs/layout.tsx | 363 ++ src/app/globals.css | 85 +- src/app/layout.tsx | 77 +- src/app/page.module.css | 168 - src/app/page.tsx | 159 +- src/assets/cncf-logo.svg | 88 + src/assets/github-logo.svg | 1 + src/assets/prometheus-logo.svg | 19 + src/components/Dots.tsx | 119 + src/components/FeaturesCards.module.css | 47 + src/components/FeaturesCards.tsx | 126 + src/components/Header.module.css | 35 + src/components/Header.tsx | 107 + src/components/Hero.module.css | 82 + src/components/Hero.tsx | 68 + src/components/UserLogos.module.css | 25 + src/components/UserLogos.tsx | 146 + src/docs-collection-types.ts | 47 + src/docs-collection.ts | 6 + src/docs-config-types.ts | 22 + src/rehypeConfigLinker.ts | 92 + src/theme.ts | 29 + tsconfig.json | 3 +- 136 files changed, 18335 insertions(+), 328 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 docs-config.ts create mode 100644 docs/alerting/index.md create mode 100644 docs/concepts/data_model.md create mode 100644 docs/concepts/index.md create mode 100644 docs/concepts/jobs_instances.md create mode 100644 docs/concepts/metric_types.md create mode 100644 docs/guides/basic-auth.md create mode 100644 docs/guides/cadvisor.md create mode 100644 docs/guides/dockerswarm.md create mode 100644 docs/guides/file-sd.md create mode 100644 docs/guides/go-application.md create mode 100644 docs/guides/index.md create mode 100644 docs/guides/multi-target-exporter.md create mode 100644 docs/guides/node-exporter.md create mode 100644 docs/guides/opentelemetry.md create mode 100644 docs/guides/query-log.md create mode 100644 docs/guides/tls-encryption.md create mode 100644 docs/guides/utf8.md create mode 100644 docs/instrumenting/clientlibs.md create mode 100644 docs/instrumenting/exporters.md create mode 100644 docs/instrumenting/exposition_formats.md create mode 100644 docs/instrumenting/index.md create mode 100644 docs/instrumenting/pushing.md create mode 100644 docs/instrumenting/writing_clientlibs.md create mode 100644 docs/instrumenting/writing_exporters.md create mode 100644 docs/introduction/comparison.md create mode 100644 docs/introduction/design-doc.md create mode 100644 docs/introduction/faq.md create mode 100644 docs/introduction/first_steps.md create mode 100644 docs/introduction/glossary.md create mode 100644 docs/introduction/index.md create mode 100644 docs/introduction/media.md create mode 100644 docs/introduction/overview.md create mode 100644 docs/introduction/release-cycle.md create mode 100644 docs/introduction/roadmap.md create mode 100644 docs/operating/index.md create mode 100644 docs/operating/integrations.md create mode 100644 docs/operating/security.md create mode 100644 docs/practices/alerting.md create mode 100644 docs/practices/consoles.md create mode 100644 docs/practices/histograms.md create mode 100644 docs/practices/index.md create mode 100644 docs/practices/instrumentation.md create mode 100644 docs/practices/naming.md create mode 100644 docs/practices/pushing.md create mode 100644 docs/practices/remote_write.md create mode 100644 docs/practices/rules.md create mode 100644 docs/prometheus/index.md create mode 100644 docs/specs/index.md create mode 100644 docs/specs/native_histograms.md create mode 100644 docs/specs/om/index.md create mode 100644 docs/specs/om/open_metrics_spec.md create mode 100644 docs/specs/om/open_metrics_spec_2_0.md create mode 100644 docs/specs/prw/index.md create mode 100644 docs/specs/prw/remote_write_spec.md create mode 100644 docs/specs/prw/remote_write_spec_2_0.md create mode 100644 docs/tutorials/alerting_based_on_metrics.md create mode 100644 docs/tutorials/getting_started.md create mode 100644 docs/tutorials/index.md create mode 100644 docs/tutorials/instrumenting_http_server_in_go.md create mode 100644 docs/tutorials/understanding_metric_types.md create mode 100644 docs/tutorials/visualizing_metrics_using_grafana.md create mode 100644 docs/visualization/browser.md create mode 100644 docs/visualization/consoles.md create mode 100644 docs/visualization/grafana.md create mode 100644 docs/visualization/index.md create mode 100644 postcss.config.cjs create mode 100644 public/assets/company-logos/Amadeus.png create mode 100644 public/assets/company-logos/Argus.png create mode 100644 public/assets/company-logos/Boxever.png create mode 100644 public/assets/company-logos/CoreOS.png create mode 100644 public/assets/company-logos/Docker.png create mode 100644 public/assets/company-logos/Ericsson.png create mode 100644 public/assets/company-logos/Eurotech.png create mode 100644 public/assets/company-logos/Fosdem.png create mode 100644 public/assets/company-logos/FreshTracks.png create mode 100644 public/assets/company-logos/Improbable.png create mode 100644 public/assets/company-logos/Jodel.png create mode 100644 public/assets/company-logos/JustWatch.png create mode 100644 public/assets/company-logos/Kubermatic.png create mode 100644 public/assets/company-logos/Kumina.png create mode 100644 public/assets/company-logos/MOIA.png create mode 100644 public/assets/company-logos/MavenSecurities.png create mode 100644 public/assets/company-logos/Outbrain.png create mode 100644 public/assets/company-logos/Qaware.png create mode 100644 public/assets/company-logos/RobustPerception.png create mode 100644 public/assets/company-logos/Showmax.png create mode 100644 public/assets/company-logos/Spacenet.png create mode 100644 public/assets/company-logos/Sysdig.png create mode 100644 public/assets/company-logos/ayedo.png create mode 100644 public/assets/company-logos/cesanta.png create mode 100644 public/assets/company-logos/crononauta.png create mode 100644 public/assets/company-logos/digitalocean.png create mode 100644 public/assets/company-logos/ecobee.png create mode 100644 public/assets/company-logos/giantswarm.png create mode 100644 public/assets/company-logos/grafana.png create mode 100644 public/assets/company-logos/mixpanel.png create mode 100644 public/assets/company-logos/pingcap.png create mode 100644 public/assets/company-logos/quobyte.png create mode 100644 public/assets/company-logos/shuttlecloud.png create mode 100644 public/assets/company-logos/soundcloud.png create mode 100644 public/assets/company-logos/transloadit.png create mode 100644 public/assets/company-logos/unosoft.png create mode 100644 public/assets/company-logos/weave.png create mode 120000 public/repo-docs-assets create mode 100644 scripts/fetch-repo-docs.ts create mode 100644 src/app/docs/[...slug]/page.tsx create mode 100644 src/app/docs/layout.tsx delete mode 100644 src/app/page.module.css create mode 100644 src/assets/cncf-logo.svg create mode 100644 src/assets/github-logo.svg create mode 100644 src/assets/prometheus-logo.svg create mode 100644 src/components/Dots.tsx create mode 100644 src/components/FeaturesCards.module.css create mode 100644 src/components/FeaturesCards.tsx create mode 100644 src/components/Header.module.css create mode 100644 src/components/Header.tsx create mode 100644 src/components/Hero.module.css create mode 100644 src/components/Hero.tsx create mode 100644 src/components/UserLogos.module.css create mode 100644 src/components/UserLogos.tsx create mode 100644 src/docs-collection-types.ts create mode 100644 src/docs-collection.ts create mode 100644 src/docs-config-types.ts create mode 100644 src/rehypeConfigLinker.ts create mode 100644 src/theme.ts diff --git a/.gitignore b/.gitignore index 5ef6a520..91005fde 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,6 @@ yarn-error.log* # typescript *.tsbuildinfo next-env.d.ts + +# Generated docs files +/generated diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..72446f43 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "typescript.tsdk": "node_modules/typescript/lib" +} diff --git a/docs-config.ts b/docs-config.ts new file mode 100644 index 00000000..dd5e758b --- /dev/null +++ b/docs-config.ts @@ -0,0 +1,34 @@ +import { DocsConfig } from "./src/docs-config-types"; + +export default { + // Docs to load from repo-local files. + localMarkdownSources: [ + { + docsDir: "docs", + slugPrefix: "", + }, + ], + + // Sources for docs to load from external repos (Prometheus, Alertmanager). + githubMarkdownSources: [ + { + owner: "prometheus", + repo: "prometheus", + repoDocsDir: "docs", + slugPrefix: "prometheus", + minNumVersions: 10, + }, + { + owner: "prometheus", + repo: "alertmanager", + repoDocsDir: "docs", + slugPrefix: "alerting", + minNumVersions: 8, + }, + ], + + // Long-term support versions configuration. + ltsVersions: { + prometheus: ["2.53"], + }, +} satisfies DocsConfig; diff --git a/docs/alerting/index.md b/docs/alerting/index.md new file mode 100644 index 00000000..46e1b28f --- /dev/null +++ b/docs/alerting/index.md @@ -0,0 +1,5 @@ +--- +title: Alertmanager +sort_rank: 7 +nav_icon: bell +--- diff --git a/docs/concepts/data_model.md b/docs/concepts/data_model.md new file mode 100644 index 00000000..6fa583b0 --- /dev/null +++ b/docs/concepts/data_model.md @@ -0,0 +1,71 @@ +--- +title: Data model +sort_rank: 1 +--- + +# Data model + +Prometheus fundamentally stores all data as [_time +series_](http://en.wikipedia.org/wiki/Time_series): streams of timestamped +values belonging to the same metric and the same set of labeled dimensions. +Besides stored time series, Prometheus may generate temporary derived time series +as the result of queries. + +## Metric names and labels + +Every time series is uniquely identified by its metric name and optional key-value pairs called labels. + +***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 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)). + +NOTE: Colons (':') are reserved for user-defined recording rules. They SHOULD NOT be used by exporters or direct instrumentation. + +***Metric labels:*** + +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 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 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. + +INFO: See also the [best practices for naming metrics and labels](/docs/practices/naming/). + +## Samples + +Samples form the actual time series data. Each sample consists of: + +* a float64 or [native histogram](https://prometheus.io/docs/specs/native_histograms/) value +* a millisecond-precision timestamp + +## Notation + +Given a metric name and a set of labels, time series are frequently identified +using this notation: + + {