Alarm の利用について

投稿日 / 投稿者名

2021.4.26 / sasa

はじめに

本レポートは、Things Cloud の利用例をより知っていただくための実利用レポートとして作成したものです。
Things Cloud は極力後方互換性を持つよう開発されていますが、今後のリリースにより、一部画面やコマンド、手順などが変更となったり、利用できない可能性があることをあらかじめご了承ください。
なお、作成にあたり、以下バージョンを用いています。

難易度　★★


所要時間

20分

前提条件

概要

本レポートでは、Things Cloud でのアラームの仕様、および利用に向けた type 付与基準などについて記載したものです。

Alarm のデータ構造

まず、Alarm のデータ構造をおさらいしておきます。

名称 タイプ 発生回数 説明 PUT/POST
creationTime datetime 1 アラームがデータベース内で作成された時間 なし
type string 1 このアラームイベントのタイプを識別します　例：「com_cumulocity_events_TamperEvent」 POST: 必須
PUT: なし
time datetime 1 アラームの時間 POST: 必須
PUT: なし
text string 1 アラームを説明するテキスト POST: 必須
PUT: なし
source ManagedObject 1 アラームの発生源となったマネージドオブジェクト。オブジェクトは「id」プロパティを含みます。 POST: 必須
PUT: なし
status string 0..1 アラームの状態：ACTIVE、ACKNOWLEDGEDまたはCLEARED。状態が表示されなかった場合、新規アラームの状態はACTIVEとなります。すべて大文字でなければなりません。 POST: 任意
PUT: 任意
severity string 1 アラームの重大度：CRITICAL、MAJOR、MINORまたはWARNING。すべて大文字でなければなりません。 POST: 必須
PUT: 任意
count long 1 このアラームが送信された回数 なし
firstOccurrenceTime datetime 1 このアラームが最初に発生した時間（すなわち「count」が1になった時間） なし
* Object 0..n イベントのカスタムプロパティ(カスタムフラグメント) なし

他にも次のパラメータがありますが、POST/PUT には指定できません：id, self, history

重複除外

アラームでは、メジャーメントやイベントと異なり「重複除外」という特殊な動きがあります。

アラームは連続して同様のものが生成(POST)された場合に、データベース上に新しいアラームを作成する代わりに、既存のアラームの回数(count)を増やすのみの処理とする場合があります。

重複除外により、デバイスが継続的に同様のアラームを複数生成した場合、UI上のアラームリストなどで１行に集約表示され、対処を行ってアラームクリアする場合も1回のクリア操作で済むようになります。

イベント/メジャーメントの場合

アラームの場合

重複除外条件

新規アラームを POST する際、以下のアラームが存在していた場合、重複除外となります。

このとき、新しいアラームオブジェクトがデータベース内で生成されず、既存アラームオブジェクトが更新される動きとなります。重複除外時、既存のアラームオブジェクトは以下のように更新されます。

アラームリストでの表示

count, time, creationTime, firstOccurrenceTime はアラームリストでは以下の箇所に表示されます。

プロパティ名 説明
① count, firstOccurrenceTime 赤い数字(count)にマウスカーソルをあてると firstOccurrenceTime が表示。
発生回数(重複回数)、初回発生日時(デバイス時間)
② time 最後に報告されたアラームのデバイス時間
③ creationTime 初回発生時間(サーバ時間)

アラームリストでの設定

ダッシュボードで利用できるウィジェット「アラームリスト」では出力するアラーム条件を細かく指定することができます。

設定項目 説明
対象のアセットもしくはデバイス 表示するアラームの対象となるグループ(アセット)またはデバイスを指定できます。
ステータス 表示対象のアラームを status で選択(限定)できます。
タイプ 表示対象のアラームを type 値で選択(限定)できます。
重大度 表示対象のアラームを severity 値で選択(限定)できます。
並び順 並び順をステータス別、または重大度別に変更できます。それぞれのカテゴリで新しいものが上に表示されます。

スマートルール(アラーム時Eメール送信)の動作

新規のアラーム発生(count=1)の際にメール送信する処理となっています。

したがって、重複時(count > 1) では、アラームが発生しません。いったんクリアすることで、再度メールが通知されます。

アラーム各値の付与基準

アラーム vs イベント

アラームは「人による確認、対応が必要な情報」の通知に向いています。特に対処不要な「再起動されました」「省電力モードに移行しました」のようなもの、また「通信リトライが行われました」のようなものも通常対処が必要ではありません。

このような情報の通知は、アラームではなくイベントを用いるとよいことが多いです。

アラームでは、人による対処が必要な場合に利用します。

アラームの各値設定

一般的に、アラームでの type 等のパラメータの付与基準をどう設定するかはケースバイケースの判断が必要になります。ここではその参考となる情報を記載します。

通常、接続するIoT-GWやセンサー、システム固有の慣例、基準があり、分解能や付与基準もさまざまで、この通りとならない場合もあります。必ずしもこの通りでなければならないわけではありませんが、後続の★の要件は考慮するようにして下さい。

type

type の付与に関する経験的によい方法は以下です。名称は大小文字、数字とアンダースコアを用いるようにしてください。

付与規則はありませんが、<接頭辞>_<アラーム内容> の形とするのがよいでしょう。接頭辞は、c8y(Things Cloud システム慣例), nttcom (NTTCom)のようなものです。

基本的な考え方

近いけれども異なる機種のデバイスに関するアラーム type の付与基準は簡単ではありませんが、概して発生条件や影響、対処内容が似ている場合、同一のものを付与するのがよいでしょう。どのデバイスから報告されたかはアラームを確認することでわかり、詳細な機種は判別可能ですし、発生アラームに対応するメール件名/本文、対処マニュアルやスマートルール設定を共通化することができます。

スマートルール設定/動作の考慮事項

スマートルールでは、アラームをトリガーとするものが用意されており、それらは type を指定できます。(詳細はスマートルールコレクションを参照下さい)

つまり、これらの動作(送信メール内容、重大度をあげる、操作)を区別したい場合は type として異なるものを付与する必要があります。逆に、type を細かく分けすぎるとスマートルール設定が煩雑となり、メンテナンス性が下がります。

text

基本的な考え方

severity

基本的な考え方

status

status 値は Things Cloud 内での扱いが決まっており、以下の意味となります。

fragments

Alarm に付随するデータを添付可能です。以下についてご注意ください。