promtool

Prometheus 監控系統的工具。

標誌

標誌	描述
-h, --help	顯示上下文相關的幫助資訊（也可以嘗試 --help-long 和 --help-man）。
--version	顯示應用程式版本。
--experimental	啟用實驗性命令。
--enable-feature ...	要啟用的特性名稱列表（逗號分隔）。有效選項：promql-experimental-functions, promql-delayed-name-removal, promql-duration-expr, promql-extended-range-selectors。有關更多詳細資訊，請參見 https://prometheus.golang.com.tw/docs/prometheus/latest/feature_flags/

命令

命令	描述
help	顯示幫助資訊。
check	檢查資源的有效性。
query	對 Prometheus 伺服器執行查詢。
debug	獲取除錯資訊。
push	推送到 Prometheus 伺服器。
test	單元測試。
tsdb	執行 tsdb 命令。
promql	PromQL 格式化和編輯。需要 --experimental 標誌。

promtool help

顯示幫助資訊。

引數

引數	描述
command	顯示命令的幫助資訊。

promtool check

檢查資源的有效性。

標誌

標誌	描述	預設值
--query.lookback-delta	伺服器的最大查詢回溯時長。	5m

promtool check service-discovery

對給定的任務（job）名稱執行服務發現並報告結果（包括重新標記 relabeling）。

標誌

標誌	描述	預設值
--timeout	等待服務發現結果的時間。	30s

引數

引數	描述	必填
config-file	Prometheus 配置檔案。	是
job	要執行服務發現的任務（job）。	是

promtool check config

檢查配置檔案是否有效。

標誌

標誌	描述	預設值
--syntax-only	僅檢查配置檔案語法，忽略配置中引用的檔案和內容的驗證。
--lint	要應用於配置中指定的規則/抓取配置的 Linting 檢查。可用選項有：all、duplicate-rules、none、too-long-scrape-interval。使用 --lint=none 停用 Linting 檢查。	duplicate-rules
--lint-fatal	使 Lint 錯誤以退出碼 3 退出。	false
--ignore-unknown-fields	忽略配置檔案讀取的規則組中的未知欄位。當你想用自定義元資料擴充套件規則檔案時，這很有用。確保在將這些欄位載入到 Prometheus 伺服器之前將其刪除，因為伺服器預設會進行嚴格檢查。	false
--agent	檢查 Agent 模式下的 Prometheus 配置檔案。

引數

引數	描述	必填
config-files	要檢查的配置檔案。	是

promtool check web-config

檢查 Web 配置檔案是否有效。

引數

引數	描述	必填
web-config-files	要檢查的配置檔案。	是

promtool check healthy

檢查 Prometheus 伺服器是否健康。

標誌

標誌	描述	預設值
--http.config.file	HTTP 客戶端配置檔案，詳細資訊見 https://prometheus.golang.com.tw/docs/prometheus/latest/configuration/promtool
--url	Prometheus 伺服器的 URL。	https://:9090

promtool check ready

檢查 Prometheus 伺服器是否就緒。

標誌

標誌	描述	預設值
--http.config.file	HTTP 客戶端配置檔案，詳細資訊見 https://prometheus.golang.com.tw/docs/prometheus/latest/configuration/promtool
--url	Prometheus 伺服器的 URL。	https://:9090

promtool check rules

檢查規則檔案是否有效。

標誌

標誌	描述	預設值
--lint	要應用的 Linting 檢查。可用選項有：all、duplicate-rules、none。使用 --lint=none 停用 Linting 檢查。	duplicate-rules
--lint-fatal	使 Lint 錯誤以退出碼 3 退出。	false
--ignore-unknown-fields	忽略規則檔案中的未知欄位。當你想用自定義元資料擴充套件規則檔案時，這很有用。確保在將這些欄位載入到 Prometheus 伺服器之前將其刪除，因為伺服器預設會進行嚴格檢查。	false

引數

引數	描述
rule-files	要檢查的規則檔案，預設從標準輸入讀取。

promtool check metrics

透過標準輸入（stdin）傳入 Prometheus 指標，以對其一致性和正確性進行 Lint 檢查，並可選擇執行基數分析。

示例

$ cat metrics.prom | promtool check metrics

$ curl -s https://:9090/metrics  | promtool check metrics --extended

$ curl -s https://:9100/metrics  | promtool check metrics --extended --lint=none

標誌

標誌	描述	預設值
--extended	列印與指標基數相關的擴充套件資訊。
--lint	要應用於指標的 Linting 檢查。可用選項：all、none。使用 --lint=none 停用指標 Linting 檢查。	all

promtool query

對 Prometheus 伺服器執行查詢。

標誌

標誌	描述	預設值
-o, --format	查詢的輸出格式。	promql
--http.config.file	HTTP 客戶端配置檔案，詳細資訊見 https://prometheus.golang.com.tw/docs/prometheus/latest/configuration/promtool

promtool query instant

執行瞬時查詢。

標誌

標誌	描述
--time	查詢評估時間（RFC3339 或 Unix 時間戳）。
--header	要傳送到伺服器的額外 HTTP 標頭（header）。

引數

引數	描述	必填
server	要查詢的 Prometheus 伺服器。	是
expr	PromQL 查詢表示式。	是

promtool query range

執行範圍查詢。

標誌

標誌	描述
--header	要傳送到伺服器的額外 HTTP 標頭（header）。
--start	查詢範圍開始時間（RFC3339 或 Unix 時間戳）。
--end	查詢範圍結束時間（RFC3339 或 Unix 時間戳）。
--step	查詢步長（持續時間）。

引數

引數	描述	必填
server	要查詢的 Prometheus 伺服器。	是
expr	PromQL 查詢表示式。	是

promtool query series

執行時間序列查詢。

標誌

標誌	描述
--match ...	序列選擇器。可以指定多次。
--start	開始時間（RFC3339 或 Unix 時間戳）。
--end	結束時間（RFC3339 或 Unix 時間戳）。

引數

引數	描述	必填
server	要查詢的 Prometheus 伺服器。	是

promtool query labels

執行標籤查詢。

標誌

標誌	描述
--start	開始時間（RFC3339 或 Unix 時間戳）。
--end	結束時間（RFC3339 或 Unix 時間戳）。
--match ...	序列選擇器。可以指定多次。

引數

引數	描述	必填
server	要查詢的 Prometheus 伺服器。	是
name	要獲取其標籤值的標籤名稱。	是

promtool query analyze

對您的 Prometheus 執行查詢，以分析某些指標的使用模式。

標誌

標誌	描述	預設值
--server	要查詢的 Prometheus 伺服器。
--type	指標型別：直方圖（histogram）。
--duration	要分析的時間範圍。	1h
--time	查詢時間（RFC3339 或 Unix 時間戳），預設為當前時間。
--match ...	序列選擇器。可以指定多次。

promtool debug

獲取除錯資訊。

promtool debug pprof

獲取效能分析（pprof）除錯資訊。

引數

引數	描述	必填
server	用於獲取 pprof 檔案的 Prometheus 伺服器。	是

promtool debug metrics

獲取指標除錯資訊。

引數

引數	描述	必填
server	用於獲取指標的 Prometheus 伺服器。	是

promtool debug all

獲取所有除錯資訊。

引數

引數	描述	必填
server	用於獲取所有除錯資訊的 Prometheus 伺服器。	是

promtool push

推送到 Prometheus 伺服器。

標誌

標誌	描述
--http.config.file	HTTP 客戶端配置檔案，詳細資訊見 https://prometheus.golang.com.tw/docs/prometheus/latest/configuration/promtool

promtool push metrics

將指標推送到 Prometheus 遠端寫入（remote write）（僅用於測試目的）。

標誌

標誌	描述	預設值
--label	要附加到指標的標籤。可以指定多次。	job=promtool
--timeout	等待推送指標的時間。	30s
--header	Prometheus 遠端寫入標頭（header）。
--protobuf_message	寫入時使用的 Protobuf 訊息型別（prometheus.WriteRequest 或 io.prometheus.write.v2.Request）。	prometheus.WriteRequest

引數

引數	描述	必填
remote-write-url	用於推送指標的 Prometheus 遠端寫入 URL。	是
metric-files	要推送的指標檔案，預設從標準輸入讀取。

promtool test

單元測試。

標誌

標誌	描述
--junit	用於儲存 JUnit XML 測試結果的檔案路徑。

promtool test rules

規則的單元測試。

標誌

標誌	描述	預設值
--run ...	如果設定，將僅執行名稱與該正則表示式匹配的測試組。可以指定多次。
--debug	啟用單元測試除錯。	false
--diff	[實驗性] 列印預期輸出與接收到的輸出之間的彩色差異對比。	false
--ignore-unknown-fields	忽略測試檔案中的未知欄位。當你想用自定義元資料擴充套件規則檔案時，這很有用。確保在將這些欄位載入到 Prometheus 伺服器之前將其刪除，因為伺服器預設會進行嚴格檢查。	false

引數

引數	描述	必填
test-rule-file	單元測試檔案。	是

promtool tsdb

執行 tsdb 命令。

promtool tsdb bench

執行基準測試。

promtool tsdb bench write

執行寫入效能基準測試。

標誌

標誌	描述	預設值
--out	設定輸出路徑。	benchout
--metrics	要讀取的指標數量。	10000
--scrapes	要模擬的抓取次數。	3000

引數

引數	描述	預設值
file	包含樣本資料的輸入檔案，預設為 (../../tsdb/testdata/20kseries.json)。	../../tsdb/testdata/20kseries.json

promtool tsdb analyze

分析流失率（churn）、標籤對基數和壓縮效率。

標誌

標誌	描述	預設值
--limit	每個列表中要顯示的條目數。	20
--extended	執行擴充套件分析。
--match	要分析的時間序列選擇器。目前僅支援一組匹配器。

引數

引數	描述	預設值
db path	資料庫路徑（預設為 data/）。	data/
block id	要分析的資料塊（預設為最後一個數據塊）。

promtool tsdb list

列出 TSDB 資料塊。

標誌

標誌	描述
-r, --human-readable	以易讀格式列印數值。

引數

引數	描述	預設值
db path	資料庫路徑（預設為 data/）。	data/

promtool tsdb dump

從 TSDB 匯出資料（時間序列 + 樣本，或者可選地僅時間序列）。

標誌

標誌	描述	預設值
--sandbox-dir-root	用於建立沙箱目錄的根目錄，該沙箱在 WAL 重放生成分片（chunks）時使用（預設是資料庫路徑）。沙箱在結束時會被清理。
--min-time	要匯出的最小時間戳，以 Unix 紀元以來的毫秒數表示。	-9223372036854775808
--max-time	要匯出的最大時間戳，以 Unix 紀元以來的毫秒數表示。	9223372036854775807
--match ...	序列選擇器。可以指定多次。	{__name__=~'(?s:.*)'}
--format	匯出的輸出格式（prom（預設）或 seriesjson）。	prom

引數

引數	描述	預設值
db path	資料庫路徑（預設為 data/）。	data/

promtool tsdb dump-openmetrics

[實驗性] 將 TSDB 中的樣本匯出為 OpenMetrics 文字格式，不包括無法在 OpenMetrics 中表示的原生直方圖和失效標記（staleness markers）。

標誌

標誌	描述	預設值
--sandbox-dir-root	用於建立沙箱目錄的根目錄，該沙箱在 WAL 重放生成分片（chunks）時使用（預設是資料庫路徑）。沙箱在結束時會被清理。
--min-time	要匯出的最小時間戳，以 Unix 紀元以來的毫秒數表示。	-9223372036854775808
--max-time	要匯出的最大時間戳，以 Unix 紀元以來的毫秒數表示。	9223372036854775807
--match ...	序列選擇器。可以指定多次。	{__name__=~'(?s:.*)'}

引數

引數	描述	預設值
db path	資料庫路徑（預設為 data/）。	data/

promtool tsdb create-blocks-from

[實驗性] 從輸入中匯入樣本並生成 TSDB 資料塊。請參閱儲存文件以獲取更多詳細資訊。

標誌

標誌	描述
-r, --human-readable	以易讀格式列印數值。
-q, --quiet	不列印已建立的資料塊。

promtool tsdb create-blocks-from openmetrics

從 OpenMetrics 輸入中匯入樣本並生成 TSDB 資料塊。請參閱儲存文件以獲取更多詳細資訊。

標誌

標誌	描述
--label	要附加到指標的標籤。可以指定多次。例如：--label=label_name=label_value

引數

引數	描述	預設值	必填
輸入檔案	用於從中讀取樣本的 OpenMetrics 檔案。		是
輸出目錄	生成的資料塊的輸出目錄。	data/

promtool tsdb create-blocks-from rules

為新的記錄規則（recording rules）建立資料塊。

標誌

標誌	描述	預設值
--http.config.file	HTTP 客戶端配置檔案，詳細資訊見 https://prometheus.golang.com.tw/docs/prometheus/latest/configuration/promtool
--url	Prometheus API 的 URL（帶有回填規則所需的資料）。	https://:9090
--start	開始回填新規則的時間。必須是 RFC3339 格式的日期或 Unix 時間戳。必填。
--end	如果提供了結束時間，則所提供規則檔案中的所有記錄規則都將回填至該結束時間。預設將回填至 3 小時前。必須是 RFC3339 格式的日期或 Unix 時間戳。
--output-dir	生成的資料塊的輸出目錄。	data/
--eval-interval	如果記錄規則檔案中未設定該值，則在回填時評估規則的頻率。	60s

引數

引數	描述	必填
rule-files	包含一個或多個要回填的記錄規則的檔案列表。檔案中列出的所有記錄規則都將被回填。告警規則（Alerting rules）不會被評估。	是

promtool promql

PromQL 格式化與編輯。需要使用 --experimental 標誌。

promtool promql format

將 PromQL 查詢格式化為美化輸出形式。

引數

引數	描述	必填
query	PromQL 查詢。	是

promtool promql label-matchers

編輯現有 PromQL 查詢中包含的標籤匹配器（label matchers）。

promtool promql label-matchers set

在查詢中設定標籤匹配器。

標誌

標誌	描述	預設值
-t, --type	要設定的標籤匹配器型別。	=

引數

引數	描述	必填
query	PromQL 查詢。	是
name	要設定的標籤匹配器名稱。	是
值	要設定的標籤匹配器的值。	是

promtool promql label-matchers delete

從查詢中刪除標籤。

引數

引數	描述	必填
query	PromQL 查詢。	是
name	要刪除的標籤名稱。	是