ジャーナル機能

ジャーナル機能を使用すると、各ファイルの処理結果を詳細にNDJSON形式で記録できます。

基本的な使い方

lightfile-shot /path/to/images --journal /path/to/journal.ndjson

ジャーナルファイルの形式

NDJSON（改行区切りJSON）形式で、各行が1ファイルの処理結果を表します。

{"version":1,"startedAt":"2024-01-01T12:00:00Z","durationMs":150,"absPath":"/path/to/image1.jpg","relPath":"image1.jpg","format":"jpeg","status":"optimized","originalSize":102400,"optimizedSize":81920}
{"version":1,"startedAt":"2024-01-01T12:00:01Z","durationMs":50,"absPath":"/path/to/image2.jpg","relPath":"image2.jpg","status":"skipped","message":"already optimized"}
{"version":1,"startedAt":"2024-01-01T12:00:02Z","durationMs":80,"absPath":"/path/to/image3.jpg","relPath":"image3.jpg","status":"failed","message":"unsupported format"}

フィールド説明

フィールド	説明	例
`version`	レコードバージョン（常に1）	`1`
`startedAt`	処理開始時刻（ISO 8601形式）	`2024-01-01T12:00:00Z`
`durationMs`	処理時間（ミリ秒）	`150`
`absPath`	絶対パス	`/path/to/image.jpg`
`relPath`	相対パス	`image.jpg`
`format`	画像フォーマット（処理時のみ）	`jpeg`, `png`
`status`	処理状態	`optimized`, `skipped`, `failed`
`originalSize`	元のファイルサイズ（バイト、optimized時のみ）	`102400`
`optimizedSize`	最適化後のサイズ（バイト、optimized時のみ）	`81920`
`message`	エラー・スキップメッセージ（skipped, failed時のみ）	`already optimized`

処理ステータス

ステータス	意味	含まれるフィールド
`optimized`	最適化成功	`format`, `originalSize`, `optimizedSize`
`skipped`	スキップ	`message`（理由）
`failed`	処理失敗	`message`（エラー詳細）

ジャーナルの活用例

最適化成功ファイルのみを抽出

# grepで抽出
grep '"status":"optimized"' result.ndjson

失敗したファイルのリストを作成

jqを使用:

grep '"status":"failed"' result.ndjson | jq -r '.absPath' > failed_files.txt

jqなしの代替方法:

grep '"status":"failed"' result.ndjson | grep -o '"absPath":"[^"]*"' | cut -d'"' -f4 > failed_files.txt

削減量の合計を計算（jq使用）

grep '"status":"optimized"' result.ndjson | jq -s 'map(.originalSize - .optimizedSize) | add'

削減率の平均を計算（jq使用）

grep '"status":"optimized"' result.ndjson | jq -s 'map((.originalSize - .optimizedSize) / .originalSize * 100) | add / length'

jqのインストール

jq は軽量で強力なJSONプロセッサです。

macOS:

brew install jq

Linux (Ubuntu/Debian):

sudo apt-get install jq

Linux (CentOS/RHEL):

sudo yum install jq

Windows:

公式サイトからダウンロード
または Chocolatey: choco install jq

注: 基本的なファイル抽出であれば grep と標準的なテキスト処理ツールでも対応可能ですが、統計計算には jq の使用を推奨します。

実行例

処理結果を記録しながら最適化

lightfile-shot /path/to/images \
  --quality high \
  --concurrency 4 \
  --journal result.ndjson

ドライランモードでもジャーナル記録

lightfile-shot /path/to/images \
  --dry-run \
  --journal preview.ndjson

ドライランモードでも、どのファイルが処理対象となるか、削減量はどれくらいかをジャーナルに記録できます。

ジャーナルファイルの管理

ファイル名の工夫

日時を含めたファイル名にすると管理しやすくなります:

# 日時をファイル名に含める
JOURNAL_FILE="journal-$(date +%Y%m%d-%H%M%S).ndjson"
lightfile-shot /path/to/images --journal "$JOURNAL_FILE"

ログローテーション

定期実行する場合は、ジャーナルファイルが肥大化しないよう定期的に削除・アーカイブすることをおすすめします。

# 30日以上前のジャーナルファイルを削除
find /var/log/lightfile-shot -name "journal-*.ndjson" -mtime +30 -delete

目次