Ingest benutzerdefinierte Metriken für eine Azure-Ressource über die REST-API

  • Artikel

Dieser Artikel zeigt Ihnen, wie Sie benutzerdefinierte Metriken für Azure-Ressourcen über die REST-API an den Metrik-speicher von Azure Monitor senden können. Sobald sich die Metriken in Azure Monitor befinden, können Sie sie genauso behandeln wie Standardmetriken. Beispielsweise können Sie Diagramme und Warnungen generieren und die Metriken an andere externe Tools weiterleiten.

Hinweis

Die REST-API gestattet nur das Senden von benutzerdefinierten Metriken für Azure-Ressourcen. Um Metriken für Ressourcen in anderen Umgebungen oder für lokale Ressourcen zu senden, verwenden Sie Application Insights.

Senden von REST-Anforderungen zum Aufnehmen benutzerdefinierter Metriken

Wenn Sie benutzerdefinierte Metriken an Azure Monitor senden, muss jeder Datenpunkt oder Wert, der in den Metriken gemeldet wird, die folgenden Informationen enthalten.

Authentifizierung

Zum Übermitteln von benutzerdefinierten Metriken an Azure Monitor muss die Entität über ein gültiges Microsoft Entra-Token im Bearer-Header der Anforderung verfügen. Unterstützte Wege zum Erwerb eines gültigen Inhaber-Tokens sind:

  • Verwaltete Identitäten für Azure-Ressourcen Sie können eine verwaltete Identität verwenden, um Ressourcen die Berechtigung zu erteilen, bestimmte Vorgänge auszuführen. Zum Beispiel erlaubt sie einer Ressource das Ausgeben von Metriken über sich. Einer Ressource bzw. ihrer verwalteten Identität können Überwachung von Metriken Publisher Berechtigungen für eine andere Ressource erhalten. Mit dieser Berechtigung kann die verwaltete Identität auch Metriken für andere Ressourcen ausgeben.

  • Microsoft Entra-Dienstprinzipal In diesem Szenario können einer Microsoft Entra-Anwendung oder einem Dienst die Berechtigungen zum Ausgeben von Metriken zu einer Azure-Ressource gewährt werden. Azure Monitor überprüft das Anwendungstoken mithilfe von öffentlichen Microsoft Entra-Schlüsseln, um die Anforderung zu authentifizieren. Die vorhandene Rolle Überwachungsmetriken veröffentlichen verfügt bereits über diese Berechtigung. Sie ist im Azure-Portal verfügbar.

    Dem Dienstprinzipal kann die Rolle Überwachungsmetriken veröffentlichen im erforderlichen Gültigkeitsbereich erteilt werden, je nachdem, für welche Ressourcen er benutzerdefinierte Metriken ausgibt. Dabei kann es sich um ein Abonnement, eine Ressourcengruppe oder eine bestimmte Ressource handeln.

Tipp

Wenn Sie ein Microsoft Entra-Token zur Ausgabe von benutzerdefinierten Metriken anfordern, stellen Sie sicher, dass https://monitoring.azure.com/ die Zielgruppe oder Ressource, für die das Token angefordert wird. Achten Sie darauf, dass der Schrägstrich am Ende enthalten ist.

Abrufen eines Autorisierungstokens

Nachdem Sie Ihre verwaltete Identität oder Ihren Dienstprinzipal erstellt und die Berechtigungen für den Herausgeber von Monitoring Metrics zugewiesen haben, können Sie mit der folgenden Anfrage ein Autorisierungstoken erhalten:

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'

Der Antwortkörper hat das folgende Format:

{
    "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"
}

Speichern Sie das Zugriffstoken aus der Antwort, um es in den folgenden HTTP-Anforderungen zu verwenden.

Betreff

Die Eigenschaft subject erfasst die Azure-Ressourcen-ID, für die eine benutzerdefinierte Metrik gemeldet wird. Diese Information wird in der URL des API-Aufrufs codiert. Jede API kann Metrikwerte nur für eine einzige Azure-Ressource übermitteln.

Hinweis

Sie können keine benutzerdefinierten Metriken für die Ressourcen-ID einer Ressourcengruppe oder eines Abonnements ausgeben.

Region

Die Eigenschaft Region erfasst die Azure-Region, in der die Ressource, für die Sie Metriken übermitteln, bereitgestellt ist. Die Metriken müssen an denselben regionalen Endpunkt von Azure Monitor gesendet werden wie die Region, in der die Ressource bereitgestellt ist. Benutzerdefinierte Metriken für eine VM, die in der Region „USA, Westen“ bereitgestellt wurde, müssen z.B. an den regionalen Endpunkt „WestUS“ von Azure Monitor gesendet werden. Die Regionsinformationen sind auch in der URL des API-Aufrufs codiert.

Timestamp

Jeder Datenpunkt, der an Azure Monitor gesendet wird, muss mit einem Zeitstempel gekennzeichnet sein. Dieser Zeitstempel erfasst das Datum und die Uhrzeit, zu der die Metrik gemessen oder erfasst wurde. Azure Monitor akzeptiert metrische Daten mit Zeitstempeln, die bis zu 20 Minuten in der Vergangenheit und bis zu 5 Minuten in der Zukunft liegen. Der Zeitstempel muss im ISO 8601-Format vorliegen.

Namespace

Namespaces sind eine Möglichkeit, ähnliche Metriken zu kategorisieren oder zu gruppieren. Namespaces ermöglichen es Ihnen, Gruppen von Metriken zu isolieren, die unterschiedliche Erkenntnisse oder Leistungsindikatoren erfassen. Sie könnten z.B. über den Namespace contosomemorymetrics verfügen, der Metriken zur Arbeitsspeichernutzung verfolgt, um ein Profile Ihrer App zu erstellen. Ein anderer Namespace mit dem Namen contosoapptransaction könnte alle Metriken über Benutzertransaktionen in Ihrer Anwendung verfolgen.

Name

Die Eigenschaft name ist der Name der Metrik, über die berichtet wird. Normalerweise ist der Name ausreichend beschreibend, um zu erkennen, was gemessen wird. Ein Beispiel ist eine Metrik, mit der sich die Anzahl der von einer VM verwendeten Speicherbytes messen lässt. Der Metrikname könnte beispielsweise Verwendete Arbeitsspeicherbytes lauten.

Dimensionsschlüssel

Eine Dimension ist ein Schlüssel-Wert-Paar, mit dem andere Merkmale der erfassten Metrik beschrieben werden. Die anderen Merkmale ermöglichen die Erfassung weiterer Informationen zur Metrik und damit umfangreichere Erkenntnisse.

Die Metrik Verwendete Arbeitsspeicherbytes könnte z.B. einen Dimensionsschlüssel namens Prozess verwenden, der erfasst, wie viele Bytes des Arbeitsspeichers pro Prozess auf einer VM belegt werden. Mithilfe dieses Schlüssels können Sie die Metrik filtern, um zu sehen, wie viele speicherspezifische Prozesse verwendet werden, oder um die fünf Prozesse mit der höchsten Speicherauslastung zu identifizieren.

Dimensionen sind optional, und nicht alle Metriken haben Dimensionen. Eine benutzerdefinierte Metrik kann bis zu 10 Dimensionen umfassen.

Dimensionswerte

Wenn Sie einen metrischen Datenpunkt melden, gibt es für jeden Dimensionsschlüssel der gemeldeten Metrik einen entsprechenden Dimensionswert. Sie möchten beispielsweise den von ContosoApp auf Ihrer VM verwendeten Arbeitsspeicher melden:

  • Der Metrikname wäre Verwendete Arbeitsspeicherbytes.
  • Der Dimensionsschlüssel wäre Prozess.
  • Der Dimensionswert wäre ContosoApp.exe.

Wenn Sie einen Metrik-Wert veröffentlichen, können Sie nur einen einzigen Dimensionswert pro Dimensionsschlüssel angeben. Wenn Sie dieselbe Speicherauslastung für mehrere Prozesse auf der VM erfassen, können Sie mehrere Metrikwerte für diesen Zeitstempel melden. Jeder Metrikwert würde einen anderen Dimensionswert für den Dimensionsschlüssel Prozess angeben.

Obwohl Bemaßungen optional sind, sind die entsprechenden Bemaßungswerte obligatorisch, wenn ein Metrik-Beitrag Bemaßungsschlüssel definiert.

Metrikwerte

Azure Monitor speichert alle Metriken mit einer Granularität von 1 Minute. Während einer bestimmten Minute muss eine Metrik möglicherweise mehrmals abgetastet werden. Ein Beispiel ist die CPU-Auslastung. Oder eine Metrik muss für viele einzelne Ereignisse gemessen werden, wie z. B. die Latenzzeit bei Anmeldetransaktionen.

Um die Anzahl der Rohwerte zu begrenzen, die Sie in Azure Monitor ausgeben und für die Sie bezahlen müssen, aggregieren Sie die Werte vorab, und geben Sie die aggregierten Werte aus:

  • Min: Der beobachtete Mindestwert aus allen Stichproben und Messungen während der Minute.
  • Max: Der beobachtete Höchstwert aus allen Stichproben und Messungen während der Minute.
  • Sum: Die Summe aller beobachteten Werte aus allen Stichproben und Messungen während der Minute.
  • Count: Die Anzahl der Stichproben und Messungen, die während der Minute durchgeführt wurden.

Hinweis

Das Definieren von Einheiten für eine benutzerdefinierte Metrik wird von Azure Monitor nicht unterstützt.

Wenn z. B. innerhalb einer Minute vier Anmeldetransaktionen für Ihre App stattfanden, ergeben sich daraus möglicherweise die folgenden gemessenen Wartezeiten für jede dieser Transaktionen:

Transaktion 1 Transaktion 2 Transaktion 3 Transaktion 4
7 ms 4 ms 13 ms 16 ms

Die sich dann daraus ergebende metrische Veröffentlichung für Azure Monitor lautet:

  • Min: 4
  • Max: 16
  • Summe: 40
  • Anzahl: 4

Wenn Ihre Anwendung nicht lokal voraggregieren kann und jede diskrete Probe oder jedes Ereignis sofort nach der Erfassung ausgeben muss, können Sie die Rohmesswerte ausgeben. So würden Sie z.B. jedes Mal, wenn in Ihrer App eine Anmeldetransaktion stattgefunden hat, eine Metrik mit nur einer einzigen Messung an Azure Monitor übermitteln. Für eine Anmeldetransaktion, die 12 Millisekunden dauerte, würde die Veröffentlichung der Metrik also wie folgt aussehen:

  • Min: 12
  • Max: 12
  • Summe: 12
  • Anzahl: 1

Mit diesem Verfahren können Sie während einer bestimmten Minute mehrere Werte für dieselbe Kombination aus Metrik und Dimension ausgeben. Azure Monitor nimmt dann alle Rohwerte, die für eine bestimmte Minute ausgegeben werden, und aggregiert sie.

Beispiel einer benutzerdefinierten metrischen Veröffentlichung

Im folgenden Beispiel erstellen Sie eine benutzerdefinierte Metrik namens Verwendete Speicherbytes unter dem Metrik-Namensraum Speicherprofil für eine virtuelle Maschine. Die Metrik weist eine einzelne Dimension namens Process auf. Für den Zeitstempel werden metrische Werte für zwei Prozesse ausgegeben.

Fügen Sie den folgende JSON-Code in eine Datei ein, und speichern Sie sie als custommetric.json auf Ihrem lokalen Computer. Aktualisieren Sie den Zeitparameter so, dass er innerhalb der letzten 20 Minuten liegt. Dem Speicher können keine Metriken hinzugefügt werden, die älter als 20 Minuten sind.

{
    "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
          }
        ]
      }
    }
  }

Übermitteln Sie die folgende HTTP POST-Anforderung mit den folgenden Variablen:

  • location: Bereitstellungsregion der Ressource, für die Sie die Metriken bereitstellen.

  • resourceId: Ressourcen-ID der Azure-Ressource, für die Sie die Metrik verfolgen.

  • accessToken: Das Autorisierungs-Token, das Sie mit dem Schritt Autorisierungs-Token holen erhalten haben.

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

Anzeigen Ihrer Metriken

  1. Melden Sie sich beim Azure-Portal an.

  2. Klicken Sie im Menü auf der linken Seite auf Überwachen.

  3. Wählen Sie auf der Seite Monitor die Option Metriken aus.

    Screenshot that shows how to select Metrics in the Azure portal.

  4. Ändern Sie den Aggregationszeitraum in Letzte Stunde.

  5. Wählen Sie in der Dropdownliste Bereich die Ressource aus, für die Sie die Metrik senden.

  6. Wählen Sie in der Dropdown-Liste Metric Namespace die Option Memory Profile.

  7. Wählen Sie in der Dropdown-Liste Metrik die Option Verwendete Speicherbytes.

Problembehandlung

Sollte im Rahmen des Prozesses eine Fehlermeldung angezeigt werden, berücksichtigen Sie die folgenden Informationen zur Problembehandlung:

  • Wenn keine Metriken für ein Abonnement, eine Ressourcengruppe oder eine Ressource ausgegeben werden, überprüfen Sie, ob Ihrer Anwendung oder Ihrem Dienstprinzipal unter Zugriffssteuerung (IAM) die Rolle Herausgeber von Überwachungsmetriken zugewiesen ist.
  • Überprüfen Sie, ob die Anzahl von Dimensionsnamen mit der Anzahl von Werten übereinstimmt.
  • Vergewissern Sie sich, dass Sie die Metriken an den richtigen regionalen Azure Monitor-Endpunkt senden. Wenn Ihre Ressource z.B. in West US bereitgestellt wird, müssen Sie Metriken an den regionalen Endpunkt West US senden.
  • Prüfen Sie, ob der Zeitstempel innerhalb der letzten 20 Minuten liegt.
  • Prüfen Sie, ob der Zeitstempel im ISO 8601-Format vorliegt.
  • Prüfen Sie, ob der Name der Metrik gültig ist. Er darf zum Beispiel keine Leerzeichen enthalten.

Nächste Schritte

Erfahren Sie mehr über benutzerdefinierte Metriken.