
# ログファイル

`logging.file.name` (ファイル) または `logging.file.path` (ディレクトリ。その中に `spring.log`) は `FileAppender` を有効にします。サーバーはこの方法でログを保持します。アプリはバグレポートに添付するためにファイルを保持することがあります。

## 使う理由

コンソールの内容はプロセスの終了とともに消えます。ファイルは後のために履歴を保持し、サイズでロールオーバーすることでディスクがいっぱいになるのを防ぎます。

## 例

```yaml
# lib/resources/application.yml
logging:
  file:
    name: logs/shop.log
    rolling-policy:
      max-file-size: 10MB
      max-history: 7
      total-size-cap: 100MB
      clean-history-on-start: false
  threshold:
    file: info
  charset:
    file: UTF-8
```

```properties
# lib/resources/application.properties: 同じ内容
logging.file.name=logs/shop.log
logging.file.rolling-policy.max-file-size=10MB
logging.file.rolling-policy.max-history=7
logging.file.rolling-policy.total-size-cap=100MB
logging.file.rolling-policy.clean-history-on-start=false
logging.threshold.file=info
logging.charset.file=UTF-8
```

```text
logs/
  shop.log       the current file
  shop.log.1     the previous one
  shop.log.2
  ...            at most 7 rolled files, at most 100 MB together
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `logging.file.name` | パス | なし | ログファイル。相対パスは `LoggingSystem.fileDirectory`、なければ作業ディレクトリを基準に解決される。パターンでは `${LOG_FILE}` |
| `logging.file.path` | ディレクトリ | なし | 名前が設定されていないとき、`<dir>/spring.log` に書く。パターンでは `${LOG_PATH}` |
| `logging.pattern.file` | パターン | Spring Boot のファイルのパターン | 行の形式。空のパターンはファイルなしを意味する |
| `logging.threshold.file` | レベル | `trace` | ファイルが保持する最も低いレベル |
| `logging.charset.file` | 文字セット | UTF-8 | UTF-8、ISO-8859-1、US-ASCII。IANA または Java の名前 (`utf8`) で。エンコードできない文字は `?` として書かれる |
| `logging.file.rolling-policy.max-file-size` | `DataSize` | `10MB` | ファイルがロールオーバーするサイズ |
| `logging.file.rolling-policy.max-history` | `int` | `7` | 保持するロールオーバー済みファイルの数。Logback と同じく `0` はすべて保持する |
| `logging.file.rolling-policy.total-size-cap` | `DataSize` | `0B`: 上限なし | ロールオーバー済みファイルの合計サイズの上限。超えると古いものから削除される |
| `logging.file.rolling-policy.clean-history-on-start` | `bool` | `false` | アプリケーションの起動時にロールオーバー済みファイルを削除する |

デフォルトのファイルのパターンは、色を除いた Spring Boot のものです。

```text
%d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd'T'HH:mm:ss.SSSXXX}} ${LOG_LEVEL_PATTERN:-%5p} ${PID:-} --- %esb(){APPLICATION_NAME}%esb{APPLICATION_GROUP}[%t] ${LOG_CORRELATION_PATTERN:-}%-40.40logger{39} : %m%X%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}
```

## ファイルの書き方

- 一回の同期的な処理でまとめてログに出された行は、マイクロタスクの終わりに一回の書き込みでまとめて書かれます。まだ待っている行は、コンテキストが閉じるときに書かれます。
- ファイルが `max-file-size` を超えそうになると、`shop.log.1` に名前が変わり、新しいファイルが始まります。古いファイルは `.2`、`.3` とずれていきます。保持されるのは `max-history` 個までで、合計が `total-size-cap` を超えている間は古いものから削除されます。
- ロールオーバーはサイズだけで、番号付きのファイルに行われます。アーカイブは圧縮されません。

## 書き込みに失敗したとき

Logback と同じく、書き込めないファイルが他の何かを止めることはありません。

- 起動時に開けないファイル (読み取り専用のディレクトリ) はコンソールに報告され、アプリケーションはファイルなしで起動します。
- 後で書き込みに失敗した場合 (ディスクがいっぱい)、エラーは一度だけ報告され、行は捨てられ、間隔を置いて書き込みが再試行されます。間隔は 20 ミリ秒から始まり、失敗するたびに約 5 分まで伸びます。再び行が書けたら、失われた行の数を示す行が一つ書かれます。その間は `FileAppender.isFailing` で分かります。
- 失敗したロールオーバーは一度だけ報告され、ロールオーバーが成功するまで (1 分後に再試行されます) 行は現在のファイルに書き続けられます。

## Flutter アプリで

Flutter アプリの書き込み可能なディレクトリは実行時にしか分からないため、アプリケーションを起動する前に設定します。

```dart
// path_provider から取得したアプリのドキュメントディレクトリ。
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  LoggingSystem.instance.fileDirectory =
      (await getApplicationDocumentsDirectory()).path;
  await runApplicationAsync(const []);
}
```

Web にはファイルシステムがありません。`logging.file.*` は警告とともに無視され、`FileAppender.isSupported` は `false` です。

## 古いキーと対応していないキー

| キー | 起こること |
|---|---|
| `logging.logback.rollingpolicy.*` (Spring Boot のもの) | 起動を止め、`logging.file.rolling-policy.*` を示す |
| `logging.file.max-size`、`logging.file.max-history`、`logging.file.total-size-cap`、`logging.file.clean-history-on-start` (Spring Boot 2.4 より前) | 現在のキーを示す警告とともに無視される |
| `logging.file.rolling-policy.file-name-pattern` | 警告とともに無視される: 日付、`%i`、`.gz` はない |

## Spring (Java) との対応

`logging.file.name` と `logging.file.path` は同じです。Logback のロールオーバーポリシーの名前は、そちらでは `logging.logback.rollingpolicy.*` です。Logback は日付とサイズでファイル名のパターンにロールオーバーし、`max-history` は日数を数えます。ここではサイズで番号付きのファイルにロールオーバーし、`max-history` はファイルの数を数えます。

## 関連項目

- [パターン](patterns.md)
- [すべてのプロパティ](properties.md)
- [Spring との違い](differences.md)
