寫客戶庫 · prometheus

## 編寫客戶端庫 --- 這篇文檔包括Prometheus客戶端API應該提供的基礎功能，目的是在客戶端庫之間保持一致性，輕松上手并避免提供導致用戶出錯的功能。已經有10種客戶端語言支持Prometheus客戶端了，因此我們知道怎么寫好一個客戶端。這個指南旨在幫助寫Prometheus客戶端其他語言的作者寫一個好的庫。 ### Conventions約定 MUST/MUST NOT/SHOULD/SHOULD NOT/MAY在[https://www.ietf.org/rfc/rfc2119.txt](https://www.ietf.org/rfc/rfc2119.txt) 另一個ENCOURAGE的含義是，一個特性對于一個庫是非常好的，但是如果關閉這個特性的話，不會影響庫的使用。記住下面的幾點： - 記住每個特性的好處。 - 常用用例應該很簡單 - 做事情正確方式是簡單的方法 - 更復雜的例子應該是可能的常用用例（有序）： - 沒有標簽的Counters在庫或者應用程序之間傳播 - Summaries/Histograms的時序功能/代碼塊 - Gauges跟蹤事情的當前狀態 - 批量任務監控 ### 總體結構客戶端`必須`在內部寫入回調。客戶通常`應該`遵循下面描述的結構。這個關鍵類是`Collector`。這個有一個典型的方法`collect`, 返回0~N個度量指標和這些指標的樣本數據。`Collector`用`CollectorRegistry`進行注冊。通過傳遞`CollectorRegistry`給稱之為`bridge`的class/method/function來暴露數據。該`bridge`返回Prometheus支持的數據格式數據。每次這個`CollectorRegistry`被收集時，都必須回調`Collector`的collect方法。和用戶交互最多的接口是`Counter`, `Gauge`, `Summary`和`Histogram Collectors`。這些表示單個度量指標，寫的代碼覆蓋絕大多數的用例。更高級的用例（例如來自其他監控/檢測系統的代理）需要編寫一個自定義`Collector`收集器。有人也可能像寫一個帶有`CollectorRegistry`的"bridge"，以不同的監控/測量系統理解的格式生產數據, 允許用戶只需要考慮一個測量系統。 `CollectorRegistry`應該提供`register()/unregister()`方法，以及一個`Collector`應該注冊多個`CollectorRegistrys` 客戶庫必須是線程安全的。對于非面向對象的客戶端，如：C語言，客戶庫編寫在實踐中應該遵循這種結構的理念。 #### 命名客戶庫應該遵循`function/method/class`在這個文檔中提及的命名規則，記住他們正在使用的語言命名規范。例如：`set_to_current_time()`對于python而言是非常好的方法名稱，`SetToCurrentTime`對于Go語言是更好的，`setToCurrentTime()`對于Java是更好的。由于技術原因（例如：不允許功能重載），名稱不能，文檔/幫助文檔應該將用戶指向其他名稱。庫禁止提供與此處給出的相同或者相似`functions/methods/classes`，但具有不同的語義。 ### Metrics `Counter`、`Gauge`、`Summary`和`Histogram`度量指標類型是最主要的接口。 `Counter`和`Gauge`必須是客戶庫的一部分。`Summary`和`Histogram`至少被提供一個。這些主要用作文件靜態變量，也就是說，全局變量與他們正在調試的代碼在同一個文件中定義。客戶端庫應該啟用此功能。常見的用例是整體測試一段代碼，而不是在對象的一個實例上下文中的一段代碼。用戶不必擔心在他們的代碼中管理他們的指標，客戶端庫應該為他們做到這一點（如果不這樣做，用戶將會圍繞庫寫一個`wrapper`, 使其更容易，少即是多）。必須有一個默認的`CollectorRegistry`，四種度量指標類型必須在不需要用戶任何干預下，就能完成默認被注冊，同時也提供一種別的注冊方法，用于批處理作業和單元測試。自定義的`Collectors`也應該遵循這點。究竟應該如何創建度量指標因語言而異。對于某些語言（Go，Java），builder是最好的，對于其他（Python）函數參數足夠豐富，可以在一個調用中執行。例如，一個簡單的Java客戶端，我們可以這樣寫： ```Java class YourClass { static final Counter requests = Counter.build() .name("requests_total") .help("Requests.").register(); } ``` 上面的例子，使用默認的`CollectorRegistry`進行注冊。如果只是調用build()方法，度量指標將不會被注冊（對于單元測試來說很方便），你還可以將`CollectorRegistry`傳遞給register()(方便批作業處理)。 #### Counter `Counter`[https://prometheus.io/docs/concepts/metric_types/#counter]是一個單調遞增的計數器。它不允許counter值下降，但是它可以被重置為0（例如：客戶端服務重啟）。一個counter必須有以下方法： - `inc()`: 增量為1. - `inc(double v)`: 增加給定值v。必須檢查v>=0。 Counter在給定代碼段拋出/引發異常的方式，也可以只選擇某些類型的一場，這是Python中的count_exceptions。 Counters必須從0開始。 #### Gauge [Gauge](https://prometheus.io/docs/concepts/metric_types/#gauge)表示一個可以上下波動的值。 gauge必須有以下的方法： - `inc()`: 每次增加1 - `inc(double v)`: 每次增加給定值v - `dec()`: 每次減少1 - `dec(double v)`: 每次減少給定值v - `set(double v)`: 設置gauge值成v Gauges值必須從0開始，你可以提供一個從不等于0的值開始。 gauge應該有以下方法： - `set_to_current_time()`: 將gauge設置為當前的unix時間（以秒為單位）。 gauge被建議有： - 一種在某些代碼/方法中跟蹤正在進行的請求方法。這是python種的`track_inprogress`。執行一段代碼，設置gauge類型數據樣本值為這段代碼執行的時間，這對于批量任務是非常有用的。在Java中是`startTimer/setDuration`，在python中是`time()` decorator/上下文管理器。這應該符合在`Summary`和`Histogram`中的pattern(通過`set()`而不是`observe()`)。 #### Summary [summary](https://prometheus.io/docs/concepts/metric_types/#summary)通過時間滑動窗口抽樣觀察（通常是要求持續時間），并提供對其分布、頻率和總和的即時觀察。 summary不允許用戶設置"quantile"作為一個標簽，因為這個名稱已在內部使用，用來指定分位數。summary鼓勵提供“quantile”導出，雖然這些不能被匯總，而且需要大量時間。summary必須允許沒有quantiles，因為只有`_count/_sum`是飛鏟更擁有的，這必須是默認值。 summary必須有以下方法： - `observe(double v)`: 觀察被給定值 summary應該有以下方法： - 統計用戶執行代碼的時間，以秒為單位。在python中，這是`time()`decorateor/context管理器。在Java中這是`startTimer/observeDuration`。不能提供秒意外的單位（如果用戶想要別的，自己手動做）。這應該遵循Gauge/Histogram相同的模式。 Summary `_count/_sum`必須從0開始。 #### Histogram [Histogram](https://prometheus.io/docs/concepts/metric_types/#histogram)允許時間的可聚合分布，如：請求延遲。每個bucket中都會有一個count值, 表示累加的樣本數量值一個histogram直方圖不允許使用`le`作為一個標簽，它已經內部用于在分bucket時的步長大小。直方圖必須提供一個方法來手動選擇buckets。應該提供一linear(start, width, count)和exponential(start，factor, count）方式設置buckets的方法。參數count值必須是有界的直方圖應該具有與其他客戶端庫相同的默認值，創建度量指標后bucket不能再更改。一個直方圖必須有下面的方法： - `observe(double v)`: 觀察給定值直方圖應該有以下的方法：統計代碼執行時間的一些方法，以秒為單位。在Python中是`time()`decorator/context管理器。在Java中是`startTimer/observeDuration`。不提供秒以外的單位（如果用戶需要別的，可以手動做）。這應該遵循與Gauge/Summary相同的模式。直方圖`_count/_sum`和buckets必須從0開始。進一步的度量指標考量提供額外的功能，超出以上記錄的指標，對于給定的語言是有意義的如果有一個常見用例，例如：次優度量指標/標簽布局或者在客戶端進行計算，可以使其更簡單。 #### 標簽標簽Labels是Prometheus系統最強大的特性之一，但是很容易被濫用。因此，客戶端庫必須非常小心地如何向用戶提供labels。客戶庫在任何情況下禁止用戶對于"Gauge/counter/summary/histogram"或者由庫提供的其他Collector的度量指標，提供不相同的標簽列表。如果你的客戶庫在收集樣本數據時間內對其進行了度量指標的驗證，那么它也可以為自定義Collector進行驗證。雖然標簽功能很強大，但大多數度量指標沒有標簽。因此，API允許有標簽，但不是強制的。客戶庫必須允許在Gauge/Counter/Summary/Histogram創建時間可選地指定標簽名稱列表。客戶端庫應該支持任意大小的標簽列表。客戶端庫必須驗證標簽名稱是否符合[要求](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)。提供訪問度量指標名稱列表最常用的方法, 是通過`labels()`方法，該方法可以獲取標簽值列表，或者獲取Map鍵值對(標簽名稱：標簽值)列表，并返回“child”，然后在Child上調用常用的`.inc()/.desc()/.observe()`等方法。 `label()`返回Child應該由用戶緩存，以避免再次查找，這在延遲至關重要的代碼中很重要。帶有標簽的度量指標應該支持一個具有與`labels()`相同簽名的`remove()`方法，它將從不再導出它的度量標準中刪除一個Child，另一個clear()方法可以從度量指標中刪除所有的`Child`。應該有一種使用默認初始化給定Child的方法，通常只需要調用labels()。沒有標簽的度量指標必須被初始化，已避免缺少度量指標的問題。 #### 度量指標名稱度量指標名稱補習遵循規范。與標簽名稱一樣，必須滿足使用`Counter/Gauge/Summary/Histogram`和庫中提供的任意其他`Collector`的使用。許多客戶庫提供三個部分的名稱：`namespace_subsystem_name`, 其中只有該`name`是強制性的。不鼓勵使用動態/自動生成的度量指標名稱或者其子部分，除非自定義"Collector"是從其他工具/監控系統代理的。你可以使用標簽名稱替代動態或者自動生成的度量指標名稱。 #### 度量指標描述和幫助 `Gauge/Counter/Summary/Histogram`要求必須提供度量指標的desc和help。帶有自定義Collector的客戶庫，在度量指標上必須有desc/help 建議將度量指標名稱的desc/help作為強制性參數，但不需要檢查其長度，提供Collectors的庫應該要有一個比較好的desc，幫助理解其含不需要檢查其長度，提供Collectors的庫應該要有一個比較好的desc，幫助理解其含義. ### 導出客戶端必須實現一個文檔[導出格式](https://prometheus.io/docs/instrumenting/exposition_formats)。客戶端可以實現多種導出格式。而且是可讀性非常好的格式。如果有疑問，請去文本格式。它不具有依賴性（protobuf），往往易于生成，是可讀取的，并且protobuf的性能優勢對于大多數用例來說并不重要。如果可以在沒有顯著的資源成本情況下實現，可以重現可用的度量指標順序（特別是對于人類可讀格式）。 ### 標準化和運行時收集器客戶端庫應該提供標準導出，如下所述：這些應該作為自定義Collectors實現，默認情況下在默認的CollectorRegistry上注冊。應該有一種方法來禁用這些，因為有一些非常適用于他們的使用方式。 #### 處理度量指標這些導出應該有前綴process_。如果一種語言或者運行時沒有公開其中一個變量，它不會被導出它。所有內存值以字節為單位，以時間戳/秒為單位。 | 度量指標名稱 | 含義 | 單位 | | --------------------------| :-------------------------:| ---------:| | process_cpu_seconds_total | 用戶和系統CPU花費的時間 | 秒 | | process_open_fds | 打開的文件描述符數量 | 文件描述符| | process_max_fds | 打開描述符最大值 | 文件描述符| | process_virtual_memory_bytes| 虛擬內存大小 | 字節| | process_resident_memory_bytes| 駐留內存大小|字節| | process_heap_bytes | 進程head堆大小| 字節| | process_start_time_seconds| unix時間 | 秒| ### 運行時度量指標另外，客戶端庫也被提供給他們的語言運行時（如：垃圾回收統計信息）的指標方面，提供了一些合適的前綴，比如： go_, hostspot_等。 ### 單元測試客戶端庫應該包含核心工具庫和展示的單元測試。客戶端庫被鼓勵提供方便用戶單元測試其使用的工具代碼。例如，python中的CollectorRegistry.get_sample_value。 ### 包和依賴理想情況下，客戶端庫可以包含在任何應用程序中以添加一些工具，而無需擔心它會破壞應用程序。因此，當向客戶端添加依賴關系時，建議謹慎。例如：如果用戶添加使用添加版本1.4的Protobuf的Prometheus客戶端庫，但是應用程序在其他地方使用1.2，會發生什么？建議在可能出現的情況下，將核心工具和給定格式的度量指標/展示分開。例如：Java簡單客戶端模塊沒有依賴關系，而simpleclient_servlet具有Http比特位。 ### 性能考慮由于客戶端庫必須是線程安全的，因此需要進行某種形式的并發控制，并且必須考慮多核機器和應用程序的性能。在我們的經驗中，性能最差的是互斥體。處理器原子指令往往處于中間，并且通常可以接受。避免不同CPU突然使用RAM的方法效果最好，例如：Java簡單客戶端中的DoubleAdder。有內存成本。如上所述，labels()的結果應該是可緩存的。趨向于使用標簽返回度量的并發映射往往相對較慢。沒有標簽的特殊套管指標，已避免labels()，像查找可以幫助很多。度量指標應該避免阻塞，當它們遞增/遞減/設置等時，因為整個應用程序在持續獲取時不會被組織。主要工具操作的基準（包括labels）得到了鼓勵。應該牢記資源消耗，特別是RAM。考慮通過stream傳輸結果來減少內存占用，并且可能對并發獲取的數量有限制。