blob: 1cb5f8785178976b43895aee624095e553b59461 [file] [log] [blame] [view]
# Logging in Dart
Dart programs on Fuchsia generally write log messages with the `lib.logging` package, consuming and
initializing it through the `fuchsia_logger` package.
See the [language agnostic logging docs] for more information
about recording and viewing logs.
## Requirements
### GN dependency
The necessary packages can be included with an addtion to `deps` in `BUILD.gn`:
```
deps = [
"//topaz/public/dart/fuchsia_logger",
]
```
The `fuchsia_logger` package also provides Dart's `lib.logging`.
See [Dart: Overview][dart-dev] for more information about building Dart within Fuchsia.
### Sandbox dependency
In order to connect to a diagnostics service, `fuchsia.logger.LogSink` must be in the sandbox
of the connecting component's [`.cmx` file]:
```
{
"sandbox": {
"services": [
"fuchsia.logger.LogSink"
]
}
}
```
The syslog library will fallback to `stderr` if the `LogSink` connection fails.
## Initialization
In your main function, call the `setupLogger()` function to initialize logging:
```dart
import 'package:fuchsia_logger/logger.dart';
main() {
// process name will be used if no name is provided here
setupLogger(name: 'my-component');
}
```
### Configure severity
By default only messages with `INFO` severity or higher are printed. Severity level can be adjusted
by providing the `level` parameter in the `setupLogger()` call.
For example, to make all log messages appear in [`fx log`]:
```dart
setupLogger(name: 'noisy-component', level: Level.ALL);
```
## Recording messages
The `log` object is a [Logger] instance.
```dart
import 'package:fuchsia_logger/logger.dart';
log.finest('quietest'); // maps to TRACE
log.finer('also quietest'); // maps to TRACE also
log.fine('quiet'); // maps to DEBUG
log.info('hello world!'); // maps to INFO
log.warning('uhhh'); // maps to WARN
log.severe('oh no!'); // maps to ERROR
log.shout('this is fatal.'); // maps to FATAL
```
## Standard streams
`print` goes to standard out (`stdout`).
See [`stdout` & `stderr`] in the language-agnostic logging docs for details on the routing of stdio
streams in the system.
[Logger]: https://pub.dev/documentation/logging/latest/logging/Logger-class.html
[`fx log`]: /docs/development/diagnostics/logs/viewing.md
[dart-dev]: /docs/development/languages/dart/README.md
[`.cmx` file]: /docs/concepts/components/v1/component_manifests.md
[`stdout` & `stderr`]: /docs/development/diagnostics/logs/recording.md#stdout-stderr
[language agnostic logging docs]: /docs/concepts/diagnostics/logs/README.md