Application Real-Time Monitoring Service：通過OpenTelemetry Python SDK自訂指標

步驟 1：代碼中增加自訂指標

請先參考如下命令引入 OpenTelemetry Python SDK。更多資訊，請參見 OpenTelemetry 官方文檔。

pip install opentelemetry-api

OpenTelemetry 當前支援的指標類型大體有以下四類，目前除了 Histogram（長條圖），其餘類型 ARMS 都支援。

• Counter：累加計數器，只增不減。

• UpDownCounter：可增可減的計數器。

• Gauge：瞬時值指標。

• Histogram：長條圖，用於記錄值的分布（暫不支援）。

下面的代碼是一段搶購商品的簡單範例程式碼，其中定義了兩個指標：

• product_seckill_count：搶購次數

• product_current_stock：當前庫存

其中在擷取定義指標的工廠類 meter 時，傳入了一個 "product_seckill" 參數，這個可以理解為一個分組的概念，後續通過該 meter 定義的指標都在該分組下，後續配置中會用到該分組。

from fastapi import FastAPI
from opentelemetry.metrics import get_meter, Observation

app = FastAPI()

# 類比庫存
stock = {"count": 100}

# 定義指標工廠類，注意這裡的 product_seckill 很重要
meter = get_meter("product_seckill", "1.0.0")

# 定義一個 counter 指標，用於記錄商品搶購的次數
seckill_counter = meter.create_counter(
    name="product_seckill_count",
    unit="1",
    description="seckill product count",
)


# 定義一個 gauge 指標，代表當前庫存的商品數量
def stock_callback(options):
    # 記錄當前商品數量
    yield Observation(stock["count"])


observable_gauge = meter.create_observable_gauge(
    name="product_current_stock",
    callbacks=[stock_callback],
    unit="1",
    description="current stock of product",
)


@app.post("/seckill")
def seckill_product():
    if stock["count"] <= 0:
        seckill_counter.add(1, {"seckill_result": "failed"})
        return {"message": "搶購失敗，商品已售罄"}
    stock["count"] -= 1
    seckill_counter.add(1, {"seckill_result": "success"})
    return {"message": f"搶購成功，剩餘庫存：{stock['count']}"}


@app.post("/stock/{count}")
def set_stock(count: int):
    stock["count"] = count
    return {"message": f"庫存已設定為：{count}"}


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

之後參考接入文檔掛載探針啟動此應用

aliyun-instrument python3 main.py

步驟 2：在控制台配置指標採集

在控制台修改探針採集配置，新增上一步建立 meter 時填入的參數 product_seckill。

該配置需探針 2.8.0 及以上版本方可生效，且無需重啟應用。完成配置後，單擊儲存。

如果暫時無法使用ARMS控制台，或者動態配置由於網路等原因無法下發，可以在本地添加如下環境變數進行配置：

export APSARA_APM_METRIC_CUSTOM_ENABLED=true
# 可選：配置 allowlist scope，不配置的話預設採集所有scope
export APSARA_APM_METRIC_CUSTOM_INCLUDE_SCOPE_LIST="my.scope,other.scope"

步驟 3：查看指標並配置警示

1. 在ARMS控制台的Prometheus監控 > 執行個體列表頁面頂部功能表列選擇應用接入的地區。搜尋以metricstore-apm-metrics-custom關鍵字開頭的 Prometheus 儲存執行個體，隨後點擊共用版前往 grafana。

2. 進入 grafana 頁面後，點擊 explore，在資料來源處選擇上一步驟拿到的 prometheus 儲存執行個體

進入對應的 Grafana 檔案夾頁面後，若該檔案夾下尚無儀錶盤，頁面會提示 This folder doesn't have any dashboards yet，可單擊 + Create Dashboard 建立儀錶盤，或通過 Manage dashboards 將已有儀錶盤移入該檔案夾。

3. 您可以通過 PromQL 簡單查詢在代碼中定義的指標，如下圖所示，也可以在 Grafana 中自訂可觀測頁面。

自此通過 OpenTelemetry SDK 定義的指標就已經成功上報並儲存到 ARMS 服務端 Prometheus 儲存執行個體中了，後續您可以對 Prometheus 儲存執行個體中的指標建立Prometheus警示規則。

注意事項

• 目前 ARMS 指標上報間隔為 15 秒一次。

• 對於 Counter 類指標，ARMS 目前上報的不是累計值，而是一個上報周期內的增加值，即每 15 秒該指標的增加值。

• 由於ARMS的指標模型與OpenTelemetry目前不是完全對齊的，所以像Histogram類型的自訂指標上報上去的資料與OpenTelemetry的Histogram會有部分區別，對於 custom 類型的 histogram，會把一個指標拆成以下幾個：

  • {name}_count：採樣次數，即這個 histogram 收到了多少個點

  • {name}_sum：所有採樣值的總和

  • {name}_min：所有採樣值中的最小值（有 min 資料時才產生）

  • {name}_max：所有採樣值中的最大值（有 max 資料時才產生）

例如 custom.latency指標會拆成：

1. custom.latency_count：請求次數

2. custom.latency_sum：延遲總和

3. custom.latency_min：最小延遲

4. custom.latency_max：最大延遲