デバイス監視ログ可視化システム（version 2.7以降）
==========================

.. contents:: 目次:
    :depth: 3

概要
###########################

デバイス監視ログ可視化システムは、各デバイスの監視ログの登録を行うデバイス監視ログ収集サーバー、
監視ログを保存するデバイス監視ログ収集データベース(Elasticsearch)、
保存された監視ログを可視化するデバイス監視ログ可視化ツール(Grafana)から構成される。

.. figure:: images/logsrv/logsrv_system.jpg
    :scale: 40
    :alt: Alternative Text
    :name: logsrv_system

    デバイス監視ログ可視化システムの概略図


Elasticsearchの導入
###########################

インストール
---------------------------

Elasticsearchに依存しているパッケージをインストールする。

.. code-block:: sh

    $ sudo yum install java-11-openjdk

Elasticsearchソフト用の公開鍵をインストールする。

.. code-block:: sh

    $ sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch

:file:`/etc/yum.repos.d/elasticsearch.repo` を作成し、以下を書き込む。

.. code-block::

    [elasticsearch]
    name=Elasticsearch repository for 7.x packages
    baseurl=https://artifacts.elastic.co/packages/7.x/yum
    gpgcheck=1
    gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
    enabled=0
    autorefresh=1
    type=rpm-md

Elasticsearchをインストールする。

.. code-block:: sh

    $ sudo yum install --enablerepo=elasticsearch elasticsearch

設定
---------------------------

Elasticsearchの設定ファイル :file:`/etc/elasticsearch/elasticsearch.yml` の修正を行う。

.. code-block::

    # 23行目を修正し、ノード名にホストの名称を設定する。
    node.name: iroha2

    # 56行目を修正し、外部ホストからの接続を許可する。
    network.host: 0.0.0.0

    # 70行目を修正して外部ネットワーク接続用のIPのアドレスを設定し、自ホストが検索できるようにする。
    # ここでは、例としてIPアドレスを192.168.0.10とする。
    discovery.seed_hosts: ["192.168.0.10"]

    # 74行目を修正し、マスターノードを指定する。
    # ノード名は、23行目に指定したnode.nameを使用する。
    cluster.initial_master_nodes: ["iroha2"]

    # ファイル末尾に以下を追加し、セキュリティ設定を有効にする。
    xpack.security.enabled: true
    xpack.security.transport.ssl.enabled: true

起動
---------------------------

systemctlコマンドでElasticsearchを起動する。

.. code-block:: sh

    # Elasticsaerchのsystemctlへの登録（初回のみ）
    $ sudo systemctl daemon-reload
    # Elasticsearchの自動起動を有効化する場合
    $ sudo systemctl enable elasticsearch
    # Elasticsearchの起動（数10秒かかる）
    $ sudo systemctl start elasticsearch

.. _es_settings_passwd:

パスワードの設定
---------------------------

以下のコマンドを実行し、対話形式でパスワードの設定を行う。
複数回パスワードを聞かれるが、すべて同じパスワードを入力すればよい。
この説明では例としてパスワードを `mlfadmin` に設定する。

.. code-block:: sh

    $ sudo /usr/share/elasticsearch/bin/elasticsearch-setup-passwords interactive

.. _es_settings_role:

Roleとユーザーの設定
---------------------------

Elasticsearchのインデックスに対する書き込み、読み取りを制限するためのRoleを設定する。

書き込み用Role
***************************

装置コードABCのすべてのインデックス（logsurv*abc）に対するすべての権限を持つRoleとして `bl00all` を追加する場合、以下のコマンドを実行する
（Elasticsearchのパスワードが `mlfadmin` の場合）。

.. code-block:: sh

    $ curl -XPOST -u elastic:mlfadmin -H 'Content-Type:application/json' localhost:9200/_security/role/bl00all -d '{ 
      "indices" : [ { 
      "names" : [ "logsurv*abc" ],
      "privileges" : [ "all" ] }
      ] }'

このRoleに属するユーザーとして `bl00` （パスワード `bl00user` ）を追加する場合、以下のコマンドを実行する
（:ref:`es_settings_passwd` で設定したElasticsearchのパスワードが `mlfadmin` の場合）。

.. code-block:: sh

    $ curl -XPOST -u elastic:mlfadmin -H 'Content-Type: application/json' localhost:9200/_security/user/bl00 -d '{ 
      "password" : "bl00user",
      "full_name" : "bl00 user",
      "roles" : "bl00all"
      }'

このユーザー `bl00` は、デバイス監視ログ収集サーバーが装置管理サーバーから収集した情報をElasticsearchに書き込むために必要となる。
また、Grafanaのデータソースを指定する際にこのユーザーを利用することで、Roleで定めた範囲のインデックス（logsurv*abc）をすべて表示させることができる。

読み取り専用Role
***************************

あるインデックスに対して読み取りのみ可能なRoleを設定する場合には、privilegesを["read", "view_index_metadata"]にしてコマンドを実行する。
例えば、装置コードABCのあるデバイス（例としてFastDouble）のインデックス（logsurvfastdouble-abc）に対する読み取りの権限を持つRoleとして `bl00fastbouble` を追加する場合、以下のコマンドを実行する
（:ref:`es_settings_passwd` で設定したElasticsearchのパスワードが `mlfadmin` の場合）。

.. code-block:: sh

    $ curl -XPOST -u elastic:mlfadmin -H 'Content-Type:application/json' localhost:9200/_security/role/bl00fastbouble -d '{ 
      "indices" : [ { 
      "names" : [ "logsurvfastdouble-abc" ],
      "privileges" : [ "read", "view_index_metadata" ] }
      ] }'

このRoleに属するユーザーの追加方法は、書き込み用Roleの場合と同様である。

このユーザー `bl00fastbouble` は、Grafanaのデータソースを指定する際に利用する。
このユーザーで指定したデータソースからは、Roleで定めた範囲のインデックス（logsurvfastdouble-abc）のみが表示できるようになる。

Grafanaの導入
###########################

インストール
---------------------------

Grafanaに依存しているパッケージをインストールする。

.. code-block:: sh

    $ sudo yum install urw-fonts

Grafanaのパッケージを取得する。

.. code-block:: sh

    $ wget https://dl.grafana.com/oss/release/grafana-8.3.1-1.x86_64.rpm 

取得したGrafanaのパッケージをインストールする。

.. code-block:: sh

    $ sudo rpm -ivh grafana-8.3.1-1.x86_64.rpm

起動
---------------------------

systemctlコマンドでGrafanaを起動する。

.. code-block:: sh

    # Grafanaのsystemctlへの登録（初回のみ）
    $ sudo systemctl daemon-reload
    # Grafanaの自動起動を有効化する場合
    $ sudo systemctl enable grafana-server
    # Grafanaの起動
    $ sudo systemctl start grafana-server

デバイス監視ログ収集サーバーの導入
###########################

インストール
---------------------------

デバイス監視ログ収集サーバーのソースファイル :file:`device-log-gathering-server` を
:file:`/opt/mlfsoft/iroha2/` に展開する。

実行に必要なパッケージをインストールする。

.. code-block:: sh

    $ sudo yum install python3-devel

デバイス監視ログ収集サーバーでは多くのライブラリが必要になるため、
Pythonの仮想環境を構築してそこにライブラリをインストールする。

.. code-block:: sh

    $ sudo pip3 install virtualenv
    $ mkdir $HOME/.virtualenvs
    $ python3 -m virtualenv -p python3 $HOME/.virtualenvs/r3iroha2_p3
    $ source $HOME/.virtualenvs/r3iroha2_p3/bin/activate
    # 以下、仮想環境が有効な状態
    $ cd /opt/mlfsoft/iroha2/device-log-gathering-server
    $ pip install -r requrements.txt

設定
---------------------------

設定ファイル :file:`device-log-gathering-server/settings_app.py` を実行環境に合わせて変更する。

.. csv-table:: settings_app.pyの設定項目
   :header-rows: 1
   :widths: 10, 30, 40, 30
   :name: settings_app

   項番, 項目名, 説明, デフォルト値
   1, PERIODIC_TASK_DURATION, 監視ログ収集間隔(秒), 300
   2, MNG_SRV_HOST, 装置管理サーバーIPアドレス, 127.0.0.1
   3, MNG_SRV_PORT, 装置管理サーバーポート番号, 8086
   4, MNG_SRV_USER, 装置管理サーバーユーザー名, admin
   5, MNG_SRV_PASSWORD, 装置管理サーバーパスワード, mlfadmin
   6, ELASTIC_SRV_URL, Elasticsearchサーバー接続URL, http://127.0.0.1:9200
   7, ELASTIC_SRV_USER, Elasticsearchの書き込み用Roleに属するユーザー名, bl00
   8, ELASTIC_SRV_PASSWORD, Elasticsearchの書き込み用Roleに属するユーザーのパスワード, bl00user
   9, INST_CODE, 装置コード, ABC
   10, NUM_OF_JOBS, ログ収集ジョブの数, 10

.. note::
    ELASTIC_SRV_USERおよびELASTIC_SRV_PASSWORDは :ref:`es_settings_role` において設定した、
    書き込み用Roleに属するユーザーのユーザー名とパスワードである

起動
---------------------------

サービス起動用スクリプトを登録する。

.. code-block:: sh

    $ sudo cp loggathsrv.service /etc/systemd/system
    $ sudo systemctl daemon-reload

サーバーを起動する。

.. code-block:: sh

    # サーバーの自動起動を有効化する場合
    $ sudo systemctl enable loggathsrv
    # サーバーの起動
    $ sudo systemctl start loggathsrv

サーバー起動後、Webブラウザで http://localhost:8080 にアクセスすると
デバイス監視ログ収集サーバーのWeb UIを開くことができる。

.. figure:: images/logsrv/logsrv_webui.jpg
    :scale: 40
    :alt: Alternative Text
    :name: logsrv_webui

    デバイス監視ログ可視化サーバーのWeb UI（ダッシュボード）

Web UIは4つのメニューで構成され、それぞれデバイス監視ログ収集サーバーに関する情報を閲覧できる。

Dashboard画面
***************************

Dashboard画面には、登録されているデバイス名とタスクの状態が表示される。

Devices and Parameters画面
***************************

Devices and Parameters画面には、登録されているデバイス名とそのパラメータ名の一覧が表示される。

Current Status画面
***************************

Current Status画面には、デバイス名とそのインデックス名、
Elasticsearchに登録されているログの数、その最新日時が表示される。

Settings画面
***************************

Settings画面では、サーバー設定ファイルに登録されている設定の一覧を見ることができる。

Grafanaの操作方法
###########################

データソースの追加
---------------------------

ブラウザからGrafanaのWeb UIにアクセスする。
例としてGrafanaが192.168.0.10にインストールされている場合は、以下のURLにアクセスする。

http://192.168.0.10:3000

管理者アカウントの情報（ユーザー：admin、パスワード：admin）を入力し、 :guilabel:`Login` ボタンを押下する。
画面遷移後、adminの新しいパスワードを入力する画面になるが、変更しない場合は :guilabel:`Skip` を押下する。

メニューから、:menuselection:`Configuration --> Data sources` を選択し、Elasticsearchへの接続情報を追加する。
例として、Elasticsearchが192.168.0.11にインストールされており、
:ref:`es_settings_role` で例に挙げたユーザー `bl00` がElasticsearchにおいて設定されているものとする。

.. csv-table:: Data sourceの設定項目
   :header-rows: 1
   :widths: 10, 30, 30, 30
   :name: settings_data_source

   項番, 名称, 設定, 説明
   1, Name, BL00, 接続名称
   2, URL, localhost:9200, Elasticsearch接続URL
   3, Basic Auth, (選択する), Basic Authを使用する設定
   4, User, bl00, 認証ユーザー名
   5, Password, bl00user, 認証パスワード
   6, Index name, logsurv*abc, インデックス名
   7, Pattern, No pattern, パターン設定
   8, Time field Name, Date, Timeフィールド名
   9, Version, 7.10+, Elasticsearchのバージョン

.. note::

    Elasticsearchにおいて複数のRole/Userを設定している場合、Data sourcesは複数設定することが可能である。

Dashboardの作成
---------------------------

数値データのグラフ作成
***************************

.. figure:: images/logsrv/grafana_timeseries.jpg
    :scale: 20
    :alt: Alternative Text
    :name: grafana_timeseries

    数値データのグラフ設定

1. ブラウザからGrafanaのWeb UIにアクセスする
2. メニューの :guilabel:`+` ボタンを押下し、 :menuselection:`Add panel --> Add a new panel` を選択する
3. Data sourceが複数設定されている場合は選択する
4. Metricとして、Average・Sum・Max・Minなどから最適なものを選択する（通常はAverage）
5. Field名へ抽出するField名を選択する
6. Queryを追加するため、 :guilabel:`+Query` ボタンを押下する
7. 表示する数値データの分だけ、4〜5を繰り返す
8. 画面右側の列の :menuselection:`Panel options --> Title` を変更し、Panelのタイトルを設定する
9. 画面右上の :guilabel:`Save` ボタンを押下し、Dashboard名、Folder名を設定する
10. 画面右上の :guilabel:`Apply` ボタンを押下し、Dashboardに戻る
11. 更にPanelを追加する場合は、画面右上のアイコン群の一番左の :guilabel:`Add Panel` を押下後、 :guilabel:`Add a new panel` を選択し、3〜10を繰り返す
12. 最後にDashboard上で右上のアイコン群から :guilabel:`Save` を押下し保存する

.. note::

    Field名は、以下の命名規則で構成されている。

    <デバイスインスタンス名>_<パラメータ名>-<装置コード>

    例えば、装置コードABCのデバイスインスタンス名LS350のパラメータtemperature_aのField名は、
    LS350_temparature_a-ABCとなる。

文字列データのグラフ作成
***************************

.. figure:: images/logsrv/grafana_statetimeline.jpg
    :scale: 20
    :alt: Alternative Text
    :name: grafana_statetimeline

    文字列データのグラフ設定

.. figure:: images/logsrv/grafana_valuemapping.jpg
    :scale: 20
    :alt: Alternative Text
    :name: grafana_valuemapping

    Value mappingの設定

1. ブラウザからGrafanaのWeb UIにアクセスする
2. メニューの :guilabel:`+` ボタンを押下し、 :menuselection:`Add panel --> Add a new panel` を選択する。または、既存のDashboardで画面右上のアイコン群の一番左の :guilabel:`Add Panel` を押下後、 :guilabel:`Add a new panel` を選択する。
3. 画面右上のPanel種別選択部分で **State timeline** を選択する
4. Data sourceが複数設定されている場合は選択する
5. Group Byとして **Terms** を選択する
6. Field名へ抽出するField名を選択する。このとき、末尾に.keywordと付いているものを選択する。
7. Group Byの右端にある :guilabel:`+` を押下する
8. Then Byとして **Histogram** を選択する
9. Field名として **Date** を入力する
10. Queryを追加するため、 :guilabel:`+Query` ボタンを押下する
11. 表示する文字列データの分だけ、5〜9を繰り返す
12. 画面右側の列のMerge equal consecutive valuesを **On** に、Line widthを **1** に設定する
13. 画面右側の列のValue mappingsへ条件、Valueへ値となる文字列とその表示文字列、色を入力する
14. 画面右側のQueryの隣の :guilabel:`Transform` をクリックする
15. 一覧から :guilabel:`Filter by name` を選択し、表示された項目から、 :guilabel:`Count` のチェックを外す
16. 画面右側の列の :menuselection:`Panel options --> Title` を変更し、Panelのタイトルを設定する
17. 画面右上の :guilabel:`Save` ボタンを押下し、必要に応じDashboard名、Folder名を設定する
18. 画面右上の :guilabel:`Apply` ボタンを押下し、Dashboardに戻る
19. 更にPanelを追加する場合は、画面右上のアイコン群の一番左の :guilabel:`Add Panel` を押下後、 :guilabel:`Add a new panel` を選択し、3〜18を繰り返す
20. 最後に、Dashboard上で右上のアイコン群から :guilabel:`Save` を押下し保存する

.. note::

    Field名は、以下の命名規則で構成されている。

    <デバイスインスタンス名>_<パラメータ名>-<装置コード>

    例えば、装置コードABCのデバイスインスタンス名LS350のパラメータsensorの「.keyword」付きField名は、
    LS350_sensor-ABC.keywordとなる。

ユーザーの追加
---------------------------

.. figure:: images/logsrv/grafana_useradd.jpg
    :scale: 20
    :alt: Alternative Text
    :name: grafana_useradd

    ユーザー追加画面

1. ブラウザからadminユーザーとしてGrafana Web UIへログインする
2. メニューから、 :menuselection:`Server Admin --> Users` を選択する
3. :guilabel:`New user` を押下し、必要項目を入力後、 :guilabel:`Create user` を押下する

ユーザーのRoleはデフォルトでは **Viewer** なので、変更する場合には以下の設定を行う。

1. メニューから :menuselection:`Configuration --> Users` を選択する
2. 変更するユーザー欄の一番右のRoleを **Admin** や **Editor** に変更する

Dashboardへのアクセス権の設定
---------------------------

.. figure:: images/logsrv/grafana_dashboard_access_setting.jpg
    :scale: 20
    :alt: Alternative Text
    :name: grafana_dashboard_access_setting

    Dashboardへのアクセス権設定画面

1. ブラウザからadminユーザーとしてGrafana Web UIへログインする
2. メニューから、 :menuselection:`Dashboards --> Browse` を選択し、アクセス権を追加するDashboardを選択する
3. 画面右上の :guilabel:`Dashboard settings` を押下する
4. 画面左のメニューから、 :guilabel:`Permissions` を選択する
5. :guilabel:`Add Permissions for` の下の選択肢を **User** に変更し、アクセス権を追加するユーザーを選び、アクセス権をView・Edit・Adminの中から選択して :guilabel:`Save` を押下する

.. note::

    DashboardのデフォルトのPermissions設定では、権限を与える対象としてEditor(Role)とViewer(Role)が設定されており、
    すべてのEditorおよびViewerのRoleを持つユーザーにその権限が与えられることになる。
    特定のユーザーにのみこれらの権限を与えたい場合には、設定画面においてEditor(Role)やViewer(Role)を削除する必要がある。

Elasticsearchのデータ操作
###########################

Elasticsearchに保存されたデータを操作することが可能である。
ここでは使用されることが想定される操作について説明する。

インデックスの一覧表示
---------------------------

Elasticsearchに保存されているインデックスの一覧を表示することができる。
:ref:`es_settings_passwd` で設定したElasticsearchのパスワードが `mlfadmin` の場合、
以下のコマンドを実行する。

.. code-block:: sh

    curl -XGET -u elastic:mlfadmin 'localhost:9200/_cat/indices?v'

インデックスの内容表示
---------------------------

Elasticsearchに保存されているインデックスのうち、任意のインデックスの内容を表示することができる。
例えば、インデックス **logsurvsample-abc** の内容を表示したい場合、以下のコマンドを実行する。

.. code-block:: sh

    curl -XGET -u elastic:mlfadmin -H 'Content-Type:application/json' 'localhost:9200/logsurvsample-abc/_search?pretty'

応答はJSON形式で表示される。
デフォルトでは直近の10件分のデータ（ドキュメント）が表示されるため、リクエストにsizeパラメータを追加する。
直近の100件分のデータを表示する場合、以下のコマンドを実行する。

.. code-block:: sh

    curl -XGET -u elastic:mlfadmin -H 'Content-Type:application/json' 'localhost:9200/logsurvsample-abc/_search?size=100&pretty'

また、指定した期間におけるデータを確認したい場合にはDate fieldを利用する。
例えば、2022年8月11日4:50から5:00までの期間についてデータを表示する場合、以下のコマンドを実行する
（sizeパラメータを指定しない場合、10件分しか表示されない）。

.. code-block:: sh

    curl -XGET -u elastic:mlfadmin -H 'Content-Type:application/json' 'localhost:9200/logsurvsample-abc/_doc/_search?size=10000&pretty' -d '{"query":{"range":{"Date":{"gte":"2022-08-11T04:50:00+09:00" , "lte":"2022-08-11T05:00:00+09:00"}}}}'

インデックスの削除
---------------------------

不要になったインデックスを削除することができる。
例えば、インデックス **logsurvsample-abc** を削除する場合、以下のコマンドを実行する。

.. code-block:: sh

    curl -XDELETE -u elastic:mlfadmin -H 'Content-Type:application/json' 'localhost:9200/logsurvsample-abc?pretty=true'

削除に成功すると、以下のレスポンスが表示される。

.. code-block:: sh

    {
      "acknowledged": true
    }