Oracle Cloud Infrastructure - Dokumentation

Benutzerdefinierte Metriken mit der API veröffentlichen

Veröffentlichen Sie benutzerdefinierte Metriken im Monitoring-Service.

Tipp

Agent-Konfigurationen sind eine weitere Möglichkeit, benutzerdefinierte Metriken in Monitoring zu veröffentlichen. Bei Agent-Konfigurationen ist die API nicht unbedingt erforderlich, um benutzerdefinierte Metriken zu veröffentlichen. Sie können jetzt Agent-Konfigurationen verwenden, um Metrikdaten in benutzerdefinierte Metriken aufzunehmen. Stellen Sie beispielsweise Metriken aus einer virtuellen Maschine (VM) mit einem HTTP-Endpunkt im Prometheus-Format bereit.

Eine benutzerdefinierte Metrik ist eine Metrik, die Sie zum Erfassen und Analysieren von Daten entwerfen.

Beispiel: Erstellen Sie eine productOrder-Metrik (in einem Metrik-Namespace, mymetricsnamespace), um Produktaufträge nach Land und Geschäftsbereich mit zusätzlichen Metadaten für Produktkategorien und Notizen zu verfolgen.

Bevor Sie beginnen

IAM-Policys: Um benutzerdefinierte Metriken veröffentlichen zu können, müssen Sie den erforderlichen Zugriffstyp in einer von einem Administrator geschriebenen Policy erhalten. Dabei spielt es keine Rolle, ob Sie die REST-API mit einem SDK, der CLI oder einem anderen Tool verwenden. Wenn Sie eine Nachricht erhalten, dass Sie keine Berechtigung oder Autorisierung haben, wenden Sie sich an den Administrator. Sie haben im aktuellen Compartment möglicherweise nicht den erforderlichen Zugriffstyp.

Administratoren: Eine Beispiel-Policy finden Sie unter Benutzerdefinierte Metriken veröffentlichen (Monitoring sichern).

Überlegungen

Wenn Sie benutzerdefinierte Metriken definieren, beachten Sie Folgendes:

  • Verwenden Sie für den Metrik-Namespace kein reserviertes Präfix (oci_ oder oracle_).
  • Stellen Sie sicher, dass benutzerdefinierte Metriken die Limits nicht überschreiten. Beachten Sie beispielsweise den gültigen Bereich von Dimensionen und die Höchstanzahl von Streams für benutzerdefinierte Metriken. Siehe PostMetricData.
  • Metriken vor der Aggregation definieren Während benutzerdefinierte Metriken sogar jede Sekunde (minimale Häufigkeit von einer Sekunde) gepostet werden können, beträgt das minimale Aggregationsintervall eine Minute.
  • Berücksichtigen Sie bei der Definition von Metriken die Retourenlimits. Die Informationen zu den Limits für die zurückgegebenen Daten umfassen das Maximum von 100.000 Datenpunkten und die maximalen Zeiträume (werden durch die Auflösung bestimmt, die sich auf das Intervall bezieht). Siehe MetricData. Siehe auch Limits für Monitoring.
  • Stellen Sie sicher, dass die Zeitstempelwerte nahezu der aktuellen Zeit entsprechen. Damit ein Datenpunkt gepostet werden kann, muss der zugehörige Zeitstempel nahezu der aktuellen Zeit entsprechen (weniger als zwei Stunden in der Vergangenheit und weniger als 10 Minuten in der Zukunft). Siehe PostMetricData.
  • Nach der Veröffentlichung benutzerdefinierter Metriken können Sie auf diese genauso zugreifen wie auf andere vom Monitoring-Service gespeicherte Metriken: Diagramme in der Konsole anzeigen, Metriken mit der CLI oder API abfragen und Alarme erstellen.
  • Wenn Sie benutzerdefinierte Metriken abrufen, können Sie diese mit einer Ressourcengruppe abgleichen. Leere Werte (Nullwerte) für die Ressourcengruppe geben Metrikdaten ohne Ressourcengruppe zurück.
  • Diese Aufgabe kann nicht in der Konsole ausgeführt werden.
  • Hinweis

    Im Gegensatz zu anderen Monitoring-Befehlen, die telemetry-Endpunkte verwenden, erfordert dieser Befehl einen telemetry-ingestion-Endpunkt.

    Verwenden Sie den Befehl oci monitoring metric-data post, den Parameter --endpoint und die erforderlichen Parameter, um benutzerdefinierte Metriken zu veröffentlichen:

    oci monitoring metric-data post --metric-data file://<json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.com

    Eine vollständige Liste der Parameter und Werte für CLI-Befehle finden Sie in der Befehlszeilenreferenz für Monitoring.

    JSON-Beispieldatei für Anforderung

    Die JSON-Beispieldatei enthält die folgenden Elemente.

    • Metrik-Namespace: mymetricsnamespace
    • Metrikname: productOrder
    • Produktdimension
    • Landesdimension
    • Ressourcengruppe (DivisionX, DivisionY)
    • Zusätzliche Metadaten für Kategorie und Notiz
    [
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 10,
        "timestamp": "2023-01-08T04:18:01+00:00",
        "value": 5.0
      },
      {
        "count": 3,
        "timestamp": "2023-01-08T05:11:01+00:00",
        "value": 10.0
      }
    ],
    "dimensions": {
      "product": "ball",
      "country": "NL"
    },
    "metadata": {
      "category": "toys",
      "note": "national holiday"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionX"
  },
  {
    "compartmentId": "$compartmentId",
    "datapoints": [
      {
        "count": 7,
        "timestamp": "2023-01-08T03:22:01+00:00",
        "value": 3.0
      },
      {
        "count": 11,
        "timestamp": "2023-01-08T05:08:03+00:00",
        "value": 2
      }
    ],
    "dimensions": {
      "product": "The Road to Nowhere",
      "country": "FR"
    },
    "metadata": {
      "category": "books",
      "note": "start second semester"
    },
    "name": "productOrder",
    "namespace": "mymetricsnamespace",
    "resourceGroup": "divisionY"
  }
]
    Beispielantwort
    {
  "data": {
    "failed-metrics": [],
    "failed-metrics-count": 0
  }
}
  • Hinweis

    Im Gegensatz zu anderen Monitoring-Vorgängen, die telemetry-Endpunkte verwenden, ist für diesen Vorgang ein telemetry-ingestion-Endpunkt erforderlich.

    Führen Sie den Vorgang PostMetricData aus, um benutzerdefinierte Metriken zu veröffentlichen.

    Beispiel für eine Anforderung im Batch

    Dieses Beispiel zeigt eine einzelne Anforderung mit Datenpunkten  für Metriken über zwei Metrik-Namespaces . 

    [
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"myFirstResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:20Z",
            "value":83.0
         },
         {
            "timestamp":"2023-01-10T22:19:40Z",
            "value":90.1
         }
      ]
   },
   {
      "namespace":"myFirstNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "resourceGroup":"mySecondResourceGroup",
      "name":"successRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.differentuniqId",
         "appName":"myAppA"
      },
      "metadata":{
         "unit":"percent",
         "displayName":"MyAppA Success Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:10Z",
            "value":100.0
         },
         {
            "timestamp":"2023-01-10T22:19:30Z",
            "value":100.0
         }
      ]
   },
   {
      "namespace":"mySecondNamespace",
      "compartmentId":"ocid1.compartment.oc1..exampleuniqueID",
      "name":"deliveryRate",
      "dimensions":{
         "resourceId":"ocid1.exampleresource.region1.phx.exampleuniqueID",
         "appName":"myAppB"
      },
      "metadata":{
         "unit":"bytes",
         "displayName":"MyAppB Delivery Rate"
      },
      "datapoints":[
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":87.0,
            "count":60
         },
         {
            "timestamp":"2023-01-10T22:19:00Z",
            "value":96.0,
            "count":30
         }
      ]
   }
]