Prometheus基礎應用

簡介

Prometheus使用掃盲，包含基礎的概念和操作說明，基於官網和個人測試。

versoin: 2.14

官網

GitHub

安裝

prometheus安裝運行非常方便，下載后解壓，運行根目錄下的可執行程序prometheus即可。

啟動參數

常用啟動參數說明

參數	說明
--version	打印版本信息
--config.file="prometheus.yml"	配置文件位置
--web.listen-address="0.0.0.0:9090"	訪問prometheus的IP端口，0.0.0.0支持本地和遠程訪問，當指定固定IP時只能使用配置IP
--web.read-timeout=5m	請求prometheus時超時時間
--web.max-connections=512	最大並發連接
--web.external-url=<URL>	可用於設置prometheus訪問的根路徑，默認/，如：設置為“root”時，訪問web、API變為http://IP:9090/root/
--web.enable-lifecycle	開啟http的shutdown和reload操作。通過PUT(POST) /-/reload重新加載prometheus配置文件，通過PUT(POST) /-/quit遠程關閉prometheus。
--web.enable-admin-api	開啟管理員的api端點
--web.cors.origin=".*"	跨域支持
--storage.tsdb.path="data/"	數據存儲目錄，默認[prometheus_dir]/data/
--storage.tsdb.retention =STORAGE.TSDB.RETENTION	已過期，使用--storage.tsdb.retention.time
--storage.tsdb.retention.time =STORAGE.TSDB.RETENTION.TIME	數據存儲過期時間，如果未配置--storage.tsdb.retention或--storage.tsdb.retention.size，則默認15天
--storage.tsdb.retention.size =STORAGE.TSDB.RETENTION.SIZE	數據存儲大小，Test版參數，后續版本可能改動
--storage.tsdb.wal-compression	預寫入日志壓縮
--storage.remote.read-sample-limit=5e7	一次抓取樣本的最大數量，0為不限制，默認5e7，流式響應忽略此配置
--storage.remote.read-concurrent-limit=10	讀取數據的並發數，默認10，0無限制
--storage.remote.read-max-bytes-in-frame=1048576	一個frame最大讀取數據的大小，默認1M，客戶端也可以做限制
--alertmanager.notification-queue-capacity=10000	alertmanager通知隊列大小
--alertmanager.timeout=10s	向alertmanager發送告警的超時時間
--query.timeout=2m	查詢超時時間
--query.max-concurrency=20	查詢最大並發線程
--query.max-samples=50000000	查詢可載入內容的最大數據，
--log.level=info	日志等級：debug, info, warn, error
--log.format=logfmt	日志格式：logfmt, json

管理API

API	描述
GET /-/healthy	健康檢查，status 200判定健康
GET /-/ready	服務可用檢查，status 200判定可提供查詢服務
PUT /-/reload POST /-/reload	重新加載配置，包括yaml和rule，需開啟 --web.enable-lifecycle
PUT /-/quit POST /-/quit	關閉程序，需開啟 --web.enable-lifecycle

參見MANAGEMENT API

本地存儲

（1）存儲方式

​ 樣本被分組存儲，每組存儲兩個小時的樣本和元數據、索引，樣本以一個或多個chunk文件存儲，執行數據刪除時首先執行的是邏輯刪除，而非物理刪除。

.
├── 01DWGZHP8QP5WC7XJF3ECEEYH1  //分組
│   ├── chunks                  //樣本
│   │   └── 000001
│   ├── index                   //索引
│   ├── meta.json               //元數據 
│   └── tombstones
├── 01DWH1PBH94RF9E5H9JV1JV040
│   ├── chunks
│   │   └── 000001
│   ├── index
│   ├── meta.json
│   └── tombstones
├── lock
├── queries.active
└── wal                          //預寫入日志
    ├── 00000004
    ├── 00000005
    ├── 00000006
    ├── 00000007
    ├── 00000008
    └── checkpoint.000003
        └── 00000000

（2）預寫入日志（WAL）

​ chunk中寫入的數據首先保存在內存里，未直接持久化。通過write-ahead-log (WAL) 預寫入日志可以確保在prometheus崩潰后重新啟動時回放日志，恢復數據。默認128MB的segments，支持壓縮（需手動開啟），最大支持10%時間的block增長，或者21天，先到為准。

注：壓縮功能是2.12版本開始引入，因wal格式內容發生變化，如果回退至2.11或以下的版本，需刪除wal。

可通過--storage.tsdb.wal-segment-size設置wal的segments大小。

參見Local storage、Compaction

配置

Prometheus配置

具體配置項內容較多，主要描述整體配置模塊及主要作用，參數明細參見官方描述。

# 配置全局指標采集周期、超時、告警采集頻率等
global:
  
# 全局告警規則文件文件列表
rule_files:

# 指標數據采集，包含多個job_name，配置對應的地址、采集接口等
scrape_configs:
 
# 關聯告警模塊Alertmanager的相關配置
alerting:

# 使用三方模塊存儲數據時的遠程寫配置
remote_write:

# 使用三方模塊存儲數據時的遠程讀配置
remote_read:

規則配置

prometheus規則配置包括兩種規則：

• recording rules：記錄規則，用於對指定計算的預處理，通過服務端定時執行，客戶端在查詢時就不需要根據PromQL表達式實時計算，可以直接返回結果。
• alerting rules：告警規則，配置滿足某一特定規則后觸發告警。

規則文件在服務啟動時會自動校驗配置文件的語法、格式，同時提供離線工具校驗promtool（prometheus安裝根目錄下）:

./promtool check rules /path/to/example.rules.yml

groups:
  # [ - <rule_group> ],一組規則
  
  # 執行頻率，可選，默認global.evaluation_interval
  interval: 15s
  # 當前配置文件中唯一名稱
  - name: example
    # 規則
    rules:
    
    # recording rules
    # record指標名稱
    - record: job:http_inprogress_requests:sum
      # PromQL表達式
      expr: sum(http_inprogress_requests) by (job)
      # 記錄規則結果中標簽，新增/覆蓋原始
      labels:
        type: recording
        
    # alerting rules
    # alert指標名稱
    - alert: HighRequestLatency
      # PromQL表達式
      expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
      # 滿足告警條件持續多久后，觸發告警
      for: 10m
      # 告警標簽，新增/覆蓋原始
      labels:
        severity: page
      # 告警注釋
      annotations:
        summary: High request latency

PromQL

概述

返回類型

Prometheus通過自身提供的PromQL語法查詢或統計，查詢的結果包含四種數據類型：

• Instant vector ：瞬時向量，一組時序數據，每個時序數據包含唯一的樣本，如*_tatal{}、*_count{}
• Range vector：范圍向量，一組時序數據，每個時序數據包含范圍內的樣本，如*{}[1m]
• Scalar ：標量，浮點數字，如sum()、count()
• String：字符串，未使用

參見Expression language data types

時序選擇器

（1）瞬時向量

http_requests_total{job="prometheus",group="canary"}

針對瞬時向量http_requests_total，通過{}描述一組選擇器，等同SQL中where條件，支持四種操作符：

=等於、!=不等於、=~ 正則匹配、!~ 正則不匹配

支持的正則表達式語法RE2

（2）范圍向量

http_requests_total{job="prometheus"}[5m]

范圍向量通過[]描述查詢的范圍，等同SQL的between，支持以下六種時間單位：

s秒、m 分、h時、d天、w周、y年

（3）偏移量

sum(http_requests_total{method="GET"} offset 5m)
rate(http_requests_total[5m] offset 1w)

通過offset查詢指定偏移范圍的數據，必須緊跟在選擇器之后，不合法使用：

sum(http_requests_total{method="GET"}) offset 5m // INVALID.

參見Time series Selectors

子查詢

針對給定的范圍和顆粒度進行瞬時向量查詢，結果為范圍向量：

rate(http_requests_total[5m])[20m:2m]

解析：

1. 范圍：20m
2. 顆粒度：2m
3. 瞬時向量：http_requests_total[5m]
4. 范圍向量：20m內，每隔2m的5m增長率

操作符

二元運算符

（1）算數運算符：

+加、-減、*乘、/除、%取余、^乘方

可用在以下操作：

• 兩個scalar
• instant vector和scalar，instant vector中每個樣本的值都會與scalar進行運算
• 兩個instant vector，取兩個vector的樣本交集進行運算，結果存放在新的vector中，結果的指標名稱將被刪除。

（2）比較運算符：

==等於、!=不等於、> 大於、<小於、>=大於等於、<=小於等於

默認情況下，比較的運算結果，是返回兩個向量中滿足比較的樣本，可通過運算符后加關鍵字bool來改變比較的結果，0表示false，1表示true，支持以下幾種類型的比較：

• 兩個scalar，必須在運算符后添加bool，返回0/1
• instant vector和scalar，scalar與instant vector中每個樣本進行比較。當使用bool時，返回instant vector中全量樣本的比較結果；未使用bool時，僅返回滿足比較的樣本。
• 兩個instant vector，取兩個vector的樣本交集進行比較。當使用bool時，返回所有交集樣本的比較結果（0或1）；未使用bool時，僅返回滿足比較的樣本內容（交集但不匹配也不會返回）。

（3）邏輯運算符

and與、or或、unless補

說明：v1 unless v2所獲取的結果是v1中有，v2中沒有的，返回內容是v1中的樣本。

（4）優先級

1. ^
2. *, /, %
3. +, -
4. ==, !=, <=, <, >=, >
5. and, unless
6. or

優先級自上至下，運算順序從左到右，^除外，從右到左。

向量匹配

（1）one-to-one

兩個向量在操作時vector1 <operator> vector2，默認匹配是按照標簽和標簽值全部匹配時才可以進行運算，使用ignoring關鍵字忽略一組匹配的標簽，使用on關鍵字僅匹配指定的一組標簽。

# 忽略le標簽，匹配handler標簽
prometheus_http_response_size_bytes_bucket{handler="/",le="100"} / ignoring (le) prometheus_http_response_size_bytes_count

# 使用handler匹配
prometheus_http_response_size_bytes_bucket{handler="/",le="100"} / on (handler) prometheus_http_response_size_bytes_count

（2）many-to-one / one-to-many

比較復雜，多數情況使用ignoring就可以處理，不做描述。

聚合運算

• sum(v instant-vector) 和
• min(v instant-vector) 最小值
• max(v instant-vector) 最大值
• avg(v instant-vector) 平均值
• stddev(v instant-vector) 標准差
• stdvar(v instant-vector) 標准方差
• count(v instant-vector) 樣本數量
• count_values(lable_name string, v instant-vector) 計算向量樣本中各個value出現的次數
• bottomk(k scalar, v instant-vector) 取最小k個value
• topk(k scalar, v instant-vector) 取最大的k個value
• quantile(φ scalar, v instant-vector) 計算分位數

使用without排除結果中的標簽，by根據指定標簽分組統計，僅適用輸入向量的處理，語法：

<aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)
或者
<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

例：

# 指標prometheus_http_response_size_bytes_bucket根據handler標簽分組求和
sum by (handler) (prometheus_http_response_size_bytes_bucket) 

# 指標prometheus_http_response_size_bytes_bucket排除handler標簽后，分組求和
sum(prometheus_http_response_size_bytes_bucket) without (handler)

函數

• abs(v instant-vector)：返回給定瞬時向量的所有樣本的絕對值
• absent(v instant-vector)：如果給定瞬時向量包含樣本，則返回空；如果給定向量為空，則返回不包含指標名的樣本，value為1
• ceil(v instant-vector)：瞬時向量值向上取整
• changes(v range-vector)：返回給定范圍向量的值變化次數，即value的枚舉數
• clamp_max(v instant-vector, max scalar)：設定給定瞬時向量的上限值：低於給定max保持原值，高於max則為max
• clamp_min(v instant-vector, min scalar)：設定給定瞬時向量的下限值：高於給定min保持原值，低於min則為min
• day_of_month(v=vector(time()) instant-vector)：返回給定的UTC時間是當月的第幾天，取值1-31
• day_of_week(v=vector(time()) instant-vector)：返回給定的UTC時間是本周的第幾天，取值0-6，0為周日
• days_in_month(v=vector(time()) instant-vector)：返回給定的UTC時間的月份有多少天，取值28-31
• delta(v range-vector)：計算范圍向量中第一個值和最后一個值的差值，用於gauge
• deriv(v range-vector)：使用簡單線性回歸計算范圍向量中時間序列的二階導數，用於gauge
• exp(v instant-vector)：返回給定瞬時向量值的指數函數值，即e^value，value很大時返回+Inf。特殊情況：Exp(+Inf) = +Inf、Exp(NaN) = NaN
• floor(v instant-vector)：瞬時向量向下取整
• histogram_quantile(φ float, b instant-vector)：計算給定瞬時向量的百分位數（0<=φ<=1）,用於直方圖(histogram)的bucket百分位數計算。如果直方圖buckets少於2，返回NaN，如果給定的百分位數φ<0，返回-Inf；φ>1，返回+Inf
• holt_winters(v range-vector, sf scalar, tf scalar)：生成給定向量的平滑值，平滑因子sf越低老數據越重要，趨勢因子tf越高趨勢數據越重要，用於gauge
• hour(v=vector(time()) instant-vector)：返回給定的UTC時間的小時，取值0-23
• idelta(v range-vector)：計算范圍向量最后兩個值的差，用於gauge
• increase(v range-vector)：計算范圍向量最后一個值減去第一個值的差，僅應用於counter，打破單調性時（如由於目標重啟導致的計數器重置）會自動調整。
• irate(v range-vector)：計算范圍向量的瞬時增長率，樣本最后兩個值的增長率，僅適用於計算快速變化的值，趨勢分析使用rate()，打破單調性時（如由於目標重啟導致的計數器重置）會自動調整
• label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...)：對瞬時向量中每一個樣本，將src_lable(范圍向量中指標的標簽)的value使用separator拼接，結果存放在新標簽dst_label中，相當於給原始樣本新增了一個dst_label
• label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)：對瞬時向量的每個樣本，滿足正則regex匹配的標簽src_label，將指定的正則子組replacement（用$1、$2...表示）放入目標標簽dst_label
• ln(v instant-vector)：瞬時向量樣本自然對數(e)，特殊情況：ln(+Inf) = +Inf、ln(0) = -Inf、ln(x < 0) = NaN、ln(NaN) = NaN
• log2(v instant-vector)：瞬時向量2的對數
• log10(v instant-vector)：瞬時向量10的對數
• minute(v=vector(time()) instant-vector)：給定的UTC時間是當前小時的多少分鍾，取值0-59
• month(v=vector(time()) instant-vector)：給定的UTC時間是當前年份第幾個月，取值1-12
• predict_linear(v range-vector, t scalar)：基於范圍向量使用簡單線性回歸，預測從當前開始t秒后的值
• rate(v range-vector)：計算范圍向量的平均增長率，打破單調性時（如由於目標重啟導致的計數器重置）會自動調整，適用趨勢分析和告警，用於counter類型。與聚合操作符或聚合函數一起使用時，需先執行rate再執行聚合，否則rate無法檢測到重置。
• resets(v range-vector)：返回范圍向量中計時器的重置次數，以瞬時向量返回，兩個連續樣本數值發生減少則認為重置，用於counter
• round(v instant-vector, to_nearest=1 scalar)：使用瞬時向量樣本進行計算，返回值是to_nearest的整數倍，該值與樣本值偏差最小。如樣本值為sample_value，存在(n-1)*to_nearest < sample_value < n*to_nearest，則與sample_value差值小的一側值為計算結果，如果差值相等，選較大值。
• scalar(v instant-vector)：給定瞬時向量的樣本值轉為標量，樣本數量=0或>1時，返回NaN
• sort(v instant-vector)：瞬時向量樣本值升序排列
• sort_desc(v instant-vector)：瞬時向量樣本值降序排列
• sqrt(v instant-vector)：瞬時向量的樣本值開方
• time()：返回表達式計算的時間。
• timestamp(v instant-vector)：返回瞬時向量中每個樣本的時間戳。
• vector(s scalar)：scalar轉為vector，不含標簽
• year(v=vector(time()) instant-vector)：返回給定時間的年
• <aggregation>_over_time()：范圍向量聚合統計類函數
  • avg_over_time(range-vector): 平均值
  • min_over_time(range-vector): 最小值
  • max_over_time(range-vector): 最大值
  • sum_over_time(range-vector): 求和
  • count_over_time(range-vector): 數量
  • quantile_over_time(scalar, range-vector): scalar在vector中的分位數
  • stddev_over_time(range-vector): 標准差
  • stdvar_over_time(range-vector): 標准方差

詳細描述，見FUNCATIONS。

HTTP API

API接口請求返回2xx狀態碼，響應數據是json格式。

異常請求返回：

• 400 Bad Request 參數錯誤
• 422 Unprocessable Entity 表達式無法執行
• 503 Service Unavailable 請求超時或被丟棄

響應數據如下：

{
  "status": "success" | "error",   // 請求狀態
  "data": <data>,                  // 響應數據

  // 請求異常時返回，status為error
  "errorType": "<string>",
  "error": "<string>",

  // 請求存在警告時返回
  "warnings": ["<string>"]
}

表達式查詢

當查詢返回結果超過server端字符限制時，可將參數使用URL編碼，並指定請求方式為POST，請求頭Content-Type: application/x-www-form-urlencoded。

查詢返回格式：

{
  "resultType": "matrix" | "vector" | "scalar" | "string",   // 響應格式
  "result": <value>                                          // 響應值
}

上述返回為[HTTP API](#HTTP API)中<data>標簽內容，返回具體格式見響應格式。

查詢主要包含以下兩種：

（1）瞬時查詢

API：

GET /api/v1/query
POST /api/v1/query

Params：

• query=: PromQL表達式
• time=: 時間，默認當前服務器時間，可選
• timeout=: 超時時間，默認使用-query.timeout，可選

（2）范圍查詢

API：

GET /api/v1/query_range
POST /api/v1/query_range

Params：

• query=: PromQL表達式
• start=: 開始時間
• end=: 結束時間
• step=: 查詢周期間隔
• timeout=: 超時時間，默認使用-query.timeout，可選

響應格式

API表達式查詢的返回格式，包括matrix, vector, scalar, string四種，對應PromQL定義的四種返回類型，以下描述的返回格式，均為表達式查詢中result標簽內容。

**（1）Range vectors **

范圍向量返回格式定義為matrix：

[
  {
    "metric": { "標簽名": "標簽值", ... },
    "values": [ [ 時間戳, "樣本值" ], ... ]
  },
  ...
]

（2）Instant vectors

瞬時向量格式定義為vector：

[
  {
    "metric": { "標簽名": "標簽值", ... },
    "value": [ 時間戳, "樣本值" ]
  },
  ...
]

**（3）scalar **

標量格式定義為scalar：

[ 時間戳, "數值" ]

**（4）string **

字符串定義為string：

[ 時間戳, "字符串值" ]

元數據查詢

（1）根據標簽查找指標

當查詢返回結果超過server端字符限制時，可將參數使用URL編碼，並指定請求方式為POST，請求頭Content-Type: application/x-www-form-urlencoded。

API：

GET /api/v1/series
POST /api/v1/series

Params：

• match[]=: 一個或多個匹配選擇器，至少一個
• start=: 開始時間
• end=: 結束時間

（2）查詢標簽名

API：

GET /api/v1/labels
POST /api/v1/labels

（3）查詢標簽值

API：

GET /api/v1/label/<label_name>/values

目標查詢

查詢prometheus監控的目標對象的狀態信息。

API：

GET /api/v1/targets

規則查詢

返回當前已加載的預警規則信息，和由實例觸發的告警規則，該新增API穩定性暫時不能保證。

API：

GET /api/v1/rules

告警查詢

返回當前激活的告警列表，該新增API穩定性暫時不能保證。

GET /api/v1/rules

目標元數據查詢

試驗性接口，可能變動，建議不應用。

API:

GET /api/v1/targets/metadata

Params:

• match_target=: 標簽選擇器，為空匹配所有目標
• metric=: 指標名稱，為空匹配所有指標
• limit=: 最大匹配數

AlertManager狀態查詢

告警組件AlertManager狀態查詢。

API：

GET /api/v1/alertmanagers

狀態查詢

查詢當前prometheus相關配置信息。

API：

GET /api/v1/status/config           // 返回當前已加載的配置yaml文件內容，不含注釋
GET /api/v1/status/flags            // 返回prometheus啟動配置項信息
GET /api/v1/status/runtimeinfo      // 返回運行信息，如啟動時間、chunk數、安裝目錄等
GET /api/v1/status/buildinfo        // 返回prometheus版本構建信息

數據庫管理API

所有數據庫管理API需要開啟--web.enable-admin-api。

（1）快照

接口用於保存實時數據的快照，數據存放在<data-dir>/snapshots/<datetime>-<rand>，接口返回生成的數據目錄名稱<datetime>-<rand>。

API：

POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot

Params：

• skip_head=: 跳過頭塊中未壓縮的數據，可選。

（2）刪除

用於刪除時間段內指定的指標數據，數據不會被立即刪除，會在后續清理或調用清理的接口。操作成功會返回204.

API：

POST /api/v1/admin/tsdb/delete_series
PUT /api/v1/admin/tsdb/delete_series

Params：

• match[]=: 一個或多個匹配選擇器，至少一個
• start=: 開始時間，可選，默認最小時間。
• end=: 結束時間，可選，默認最大時間

（3）清理

用於清理 已刪除的數據，會立即釋放磁盤空間，操作成功返回204

API：

POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones