Merge pull request #401 from dart-lang/merge-logging-package

Merge `package:logging`

.github/ISSUE_TEMPLATE/logging.md

@@ -0,0 +1,5 @@
+---
+name: "package:logging"
+about: "Create a bug or file a feature request against package:logging."
+labels: "package:logging"
+---

.github/labeler.yml

@@ -23,3 +23,7 @@
 "package:fixnum":
   - changed-files:
       - any-glob-to-any-file: 'pkgs/fixnum/**'
+
+"package:logging":
+  - changed-files:
+      - any-glob-to-any-file: 'pkgs/logging/**'

.github/workflows/logging.yaml

@@ -0,0 +1,70 @@
+name: package:logging
+
+on:
+  # Run CI on pushes to the main branch, and on PRs against main.
+  push:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/logging.yaml'
+      - 'pkgs/logging/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/logging.yaml'
+      - 'pkgs/logging/**'
+  schedule:
+    - cron: "0 0 * * 0"
+env:
+  PUB_ENVIRONMENT: bot.github
+
+defaults:
+  run:
+    working-directory: pkgs/logging/
+
+jobs:
+  # Check code formatting and static analysis.
+  analyze:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [dev]
+    steps:
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Check formatting
+        run: dart format --output=none --set-exit-if-changed .
+        if: always() && steps.install.outcome == 'success'
+      - name: Analyze code
+        run: dart analyze --fatal-infos
+        if: always() && steps.install.outcome == 'success'
+
+  # Run tests on a matrix of platforms and sdk versions.
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add macos-latest and/or windows-latest if relevant for this package.
+        os: [ubuntu-latest]
+        sdk: [3.4, dev]
+    steps:
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Run VM tests
+        run: dart test --platform vm
+        if: always() && steps.install.outcome == 'success'
+      - name: Run Chrome tests
+        run: dart test --platform chrome
+        if: always() && steps.install.outcome == 'success'

README.md

@@ -14,6 +14,7 @@ This repository is home to various Dart packages under the [dart.dev](https://pu
 | [convert](pkgs/convert/) | Utilities for converting between data representations. | [![pub package](https://img.shields.io/pub/v/convert.svg)](https://pub.dev/packages/convert) |
 | [crypto](pkgs/crypto/) | Implementations of SHA, MD5, and HMAC cryptographic functions. | [![pub package](https://img.shields.io/pub/v/crypto.svg)](https://pub.dev/packages/crypto) |
 | [fixnum](pkgs/fixnum/) | Library for 32- and 64-bit signed fixed-width integers. | [![pub package](https://img.shields.io/pub/v/fixnum.svg)](https://pub.dev/packages/fixnum) |
+| [logging](pkgs/logging/) | Provides APIs for debugging and error logging. | [![pub package](https://img.shields.io/pub/v/logging.svg)](https://pub.dev/packages/logging) |
 
 ## Publishing automation
 

pkgs/logging/.gitignore

@@ -0,0 +1,3 @@
+.dart_tool
+.packages
+pubspec.lock

pkgs/logging/AUTHORS

@@ -0,0 +1,10 @@
+# Names should be added to this file with this pattern:
+#
+# For individuals:
+#   Name <email address>
+#
+# For organizations:
+#   Organization <fnmatch pattern>
+#
+Google Inc. <*@google.com>
+Anton Astashov <anton.astashov@gmail.com>

pkgs/logging/CHANGELOG.md

@@ -0,0 +1,92 @@
+## 1.3.0
+
+* Override empty stack traces for trace level events.
+* Require Dart 3.4
+* Move to `dart-lang/core` monorepo.
+
+## 1.2.0
+
+* Add notification when the log level is changed. Logger `onLevelChanged` broadcasts a stream of level values.
+* Require Dart 2.19.
+
+## 1.1.1
+
+* Add a check that throws if a logger name ends with '.'.
+* Require Dart 2.18
+
+## 1.1.0
+
+* Add `Logger.attachedLoggers` which exposes all loggers created with the
+  default constructor.
+* Enable the `avoid_dynamic_calls` lint.
+
+## 1.0.2
+
+* Update description.
+* Add example.
+
+## 1.0.1
+
+* List log levels in README.
+
+## 1.0.0
+
+* Stable null safety release.
+
+## 1.0.0-nullsafety.0
+
+* Migrate to null safety.
+* Removed the deprecated `LoggerHandler` typedef.
+
+## 0.11.4
+
+* Add top level `defaultLevel`.
+* Require Dart `>=2.0.0`.
+* Make detached loggers work regardless of `hierarchicalLoggingEnabled`.
+
+## 0.11.3+2
+
+* Set max SDK version to `<3.0.0`, and adjust other dependencies.
+
+## 0.11.3+1
+
+* Fixed several documentation comments.
+
+## 0.11.3
+
+* Added optional `LogRecord.object` field.
+
+* `Logger.log` sets `LogRecord.object` if the message is not a string or a
+  function that returns a string. So that a handler can access the original
+  object instead of just its `toString()`.
+
+## 0.11.2
+
+* Added `Logger.detached` - a convenience factory to obtain a logger that is not
+  attached to this library's logger hierarchy.
+
+## 0.11.1+1
+
+* Include default error with the auto-generated stack traces.
+
+## 0.11.1
+
+* Add support for automatically logging the stack trace on error messages. Note
+  this can be expensive, so it is off by default.
+
+## 0.11.0
+
+* Revert change in `0.10.0`. `stackTrace` must be an instance of `StackTrace`.
+  Use the `Trace` class from the [stack_trace package][] to convert strings.
+
+[stack_trace package]: https://pub.dev/packages/stack_trace
+
+## 0.10.0
+
+* Change type of `stackTrace` from `StackTrace` to `Object`.
+
+## 0.9.3
+
+* Added optional `LogRecord.zone` field.
+
+* Record current zone (or user specified zone) when creating new `LogRecord`s.

pkgs/logging/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2013, the Dart project authors. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/logging/README.md

@@ -0,0 +1,141 @@
+[![Dart CI](https://github.com/dart-lang/core/actions/workflows/logging.yaml/badge.svg)](https://github.com/dart-lang/core/actions/workflows/logging.yaml)
+[![Pub](https://img.shields.io/pub/v/logging.svg)](https://pub.dev/packages/logging)
+[![package publisher](https://img.shields.io/pub/publisher/logging.svg)](https://pub.dev/packages/logging/publisher)
+
+## Initializing
+
+By default, the logging package does not do anything useful with the log
+messages. You must configure the logging level and add a handler for the log
+messages.
+
+Here is a simple logging configuration that logs all messages via `print`.
+
+```dart
+Logger.root.level = Level.ALL; // defaults to Level.INFO
+Logger.root.onRecord.listen((record) {
+  print('${record.level.name}: ${record.time}: ${record.message}');
+});
+```
+
+First, set the root `Level`. All messages at or above the current level are sent to the
+`onRecord` stream. Available levels are:
+
++ `Level.OFF`
++ `Level.SHOUT`
++ `Level.SEVERE`
++ `Level.WARNING`
++ `Level.INFO`
++ `Level.CONFIG`
++ `Level.FINE`
++ `Level.FINER`
++ `Level.FINEST`
+
+Then, listen on the `onRecord` stream for `LogRecord` events. The `LogRecord`
+class has various properties for the message, error, logger name, and more.
+
+To listen for changed level notifications use:
+
+```dart
+Logger.root.onLevelChanged.listen((level) {
+  print('The new log level is $level');
+});
+```
+
+## Logging messages
+
+Create a `Logger` with a unique name to easily identify the source of the log
+messages.
+
+```dart
+final log = Logger('MyClassName');
+```
+
+Here is an example of logging a debug message and an error:
+
+```dart
+var future = doSomethingAsync().then((result) {
+  log.fine('Got the result: $result');
+  processResult(result);
+}).catchError((e, stackTrace) => log.severe('Oh noes!', e, stackTrace));
+```
+
+When logging more complex messages, you can pass a closure instead that will be
+evaluated only if the message is actually logged:
+
+```dart
+log.fine(() => [1, 2, 3, 4, 5].map((e) => e * 4).join("-"));
+```
+
+Available logging methods are:
+
++ `log.shout(logged_content);`
++ `log.severe(logged_content);`
++ `log.warning(logged_content);`
++ `log.info(logged_content);`
++ `log.config(logged_content);`
++ `log.fine(logged_content);`
++ `log.finer(logged_content);`
++ `log.finest(logged_content);`
+
+## Configuration
+
+Loggers can be individually configured and listened to. When an individual logger has no
+specific configuration, it uses the configuration and any listeners found at `Logger.root`.
+
+To begin, set the global boolean `hierarchicalLoggingEnabled` to `true`.
+
+Then, create unique loggers and configure their `level` attributes and assign any listeners to
+their `onRecord` streams.
+
+
+```dart
+  hierarchicalLoggingEnabled = true;
+  Logger.root.level = Level.WARNING;
+  Logger.root.onRecord.listen((record) {
+    print('[ROOT][WARNING+] ${record.message}');
+  });
+
+  final log1 = Logger('FINE+');
+  log1.level = Level.FINE;
+  log1.onRecord.listen((record) {
+    print('[LOG1][FINE+] ${record.message}');
+  });
+
+  // log2 inherits LEVEL value of WARNING from `Logger.root`
+  final log2 = Logger('WARNING+');
+  log2.onRecord.listen((record) {
+    print('[LOG2][WARNING+] ${record.message}');
+  });
+
+
+  // Will NOT print because FINER is too low level for `Logger.root`.
+  log1.finer('LOG_01 FINER (X)');
+
+  // Will print twice ([LOG1] & [ROOT])
+  log1.fine('LOG_01 FINE (√√)');
+
+  // Will print ONCE because `log1` only uses root listener.
+  log1.warning('LOG_01 WARNING (√)');
+
+  // Will never print because FINE is too low level.
+  log2.fine('LOG_02 FINE (X)');
+
+  // Will print twice ([LOG2] & [ROOT]) because warning is sufficient for all
+  // loggers' levels.
+  log2.warning('LOG_02 WARNING (√√)');
+
+  // Will never print because `info` is filtered by `Logger.root.level` of
+  // `Level.WARNING`.
+  log2.info('INFO (X)');
+```
+
+Results in:
+
+```
+[LOG1][FINE+] LOG_01 FINE (√√)
+[ROOT][WARNING+] LOG_01 FINE (√√)
+[LOG1][FINE+] LOG_01 WARNING (√)
+[ROOT][WARNING+] LOG_01 WARNING (√)
+[LOG2][WARNING+] LOG_02 WARNING (√√)
+[ROOT][WARNING+] LOG_02 WARNING (√√)
+```