
# Patterns

`logging.pattern.console` and `logging.pattern.file` describe a log line. The syntax is Logback's `PatternLayout` with Spring Boot's converters, so the patterns of a Spring Boot application work here as they are. In code the class is `LogPattern`.

## Why

The default line suits most applications. A pattern changes it where it matters: a short line for a terminal, a fixed layout for a log collector, the order id of every record in a column.

## Example

```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: the same
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}
```

In YAML, quote a pattern: `%` and `{` have meanings there.

## Conversion words

| Conversion | Output |
|---|---|
| `%d`, `%date{pattern[, UTC]}` | The time. Java pattern letters (`yyyy-MM-dd'T'HH:mm:ss.SSSXXX`, `EEE`, `MMM`, `a`, ...), or `ISO8601` (the default: `yyyy-MM-dd HH:mm:ss,SSS`) |
| `%p`, `%le`, `%level` | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `%c`, `%lo`, `%logger{n}` | The logger name, shortened as Logback does (`%logger{15}`: `n.c.Payments`; `{0}`: the last segment) |
| `%m`, `%msg`, `%message` | The message |
| `%t`, `%thread` | The isolate name: `main`; `isolate-1`, `isolate-2`, … in the isolates of the web server's pool (`server.isolates.count`) |
| `%X{key}`, `%X{key:-default}`, `%X` | One field of the record; `%X` alone gives all fields as ` {k=v, ...}` (nothing when there are none) |
| `%ex`, `%exception`, `%throwable{short\|full\|n}`, `%xEx`, `%rEx` | The error and its stack trace |
| `%wEx` | The same, between line breaks (Spring Boot) |
| `%nopex` | No error output |
| `%clr(...){color}` | Colours its content (Spring Boot): `faint`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `black`, `white`, `bright_*`; without a colour, by level |
| `%esb(...){VAR}` | `[value] ` of its content or of a variable, nothing when empty (Spring Boot) |
| `%red(...)`, `%boldRed(...)`, `%gray(...)`, `%highlight(...)` | Logback's colours, always ANSI: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray` and `bold...`; `%highlight` by level |
| `%replace(...){regex, replacement}` | Its content with every match replaced (`$1` for groups) |
| `%kvp{DOUBLE\|SINGLE\|NONE}` | The fields as `key="value"` pairs |
| `%prefix(...)` | Each conversion inside as `name=value` (`level=INFO`) |
| `%property{key}` | A pattern variable, then a property (`null` when there is none) |
| `%(...)` | Groups content for a format modifier |
| `%r`, `%relative` | Milliseconds since logging started |
| `%seq` | The record's sequence number |
| `%n`, `%%`, `\%`, `\(`, `\)` | A line break, `%`, `(`, `)` |

## Format modifiers

As in Logback:

| Modifier | Effect |
|---|---|
| `%5p` | Pads on the left to 5 characters |
| `%-5p` | Pads on the right |
| `%.10c` | Keeps the last 10 characters |
| `%.-10c` | Keeps the first 10 characters |
| `%-40.40logger{39}` | Shortens the logger to 39, keeps at most 40, pads to 40 |

## Variables

`${NAME}` and `${NAME:-default}` are replaced before the pattern is read: first Spring Boot's logging variables, then properties (`${spring.application.name}`).

| Variable | Value |
|---|---|
| `PID` | The process id |
| `APPLICATION_NAME` | `spring.application.name`, when `logging.include-application-name` is `true` |
| `APPLICATION_GROUP` | `spring.application.group`, when `logging.include-application-group` is `true` |
| `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` |

So `${PID}` and `${LOG_LEVEL_PATTERN:-%5p}` work as in Spring Boot. Pattern properties are bound as written (`@RawValue`): the `${...}` in them is resolved by the pattern, not by the environment.

## Rules

- One line per record: the console and the file add the line break, so a pattern's final `%n` is dropped.
- As in Logback, a pattern without an error conversion still prints the error, on the lines after the record.
- Anything the parser cannot read (an unknown word, an unclosed `(`, an unknown colour, date letter or variable) stops the start.
- Caller data does not exist in Dart: `%C`, `%M`, `%L`, `%F` and `%caller` stop the start as unknown words. `%marker` and `%contextName` are not supported either.
- `%d` writes UTC; a `%d` time zone other than UTC is not supported.

## In code

```dart
// Format a record the way the file would, for an export.
final pattern = LogPattern('%d %5p [%logger] %m%X');
final line = pattern.formatLine(record);
```

`LogPattern.defaultConsolePattern` and `LogPattern.defaultFilePattern` are Spring Boot's defaults.

## In Spring (Java)

The same syntax as Logback's `PatternLayout` with Spring Boot's `%clr`, `%esb` and `%wEx`. `%X` prints ` {k=v, ...}` with a leading space instead of `k=v, k=v`; `%kvp` prints the record's fields (Dart has no SLF4J key-value pairs); `%property` reads the pattern variables, then the environment.

## See also

- [The console](console.md)
- [Log files](log-files.md)
- [All properties](properties.md)
