应用实时监控服务ARMS：通过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：最大延迟