
# @Log

`@Log()` (from `spring_core_dart`) gives a class a `log` getter that returns a `SpringLog`, like Lombok's `@Slf4j` in Java. The generator writes the getter as an extension on the class, in the `.spring.dart` file of the `@ComponentScan` or `@SpringBootApplication` that scans the class.

## Why

A class that logs needs a logger, usually a constant such as `const log = SpringLog('my_app.Checkout');`. Writing it by hand in every class repeats the class name, and the name goes stale when the class is renamed or moved. Dart cannot add a field to a class from outside, but an extension can add a getter. So the generator writes one extension per `@Log` class, with the logger name computed at build time.

## Example

```dart
// lib/src/checkout.dart in the package my_app
import 'package:spring_core_dart/spring_core_dart.dart';

import '../spring_gen/main.spring.dart'; // where the extension is

@Service()
@Log()
class Checkout {
  void pay(double amount) => log.info('paid $amount');
}

// Not a bean: @Log works on any class of the scan.
@Log(topic: 'neon.payments', fieldName: 'logger')
class Payments {
  void refund() => logger.warning('refund');
}
```

The generator writes, into the `.spring.dart` file of the scan (simplified: the real file uses import prefixes such as `_i1.`):

```dart
/// `@Log` of [Checkout]: the logger 'my_app.Checkout'.
extension $CheckoutLog on Checkout {
  SpringLog get log => const SpringLog(r'my_app.Checkout');
}

/// `@Log` of [Payments]: the logger 'neon.payments'.
extension $PaymentsLog on Payments {
  SpringLog get logger => const SpringLog(r'neon.payments');
}
```

Inside the class, `log.info(...)` calls the extension's getter. The getter returns a constant, so there is no object per instance and no lookup at run time.

A real excerpt, from the `spring_core_dart` example (`example/spring_gen/main.spring.dart`), for two classes with `@Log(topic: 'tour')`:

```dart
/// `@Log` of [WelcomeMail]: the logger 'tour'.
extension $WelcomeMailLog on _i2.WelcomeMail {
  _i1.SpringLog get log => const _i1.SpringLog(r'tour');
}

/// `@Log` of [Tour]: the logger 'tour'.
extension $TourLog on _i2.Tour {
  _i1.SpringLog get log => const _i1.SpringLog(r'tour');
}
```

## The arguments

| Argument | Default | Effect |
|---|---|---|
| `topic:` | `<package>.<Class>` | the logger name passed to `SpringLog` |
| `fieldName:` | `log` | the name of the generated getter |

The default logger name is the package name and the class name: `my_app.Checkout` for a class in any library of the package `my_app` (the folder below `lib/` does not count). For a library outside `lib/`, which has no `package:` URI (a file in `bin/`, `example/` or `test/`), the file name without `.dart` is used instead of the package: a class `Tour` in `bin/main.dart` logs as `main.Tour`.

Use `topic:` to group several classes under one logger, so one setting controls them:

```properties
# lib/resources/application.properties
logging.level.neon.payments=debug
```

Levels follow the dots in the name (`neon.payments` also covers `neon.payments.refunds`). See [SpringLog](../spring-core-dart/logging/spring-log.md).

Use `fieldName:` when `log` is taken. `dart:math` and `dart:developer` both declare a top-level function `log`, and a `log` declared in the library's scope wins over an extension getter. With one of them imported, pick another name: `@Log(fieldName: 'logger')`.

## How it works

1. **Which classes.** Every class of the libraries a module scans is checked for `@Log`, bean or not: a `@Service`, a plain class, a class that the scan's filters do not make a bean. A class outside every scan (for example in a test file) gets no getter.
2. **The checks.** The class must be public, `fieldName` must be a valid getter name, and the class must not already have a member with that name (see [Build errors](#build-errors)).
3. **The name.** The logger name is computed from the library's URI and the class name, unless `topic:` is given.
4. **The extension.** It is named `$<Class>Log` and written after the module and the application functions. Two `@Log` classes with the same name in different libraries of one module get `$CheckoutLog` and `$CheckoutLog2`, in scan order, so the extensions do not clash.
5. **Generic classes.** The extension is on the raw type: `@Log() class Repo<T>` gives `extension $RepoLog on Repo`, which matches every `Repo<...>`.

## Importing the getter

An extension is visible only where its library is imported. The class's own library must import the `.spring.dart` file that scans it:

| The class is scanned by | Import |
|---|---|
| `@SpringBootApplication` in `bin/main.dart` | `bin/spring_gen/main.spring.dart` |
| `@SpringBootApplication` in `lib/main.dart` | `package:my_app/spring_gen/main.spring.dart` |
| `@ComponentScan` in `lib/src/beans.dart` | `package:my_app/spring_gen/src/beans.spring.dart` |

Without the import, `log` is an unknown name and the class does not compile. A library imported by its generated file and importing it back is a normal import cycle in Dart.

## Build errors

A getter that could not work fails the build, with the class as the location. The errors are collected with the other problems of the build and reported together.

| Problem | Message |
|---|---|
| a private class | `@Log on _Hidden: the class is private, so the generated getter (an extension in the .spring.dart file) cannot name it; make the class public or declare the logger yourself: const _log = SpringLog('...');` |
| an invalid getter name | `@Log on A: fieldName "class" is not a valid getter name (a public Dart identifier that is no reserved word).` |
| a member with the getter's name | `@Log on C: C already has a member "log", which would win over the generated getter; choose another name with @Log(fieldName: '...').` |

A valid `fieldName` starts with a letter or `$`, then has letters, digits, `_` or `$`. A name starting with `_` is refused (the getter would be private to the generated file), and so are Dart's reserved words and built-in identifiers (`class`, `get`, `set`, `type`, `late`, `required` and the others).

The member check looks at the methods, getters, setters and fields of the class and of all its supertypes. A member of a superclass counts too, since a class member always wins over an extension member:

```dart
class Base {
  void log() {}
}

@Log() // ✗ @Log on D: D already has a member "log", ...
class D extends Base {}
```

## In Spring (Java)

```java
@Slf4j(topic = "neon.payments")
class Payments {
  void refund() { log.warn("refund"); }
}
```

Differences that matter:

- Lombok adds a static field to the class while it compiles. Here the generator writes an extension getter in the `.spring.dart` file, which the class's library must import.
- The default logger name is `<package>.<Class>`, not the fully qualified class name.
- Lombok's `@Slf4j` uses SLF4J. Here the getter returns a `SpringLog`, the one logging API of Spring for Dart.

## See also

- [SpringLog](../spring-core-dart/logging/spring-log.md): levels, handlers and the logging API.
- [Logging](../spring-core-dart/logging/index.md)
- [@ComponentScan modules](component-scan.md): which libraries a module scans.
