Alarm の利用について

投稿日 / 投稿者名

2021.4.26 / sasa

はじめに

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

  • ver.10.6.6（backend/UI）

難易度　★★


所要時間

20分

前提条件

  • 基本的なデータモデル(Alarm, Managed Object など)の理解があること
  • REST API を利用できること
  • cockpit, device management アプリケーションを利用できること

概要

本レポートでは、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 する際、以下のアラームが存在していた場合、重複除外となります。

  • source, type が同じ(＝同じデバイスからの、同じ種類のアラーム)
  • かつ status が ACTIVE または ACKNOWLEDGED (＝まだ解決していない)

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

  • count が +1 される(発生回数はカウントされる)
  • time が新しいものに更新される
  • firstOccurrenceTime (デバイス時間)プロパティがセットされる
  • 他のパラメータ(text, status, severity, fragment など)は変更されない(POSTしても無視されます)

アラームリストでの表示

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

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

アラームリストでの設定

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

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

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

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

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

アラーム各値の付与基準

アラーム vs イベント

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

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

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

  • アラーム「バッテリー電圧が下がっています」→対処「バッテリー交換」
  • アラーム「内部ストレージ容量が足りません」→対処「SDカード交換」
  • アラーム「室温が上昇しています」→対処「空調による室温調節」
  • アラーム「窓口が混雑しています」→対処「入場規制」「対応者増員」

アラームの各値設定

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

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

type

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

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

基本的な考え方
  • 同一原因のアラームは同一 type とする
  • 異なる対処となるアラームは異なる type とする
    • ★承認、クリアは device/type 単位に行われます
  • 障害に関する統計分析に回数以外の情報がある場合
    • ★同一デバイスで type が同一の場合、重複除外が行われ、回数以外の情報(特にfragment 情報)が失われます。
    • 重複除外させたくない場合、イベントの利用も検討下さい。
  • 同時発生の可能性があり、メール通知が別々に必要な場合、異なる type を付与するようにして下さい
    • ★重複除外に該当すると連続する２回目以降のアラームはメール通知対象になりません

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

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

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

  • アラーム時Eメールを送信
  • アラーム継続時アラーム重大度を上げる
  • アラーム時実行操作

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

text

基本的な考え方
  • 人が読んで理解しやすいよう、どのような障害が発生しているのか誤解を与えないよう簡潔に記載ください
  • さらに、どの対処を行うか判断しやすい情報を記載するとよいです

severity

基本的な考え方

  • デバイスが動作不可となるものは severity = “CRITICAL” を設定して下さい

status

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

  • ★ACTIVE 発生後、認知されていない

  • ★ACKNOWLEDGED 発生後、認知された(対応中)、未解決

  • ★CLEARED 発生後、解決済

fragments

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

  • ★同一デバイスで type が同一の場合、重複除外が行われ、回数以外の情報(特にfragment 情報)は最初の値のみ保持されます。