Oracle Cloud Infrastructureドキュメント

APIを使用したカスタム・メトリックの公開

カスタム・メトリックをモニタリング・サービスに公開します。

ヒント

エージェント構成は、カスタム・メトリックをMonitoringに公開するもう1つの方法です。エージェント構成では、APIはカスタム・メトリックの公開に必ずしも必要とはかぎりません。エージェント構成を使用して、メトリック・データをカスタム・メトリックに取り込むことができるようになりました。たとえば、Prometheus形式のHTTPエンドポイントを使用して、仮想マシン(VM)からメトリックを公開します。

カスタム・メトリックは、データを収集および分析するために設計するメトリックです。

たとえば、productOrderメトリックを(メトリック・ネームスペースのmymetricsnamespaceで)作成し、製品カテゴリおよびノートの追加メタデータを使用して、国および部門別に製品オーダーを追跡します。

開始前

IAMポリシー: カスタム・メトリックを公開するには、管理者が作成したポリシーで必要なアクセス・タイプを付与される必要があります。この要件は、REST APIをSDK、CLIまたはその他のツールのどれと使用する場合でも適用されます。権限がない、または認可されていないというメッセージが表示された場合は、管理者に連絡してください。現在のコンパートメントに必要なアクセス・タイプがない可能性があります。

管理者: ポリシーの例は、カスタム・メトリックの公開(モニタリングの保護)を参照してください。

考慮事項

カスタム・メトリックを定義する場合は、次の点に注意してください:

  • メトリック・ネームスペースには、予約済接頭辞(oci_またはoracle_)を使用しないでください。
  • カスタム・メトリックが制限を超えないようにします。たとえば、有効なディメンション範囲とカスタム・メトリックの最大ストリーム数に気を付けてください。PostMetricDataを参照してください。
  • 集計を考慮してメトリックを定義します。カスタム・メトリックは1秒ごとに頻繁にポストできますが(最小頻度は1秒)、最小集約間隔は1分です。
  • 返される際の制限を考慮してメトリックを定義します。返されるデータの制限情報には、100,000データ・ポイントの最大値と時間範囲の最大値(レゾリューションによって決定され、間隔に関連しています)が含まれます。MetricDataを参照してください。モニタリングの制限も参照してください。
  • タイムスタンプ値が現在の時間に近いことを確認します。データ・ポイントをポストするには、そのタイムスタンプが現在の時間に近い必要があります(過去2時間未満かつ将来10分未満)。PostMetricDataを参照してください。
  • カスタム・メトリックを公開した後、モニタリング・サービスによって格納されている他のメトリックと同じ方法でアクセスできます(コンソールでのチャートの表示、CLIまたはAPIを使用したメトリックの問合せおよびアラームの作成)。
  • カスタム・メトリックを取得するときに、リソース・グループと照合できます。リソース・グループに空白(null)を指定すると、リソース・グループを持たないメトリック・データが返されます。
  • このタスクはコンソールでは実行できません。
  • ノート

    telemetryエンドポイントを使用する他のモニタリング・コマンドとは異なり、このコマンドにはtelemetry-ingestionエンドポイントが必要です。

    カスタム・メトリックを公開するには、oci monitoring Metric-data postコマンド、--endpointパラメータおよび必須パラメータを使用します:

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

    CLIコマンドのパラメータおよび値の完全なリストは、モニタリングのコマンドライン・リファレンスを参照してください。

    リクエストのJSONファイルの例

    JSONファイルの例には、次の項目が含まれています。

    • メトリック・ネームスペース: mymetricsnamespace
    • メトリック名: productOrder
    • 製品ディメンション
    • 国ディメンション
    • リソース・グループ(DivisionX、DivisionY)
    • カテゴリおよびノートの追加メタデータ
    [
  {
    "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"
  }
]
    レスポンスの例
    {
  "data": {
    "failed-metrics": [],
    "failed-metrics-count": 0
  }
}
  • ノート

    telemetryエンドポイントを使用する他のモニタリング操作とは異なり、この操作にはtelemetry-ingestionエンドポイントが必要です。

    PostMetricData操作を実行して、カスタム・メトリックを公開します。

    バッチ処理されたリクエストの例

    この例は、2つのメトリック・ネームスペース間のメトリックのデータ・ポイントを含む単一のリクエストを示しています。 

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