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

ARMS提供了常見的應用監控指標，如果您需要自訂指標，可以引入OpenTelemetry Java SDK實現。本文介紹如何自訂指標並在Grafana中查詢自訂指標。

前提條件

已經成功接入ARMS應用監控，具體操作，請參見應用接入。
ARMS探針版本為 4.5.0 及以上版本。

引入依賴

請先參考如下Maven代碼引入OpenTelemetry Java SDK。更多資訊，請參見OpenTelemetry官方文檔。

<dependencies>
    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    </dependency>
    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-trace</artifactId>
    </dependency>
    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-bom</artifactId>
      <version>1.23.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

自訂指標步驟

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

Counter（計數器）用途：記錄單調遞增的累積值（只能增加，不能減少）。樣本：HTTP 要求總數、錯誤發生次數。
UpDownCounter（可增減計數器）用途：記錄可增減的非單調值（如當前活躍串連數）。樣本：並發請求數、隊列中的任務數。
Histogram（長條圖，暫不支援）用途：記錄值的分布（如延遲、響應大小），支援計算分位元。樣本：請求延遲分布（P90、P95）、檔案上傳大小。
Gauge（儀錶）用途：捕獲某一時刻的瞬時值（如 CPU 使用率、記憶體佔用）。樣本：系統溫度、即時記憶體使用量量。

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

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

product_seckill_count：搶購次數
product_current_stock：當前庫存

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

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.api.metrics.ObservableLongGauge;

import javax.annotation.PreDestroy;
import java.util.concurrent.atomic.AtomicInteger;

class ProductService {

    // 靜態庫存計數器
    public final AtomicInteger stock = new AtomicInteger(0);

    private LongCounter seckillCounter;
    private ObservableLongGauge observableLongGauge;
    private final AttributeKey<String> seckillResult = AttributeKey.stringKey("seckill_result");

    public ProductService() {
        OpenTelemetry agentOpenTelemetry = GlobalOpenTelemetry.get();

        //定義指標工廠類，注意這裡的product_seckill很重要
        Meter meter = agentOpenTelemetry.getMeter("product_seckill");
        //定義一個counter指標，用於記錄商品搶購的次數
        seckillCounter = meter.counterBuilder("product_seckill_count")
                .setUnit("1")
                .setDescription("seckill product count")
                .build();

        //定義一個gauge指標，代表當前庫存的商品數量
        observableLongGauge = meter.gaugeBuilder("product_current_stock").ofLongs().buildWithCallback((measurement -> {
            //記錄當前商品數量
            measurement.record(stock.get());
        }));

    }
    
    @PreDestroy
    public void clear() {
        observableLongGauge.close(); 
    }
    
    public void setKillProductCount(int count) {
        stock.set(count);
    }

    public String seckillProduct() {
        int currentStock = stock.get();
        if (currentStock <= 0) {
            seckillCounter.add(1, Attributes.of(seckillResult, "failed"));
            return "搶購失敗，商品已售罄";
        }
        // 嘗試扣減庫存
        if (stock.decrementAndGet() >= 0) {
            seckillCounter.add(1, Attributes.of(seckillResult, "success"));
            return "搶購成功，剩餘庫存：" + stock.get();
        } else {
            stock.incrementAndGet(); // 復原
            seckillCounter.add(1, Attributes.of(seckillResult, "success"));
            return "搶購失敗，商品已售罄";
        }
    }
}

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

在控制台修改自訂指標採集配置，新增上一步建立 meter 時填入的參數。

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

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

在ARMS控制台的Prometheus监控 > 实例列表頁面頂部功能表列選擇應用接入的地區。搜尋以metricstore-apm-metrics-custom關鍵字開頭的 Prometheus 儲存執行個體，隨後點擊共用版前往 grafana。
進入 grafana 頁面後，點擊 explore，在資料來源處選擇上一步驟拿到的 prometheus 儲存執行個體

進入對應的 Grafana 檔案夾頁面後，若該檔案夾下尚無儀錶盤，頁面會提示 This folder doesn't have any dashboards yet，可單擊 + Create Dashboard 建立儀錶盤，或通過 Manage dashboards 將已有儀錶盤移入該檔案夾。
您可以通過 PromQL 簡單查詢在代碼中定義的指標，如下圖所示，也可以在 Grafana 中自訂展示大盤。

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

注意事項

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