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. Beispiel: Sie können Metriken von einer virtuellen Maschine (VM) mit einem HTTP-Endpunkt im Prometheus-Format bereitstellen.

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 Produktbestellungen nach Land und Geschäftsbereich mit zusätzlichen Metadaten für Produktkategorien und Notizen zu verfolgen.

Bevor Sie beginnen

IAM-Policys: Um benutzerdefinierte Metriken zu veröffentlichen, 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 nicht über die entsprechende Berechtigung verfügen oder nicht autorisiert sind, fragen Sie den Administrator. Möglicherweise verfügen Sie im aktuellen Compartment nicht über den erforderlichen Zugriffstyp.

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

Überlegungen

Beim Definieren benutzerdefinierter Metriken beachten Sie Folgendes:

  • Verwenden Sie für den Metrik-Namespace kein reserviertes Präfix (oci_ oder oracle_).
  • Stellen Sie sicher, dass benutzerdefinierte Metriken die Grenzwerte nicht überschreiten. Beachten Sie beispielsweise den gültigen Bereich von Dimensionen und die Höchstanzahl von Streams für benutzerdefinierte Metriken. Siehe PostMetricData.
  • Definieren von Metriken unter Berücksichtigung der Aggregation. Während benutzerdefinierte Metriken sogar jede Sekunde (minimale Häufigkeit von einer Sekunde) gepostet werden können, beträgt das minimale Aggregationsintervall eine Minute.
  • Definieren Sie Metriken unter Berücksichtigung der Rückgabelimits. 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 sein Zeitstempel nahezu der aktuellen Zeit (weniger als zwei Stunden in der Vergangenheit und weniger als 10 Minuten in der Zukunft) entsprechen. Siehe PostMetricData.
  • Nachdem sie benutzerdefinierte Metriken veröffentlicht haben, 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) unter Ressourcengruppe geben Metrikdaten zurück, die keine Ressourcengruppe haben.
  • 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
         }
      ]
   }
]