
# パターン

`logging.pattern.console` と `logging.pattern.file` はログの行を記述します。構文は Spring Boot のコンバーターを加えた Logback の `PatternLayout` なので、Spring Boot のアプリケーションのパターンはここでもそのまま動きます。コードでのクラスは `LogPattern` です。

## 使う理由

ほとんどのアプリケーションにはデフォルトの行で十分です。パターンは必要な箇所でそれを変えます。ターミナル向けの短い行、ログコレクター向けの固定のレイアウト、すべてのレコードの注文 ID を一列に、などです。

## 例

```yaml
# lib/resources/application.yml
logging:
  pattern:
    console: "%d{HH:mm:ss.SSS} %clr(%5p) [%logger{20}] %m%X%n"
    file: "%d %5p ${PID} --- [%t] %-40.40logger{39} : %m %kvp%n"
    dateformat: "yyyy-MM-dd HH:mm:ss.SSS"
```

```properties
# lib/resources/application.properties: 同じ内容
logging.pattern.console=%d{HH:mm:ss.SSS} %clr(%5p) [%logger{20}] %m%X%n
logging.pattern.file=%d %5p ${PID} --- [%t] %-40.40logger{39} : %m %kvp%n
logging.pattern.dateformat=yyyy-MM-dd HH:mm:ss.SSS
```

```text
21:08:01.580  INFO [n.checkout] paid 12.5 {order=1}
```

YAML ではパターンを引用符で囲んでください。`%` と `{` はそこで意味を持つためです。

## 変換ワード

| 変換 | 出力 |
|---|---|
| `%d`、`%date{pattern[, UTC]}` | 時刻。Java のパターン文字 (`yyyy-MM-dd'T'HH:mm:ss.SSSXXX`、`EEE`、`MMM`、`a`、...)、または `ISO8601` (デフォルト: `yyyy-MM-dd HH:mm:ss,SSS`) |
| `%p`、`%le`、`%level` | `TRACE`、`DEBUG`、`INFO`、`WARN`、`ERROR` |
| `%c`、`%lo`、`%logger{n}` | ロガー名。Logback と同じく短縮する (`%logger{15}`: `n.c.Payments`。`{0}`: 最後のセグメント) |
| `%m`、`%msg`、`%message` | メッセージ |
| `%t`、`%thread` | Isolate の名前: `main`。Web サーバーのプール (`server.isolates.count`) の Isolate では `isolate-1`、`isolate-2`、… |
| `%X{key}`、`%X{key:-default}`、`%X` | レコードのフィールドの一つ。単独の `%X` はすべてのフィールドを ` {k=v, ...}` として出す (なければ何も出さない) |
| `%ex`、`%exception`、`%throwable{short\|full\|n}`、`%xEx`、`%rEx` | エラーとそのスタックトレース |
| `%wEx` | 同じものを改行で挟んで (Spring Boot) |
| `%nopex` | エラーを出力しない |
| `%clr(...){color}` | 中身に色を付ける (Spring Boot): `faint`、`red`、`green`、`yellow`、`blue`、`magenta`、`cyan`、`black`、`white`、`bright_*`。色がなければレベルに応じて |
| `%esb(...){VAR}` | 中身または変数の `[value] `。空なら何も出さない (Spring Boot) |
| `%red(...)`、`%boldRed(...)`、`%gray(...)`、`%highlight(...)` | Logback の色。常に ANSI: `black`、`red`、`green`、`yellow`、`blue`、`magenta`、`cyan`、`white`、`gray` と `bold...`。`%highlight` はレベルに応じて |
| `%replace(...){regex, replacement}` | 一致するものをすべて置き換えた中身 (グループには `$1`) |
| `%kvp{DOUBLE\|SINGLE\|NONE}` | フィールドを `key="value"` のペアとして |
| `%prefix(...)` | 中の各変換を `name=value` として (`level=INFO`) |
| `%property{key}` | パターン変数、次にプロパティ (なければ `null`) |
| `%(...)` | 書式修飾子のために中身をまとめる |
| `%r`、`%relative` | ロギング開始からのミリ秒 |
| `%seq` | レコードの通し番号 |
| `%n`、`%%`、`\%`、`\(`、`\)` | 改行、`%`、`(`、`)` |

## 書式修飾子

Logback と同じです。

| 修飾子 | 効果 |
|---|---|
| `%5p` | 左側を埋めて 5 文字にする |
| `%-5p` | 右側を埋める |
| `%.10c` | 最後の 10 文字を残す |
| `%.-10c` | 最初の 10 文字を残す |
| `%-40.40logger{39}` | ロガーを 39 に短縮し、最大 40 文字を残し、40 文字に埋める |

## 変数

`${NAME}` と `${NAME:-default}` は、パターンが読まれる前に置き換えられます。まず Spring Boot のロギング変数、次にプロパティ (`${spring.application.name}`) です。

| 変数 | 値 |
|---|---|
| `PID` | プロセス ID |
| `APPLICATION_NAME` | `logging.include-application-name` が `true` のとき、`spring.application.name` |
| `APPLICATION_GROUP` | `logging.include-application-group` が `true` のとき、`spring.application.group` |
| `LOG_DATEFORMAT_PATTERN` | `logging.pattern.dateformat` |
| `LOG_LEVEL_PATTERN` | `logging.pattern.level` |
| `LOG_CORRELATION_PATTERN` | `logging.pattern.correlation` |
| `LOG_EXCEPTION_CONVERSION_WORD` | `logging.exception-conversion-word` |
| `LOG_FILE` | `logging.file.name` |
| `LOG_PATH` | `logging.file.path` |

そのため `${PID}` や `${LOG_LEVEL_PATTERN:-%5p}` は Spring Boot と同じように動きます。パターンのプロパティは書かれたとおりにバインドされます (`@RawValue`)。その中の `${...}` は Environment ではなくパターンが解決します。

## ルール

- レコードごとに 1 行です。コンソールとファイルが改行を追加するため、パターンの最後の `%n` は取り除かれます。
- Logback と同じく、エラーの変換のないパターンでも、エラーはレコードの後の行に出力されます。
- パーサーが読めないもの (不明なワード、閉じていない `(`、不明な色、日付の文字、変数) は起動を止めます。
- Dart には呼び出し元のデータがありません。`%C`、`%M`、`%L`、`%F`、`%caller` は不明なワードとして起動を止めます。`%marker` と `%contextName` にも対応していません。
- `%d` は UTC で書きます。UTC 以外の `%d` のタイムゾーンには対応していません。

## コードで

```dart
// エクスポートのために、ファイルと同じ方法でレコードを書式化する。
final pattern = LogPattern('%d %5p [%logger] %m%X');
final line = pattern.formatLine(record);
```

`LogPattern.defaultConsolePattern` と `LogPattern.defaultFilePattern` は Spring Boot のデフォルトです。

## Spring (Java) との対応

構文は、Spring Boot の `%clr`、`%esb`、`%wEx` を加えた Logback の `PatternLayout` と同じです。`%X` は `k=v, k=v` ではなく、先頭に空白を付けた ` {k=v, ...}` を出力します。`%kvp` はレコードのフィールドを出力します (Dart には SLF4J のキーと値のペアがありません)。`%property` はパターン変数を読み、次に Environment を読みます。

## 関連項目

- [コンソール](console.md)
- [ログファイル](log-files.md)
- [すべてのプロパティ](properties.md)
