使用 REST API 內嵌 Azure 資源的自訂計量

文章
01/08/2024

本文說明如何透過 REST API 將 Azure 資源的自定義計量傳送至 Azure 監視器計量存放區。當計量位於 Azure 監視器中時，您可以使用這些計量來執行所有使用標準計量的動作。例如，您可以產生圖表和警示，並將計量路由傳送至其他外部工具。

注意

REST API 只允許傳送 Azure 資源的自定義計量。若要傳送其他環境或內部部署資源計量，請使用 Application Insights。

將 REST 要求傳送至內嵌自定義計量

當您將自定義計量傳送至 Azure 監視器時，計量中報告的每個數據點或值都必須包含下列資訊。

驗證令牌
主體
區域
Timestamp
Namespace
名稱
維度索引鍵
維度值
計量值

驗證

若要將自定義計量提交至 Azure 監視器，提交計量的實體需要要求持有人標頭中的有效 Microsoft Entra 令牌。取得有效持有人令牌的支援方式包括：

Azure 資源的受控識別。您可以使用受控識別來授與資源執行特定作業的許可權。例如，允許資源發出有關本身的計量。資源或其受控識別可以授 與其他資源的監視計量發行者 許可權。透過此許可權，受控識別也可以針對其他資源發出計量。
Microsoft Entra 服務主體。在此案例中，Microsoft Entra 應用程式或服務可以獲指派許可權來發出 Azure 資源的相關計量。若要驗證要求，Azure 監視器會使用 Microsoft Entra 公鑰來驗證應用程式令牌。現有的 監視計量發行者 角色已有此許可權。 Azure 入口網站中提供。

服務主體，視其發出自定義計量的資源而定，可以在所需的範圍內提供 監視計量發行者 角色。範例包括訂用帳戶、資源群組或特定資源。

提示

當您要求 Microsoft Entra 令牌發出自訂計量時，請確定要求令牌的物件或資源為 https://monitoring.azure.com/。請務必包含尾端斜線。

取得授權令牌

建立受控識別或服務主體並指派監視 計量發行者 許可權之後，您可以使用下列要求來取得授權令牌：

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

回應本文會以下欄格式顯示：

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

從回應儲存存取令牌，以用於下列 HTTP 要求。

主旨

主旨屬性會擷取要報告自定義計量的 Azure 資源識別碼。這項資訊會在 API 呼叫的 URL 中編碼。每個 API 只能針對單一 Azure 資源提交計量值。

注意

您無法針對資源群組或訂用帳戶的資源識別碼發出自定義計量。

區域

region 屬性會擷取您要為其發出計量之資源的 Azure 區域。計量必須發出至與部署資源的區域相同的 Azure 監視器區域端點。例如，部署在美國西部的 VM 自定義計量必須傳送至 WestUS 區域 Azure 監視器端點。區域資訊也會在 API 呼叫的 URL 中編碼。

時間戳記

傳送至 Azure 監視器的每個數據點都必須以時間戳標示。此時間戳會擷取測量或收集計量值的日期和時間。 Azure 監視器會接受過去 20 分鐘和未來 5 分鐘時間戳的計量數據。時間戳必須是 ISO 8601 格式。

Namespace

命名空間是一種將類似計量分類或分組的方式。藉由使用命名空間，您可以在可能會收集不同深入解析或效能指標的計量群組之間達成隔離。例如，您可能有一 個名為 contosomemorymetrics 的 命名空間，可追蹤分析您應用程式的記憶體使用計量。另一個名為 contosoapptransaction 的命名空間可能會追蹤應用程式中使用者交易的所有計量。

名稱

name 屬性是所報告計量的名稱。通常，名稱的描述性足以協助識別所測量的內容。例如，測量 VM 上使用的記憶體位元組數目的計量。它可能有計量名稱，例如 記憶體位元組使用中。

維度索引鍵

維度是索引鍵/值組，可協助描述所收集計量的其他特性。藉由使用其他特性，您可以收集計量的詳細資訊，以取得更深入的見解。

例如，「使用中的記憶體位元組」計量可能會有一個稱為 Process 的維度索引鍵，可擷取 VM 上每個進程的記憶體位元組數目。藉由使用此金鑰，您可以篩選計量，以查看記憶體特定進程使用多少記憶體，或依記憶體使用量識別前五個進程。

維度是選擇性的，並非所有計量都有維度。自定義計量最多可以有10個維度。

維度值

當您報告計量數據點時，針對所報告計量上的每個維度索引鍵，會有對應的維度值。例如，您可能想要報告 ContosoApp 在您的 VM 上使用的記憶體：

計量名稱會是 [使用中的記憶體位元節]。
維度索引鍵會是 Process。
維度值會 ContosoApp.exe。

當您發佈計量值時，每個維度索引鍵只能指定單一維度值。如果您針對 VM 上的多個行程收集相同的記憶體使用率，您可以報告該時間戳的多個計量值。每個計量值都會為 Process 維度索引鍵指定不同的維度值。

雖然維度是選擇性的，但如果計量後置定義維度索引鍵，則對應的維度值是必要的。

計量值

Azure 監視器會以 1 分鐘的粒度間隔儲存所有計量。在指定的分鐘內，可能需要取樣計量數次。例如根據 CPU 使用率。或者，可能需要針對許多離散事件測量計量，例如登入交易延遲。

若要限制您必須在 Azure 監視器中發出並支付的原始值數目，請在本機預先匯總併發出匯總值：

最小值：分鐘期間所有樣本和測量中觀察到的最小值。
最大值：分鐘期間所有樣本和測量的最大觀察值。
總和：分鐘期間所有樣本和測量中所有觀察值的總和。
計數：在分鐘期間拍攝的樣本和測量數目。

注意

Azure 監視器不支援定義 自定義計量的單位 。

例如，如果在一分鐘內對您的應用程式進行四個登入交易，則每個交易所產生的測量延遲可能是：

交易 1	交易 2	交易 3	交易 4
7 毫秒	4 毫秒	13 毫秒	16 毫秒

然後，產生的計量發行集會是 Azure 監視器：

最小值：4
最大值：16
總和：40
計數：4

如果您的應用程式無法在本機預先匯總，而且需要在收集時立即發出每個離散樣本或事件，您可以發出原始量值值。例如，每次您的應用程式上發生登入交易時，您只要使用單一度量，即可將計量發佈至 Azure 監視器。因此，對於花費 12 毫秒的登入交易，計量發行集會是：

最小值：12
最大值：12
總和：12
計數：1

透過此程式，您可以在指定分鐘內針對相同的計量/維度組合發出多個值。 Azure 監視器接著會擷取指定分鐘發出的所有原始值，並加以匯總。

範例自定義計量發行集

在下列範例中，在虛擬機的計量命名空間記憶體配置檔下，於 [使用] 中建立名為 Memory Bytes 的自定義計量。計量具有稱為 Process 的單一維度。針對時間戳，會針對兩個進程發出計量值。

將下列 JSON 儲存在本機計算機上名為 custommetric.json 的 檔案中。更新 time 參數，使其在最近 20 分鐘內。您無法將計量放入超過 20 分鐘的商店。

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

使用下列變數提交下列 HTTP POST 要求：

location：您要為其發出計量之資源的部署區域。
resourceId：您要追蹤計量之 Azure 資源的資源識別碼。

accessToken：從 取得授權令牌步驟取得的授權令牌 。

curl -X POST 'https://<location>.monitoring.azure.com/<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

檢視您的計量

登入 Azure 入口網站。
在左側功能表中，選取 [ 監視]。
在 [監視] 頁面上，選取 [計量]。
將匯總期間變更為 [過去一小時]。
在 [ 範圍 ] 下拉式清單中，選取您傳送計量的資源。
在 [ 計量命名空間] 下拉式清單中，選取 [ 記憶體配置檔]。
在 [ 計量 ] 下拉式清單中，選取 [ 使用中的記憶體位元節]。

疑難排解

如果您收到一些程式部分的錯誤訊息，請考慮下列疑難解答資訊：

如果您無法針對訂用帳戶或資源群組或資源發出計量，請檢查您的應用程式或服務主體是否具有訪問控制（IAM） 中指派的監視計量發行者角色。
檢查維度名稱的數目是否符合值數目。
檢查您是否向正確的 Azure 監視器區域端點發出計量。例如，如果您的資源部署在美國西部，您必須向美國西部區域端點發出計量。
檢查時間戳是否在最近 20 分鐘內。
檢查時間戳是否為 ISO 8601 格式。
檢查計量名稱是否有效。例如，它不能包含空格。

下一步

深入了解自訂計量。

分享方式：