feat(logging): add a new logging category and plugin interface

packages/amplify_core/lib/amplify_core.dart

@@ -45,6 +45,7 @@ export 'src/plugin/amplify_analytics_plugin_interface.dart';
 export 'src/plugin/amplify_api_plugin_interface.dart';
 export 'src/plugin/amplify_auth_plugin_interface.dart';
 export 'src/plugin/amplify_datastore_plugin_interface.dart';
+export 'src/plugin/amplify_logging_plugin_interface.dart';
 export 'src/plugin/amplify_plugin_interface.dart';
 export 'src/plugin/amplify_plugin_key.dart';
 export 'src/plugin/amplify_push_notifications_plugin_interface.dart';
@@ -88,6 +89,9 @@ export 'src/types/exception/error/configuration_error.dart';
 export 'src/types/exception/error/plugin_error.dart';
 export 'src/types/exception/url_launcher_exception.dart';
 
+/// Logging
+export 'src/types/logging/logger.dart';
+
 /// Model-based types used in datastore and API
 export 'src/types/models/auth_rule.dart';
 export 'src/types/models/model.dart';

packages/amplify_core/lib/src/category/amplify_categories.dart

@@ -14,6 +14,7 @@ import 'package:meta/meta.dart';
 part 'amplify_analytics_category.dart';
 part 'amplify_api_category.dart';
 part 'amplify_datastore_category.dart';
+part 'amplify_logging_category.dart';
 part 'amplify_notifications_category.dart';
 part 'amplify_push_notifications_category.dart';
 part 'amplify_storage_category.dart';

packages/amplify_core/lib/src/category/amplify_logging_category.dart

@@ -0,0 +1,60 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+part of 'amplify_categories.dart';
+
+/// {@template amplify_core.amplify_logging_category}
+/// The Amplify Logging category provides an interface for interacting with
+/// a logging plugin.
+///
+/// It comes with default, built-in support for Amazon CloudWatch service
+/// leveraging Amplify Auth Category for authorization.
+/// {@endtemplate}
+class LoggingCategory extends AmplifyCategory<LoggingPluginInterface> {
+  @override
+  @nonVirtual
+  Category get category => Category.logging;
+
+  @override
+  @nonVirtual
+  Set<Category> get categoryDependencies => const {Category.auth};
+
+  P getPlugin<P extends LoggingPluginInterface>(
+    LoggingPluginKey<P> pluginKey,
+  ) =>
+      plugins.singleWhere(
+        (p) => p is P,
+        orElse: () => throw PluginError(
+          'No plugin registered for $pluginKey',
+        ),
+      ) as P;
+
+  /// {@template amplify_core.amplify_logging_category.logger}
+  /// Creates a logger for the specified namespace. If a [category] is provided,
+  /// the logger namespace is prefixed with the `category.name`.
+  /// {@endtemplate}
+  Logger logger(String nameSpace, {Category? category}) {
+    return defaultPlugin.logger(nameSpace);
+  }
+
+  /// {@template amplify_core.amplify_logging_category.enable}
+  /// Starts recording logs emitted by [logger].
+  /// {@endtemplate}
+  void enable() {
+    return defaultPlugin.enable();
+  }
+
+  /// {@template amplify_core.amplify_logging_category.disable}
+  /// Stops recording logs emitted by [logger].
+  /// {@endtemplate}
+  void disable() {
+    return defaultPlugin.disable();
+  }
+
+  /// {@template amplify_core.amplify_logging_category.flushLogs}
+  /// Sends recorded logs to an output.
+  /// {@endtemplate}
+  void flushLogs() {
+    return defaultPlugin.flushLogs();
+  }
+}

packages/amplify_core/lib/src/plugin/amplify_logging_plugin_interface.dart

@@ -0,0 +1,36 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+library amplify_logging_plugin_interface;
+
+import 'package:amplify_core/amplify_core.dart';
+import 'package:meta/meta.dart';
+
+/// Defines Amplify Logging plugin interface.
+///
+/// {@macro amplify_core.amplify_logging_category}
+abstract class LoggingPluginInterface extends AmplifyPluginInterface {
+  @override
+  @nonVirtual
+  Category get category => Category.logging;
+
+  /// {@macro amplify_core.amplify_logging_category.logger}
+  Logger logger(String namespace, {Category? category}) {
+    throw UnimplementedError('logger has not been implemented');
+  }
+
+  /// {@macro amplify_core.amplify_logging_category.enable}
+  void enable() {
+    throw UnimplementedError('enable has not been implemented');
+  }
+
+  /// {@macro amplify_core.amplify_logging_category.disable}
+  void disable() {
+    throw UnimplementedError('disable has not been implemented');
+  }
+
+  /// {@macro amplify_core.amplify_logging_category.flushLogs}
+  void flushLogs() {
+    throw UnimplementedError('flushLogs has not been implemented');
+  }
+}

packages/amplify_core/lib/src/plugin/amplify_plugin_key.dart

@@ -23,7 +23,20 @@ abstract class AuthPluginKey<Plugin extends AuthPluginInterface>
   const AuthPluginKey();
 }
 
+/// {@template amplify_core.plugin.storage_plugin_key}
+/// A plugin identifier which can be passed to the Storage category's
+/// `getPlugin` method to retrieve a plugin-specific Storage category wrapper.
+/// {@endtemplate}
 abstract class StoragePluginKey<P extends StoragePluginInterface>
     extends AmplifyPluginKey<P> {
   const StoragePluginKey();
 }
+
+/// {@template amplify_core.plugin.logging_plugin_key}
+/// A plugin identifier which can be passed to the Logging category's
+/// `getPlugin` method to retrieve a plugin-specific Logging category wrapper.
+/// {@endtemplate}
+abstract class LoggingPluginKey<P extends LoggingPluginInterface>
+    extends AmplifyPluginKey<P> {
+  const LoggingPluginKey();
+}

packages/amplify_core/lib/src/types/logging/logger.dart

@@ -0,0 +1,36 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import 'package:aws_common/aws_common.dart';
+
+/// {@template amplify_core.logging.logger}
+/// Logger interface for emitting log messages at different log levels.
+/// {@endtemplate}
+
+abstract interface class Logger {
+  /// The namespace of this logger.
+  String get namespace;
+
+  /// Logs a [message] at the given [level].
+  void log(
+    LogLevel level,
+    String message, [
+    Object? error,
+    StackTrace? stackTrace,
+  ]);
+
+  /// Logs a [message] with level [LogLevel.verbose].
+  void verbose(String message, [Object? error, StackTrace? stackTrace]);
+
+  /// Logs a [message] with level [LogLevel.debug].
+  void debug(String message, [Object? error, StackTrace? stackTrace]);
+
+  /// Logs a [message] with level [LogLevel.info].
+  void info(String message, [Object? error, StackTrace? stackTrace]);
+
+  /// Logs a [message] with level [LogLevel.warn].
+  void warn(String message, [Object? error, StackTrace? stackTrace]);
+
+  /// Logs a [message] with level [LogLevel.error].
+  void error(String message, [Object? error, StackTrace? stackTrace]);
+}