ログデータクリーンアップ

概要

HAPのプライベートデプロイ環境では、一部の「ログ」形式データがMongoDBに長期間保持されており、利用状況によってはデータ量が非常に膨大になり、データベースのストレージを大きく消費する場合があります。
MongoDBで show dbs コマンドを利用することで、各データベースの容量を確認できます。また、テーブルサイズの計算コマンドを使ってストレージ使用量の多いテーブルを特定できます。
本ドキュメントでは、指定したルールに基づいて関連テーブルから物理的にデータを削除する「ログデータクリーンアップ」ソリューションをご案内します。

作業前の重要なお知らせ

クリーンアップ処理は物理削除となり、該当データは完全に消去されます。
操作完了後、指定期間のログデータはシステム上で復旧・閲覧できません。

影響範囲:

mdworkflow データベースのクリーンアップ対象テーブル
主に以下に影響します:
- ワークフロー実行履歴
- 承認フロー履歴
- 進行中プロセスの中断: クリーンアップ対象に未完了のワークフロー・承認フローが含まれる場合、データ消失によって当該プロセスは継続できなくなります。
mdworksheetlog データベースのテーブル
- ワークシートレコードの操作ログ
mdintegration データベースのテーブル
- インテグレーションセンターのリクエストログ
mdservicedata データベースのテーブル
- アプリケーション動作ログ
- 利用分析ログ

データクリーンアップホワイトリスト

データベース	テーブル名	用途説明
mdworkflow	wf_instanceHistory	ワークフローノードのログ。標準では直近90日分のみ保持します。
mdworkflow	wf_instance	メインワークフロー実行履歴関連データ
mdworkflow	wf_subInstanceActivity	サブプロセス実行履歴関連データ
mdworkflow	wf_subInstanceCallback	サブプロセス実行履歴関連データ
mdworkflow	wf_instanceExtends	ワークフロー実行履歴関連データ
mdworkflow	code_catch	コードブロックノードの実行時に生成される一時データを格納
mdworkflow	hooks_catch	受信したWebhookデータを格納
mdworkflow	webhooks_catch	ワークフローノード「APIリクエスト送信」で取得したデータを格納
mdworkflow	app_multiple_catch	マルチデータノードで「直接取得」を選択した際に取得したデータを格納
mdworkflow	custom_apipackageapi_catch	API連携呼び出し時のレスポンスデータを格納
mdworkflow	custom_apipackage_catch	APIパッケージノードの結果を保存し、後続ノードの値取得に使用。単一テーブルのクリーンアップにはアーカイブツール 1.0.7 以降が必要
mdworksheetlog	wslog*	対応月のワークシートレコード操作ログテーブル名形式：wslog+日付（例：wslog202409）
mdintegration	wf_instance	インテグレーションセンターのリクエストログ
mdintegration	wf_instance_relation	リクエストログ関連データ
mdintegration	webhooks_catch	リクエストログ「詳細を見る」相当のログデータ
mdintegration	code_catch	リクエストログ「詳細を見る」相当のログデータ
mdintegration	json_catch	リクエストログ「詳細を見る」相当のログデータ
mdintegration	custom_parameter_catch	リクエストログ「詳細を見る」相当のログデータ
mdservicedata	al_actionlog*	対応月のアプリケーション動作ログテーブル名形式：al_actionlog+日付（例：al_actionlog202409）
mdservicedata	al_uselog	「利用分析」機能のログデータ

データクリーンアップの推奨方法

下記はデータ種別ごとの具体的なクリーンアップ方法と注意点です。

月次アーカイブ型のログテーブル

自動的に月単位で生成されるログテーブルに対する方法です。

対象テーブル:
- mdworksheetlog 配下の全ての wslog で始まるテーブル
- mdservicedata 配下の全ての al_actionlog で始まるテーブル
操作方法: 最も効率的な方法は、drop コマンドで月次アーカイブテーブルごと削除することです。
この操作は極めて高速で、テーブルで消費されていたディスク領域を即座に開放します。
操作例:
```
use mdworksheetlog;
db.wslog202401.drop();
```
上記は、2024年1月分のワークシートログを削除する例です。

ワークフローパラメータの月別テーブル

mdworkflowデータベースのwf_instanceVariable_xxxxxxテーブルは、指定月に開始されたワークフローが実行中に生成したプロセスパラメータを保存します。xxxxxxは開始月を表すyyyyMM形式で、例えばwf_instanceVariable_202601、wf_instanceVariable_202602です。

実行中に生成されたプロセスパラメータは、ワークフローの開始月に対応する月別テーブルに書き込まれます。

ある過去の月について、プロセスパラメータを使用するすべてのワークフローが完了したことを確認できれば、その月のデータが後続の処理で使用されることはありません。この場合、dropコマンドで該当月のテーブル全体を削除すると、ストレージ領域を迅速に回収できます。

削除前に、その月のプロセスパラメータを読み取る必要がある実行中のワークフローが残っていないことを必ず確認してください。残っている場合、パラメータの欠落によってワークフローが失敗したり、異常が発生したりする可能性があります。

操作例：以下はmdworkflowデータベースの2026年1月のプロセスパラメータを削除します。

use mdworkflow;
db.wf_instanceVariable_202601.drop();

ワークフロー実行履歴データ

ワークフローや承認フローの実行履歴のクリーンアップ時は、以下4つの主要テーブルが対象となります。

wf_instance
wf_subInstanceActivity
wf_subInstanceCallback
wf_instanceExtends

これら4テーブルは密接に関連し、一連のプロセス記録を構成しています。
クリーンアップ時は「同じ期間・同じルールで4テーブル全て」に対して同期的に操作してください。
どれか一つでも削除ルールをずらすと、履歴検索ができなくなったり、システムの予期せぬ不具合につながります。

キャッシュ系テーブル（_catchで終わるもの）

mdworkflow および mdintegration 配下に分散して格納されるキャッシュ用テーブルです。
ワークフローやインテグレーション実行時の一時データの保存に使われます。
実際の状況に応じて任意に/個別クリーンアップが可能です。

custom_apipackage_catch と custom_apipackageapi_catch はどちらもノードの結果を保存しており、後続ノードが値を取得する際に参照する場合があります。ホワイトリストへの追加は、無条件に削除できることを意味しません。削除前に、関連するプロセスがすべて完了し、実行履歴の詳細を参照する必要がないことを確認してください。保持範囲は関連するプロセス履歴と一致させてください。

両テーブルの自動クリーンアップの仕組みは異なるため、デプロイ済みバージョンのクリーンアップタスクの対象範囲を確認してください。日時フィールドが空であること、日時が古いこと、月別テーブルが存在することだけを理由に、元のテーブルのデータを削除できると判断しないでください。

主なリスク・注意点：

mdworkflow 側のキャッシュをクリーンアップすると、実行中のワークフローが依存データ消失でエラー停止する場合があります。（例：webhooks_catch はAPIリクエストノードの取得データ一時保管で利用、プロセス中に削除すると進行不能）
mdintegration 側のキャッシュクリーンアップは、インテグレーションセンターの「リクエストログ > 詳細を見る」データが参照できなくなります。

操作推奨：
上記リスク許容度に応じて以下のいずれかを選択します。

条件付き削除
業務継続性を優先する場合、「期間指定などの条件」を設定したクリーンアップツール等で古いキャッシュデータのみを削除してください。
テーブルごと全削除
プロセスの中断や過去の詳細の参照が不要と明確な場合は、テーブルごと drop しても問題ありません。一括削除が最速で空き容量を確保できます。

利用分析ログ

mdservicedata データベースの al_uselog テーブルは、プロダクトの「利用分析」機能で使用するデータを保存しています。
フロントエンド画面上での参照は「過去1年分のみ」が対象のため、1年以上前のデータは定期的にクリーンアップすることを推奨します。

データクリーンアップタスクの設定方法

custom_apipackage_catch のみをクリーンアップする場合は、アーカイブツール 1.0.7 以降を使用し、config.json の table を custom_apipackage_catch に設定してください。旧バージョンの *_catch は許可された設定パターンですが、この正確なテーブル名は許可されません。単一テーブルの設定を *_catch に置き換えると、他のノード結果テーブルも対象となるため、置き換えないでください。

このテーブルを個別にクリーンアップする際のイメージ：

amd64：nocoly/archivetools:1.0.7
arm64：nocoly/archivetools-arm64:-

イメージ（オフラインパッケージダウンロード）を取得します。
```
docker pull nocoly/archivetools:1.0.7
```

config.json 設定ファイルを作成します。以下はワークフロー実行履歴削除の例です。

[
  {
    "id": "1",
    "text": "説明",
    "start": "2023-05-31 16:00:00",
    "end": "2023-06-30 16:00:00",
    "src": "mongodb://root:password@192.168.1.20:27017/mdworkflow?authSource\u003dadmin",
    "archive": "",
    "table": "wf_instance",
    "delete": true,
    "batchSize": 500,
    "retentionDays": 0,
    "concurrencyLimit": 100
  },
  {
    "id": "2",
    "text": "説明",
    "start": "2023-05-31 16:00:00",
    "end": "2023-06-30 16:00:00",
    "src": "mongodb://root:password@192.168.1.30:27017/mdworkflow?authSource\u003dadmin",
    "archive": "",
    "table": "wf_subInstanceActivity",
    "delete": true,
    "batchSize": 500,
    "retentionDays": 0,
    "concurrencyLimit": 100
  },
  {
    "id": "3",
    "text": "説明",
    "start": "2023-05-31 16:00:00",
    "end": "2023-06-30 16:00:00",
    "src": "mongodb://root:password@192.168.1.30:27017/mdworkflow?authSource\u003dadmin",
    "archive": "",
    "table": "wf_subInstanceCallback",
    "delete": true,
    "batchSize": 500,
    "retentionDays": 0,
    "concurrencyLimit": 100
  },
  {
    "id": "4",
    "text": "説明",
    "start": "2023-05-31 16:00:00",
    "end": "2023-06-30 16:00:00",
    "src": "mongodb://root:password@192.168.1.30:27017/mdworkflow?authSource\u003dadmin",
    "archive": "",
    "table": "wf_instanceExtends",
    "delete": true,
    "batchSize": 500,
    "retentionDays": 0,
    "concurrencyLimit": 100
  }
]

上記フォーマットに従ってクリーンアップ対象テーブルごとに設定を追加・調整してください。
設定ファイル上の時刻は「UTC」表記です。
- UTC: 2023-05-31 16:00:00 → UTC+8に変換: 2023-06-01 00:00:00
- UTC: 2023-06-30 16:00:00 → UTC+8に変換: 2023-07-01 00:00:00

パラメータ説明:

"id": "タスク識別用ID",
"text": "任意の説明",
"start": "削除開始時刻（UTC）、この時間以降のデータを削除（retentionDays値が1以上の場合は無効化）",
"end": "削除終了時刻（UTC）、この時間未満のデータを削除（retentionDays値が1以上の場合は無効化）",
"src": "接続元データベースのアドレス",
"archive": "接続先アーカイブDBアドレス（空の場合はアーカイブなし、削除のみ実施）",
"table": "対象テーブル名",
"delete": "trueでタスク完了後に元データ削除、レコード件数一致確認後のみ削除。不要ならfalse指定",
"batchSize": "1回のinsert/deleteのバッチ数",
"retentionDays": "既定値0。1以上の場合、指定日前以前のデータを全削除、スケジュール実行方式（start/end無効）、既定実行間隔24時間",
"concurrencyLimit": "同時実行上限（既定：100）"

config.json の配置ディレクトリでアーカイブサービスを起動します。

docker run -d -it -v $(pwd)/config.json:/usr/local/MDArchiveTools/config.json -v /usr/share/zoneinfo/Etc/GMT-8:/etc/localtime nocoly/archivetools:1.0.7

補足事項:

クリーンアッププログラムとHAPを同一サーバ単体モードで運用する場合、docker run コマンドに --network script_default を追加してください。これによりMongoDBにDocker内部ネットワーク経由でアクセス可となるため、config.jsonのsrcは mongodb://sc:27017/dbname と記載します。
実行時は、ソースDB／アーカイブDB／実行サーバに一定の負荷が生じます。業務のアイドル時間帯等で実施してください。
ログ閲覧:
- バックグラウンド実行（既定）: docker ps -a でコンテナIDを特定し、docker logs <コンテナID> で状態確認
- フォアグラウンド実行: 先頭の -d オプションを省略するとリアルタイム出力で進捗監視が可能です
スケジューリング:
- 実行間隔はカスタムENV変数 ENV_ARCHIVE_INTERVAL（単位ミリ秒、既定86400000＝24時間）で変更可能です
ディスク空き領域の回収について: クリーンアップツール等でデータ削除後、即座にディスク空き領域として反映されることはありませんが、同テーブルの格納領域として再利用されます。

概要​

作業前の重要なお知らせ​

データクリーンアップホワイトリスト​

データクリーンアップの推奨方法​

月次アーカイブ型のログテーブル​

ワークフローパラメータの月別テーブル​

ワークフロー実行履歴データ​

キャッシュ系テーブル（_catchで終わるもの）​

利用分析ログ​

データクリーンアップタスクの設定方法​

概要