Document command line tools

Signed-off-by: Julien Pivotto <roidelapluie@o11y.eu>
2024-11-09 23:24:05 -08:00 · 2023-03-12 00:18:33 +01:00 · 2023-03-12 00:18:33 +01:00 · 1922db0586
parent 001ee2620e
commit 1922db0586
12 changed files with 934 additions and 3 deletions
--- a/5
+++ b/5
@ -133,3 +133,8 @@ bench_tsdb: $(PROMU)
 	@$(GO) tool pprof --alloc_space -svg $(PROMTOOL) $(TSDB_BENCHMARK_OUTPUT_DIR)/mem.prof > $(TSDB_BENCHMARK_OUTPUT_DIR)/memprof.alloc.svg
 	@$(GO) tool pprof -svg $(PROMTOOL) $(TSDB_BENCHMARK_OUTPUT_DIR)/block.prof > $(TSDB_BENCHMARK_OUTPUT_DIR)/blockprof.svg
 	@$(GO) tool pprof -svg $(PROMTOOL) $(TSDB_BENCHMARK_OUTPUT_DIR)/mutex.prof > $(TSDB_BENCHMARK_OUTPUT_DIR)/mutexprof.svg
+
+.PHONY: cli-documentation
+cli-documentation:
+	$(GO) run ./cmd/prometheus/ --write-documentation > docs/command-line/prometheus.md
+	$(GO) run ./cmd/promtool/ write-documentation > docs/command-line/promtool.md
--- a/cmd/prometheus/main.go
+++ b/cmd/prometheus/main.go
@ -70,6 +70,7 @@ import (
 	"github.com/prometheus/prometheus/tracing"
 	"github.com/prometheus/prometheus/tsdb"
 	"github.com/prometheus/prometheus/tsdb/agent"
+	"github.com/prometheus/prometheus/util/documentcli"
 	"github.com/prometheus/prometheus/util/logging"
 	prom_runtime "github.com/prometheus/prometheus/util/runtime"
 	"github.com/prometheus/prometheus/web"
@ -413,6 +414,15 @@ func main() {

 	promlogflag.AddFlags(a, &cfg.promlogConfig)

+	a.Flag("write-documentation", "Generate command line documentation. Internal use.").Hidden().Action(func(ctx *kingpin.ParseContext) error {
+		if err := documentcli.GenerateMarkdown(a.Model(), os.Stdout); err != nil {
+			os.Exit(1)
+			return err
+		}
+		os.Exit(0)
+		return nil
+	}).Bool()
+
 	_, err := a.Parse(os.Args[1:])
 	if err != nil {
 		fmt.Fprintln(os.Stderr, fmt.Errorf("Error parsing commandline arguments: %w", err))
--- a/cmd/prometheus/main_test.go
+++ b/cmd/prometheus/main_test.go
@ -23,6 +23,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"syscall"
 	"testing"
@ -483,3 +484,31 @@ func TestModeSpecificFlags(t *testing.T) {
 		})
 	}
 }
+
+func TestDocumentation(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.SkipNow()
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, promPath, "-test.main", "--write-documentation")
+
+	var stdout bytes.Buffer
+	cmd.Stdout = &stdout
+
+	if err := cmd.Run(); err != nil {
+		if exitError, ok := err.(*exec.ExitError); ok {
+			if exitError.ExitCode() != 0 {
+				fmt.Println("Command failed with non-zero exit code")
+			}
+		}
+	}
+
+	generatedContent := strings.ReplaceAll(stdout.String(), filepath.Base(promPath), strings.TrimSuffix(filepath.Base(promPath), ".test"))
+
+	expectedContent, err := os.ReadFile(filepath.Join("..", "..", "docs", "command-line", "prometheus.md"))
+	require.NoError(t, err)
+
+	require.Equal(t, string(expectedContent), generatedContent, "Generated content does not match documentation. Hint: run `make cli-documentation`.")
+}
--- a/cmd/promtool/main.go
+++ b/cmd/promtool/main.go
@ -59,6 +59,7 @@ import (
 	_ "github.com/prometheus/prometheus/plugins" // Register plugins.
 	"github.com/prometheus/prometheus/promql"
 	"github.com/prometheus/prometheus/scrape"
+	"github.com/prometheus/prometheus/util/documentcli"
 )

 const (
@ -223,6 +224,8 @@ func main() {

 	featureList := app.Flag("enable-feature", "Comma separated feature names to enable (only PromQL related and no-default-scrape-port). See https://prometheus.io/docs/prometheus/latest/feature_flags/ for the options and more details.").Default("").Strings()

+	documentationCmd := app.Command("write-documentation", "Generate command line documentation. Internal use.").Hidden()
+
 	parsedCmd := kingpin.MustParse(app.Parse(os.Args[1:]))

 	var p printer
@ -329,6 +332,8 @@ func main() {

 	case importRulesCmd.FullCommand():
 		os.Exit(checkErr(importRules(serverURL, httpRoundTripper, *importRulesStart, *importRulesEnd, *importRulesOutputDir, *importRulesEvalInterval, *maxBlockDuration, *importRulesFiles...)))
+	case documentationCmd.FullCommand():
+		os.Exit(checkErr(documentcli.GenerateMarkdown(app.Model(), os.Stdout)))
 	}
 }

--- a/cmd/promtool/main_test.go
+++ b/cmd/promtool/main_test.go
@ -14,6 +14,8 @@
 package main

 import (
+	"bytes"
+	"context"
 	"errors"
 	"fmt"
 	"net/http"
@ -21,6 +23,7 @@ import (
 	"net/url"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"runtime"
 	"strings"
 	"syscall"
@ -433,3 +436,31 @@ func TestExitCodes(t *testing.T) {
 		})
 	}
 }
+
+func TestDocumentation(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.SkipNow()
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, promtoolPath, "-test.main", "write-documentation")
+
+	var stdout bytes.Buffer
+	cmd.Stdout = &stdout
+
+	if err := cmd.Run(); err != nil {
+		if exitError, ok := err.(*exec.ExitError); ok {
+			if exitError.ExitCode() != 0 {
+				fmt.Println("Command failed with non-zero exit code")
+			}
+		}
+	}
+
+	generatedContent := strings.ReplaceAll(stdout.String(), filepath.Base(promtoolPath), strings.TrimSuffix(filepath.Base(promtoolPath), ".test"))
+
+	expectedContent, err := os.ReadFile(filepath.Join("..", "..", "docs", "command-line", "promtool.md"))
+	require.NoError(t, err)
+
+	require.Equal(t, string(expectedContent), generatedContent, "Generated content does not match documentation. Hint: run `make cli-documentation`.")
+}
--- a/docs/command-line/index.md
+++ b/docs/command-line/index.md
@ -0,0 +1,4 @@
+---
+title: Command Line
+sort_rank: 9
+---
--- a/docs/command-line/prometheus.md
+++ b/docs/command-line/prometheus.md
@ -0,0 +1,59 @@
+---
+title: prometheus
+---
+
+# prometheus
+
+The Prometheus monitoring server
+
+
+
+## Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">-h</code>, <code class="text-nowrap">--help</code> | Show context-sensitive help (also try --help-long and --help-man). |  |
+| <code class="text-nowrap">--version</code> | Show application version. |  |
+| <code class="text-nowrap">--config.file</code> | Prometheus configuration file path. | `prometheus.yml` |
+| <code class="text-nowrap">--web.listen-address</code> | Address to listen on for UI, API, and telemetry. | `0.0.0.0:9090` |
+| <code class="text-nowrap">--web.config.file</code> | [EXPERIMENTAL] Path to configuration file that can enable TLS or authentication. |  |
+| <code class="text-nowrap">--web.read-timeout</code> | Maximum duration before timing out read of the request, and closing idle connections. | `5m` |
+| <code class="text-nowrap">--web.max-connections</code> | Maximum number of simultaneous connections. | `512` |
+| <code class="text-nowrap">--web.external-url</code> | The URL under which Prometheus is externally reachable (for example, if Prometheus is served via a reverse proxy). Used for generating relative and absolute links back to Prometheus itself. If the URL has a path portion, it will be used to prefix all HTTP endpoints served by Prometheus. If omitted, relevant URL components will be derived automatically. |  |
+| <code class="text-nowrap">--web.route-prefix</code> | Prefix for the internal routes of web endpoints. Defaults to path of --web.external-url. |  |
+| <code class="text-nowrap">--web.user-assets</code> | Path to static asset directory, available at /user. |  |
+| <code class="text-nowrap">--web.enable-lifecycle</code> | Enable shutdown and reload via HTTP request. | `false` |
+| <code class="text-nowrap">--web.enable-admin-api</code> | Enable API endpoints for admin control actions. | `false` |
+| <code class="text-nowrap">--web.enable-remote-write-receiver</code> | Enable API endpoint accepting remote write requests. | `false` |
+| <code class="text-nowrap">--web.console.templates</code> | Path to the console template directory, available at /consoles. | `consoles` |
+| <code class="text-nowrap">--web.console.libraries</code> | Path to the console library directory. | `console_libraries` |
+| <code class="text-nowrap">--web.page-title</code> | Document title of Prometheus instance. | `Prometheus Time Series Collection and Processing Server` |
+| <code class="text-nowrap">--web.cors.origin</code> | Regex for CORS origin. It is fully anchored. Example: 'https?://(domain1|domain2)\.com' | `.*` |
+| <code class="text-nowrap">--storage.tsdb.path</code> | Base path for metrics storage. Use with server mode only. | `data/` |
+| <code class="text-nowrap">--storage.tsdb.retention</code> | [DEPRECATED] How long to retain samples in storage. This flag has been deprecated, use "storage.tsdb.retention.time" instead. Use with server mode only. |  |
+| <code class="text-nowrap">--storage.tsdb.retention.time</code> | How long to retain samples in storage. When this flag is set it overrides "storage.tsdb.retention". If neither this flag nor "storage.tsdb.retention" nor "storage.tsdb.retention.size" is set, the retention time defaults to 15d. Units Supported: y, w, d, h, m, s, ms. Use with server mode only. |  |
+| <code class="text-nowrap">--storage.tsdb.retention.size</code> | Maximum number of bytes that can be stored for blocks. A unit is required, supported units: B, KB, MB, GB, TB, PB, EB. Ex: "512MB". Based on powers-of-2, so 1KB is 1024B. Use with server mode only. |  |
+| <code class="text-nowrap">--storage.tsdb.no-lockfile</code> | Do not create lockfile in data directory. Use with server mode only. | `false` |
+| <code class="text-nowrap">--storage.tsdb.head-chunks-write-queue-size</code> | Size of the queue through which head chunks are written to the disk to be m-mapped, 0 disables the queue completely. Experimental. Use with server mode only. | `0` |
+| <code class="text-nowrap">--storage.agent.path</code> | Base path for metrics storage. Use with agent mode only. | `data-agent/` |
+| <code class="text-nowrap">--storage.agent.wal-compression</code> | Compress the agent WAL. Use with agent mode only. | `true` |
+| <code class="text-nowrap">--storage.agent.retention.min-time</code> | Minimum age samples may be before being considered for deletion when the WAL is truncated Use with agent mode only. |  |
+| <code class="text-nowrap">--storage.agent.retention.max-time</code> | Maximum age samples may be before being forcibly deleted when the WAL is truncated Use with agent mode only. |  |
+| <code class="text-nowrap">--storage.agent.no-lockfile</code> | Do not create lockfile in data directory. Use with agent mode only. | `false` |
+| <code class="text-nowrap">--storage.remote.flush-deadline</code> | How long to wait flushing sample on shutdown or config reload. | `1m` |
+| <code class="text-nowrap">--storage.remote.read-sample-limit</code> | Maximum overall number of samples to return via the remote read interface, in a single query. 0 means no limit. This limit is ignored for streamed response types. Use with server mode only. | `5e7` |
+| <code class="text-nowrap">--storage.remote.read-concurrent-limit</code> | Maximum number of concurrent remote read calls. 0 means no limit. Use with server mode only. | `10` |
+| <code class="text-nowrap">--storage.remote.read-max-bytes-in-frame</code> | Maximum number of bytes in a single frame for streaming remote read response types before marshalling. Note that client might have limit on frame size as well. 1MB as recommended by protobuf by default. Use with server mode only. | `1048576` |
+| <code class="text-nowrap">--rules.alert.for-outage-tolerance</code> | Max time to tolerate prometheus outage for restoring "for" state of alert. Use with server mode only. | `1h` |
+| <code class="text-nowrap">--rules.alert.for-grace-period</code> | Minimum duration between alert and restored "for" state. This is maintained only for alerts with configured "for" time greater than grace period. Use with server mode only. | `10m` |
+| <code class="text-nowrap">--rules.alert.resend-delay</code> | Minimum amount of time to wait before resending an alert to Alertmanager. Use with server mode only. | `1m` |
+| <code class="text-nowrap">--alertmanager.notification-queue-capacity</code> | The capacity of the queue for pending Alertmanager notifications. Use with server mode only. | `10000` |
+| <code class="text-nowrap">--query.lookback-delta</code> | The maximum lookback duration for retrieving metrics during expression evaluations and federation. Use with server mode only. | `5m` |
+| <code class="text-nowrap">--query.timeout</code> | Maximum time a query may take before being aborted. Use with server mode only. | `2m` |
+| <code class="text-nowrap">--query.max-concurrency</code> | Maximum number of queries executed concurrently. Use with server mode only. | `20` |
+| <code class="text-nowrap">--query.max-samples</code> | Maximum number of samples a single query can load into memory. Note that queries will fail if they try to load more samples than this into memory, so this also limits the number of samples a query can return. Use with server mode only. | `50000000` |
+| <code class="text-nowrap">--enable-feature</code> | Comma separated feature names to enable. Valid options: agent, exemplar-storage, expand-external-labels, memory-snapshot-on-shutdown, promql-at-modifier, promql-negative-offset, promql-per-step-stats, remote-write-receiver (DEPRECATED), extra-scrape-metrics, new-service-discovery-manager, auto-gomaxprocs, no-default-scrape-port, native-histograms. See https://prometheus.io/docs/prometheus/latest/feature_flags/ for more details. |  |
+| <code class="text-nowrap">--log.level</code> | Only log messages with the given severity or above. One of: [debug, info, warn, error] | `info` |
+| <code class="text-nowrap">--log.format</code> | Output format of log messages. One of: [logfmt, json] | `logfmt` |
+
+
--- a/docs/command-line/promtool.md
+++ b/docs/command-line/promtool.md
@ -0,0 +1,536 @@
+---
+title: promtool
+---
+
+# promtool
+
+Tooling for the Prometheus monitoring system.
+
+
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">-h</code>, <code class="text-nowrap">--help</code> | Show context-sensitive help (also try --help-long and --help-man). |
+| <code class="text-nowrap">--version</code> | Show application version. |
+| <code class="text-nowrap">--enable-feature</code> | Comma separated feature names to enable (only PromQL related and no-default-scrape-port). See https://prometheus.io/docs/prometheus/latest/feature_flags/ for the options and more details. |
+
+
+
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| help | Show help. |
+| check | Check the resources for validity. |
+| query | Run query against a Prometheus server. |
+| debug | Fetch debug information. |
+| test | Unit testing. |
+| tsdb | Run tsdb commands. |
+
+
+
+
+### `promtool help`
+
+Show help.
+
+
+
+#### Arguments
+
+| Argument | Description |
+| --- | --- |
+| command | Show help on command. |
+
+
+
+
+### `promtool check`
+
+Check the resources for validity.
+
+
+
+#### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">--extended</code> | Print extended information related to the cardinality of the metrics. |
+
+
+
+
+##### `promtool check service-discovery`
+
+Perform service discovery for the given job name and report the results, including relabeling.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--timeout</code> | The time to wait for discovery results. | `30s` |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| config-file | The prometheus config file. | Yes |
+| job | The job to run service discovery for. | Yes |
+
+
+
+
+##### `promtool check config`
+
+Check if the config files are valid or not.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--syntax-only</code> | Only check the config file syntax, ignoring file and content validation referenced in the config |  |
+| <code class="text-nowrap">--lint</code> | Linting checks to apply to the rules specified in the config. Available options are: all, duplicate-rules, none. Use --lint=none to disable linting | `duplicate-rules` |
+| <code class="text-nowrap">--lint-fatal</code> | Make lint errors exit with exit code 3. | `false` |
+| <code class="text-nowrap">--agent</code> | Check config file for Prometheus in Agent mode. |  |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| config-files | The config files to check. | Yes |
+
+
+
+
+##### `promtool check web-config`
+
+Check if the web config files are valid or not.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| web-config-files | The config files to check. | Yes |
+
+
+
+
+##### `promtool check rules`
+
+Check if the rule files are valid or not.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--lint</code> | Linting checks to apply. Available options are: all, duplicate-rules, none. Use --lint=none to disable linting | `duplicate-rules` |
+| <code class="text-nowrap">--lint-fatal</code> | Make lint errors exit with exit code 3. | `false` |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| rule-files | The rule files to check. | Yes |
+
+
+
+
+##### `promtool check metrics`
+
+Pass Prometheus metrics over stdin to lint them for consistency and correctness.
+
+examples:
+
+$ cat metrics.prom | promtool check metrics
+
+$ curl -s http://localhost:9090/metrics | promtool check metrics
+
+
+
+### `promtool query`
+
+Run query against a Prometheus server.
+
+
+
+#### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">-o</code>, <code class="text-nowrap">--format</code> | Output format of the query. | `promql` |
+| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |  |
+
+
+
+
+##### `promtool query instant`
+
+Run instant query.
+
+
+
+###### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">--time</code> | Query evaluation time (RFC3339 or Unix timestamp). |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to query. | Yes |
+| expr | PromQL query expression. | Yes |
+
+
+
+
+##### `promtool query range`
+
+Run range query.
+
+
+
+###### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">--header</code> | Extra headers to send to server. |
+| <code class="text-nowrap">--start</code> | Query range start time (RFC3339 or Unix timestamp). |
+| <code class="text-nowrap">--end</code> | Query range end time (RFC3339 or Unix timestamp). |
+| <code class="text-nowrap">--step</code> | Query step size (duration). |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to query. | Yes |
+| expr | PromQL query expression. | Yes |
+
+
+
+
+##### `promtool query series`
+
+Run series query.
+
+
+
+###### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">--match</code> | Series selector. Can be specified multiple times. |
+| <code class="text-nowrap">--start</code> | Start time (RFC3339 or Unix timestamp). |
+| <code class="text-nowrap">--end</code> | End time (RFC3339 or Unix timestamp). |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to query. | Yes |
+
+
+
+
+##### `promtool query labels`
+
+Run labels query.
+
+
+
+###### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">--start</code> | Start time (RFC3339 or Unix timestamp). |
+| <code class="text-nowrap">--end</code> | End time (RFC3339 or Unix timestamp). |
+| <code class="text-nowrap">--match</code> | Series selector. Can be specified multiple times. |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to query. | Yes |
+| name | Label name to provide label values for. | Yes |
+
+
+
+
+### `promtool debug`
+
+Fetch debug information.
+
+
+
+##### `promtool debug pprof`
+
+Fetch profiling debug information.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to get pprof files from. | Yes |
+
+
+
+
+##### `promtool debug metrics`
+
+Fetch metrics debug information.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to get metrics from. | Yes |
+
+
+
+
+##### `promtool debug all`
+
+Fetch all debug information.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| server | Prometheus server to get all debug information from. | Yes |
+
+
+
+
+### `promtool test`
+
+Unit testing.
+
+
+
+##### `promtool test rules`
+
+Unit tests for rules.
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| test-rule-file | The unit test file. | Yes |
+
+
+
+
+### `promtool tsdb`
+
+Run tsdb commands.
+
+
+
+##### `promtool tsdb bench`
+
+Run benchmarks.
+
+
+
+##### `promtool tsdb bench write`
+
+Run a write performance benchmark.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--out</code> | Set the output path. | `benchout` |
+| <code class="text-nowrap">--metrics</code> | Number of metrics to read. | `10000` |
+| <code class="text-nowrap">--scrapes</code> | Number of scrapes to simulate. | `3000` |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| file | Input file with samples data, default is (../../tsdb/testdata/20kseries.json). | `../../tsdb/testdata/20kseries.json` |
+
+
+
+
+##### `promtool tsdb analyze`
+
+Analyze churn, label pair cardinality and compaction efficiency.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--limit</code> | How many items to show in each list. | `20` |
+| <code class="text-nowrap">--extended</code> | Run extended analysis. |  |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| db path | Database path (default is data/). | `data/` |
+| block id | Block to analyze (default is the last block). |  |
+
+
+
+
+##### `promtool tsdb list`
+
+List tsdb blocks.
+
+
+
+###### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">-r</code>, <code class="text-nowrap">--human-readable</code> | Print human readable values. |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| db path | Database path (default is data/). | `data/` |
+
+
+
+
+##### `promtool tsdb dump`
+
+Dump samples from a TSDB.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--min-time</code> | Minimum timestamp to dump. | `-9223372036854775808` |
+| <code class="text-nowrap">--max-time</code> | Maximum timestamp to dump. | `9223372036854775807` |
+| <code class="text-nowrap">--match</code> | Series selector. | `{__name__=~'(?s:.*)'}` |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| db path | Database path (default is data/). | `data/` |
+
+
+
+
+##### `promtool tsdb create-blocks-from`
+
+[Experimental] Import samples from input and produce TSDB blocks. Please refer to the storage docs for more details.
+
+
+
+###### Flags
+
+| Flag | Description |
+| --- | --- |
+| <code class="text-nowrap">-r</code>, <code class="text-nowrap">--human-readable</code> | Print human readable values. |
+| <code class="text-nowrap">-q</code>, <code class="text-nowrap">--quiet</code> | Do not print created blocks. |
+
+
+
+
+##### `promtool tsdb create-blocks-from openmetrics`
+
+Import samples from OpenMetrics input and produce TSDB blocks. Please refer to the storage docs for more details.
+
+
+
+###### Arguments
+
+| Argument | Description | Default | Required |
+| --- | --- | --- | --- |
+| input file | OpenMetrics file to read samples from. |  | Yes |
+| output directory | Output directory for generated blocks. | `data/` |  |
+
+
+
+
+##### `promtool tsdb create-blocks-from rules`
+
+Create blocks of data for new recording rules.
+
+
+
+###### Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| <code class="text-nowrap">--http.config.file</code> | HTTP client configuration file for promtool to connect to Prometheus. |  |
+| <code class="text-nowrap">--url</code> | The URL for the Prometheus API with the data where the rule will be backfilled from. | `http://localhost:9090` |
+| <code class="text-nowrap">--start</code> | The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required. |  |
+| <code class="text-nowrap">--end</code> | If an end time is provided, all recording rules in the rule files provided will be backfilled to the end time. Default will backfill up to 3 hours ago. Must be a RFC3339 formatted date or Unix timestamp. |  |
+| <code class="text-nowrap">--output-dir</code> | Output directory for generated blocks. | `data/` |
+| <code class="text-nowrap">--eval-interval</code> | How frequently to evaluate rules when backfilling if a value is not set in the recording rule files. | `60s` |
+
+
+
+
+###### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| rule-files | A list of one or more files containing recording rules to be backfilled. All recording rules listed in the files will be backfilled. Alerting rules are not evaluated. | Yes |
+
+
--- a/docs/feature_flags.md
+++ b/docs/feature_flags.md
@ -1,6 +1,6 @@
 ---
 title: Feature flags
-sort_rank: 11
+sort_rank: 12
 ---

 # Feature flags
--- a/docs/migration.md
+++ b/docs/migration.md
@ -1,6 +1,6 @@
 ---
 title: Migration
-sort_rank: 9
+sort_rank: 10
 ---

 # Prometheus 2.0 migration guide
--- a/docs/stability.md
+++ b/docs/stability.md
@ -1,6 +1,6 @@
 ---
 title: API Stability
-sort_rank: 10
+sort_rank: 11
 ---

 # API Stability Guarantees
--- a/util/documentcli/documentcli.go
+++ b/util/documentcli/documentcli.go
@ -0,0 +1,252 @@
+// Copyright 2023 The Prometheus Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// If we decide to employ this auto generation of markdown documentation for
+// amtool and alertmanager, this package could potentially be moved to
+// prometheus/common. However, it is crucial to note that this functionality is
+// tailored specifically to the way in which the Prometheus documentation is
+// rendered, and should be avoided for use by third-party users.
+
+package documentcli
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/alecthomas/kingpin/v2"
+)
+
+// GenerateMarkdown generates the markdown documentation for an application from
+// its kingpin ApplicationModel.
+func GenerateMarkdown(model *kingpin.ApplicationModel, writer io.Writer) error {
+	h := header(model.Name, model.Help)
+	if _, err := writer.Write(h); err != nil {
+		return err
+	}
+
+	if err := writeFlagTable(writer, 0, model.FlagGroupModel); err != nil {
+		return err
+	}
+
+	if err := writeArgTable(writer, 0, model.ArgGroupModel); err != nil {
+		return err
+	}
+
+	if err := writeCmdTable(writer, model.CmdGroupModel); err != nil {
+		return err
+	}
+
+	return writeSubcommands(writer, 1, model.Name, model.CmdGroupModel.Commands)
+}
+
+func header(title, help string) []byte {
+	return []byte(fmt.Sprintf(`---
+title: %s
+---
+
+# %s
+
+%s
+
+`, title, title, help))
+}
+
+func createFlagRow(flag *kingpin.FlagModel) []string {
+	defaultVal := ""
+	if len(flag.Default) > 0 && len(flag.Default[0]) > 0 {
+		defaultVal = fmt.Sprintf("`%s`", flag.Default[0])
+	}
+
+	name := fmt.Sprintf(`<code class="text-nowrap">--%s</code>`, flag.Name)
+	if flag.Short != '\x00' {
+		name = fmt.Sprintf(`<code class="text-nowrap">-%c</code>, <code class="text-nowrap">--%s</code>`, flag.Short, flag.Name)
+	}
+
+	return []string{name, flag.Help, defaultVal}
+}
+
+func writeFlagTable(writer io.Writer, level int, fgm *kingpin.FlagGroupModel) error {
+	if fgm == nil || len(fgm.Flags) == 0 {
+		return nil
+	}
+
+	rows := [][]string{
+		{"Flag", "Description", "Default"},
+	}
+
+	for _, flag := range fgm.Flags {
+		if !flag.Hidden {
+			row := createFlagRow(flag)
+			rows = append(rows, row)
+		}
+	}
+
+	return writeTable(writer, rows, fmt.Sprintf("%s Flags", strings.Repeat("#", level+2)))
+}
+
+func createArgRow(arg *kingpin.ArgModel) []string {
+	defaultVal := ""
+	if len(arg.Default) > 0 {
+		defaultVal = fmt.Sprintf("`%s`", arg.Default[0])
+	}
+
+	required := ""
+	if arg.Required {
+		required = "Yes"
+	}
+
+	return []string{arg.Name, arg.Help, defaultVal, required}
+}
+
+func writeArgTable(writer io.Writer, level int, agm *kingpin.ArgGroupModel) error {
+	if agm == nil || len(agm.Args) == 0 {
+		return nil
+	}
+
+	rows := [][]string{
+		{"Argument", "Description", "Default", "Required"},
+	}
+
+	for _, arg := range agm.Args {
+		row := createArgRow(arg)
+		rows = append(rows, row)
+	}
+
+	return writeTable(writer, rows, fmt.Sprintf("%s Arguments", strings.Repeat("#", level+2)))
+}
+
+func createCmdRow(cmd *kingpin.CmdModel) []string {
+	if cmd.Hidden {
+		return nil
+	}
+	return []string{cmd.FullCommand, cmd.Help}
+}
+
+func writeCmdTable(writer io.Writer, cgm *kingpin.CmdGroupModel) error {
+	if cgm == nil || len(cgm.Commands) == 0 {
+		return nil
+	}
+
+	rows := [][]string{
+		{"Command", "Description"},
+	}
+
+	for _, cmd := range cgm.Commands {
+		row := createCmdRow(cmd)
+		if row != nil {
+			rows = append(rows, row)
+		}
+	}
+
+	return writeTable(writer, rows, "## Commands")
+}
+
+func writeTable(writer io.Writer, data [][]string, header string) error {
+	if len(data) < 2 {
+		return nil
+	}
+
+	buf := bytes.NewBuffer(nil)
+
+	buf.WriteString(fmt.Sprintf("\n\n%s\n\n", header))
+	columnsToRender := determineColumnsToRender(data)
+
+	headers := data[0]
+	buf.WriteString("|")
+	for _, j := range columnsToRender {
+		buf.WriteString(fmt.Sprintf(" %s |", headers[j]))
+	}
+	buf.WriteString("\n")
+
+	buf.WriteString("|")
+	for range columnsToRender {
+		buf.WriteString(" --- |")
+	}
+	buf.WriteString("\n")
+
+	for i := 1; i < len(data); i++ {
+		row := data[i]
+		buf.WriteString("|")
+		for _, j := range columnsToRender {
+			buf.WriteString(fmt.Sprintf(" %s |", row[j]))
+		}
+		buf.WriteString("\n")
+	}
+
+	if _, err := writer.Write(buf.Bytes()); err != nil {
+		return err
+	}
+
+	if _, err := writer.Write([]byte("\n\n")); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func determineColumnsToRender(data [][]string) []int {
+	columnsToRender := []int{}
+	if len(data) == 0 {
+		return columnsToRender
+	}
+	for j := 0; j < len(data[0]); j++ {
+		renderColumn := false
+		for i := 1; i < len(data); i++ {
+			if data[i][j] != "" {
+				renderColumn = true
+				break
+			}
+		}
+		if renderColumn {
+			columnsToRender = append(columnsToRender, j)
+		}
+	}
+	return columnsToRender
+}
+
+func writeSubcommands(writer io.Writer, level int, modelName string, commands []*kingpin.CmdModel) error {
+	level++
+	if level > 4 {
+		level = 4
+	}
+	for _, cmd := range commands {
+		if cmd.Hidden {
+			continue
+		}
+
+		help := cmd.Help
+		if cmd.HelpLong != "" {
+			help = cmd.HelpLong
+		}
+		if _, err := writer.Write([]byte(fmt.Sprintf("\n\n%s `%s %s`\n\n%s\n\n", strings.Repeat("#", level+1), modelName, cmd.FullCommand, help))); err != nil {
+			return err
+		}
+
+		if err := writeFlagTable(writer, level, cmd.FlagGroupModel); err != nil {
+			return err
+		}
+
+		if err := writeArgTable(writer, level, cmd.ArgGroupModel); err != nil {
+			return err
+		}
+
+		if cmd.CmdGroupModel != nil && len(cmd.CmdGroupModel.Commands) > 0 {
+			if err := writeSubcommands(writer, level+1, modelName, cmd.CmdGroupModel.Commands); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}