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 <json_file_path> --endpoint https://telemetry-ingestion.<region>.oraclecloud.com

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

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

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

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