JOCコックピット - 操作ログ

# 訳注

オープンソースジョブ管理システム[SOS JobScheduler](http://ossl.cloudblog.jp/?page_id=148) V.1.11から導入されたJOCコックピットの操作ログ機能についてご紹介します。
本記事はSOS社のナレッジベース記事[JOC Cockpit - Audit Log](https://kb.sos-berlin.com/display/PKB/JOC+Cockpit+-+Audit+Log)の2017/5月末時点での翻訳です。
元記事は随時更新されていますので、できるだけアップデートしていくつもりですが、一応元記事も確認してください。

# イントロダクション

操作ログ機能は、JOCコックピットユーザーや外部アプリケーションを含むJobScheduler Webサービス（REST API、以下WEBサービスと呼びます）のユーザーが実行する、JobSchedulerオブジェクトへのすべての操作を安全かつ自動的に記録することにより、ジョブ管理におけるコンプライアンスと監査の要件を満たすことができます。 
操作ログには、ジョブ、ジョブチェーン、オーダーなどのJobSchedulerオブジェクト（以下オブジェクトと呼びます）とそのステータスを変更する操作が一覧表示されます。操作ログは、WEBサービスによって、データベースとログファイルに書き込まれます。

# 操作ログの範囲

操作ログは、 ジョブ、ジョブチェーン、オーダーなどのすべてのオブジェクトに対する、ユーザーのオーダーやジョブの開始、終了、一時停止などの操作によるステータスの変更を記録します。記録は、人間とシステムで読み取り可能なフォーマットを使用し、次の主要機能を提供します。

- コンプライアンスを満たす記録をコンプライアンス担当者に渡すことができるシンプルなファイル形式で提供
- レポーティングのためのジョブ管理の運用記録を提供
- 運用スタッフが容易にアクセスできる運用記録を提供
- 記録を格納するために使用されたデータベースが利用可能でない場合、第２の運用情報源を提供

必要な権限を持つJOCコックピットのユーザーは、JOCコックピットのメインメニューの【操作ログ】リンクをクリックして、以下のスクリーンショットに示すように、JOCコックピットの操作ログを表示できます。 このビュー、特にコメント、作業時間、およびチケットリンクの情報は、履歴情報よりも関連性の高い操作情報をユーザーに提供することを目的としています。

![スクリーンショット 2017-05-21 14.37.27.png](https://qiita-image-store.s3.amazonaws.com/0/52445/18aa5e92-135c-56ed-d523-5151b18186c8.png)

# 注意

操作ログには、JOCコックピットおよびWEBサービスを使用する他のアプリケーションから操作された、オブジェクト変更に関する情報が含まれます。 JOE（JobSchedulerオブジェクトエディタ）を使用したオブジェクトに対する変更、またはテキストエディタなどを使用してファイルシステム上のオブジェクトに直接行われた変更は含まれません。

# 説明

**コンプライアンス、レポート作成、運用機能**

操作ログは、WEBサービスによって自動的に書き込まれます。

- 操作ログへのエントリは、オブジェクトの状態を変更する操作がJOCコックピットまたはWEBサービスにアクセスする他のアプリケーションで開始されたときに行われます。
- 操作ログを無効にすることはできません。

操作ログは同時に2つの場所に書き込まれます。

- WEBサービスで使用されるデータベース：
オペレータが操作ログ情報を確認できるように、JOCコックピットから使用されます。
また、JOCコックピットはレポート目的でMicrosoft Excel互換のエクスポートファイルを生成するためにも使用します。

- 操作ログファイル：
このファイルはアーカイブされ、コンプライアンス記録として使用されることを意図しています。 システム管理者は、データベースを使用できない場合、このファイルのコピーを運用スタッフが利用できるようにすることができます。
操作ログファイルはJetty_base/logsフォルダ（Jetty Webサーバー設定ファイルを含むディレクトリ）にある、JOCAuditLog.logです。

すべての新しいエントリは操作ログに追加され、ログファイルおよびデータベースは上書きされません。

- システム管理者は、準拠する法律およびコーポレートガバナンスに従って、ログファイルのアーカイブおよびハウスキーピングシステムを手配しなければなりません。
- システム管理者は、操作ログファイルに含まれる情報の保存期間などのコンプライアンス要件を確認する必要があります。

操作ログへのアクセス制御は以下のとおりです。

- JOCコックピットからは、適切な権限を持つユーザーだけに表示されます。ユーザーのアクセス許可の指定については、「[JOCコックピット - 認証と認可](http://qiita.com/satoruf/items/20765b902b1a70cd9597)」の記事を参照してください。 
操作ログのアクセス許可の初期設定は、[Authentication and Authorization - Permissions](https://kb.sos-berlin.com/display/PKB/Authentication+and+Authorization+-+Permissions+for+the+JOC+Cockpit+Web+Service)に記載されています。
- システム管理者は、JOCコックピットが使用するデータベース、または操作ログファイルが書き込まれるファイルシステムからアクセスできます。
- 操作ログは、すべてのJOCコックピットユーザーに対して読み取り専用です。ファイルシステムとデータベースの両方にアクセスできるシステム管理者のみがログを変更できます。

**操作ログの内容**

- Created：操作が実行された時点のタイムスタンプ。
- Account：操作を実行したユーザーアカウント。
- Request URL：JOCコックピットによって呼び出されたWEBサービスのURL、URLはオブジェクトのタイプとアクションを表します（例： /orders/ start）。
- Job Chain, Order ID, Job：操作が実行されたオブジェクトを識別します。
- Reasons：アクションが実行された理由の説明（必須またはオプション、以下を参照）。 あらかじめ定義されたリスト（joc.propertiesファイルで設定可能）、またはフリーテキスト入力から項目を選択することによって作成されます。 フリーテキストは最大2,000文字を追加できます。
- Time Spent（オプション）：作業に要する時間（影響分析の時間を含む）を追加することができます。
- Ticket Link（オプション）：変更管理のための基礎となるチケットを識別するために、チケットシステムなどのチケットを指すURLを追加できます。

**コメント：理由、時間、チケットのリンク**

操作を実行するユーザーは、コメント（理由、作業時間、チケットリンク）を操作ごとに追加できます。 これらのコメントは、操作の一部として入力され、操作ログに保存されます。 その後、必要な権限を持つ他のすべてのJOCコックピットユーザーがこれらを読み取ることができます。例として 「新規オーダー追加」操作のフォームを示します。
![スクリーンショット 2017-05-21 16.17.55.png](https://qiita-image-store.s3.amazonaws.com/0/52445/02a4cd28-f73f-3e38-9593-e4cad8d05a65.png)
コメントは、上のスクリーンショットに示すように、3つの要素で構成されています。

- 理由 （必須またはオプション）：ドロップダウンリストから選択された定義済みの理由、または個別の理由は、テキストフィールドに入力
- 作業時間 （常にオプション）：分
- チケットリンク （常にオプション）：http://から入力

理由は、操作がなぜ実行されたのかを後で理解するための助けとなるように意図されています。
作業時間とチケットリンクは、必要に応じて、エンドユーザのジョブ管理に関するアカウンティングとレポートの基本情報として使用されます。

**コメントの設定**

コメントは設定によって、JOCコックピットのすべてのユーザーにとって必須またはオプションにすることができます。

- コメントが必須の場合：
ユーザーは、実行する各操作に理由を入力する必要があります。
作業時間とチケットリンクはオプションです。
- コメントがオプションの場合：
ユーザーは、ユーザープロファイルで個別に有効化する事ができます。
コメントの有効化により、作業時間とチケットリンクを入力することができます。

***コメントの必須設定方法***
force_comments_for_audit_logフラグは、 コメント入力を必須にするために使用されます。 このパラメータは、./joc_home/jetty_base/resources/joc/joc.propertiesファイルで設定します。

```
### This flag controls if the comment is required or not.
force_comments_for_audit_log = false
```

force_comments_for_audit_logの初期設定は、falseになっています。
force_comments_for_audit_log = trueに設定した場合、定義済みまたは個別の理由のいずれかが必須入力となります。

***プロファイルでのコメントの有効化設定***
コメントが必須設定ではない場合（force_comments_for_audit_logフラグがfalseに設定されている）、ユーザは、実行する操作の理由を入力するオプションを表示するかどうかを自分のプロファイルで設定できます。 これは、次のスクリーンショットに示すように、ユーザーのプロファイルで【ログコメント有効化】にチェックすることで設定できます。
![スクリーンショット 2017-05-21 17.06.20.png](https://qiita-image-store.s3.amazonaws.com/0/52445/d1452276-8f6e-f4d8-e56c-3157a3241f70.png)
このオプションが設定されておらず、 理由が必須ではなくデフォルト設定である場合、オーダーまたはジョブの開始時にユーザーは理由入力機能は表示されません。

***オーダー開始とタスク開始の動作***
[オーダー開始]および[タスク開始]の動作は、ユーザーのプロファイル設定でログコメントが有効かどうか、 コメントが必須かオプションか（force_comments_for_audit_log = trueまたはfalse）によって、動作が異なります。

|ログコメント有効化(プロファイル) |コメント必須設定|コメントオプション設定|
|:-----------------|:------------------|:------------------|
|無効|コメント入力画面|オーダー／タスクが即時開始|
|有効|コメント入力画面|コメント入力画面|

**理由リストの設定**

JOCコックピットには、事前定義された理由リストが設定されています。
定義済みの理由リストは、 `./joc_home/jetty_base/resources/joc/joc.properties`にありますので、自由に変更可能です。(日本語可)

```
### Pre-defined comments
comments =  System maintenance; \
            Repeat execution; \
            Business requirement; \
            Restart failed execution; \
            Re-instantiate stopped object; \
            Temporary stop; \
            Change of JobScheduler object; \
            Rerun with parameter changes; \
            Change of external dependency; \
            Application deployment and upgrade
```
***理由リストの構文***

- 各行の終わり近くのセミコロン";" は、コメントの終わりを示します。 セミコロンは区切り文字として機能しますので、カンマを文章内で使用できるようにします。
- バックスラッシュ"\"は、改行を示します。

***理由リストの変更***
システム管理者は、理由リストとforce_comments_for_audit_logフラグを、独自の要件に合わせて変更することができます。
joc.propertiesファイルへの変更を有効にするには、JOCコックピットを再起動する必要があります。

***個別の理由***
個別の理由は、このページの上部付近のスクリーンショットに示すように、テキストフィールドに入力することができます。(日本語可)

**操作ログ表示**

JOCコックピットのメインメニューで【操作ログ】を選択すると、 操作ログ全体を表示できます。
個々のジョブチェーンの操作ログは、 ジョブチェーンの【フロー表示】が選択されているときに【操作ログ】タブで表示されます。 これは、スタンドアロンジョブでは使用できません。

***パラメータ***

操作ログ表示リストの各エントリの左側にある矢印は、参照するWEBサービスに送信されたリクエストに関するより詳細な情報を提供します。 これは、次のスクリーンショットに示すように、新しい行を開き、実行コマンドの詳細が表示できます。
<img width="685" alt="スクリーンショット 2017-05-21 18.03.08.png" src="https://qiita-image-store.s3.amazonaws.com/0/52445/a3281e89-c93b-983a-2577-73ff57d3a533.png">

***フィルタ***

フィルタを使用して、操作ログの検索ができます。

- 詳細検索：
操作ログ表示画面の上部に表示されている、全て・本日・最新１時間前などのフィルタに加えて、ビューの右上にある詳細検索ボタンで開く詳細検索機能があります。 このボタンをクリックすると、詳細検索機能が開きます。 新たなフィルタは、以前のフィルタを上書きします。 たとえば、[本日]プリセットフィルタが選択されてから[09:00:00]から[18:00:00]までを設定すると、09：00〜18：00の間に開始されたすべての操作ログが、表示されます。
![スクリーンショット 2017-05-21 18.29.01.png](https://qiita-image-store.s3.amazonaws.com/0/52445/6fcd0cc2-011e-006b-10bb-e391b37c409d.png)

***検索フィールド***
[検索]フィールドでは、フリーテキスト検索を実行できます。

**操作ログの場所**

操作ログファイルは、 `./joc_home/jetty_base/logs`ディレクトリのJOCAuditLog.logです。
ファイルが存在しない場合は、ユーザーがオブジェクトの状態を変更する最初の操作で作成されます。
操作ログファイルの場所と名前は、 log4j.propertiesファイルで指定できます。 詳細については、 [JOC Cockpit - Logging](https://kb.sos-berlin.com/display/PKB/JOC+Cockpit+-+Logging)を参照してください。

**操作ログのサンプル**
次のサンプルは、異なるブラウザを使用してaa_itoと並行して14:13:47にログインした2人のユーザーaa_itoとrootによって実行された多数のWebサービス要求を示しています。
```
2017-02-10 11:39:55,992 INFO  REQUEST: ./orders/add - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"jobChain":"/tutorials/hello_world_job_chain","at":"now"}]} - COMMENT: Demo start for documentation
2017-02-10 11:43:05,831 INFO  REQUEST: ./jobs/start - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","jobs":[{"job":"/standalone-jobs/test_sa_job1","at":"now"}]} - COMMENT: Demo start for documentation
2017-02-10 11:54:11,731 INFO  REQUEST: ./jobs/start - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","jobs":[{"job":"/standalone-jobs/test_sa_job1","at":"now"}]} - COMMENT: null
2017-02-10 12:38:31,507 INFO  REQUEST: ./login - USER: aa_ito - PARAMS: {} - COMMENT: it_operator
2017-02-10 12:48:39,857 INFO  REQUEST: ./orders/start - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"orderId":"hello_world_order","jobChain":"/tutorials/hello_world_job_chain","at":"now"}]} - COMMENT: null
2017-02-10 13:34:57,995 INFO  REQUEST: ./login - USER: aa_ito - PARAMS: {} - COMMENT:
2017-02-10 13:35:03,391 INFO  REQUEST: ./login - USER: aa_ito - PARAMS: {} - COMMENT: it_operator
2017-02-10 13:35:49,186 INFO  REQUEST: ./orders/start - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"orderId":"hello_world_order","jobChain":"/tutorials/hello_world_job_chain","at":"now"}]} - COMMENT: null
2017-02-10 13:36:13,905 INFO  REQUEST: ./jobs/start - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","jobs":[{"job":"/standalone-jobs/test_sa_job1","at":"now"}]} - COMMENT: null
2017-02-10 13:53:50,184 INFO  REQUEST: ./orders/add - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"jobChain":"/tutorials/hello_world_job_chain","state":"20","at":"now"}]} - COMMENT: Test Start from step 20
2017-02-10 13:56:05,459 INFO  REQUEST: ./orders/add - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"jobChain":"/tutorials/hello_world_job_chain","at":"now"}]} - COMMENT: null
2017-02-10 14:02:30,467 INFO  REQUEST: ./login - USER: aa_ito - PARAMS: {} - COMMENT: it_operator
2017-02-10 14:09:38,471 INFO  REQUEST: ./orders/add - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"jobChain":"/tutorials/hello_world_job_chain","state":"20","at":"now"}]} - COMMENT: Repeat execution
2017-02-10 14:10:36,839 INFO  REQUEST: ./orders/add - USER: aa_ito - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"jobChain":"/tutorials/hello_world_job_chain","state":"20","at":"now"}]} - COMMENT: Repeat execution
2017-02-10 14:13:47,553 INFO  REQUEST: ./login - USER: root - PARAMS: {} - COMMENT: all
2017-02-10 14:14:48,351 INFO  REQUEST: ./orders/add - USER: root - PARAMS: {"jobschedulerId":"jobscheduler_1.11","orders":[{"jobChain":"/tutorials/hello_world_job_chain","state":"20","at":"now"}]} - COMMENT: Repeat execution
```
***操作ログの説明***
操作ログには、オブジェクトタイプと操作を識別できるWEBサービスURLが含まれています。 例えば、 `. /orders/resume`は、オーダーを再開する操作であり、各ログエントリのPARAMS部分で指定されているように、オーダーIDとジョブチェーンパスで識別されます。

**操作ログのエキスポート**

操作ログのエキスポート機能は、次のスクリーンショットに示す右上にある矢印の付いたボタンをクリックすると、操作ログを全体またはフィルタリングのいずれかでExcel形式でエキスポートすることができます。![スクリーンショット 2017-05-21 18.48.12.png](https://qiita-image-store.s3.amazonaws.com/0/52445/afac8dba-f59d-aa97-5194-072aac49d4e0.png)
操作ログビューに表示されているフィルタされたテーブルは、MicrosoftExcel®互換の.xlsファイルとしてエキスポートされます。 ![スクリーンショット 2017-05-21 18.53.24.png](https://qiita-image-store.s3.amazonaws.com/0/52445/00c3e1b3-9826-4b8c-5817-064536addbed.png)
上記の操作ログファイルのサンプルにある、PARAMS部分はエキスポートされません。

***エキスポートの設定***
エキスポート機能では、【操作ログ】画面に表示されるログのみが使用されます。 たとえば、900行の操作ログをエキスポートするには、表示行数を1000に設定し900行全てを操作ログ画面にロードする必要があります。
たとえば、2,500行の操作ログをエキスポートするには、 プロファイル設定で最大リスト表示行数を増やす必要があります。この場合、3000で十分です。![スクリーンショット 2017-05-21 19.02.45.png](https://qiita-image-store.s3.amazonaws.com/0/52445/a75c3849-f7bc-deec-3aff-17b41956b153.png)
注：最大リスト表示行数の設定は、エキスポートなどの他のリストビューの読み込みを大幅に遅くする可能性があるため、エキスポートを実行した後にリセットしてください。

**操作ログのハウスキーピングとアーカイブ**

すでに述べたように、JOCコックピットは継続的に操作ログを追加します。
システム管理者は、ビジネスとコンプライアンスの要件に従って、それぞれハウスキーピング/ログローテーションとアーカイブシステムを実装する必要があります。