共通事項#
📒注: 監視サービスが 2024年12月25日に製品終息(EOL)を迎えるため、後継の監視サービスへのアラーム移行が必要です。
本章では、現行の監視サービス（以降、旧監視サービスと称す）と後継の監視サービス（以降、新監視サービスと称す）の アラーム用の APIの変更点について説明します。
以下、旧監視サービスのアラーム用APIを「旧API」、新監視サービスのアラーム用APIを「新API」と表記します。
移行手順については、監視サービス アラーム移行手順 を参照してください。
本章では、現行の監視サービス（以降、旧監視サービスと称す）と後継の監視サービス（以降、新監視サービスと称す）の アラーム用の APIの変更点について説明します。
以下、旧監視サービスのアラーム用APIを「旧API」、新監視サービスのアラーム用APIを「新API」と表記します。
移行手順については、監視サービス アラーム移行手順 を参照してください。
用語説明#
本章のAPIで使用する用語を説明します。
| 用語 | 説明 |
|---|---|
| 監視項目 | リソースに対する測定項目(性能情報や起動状態など)を表します。 |
| アラーム | 監視項目に対するしきい値監視の設定です。しきい値条件に対するアクションを設定することができます。 |
| リソース | 測定対象。本章ではインスタンス、ボリューム等を指します。 |
| ソース | 測定データの収集元を示す情報です。 |
| 集合体 | 特定のインスタンスを指定し、識別するために分類した測定対象群(単体でも指定可能)です。 アラームの対象に集合体を設定することで、複数のインスタンスを同じ条件で監視することができます。 |
旧監視サービス#
MetricType#
アラームに設定する監視種別(MetricType)の値を以下に示します。
Threshold項目には、下記の表の「単位」に対応した値を設定してください(80%のcpu使用率を指定したい場合は"80"を指定します)。
| MetricType設定値 | 説明 | 単位 |
|---|---|---|
| cpu.usage | インスタンスに使用可能なCPUの総数に対する消費されたCPUの割合 | % |
| memory.usage | インスタンス上で使用可能な合計メモリに対する消費されたメモリの割合 | % |
| network.egress.bit_rate | ネットワークインターフェイスの出力ネットワーク帯域幅 | Mbps |
| network.egress.drops | ネットワークインターフェイスの出力方向にドロップされたパケットの数 | Drops/s |
| network.egress.errors | ネットワークインターフェイスの出力方向で観測されるパケットエラー数 | Errors/s |
| network.egress.packet_rate | ネットワークインターフェイスの出力方向で観測されるパケットレート | Packets/s |
| network.ingress.bit_rate | ネットワークインターフェイスの入力ネットワーク帯域幅 | Mbps |
| network.ingress.drops | ネットワークインターフェイスの入力方向にドロップされたパケットの数 | Drops/s |
| network.ingress.errors | ネットワークインターフェイスの入力方向で観測されるパケットエラー数 | Errors/s |
| network.ingress.packet_rate | ネットワークインターフェイスの入力方向で観測されるパケットレート | Packets/s |
新監視サービス#
TargetType#
アラーム作成時または更新時、アラーム設定対象のタイプ(target_type)と、タイプに応じたアラーム設定対象のオブジェクトID(object_id) を指定します。
アラーム設定対象のタイプ(target_type)の一覧を以下に示します。
| target_type設定値 | アラームの設定対象 | object_idに設定する値 |
|---|---|---|
| project | プロジェクト内の全仮想サーバ | プロジェクトID |
| aggregate | 集合体(aggregate)内の仮想サーバ | 集合体ID (Aggregate ID) |
| stack | スタックによって作成された仮想サーバ | スタックID |
| auto_scaling_group | スタックのオートスケールグループ内の仮想サーバ | OS::Heat::AutoScalingGroup タイプのリソースのID |
スタックについては、機能説明書の オーケストレーション機能 のページを参照してください。
MetricType#
アラームに設定する監視項目(metric_type)の値を以下に示します。
Threshold項目には、下記の表の「単位」に対応した値を設定してください(80%のcpu使用率を指定したい場合は"80"を指定します)。
| metric_type設定値 | 単位 | 説明 |
|---|---|---|
| instance.cpu.usage | % | CPU使用率 |
| instance.memory.usage | % | メモリ使用率 |
| instance.network.egress.bit_rate | Mbps | ネットワーク帯域（出力） |
| instance.network.egress.drops | drops/s | 1秒間当たりにドロップした出力パケット数 |
| instance.network.egress.errors | errors/s | 1秒間当たりのパケットエラー数（出力） |
| instance.network.egress.packet_rate | packet/s | 1秒間当たりの送信パケット数 |
| instance.network.ingress.bit_rate | Mbps | ネットワーク帯域（入力） |
| instance.network.ingress.drops | drops/s | 1秒間当たりにドロップした入力パケット数 |
| instance.network.ingress.errors | errors/s | 1秒間当たりのパケットエラー数（入力） |
| instance.network.ingress.packet_rate | packet/s | 1秒間当たりの受信パケット数 |
Aggregation Function#
アラームに設定する集計関数(aggregation_function)の値を以下に示します。
| aggregation_function設定値 | 説明 |
|---|---|
| avg | 平均（各仮想サーバ毎に集計） |
| max | 最大（各仮想サーバ毎に集計） |
| min | 最小（各仮想サーバ毎に集計） |
| sum | 合計（各仮想サーバ毎に集計） |
| grp_avg | アラーム設定対象のすべての仮想サーバの平均 |
| grp_max | アラーム設定対象のすべての仮想サーバの最大 |
| grp_min | アラーム設定対象のすべての仮想サーバの最小 |
| grp_sum | アラーム設定対象のすべての仮想サーバの合計 |
📒注: grp_avg、grp_max、grp_min、grp_sumを指定した場合、アラーム設定対象のすべての仮想サーバの集計期間内の監視データを指定された集計関数で集計して1つの値を算出し、しきい値(Threshold)とを比較します。
avg、max、min、sumを指定した場合、仮想サーバごとに集計期間内のデータを指定された集計関数で集計し、しきい値(Threshold)と比較します。そのため、仮想サーバ単位でアラームが発報されます。
avg、max、min、sumを指定した場合、仮想サーバごとに集計期間内のデータを指定された集計関数で集計し、しきい値(Threshold)と比較します。そのため、仮想サーバ単位でアラームが発報されます。
Alarm 旧API と 新API の比較#
Alarm 旧API と 新API におけるパラメータ名の対応#
| 旧パラメータ名 | 新パラメータ名 | Description |
|---|---|---|
| EventRuleId | id | アラームID |
| Name | name | アラーム名 |
| ProjectId | project_id | プロジェクトID |
| MetricType | metric_type | 監視項目種別 |
| IntervalDuration | interval_duration | 監視間隔 |
| AggregationFunction | aggregation_function | 集計関数 |
| ComparisonFunction | comparison_function | 比較式 |
| Threshold | threshold | 比較値(しきい値や判定値) |
| Severity | severity | アラームレベル |
| AlarmAction | alarm_action | アラームアクション |
| Instances | instances | 監視対象仮想サーバ |
新API で廃止されたパラメータ#
| 旧パラメータ名 | Description |
|---|---|
| ConfigurationStatus | アラームの定義反映状態 |
| EventRuleScope | アラーム計測種別 |
| AggregateId | 集合体(aggregate)のID 新APIにて aggregateを対象としたアラームを作成する場合、target_typeパラメータに aggregate を、object_idパラメータに aggregateの IDを設定してください。 |
| IntervalCount | 監視項目の状態判定回数 |
| IntervalsWithException | アラーム通知のしきい値 新APIには類似のパラメータとして alert_countパラメータが存在します。 本パラメータは、監視条件を満たした状態が何回連続したらアラームを通知するかを表しますが、alert_countパラメータは何分連続したらアラームを通知するかを表します。 |
| Module | アラームモジュール |
| Mode | アラーム起動種別 |
| Status | アラームの有効/無効状態 旧APIでは文字列で enabled/disabled を設定していました。 新API では、enabledパラメータに true/falseを設定してください。 |
新API で新たに追加されたパラメータ#
| 名前 | In | Type | デフォルト値 /作成時必須指定 |
Description |
|---|---|---|---|---|
| description | body | string | 任意 | アラームの説明 255文字まで。 |
| target_type | body | string | 必須 | アラームの設定対象 プロジェクト内の全インスタンスを対象とする場合は projectを、aggregate内のインスタンスを対象とする場合は aggregateを設定します。 |
| object_id | body | string | 必須 | アラームの設定対象オブジェクトIDtarget_type パラメータに projectを設定した場合はプロジェクトID、aggregateを設定した場合は Aggregate IDを設定します。📒注: Instances指定時は指定不要です。object_idと Instancesを同時に指定した場合、Instancesの内容が優先されます。 |
| from | body | string | 1m/任意 | 集計対象期間 ある監視タイミングにおいて、直近のどれくらいの期間のデータを集計対象とするかを設定します。 |
| alert_count | body | integer | 1/任意 | アラーム通知のしきい値 監視条件が満たされた状態が何分続いたら alertを上げるかを設定します。 |
| enabled | body | bool | true/任意 | アラームの状態 有効の場合は true、無効の場合は falseで設定します。falseに設定されている場合、アラームが条件を満たしてもアラームアクションが実行されません。 |
| nodata_alert | body | bool | false/任意 | 監視データ取得不可時の通知有無 有効の場合は true、無効の場合は falseで設定します。アラームアクションにメール通知を設定している、かつ本項目の設定値が trueの場合、監視対象のすべての仮想サーバから監視条件に合致するデータが取得できない状態を検知するとメール通知を実行します。 📒注: アラームが複数の仮想サーバを監視しており、そのうち一部の仮想サーバからだけ監視データが取得できない場合、通知は実行されません。各仮想サーバごとに監視データが取得できない状態を監視する必要がある場合は、それぞれ個別にアラームを作成し、その上で nodata_alertを有効にしてください。 |
Get the history of an alarm の差分#
アラームのステータス変化の履歴参照を参照できるAPI、Get the history of an alarm における旧と新の差分は以下のとおりです。
新APIの詳細は Get the history of an alarm を参照してください。
- アラーム履歴取得APIのURIが、以下のとおり
alarm/historyがalarm_historyに変更されます。- 旧:
GET /v3.0/alarm/history/{alarm_id} - 新:
GET /v4.0/alarm_history/{alarm_id}
- 旧:
- レスポンスデータは、旧APIでは
actionHistorysキーのリストに格納されていましたが、新APIでは、キー名がaction_historyに変更されています。 - レスポンスデータにおけるアラーム履歴情報のデータ構造が大きく変更されています。
新APIでは、アラームの状態変化時点での Get a single Alarm で取得できるアラーム情報に加え、以下の項目が履歴情報として示されます。
| 名前 | Type | Description |
|---|---|---|
| alarm_id | string | アラームID Get a single Alarm APIではキー名が idですが、履歴ではキー名が alarm_idです。 |
| timestamp | string | アラーム発生時間(YYYY-MM-DDThh:mm:ssZ形式) 旧APIでは timestampStrキーに 3桁のミリ秒を含む 13桁の UNIX時刻が設定されていましたが、新APIでは YYYY-MM-DDThh:mm:ssZ 形式です。 |
| state | string | 発生したアラームの状態 アラームの条件一致の場合は firing、条件不一致の場合は resolved、監視データなしの場合は nodataを示します。旧APIでは、アラームの条件一致の場合は active、条件不一致の場合は inactiveと示されていました。また、新APIではアラームの有効無効を切り替えた履歴は表示されません。 |
| instance_id | string | アラームの状態が変化した仮想サーバのID 旧APIではキー名が entityTypeでした。 aggregate_functionで avg、max、min、sumが指定されているアラームの場合だけ設定されます。 grp_avg、grp_max、grp_min、grp_sumが指定されている場合、空欄が表示されます。 |
その他の差分#
- AggregationFunction パラメータにおいて、集計関数を平均とする場合、旧APIにおいては
averageを設定しましたが、新APIではavgを設定します。
また、新APIでは、アラーム設定対象の全仮想サーバについて平均、最大、最小、合計を集計することができます。
詳細は「集計関数」を参照してください。 - Alarm情報は、旧APIでは以下のように jsonのルート直下に示されていましたが、新APIでは
alarmキーの内部に情報が示されるようになります。
詳細は Get a single alarm を参照してください。
（旧APIの例）（新APIの例）{ "EventRuleId": "5e1cf886-27e2-11eb-a7fc-0242ac120006", "Name": "cpu_alarm_high", ... }
{ "alarm": { "id": "5e1cf886-27e2-11eb-a7fc-0242ac120006", "name": "cpu_alarm_high", ... } }
- Alarmの一覧取得APIのレスポンスは、旧APIでは
EventRulesキーのリスト内に各 Aggregate情報がありましたが、新APIではこのキー名がalarmsに変更されます。
また、Alarm情報はEventRuleキー内に含まれていましたが、新APIではリスト内に直接 Alarm情報が含まれています。
詳細は Get all alarms を参照してください。
（旧APIの例）（新APIの例）{ "EventRules": [ { "EventRule": { "EventRuleId": "5e1cf886-27e2-11eb-a7fc-0242ac120006", "Name": "cpu_alarm_high", ... } }, ... ] }
{ "alarms": [ { "id": "5e1cf886-27e2-11eb-a7fc-0242ac120006", "name": "cpu_alarm_high", ... }, ] }
- Alarmの更新APIのリクエストパラメータが変更されています。
旧APIでは有効無効は Statusパラメータで指定していましたが、新APIでは enabledパラメータで指定します。
また、アラームアクションの更新は、旧APIでは AlarmActionまたは DeleteAlarmActionパラメータで追加・削除するアクションを指定する形式でしたが、新APIでは、アラームアクション全体を alarm_actionパラメータで指定されたとおりに更新します。
詳細は Update an Alarm を参照してください。 - ComparisonFunctionパラメータにおいて、旧APIでは equalを設定できましたが、新APIでは指定できません。aboveまたは belowを使用してください。
Aggregate 旧API と 新API の比較#
Alarm 旧API と 新API におけるパラメータ名の対応#
| 旧パラメータ名 | 新パラメータ名 | Description |
|---|---|---|
| Name | name | 集合体(aggregate)の名前 |
| Id | id | 集合体(aggregate)のID |
| ObjectList | object_list | 集合体に含む対象のID |
| Metadata | description | 集合体の付帯情報 |
新API で廃止されたパラメータ#
| v3パラメータ名 | Description |
|---|---|
| Type | 対象の種別 |
| Source | 作成元種別 |
| ObjectMap | ※不要な項目 |
その他の差分#
- Aggregate情報は、旧APIでは以下のように
Aggregateキーの内部に含まれていましたが、新APIではこのキー名がaggregateに変更されます。
詳細は Get a single aggregate を参照してください。
（旧APIの例）（新APIの例）{ "Aggregate": { "Name": "aggregate_name", ... } }
{ "aggregate": { "name": "aggregate_name", ... } }
- Aggregateの一覧取得時、旧APIでは
Aggregatesキーのリスト内に各 Aggregate情報がありましたが、新APIではこのキー名がaggregatesに変更されます。
また、Aggregate情報はAggregateキー内に含まれていましたが、新APIではリスト内に直接 Aggregate情報が含まれています。
詳細は Get all aggregates を参照してください。 （旧APIの例）（新APIの例）{ "Aggregates": [ { "Aggregate": { "Name": "aggregate_name", ... } }, ... ] }
{ "aggregates": [ { "name": "aggregate_name", ... }, ] }