release 0.2.0

CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.2.0] - 2021/07/14
+
+* Added CloudWatchHandler class to easily manage multiple CloudWatch instances
+* Added quick start logging example file
+* Automatically creates Log Groups that don't exist
+* Updated the README with info on CloudWatchHandler and quick start
+* Improved code readability
+* Updated to new version of aws_request
+* Added min 0 delay in place it was missing
+
 ## [0.1.12] - 2021/07/14
 
 * Fixed bug where delay was input in seconds instead of milliseconds
@@ -6,7 +16,7 @@
 
 QOL update
 
-* Fully removed optional deprecated xAmzTarget argument from main constructor (deprecated in 0.1.0) 
+* Fully removed optional deprecated xAmzTarget argument from main constructor (deprecated in 0.1.0)
 * Added optional arguments for group / stream name to both constructors
 * Added missing method setLoggingParameters that was shown in error message when group / stream name was null
 * Updated all examples to show different group / stream name instantiations
@@ -32,13 +42,13 @@ QOL update
 ## [0.1.7] - 2021/05/18
 
 * Moved to new version of aws_requests to fix hard coded region bug
-* Improved error handling 
-  
+* Improved error handling
+
 ## [0.1.6] - 2021/03/26
 
 * Added console output logging with 4 verbosity levels
 * Added optional delay parameter to address possible rate limiting
-  * Updated readme with new rate limiting example
+    * Updated readme with new rate limiting example
 
 ## [0.1.5] - 2021/03/26
 
@@ -64,25 +74,28 @@ QOL update
 
 * Updated dependencies for null safety
 * Put deprecation warning on xAmzTarget (formerly serviceInstance
-  * Updated example and docs to reflect changes with xAmzTarget
+    * Updated example and docs to reflect changes with xAmzTarget
 * Added exception if PutLogEvents returns a status code other than 200
 
 ## [0.0.6] - 2021/03/26
 
 Non-null Safety Update
+
 * Updated examples
 * Fixed issue with attempted logging before logstream creation was finished
 
 ## [0.0.5] - 2021/03/25
 
 Non-null Safety Update
+
 * Fixed issue with sending empty logs
 
 ## [0.0.4] - 2021/03/25
 
 Non-null Safety Update
+
 * Put deprecation warning on xAmzTarget (formerly serviceInstance)
-  * Updated example and docs to reflect changes with xAmzTarget
+    * Updated example and docs to reflect changes with xAmzTarget
 * Added exception if PutLogEvents returns a status code other than 200
 * Updated aws_request version to fix unicode error
 

README.md

@@ -25,36 +25,59 @@ CloudWatch cloudWatch = new CloudWatch(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
 
 Finally, send a log by calling `cloudWatch.log('STRING TO LOG');`
 
-## Important Notes:
-
-### Avoiding AWS Cloudwatch API Rate Limiting
-
-As of now (2021/07/09), AWS has a rate limit of 5 log requests per second per log stream. You may hit this limit rather
-quickly if you have a high volume of logs. It is highly recommended to include the optional delay parameter with a value
-of 200 (milliseconds) to avoid hitting this upper limit. With a delay, logs will continue to collect, but the api calls
-will be limited to 5 per second. At the moment there is no way around this limit.
-
-Example 2 below shows how to add a delay. The default delay is 0 milliseconds.
-
-### Log Groups and Log Streams
+## Examples
 
-Creating streams and uploading logs is the primary reason this package exists. Log groups must still be created
-manually. If you would like this feature let me know, and I will work on implementing it. With my use cases, I haven't
-felt the need for it.
+### Example - Quick Start
 
-There are multiple ways to set the log group and log stream and all are roughly equivalent.
+This is the quick start file. It is also location in example/aws_cloudwatch.dart
 
-Log stream names currently (2021/07/09) have the following limits:
-
-* Log stream names must be unique within the log group.
-* Log stream names can be between 1 and 512 characters long.
-* The ':' (colon) and '*' (asterisk) characters are not allowed.
+~~~dart
+import 'package:aws_cloudwatch/aws_cloudwatch.dart';
+import 'package:intl/intl.dart';
+
+/// QUICK START LOGGING FILE
+///
+/// PLEASE FILL OUT THE FOLLOWING VARIABLES:
+
+const String _AWS_ACCESS_KEY_ID = 'YOUR_ACCESS_KEY';
+const String _AWS_SECRET_ACCESS_KEY = 'YOUR_SECRET_ACCESS_KEY';
+const String _Region = 'YOUR_REGION_CODE'; // (us-west-1, us-east-2, etc)
+const String _LogGroup = 'DESIRED_LOG_GROUP_NAME';
+const String _ErrorGroup = 'DESIRED_ERROR_LOG_GROUP_NAME';
+
+/// END OF VARIABLES
+
+CloudWatchHandler logging = CloudWatchHandler(
+  awsAccessKey: _AWS_ACCESS_KEY_ID,
+  awsSecretKey: _AWS_SECRET_ACCESS_KEY,
+  region: _Region,
+);
+
+String logStreamName = '';
+
+// You may want to edit this function to suit your needs
+String _getLogStreamName() {
+  if (logStreamName == "") {
+    logStreamName = DateFormat("yyyy-MM-dd HH-mm-ss").format(
+      DateTime.now().toUtc(),
+    );
+  }
+  return logStreamName;
+}
 
-This package does not enforce or check log stream names with regard to these limits in case AWS decides to add or remove
-limitations. It is up to **you** to check the errors returned by the API to figure out if the problem is with the
-provided log stream name.
+void log(String logString, {isError = false}) {
+  logging.log(
+    msg: logString,
+    logGroupName: isError ? _LogGroup : _ErrorGroup,
+    logStreamName: _getLogStreamName(),
+  );
+}
+~~~
 
-## Examples
+Then just import this file somewhere in your code and call `log('HELLO WORLD');`. The package will handle creating the
+log groups and log streams on its own. The way the quick start file is setup, you will end up with one log group for
+standard logging and another for errors. Both with have the same log stream name. To automatically send logs for all
+flutter errors see example 3.
 
 ### Example 1
 
@@ -115,6 +138,7 @@ it `errorLog.dart`
 
 ~~~dart
 import 'package:aws_request/aws_cloudwatch.dart';
+import 'package:intl/intl.dart';
 
 // AWS Variables
 const String AWS_ACCESS_KEY_ID = 'ExampleKey';
@@ -123,14 +147,40 @@ const String Region = 'us-west-2';
 
 // Logging Variables
 const String logGroupName = 'LogGroupExample';
-const String logStreamName = 'LogStreamExample';
-CloudWatch cloudWatch = new CloudWatch(AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
-    Region);
-cloudWatch.setLoggingParameters(logGroupName, logStreamName);
+const String logGroupNameError = 'LogGroupExample';
+
+CloudWatchHandler logging = CloudWatchHandler(
+  awsAccessKey: AWS_ACCESS_KEY_ID,
+  awsSecretKey: AWS_SECRET_ACCESS_KEY,
+  region: Region,
+);
+
+String logStreamName = '';
+
+// You may want to edit this function to suit your needs
+String _getLogStreamName() {
+  if (logStreamName == "") {
+    logStreamName = DateFormat("yyyy-MM-dd HH-mm-ss").format(
+      DateTime.now().toUtc(),
+    );
+  }
+  return logStreamName;
+}
+
+void log(String logString, {isError = false}) {
+  logging.log(
+    msg: logString,
+    logGroupName: isError ? logGroupName : logGroupNameError,
+    logStreamName: _getLogStreamName(),
+  );
+}
 
 void logFlutterSystemError(dynamic logString, dynamic stackTrace) async {
-  cloudWatch.log('Auto Captured Error: ${logString.toString()}\n\n'
-      'Auto Captured Stack Trace:\n${stackTrace.toString()}');
+  log(
+    'Auto Captured Error: ${logString.toString()}\n\n'
+        'Auto Captured Stack Trace:\n${stackTrace.toString()}',
+    isError: true,
+  );
 }
 ~~~
 
@@ -157,4 +207,31 @@ void main() {
     throw error;
   });
 }
-~~~
+~~~
+
+To send normal logs, import the logging file anywhere and call `log('Hello world!');`
+
+## Important Notes:
+
+### Avoiding AWS Cloudwatch API Rate Limiting
+
+As of now (2021/07/09), AWS has a rate limit of 5 log requests per second per log stream. You may hit this limit rather
+quickly if you have a high volume of logs. It is highly recommended to include the optional delay parameter with a value
+of 200 (milliseconds) to avoid hitting this upper limit. With a delay, logs will continue to collect, but the api calls
+will be limited to 5 per second. At the moment there is no way around this limit.
+
+Example 2 below shows how to add a delay. The default delay is 0 milliseconds.
+
+### Log Groups and Log Streams
+
+There are multiple ways to set the log group and log stream and all are roughly equivalent.
+
+Log stream names currently (2021/07/09) have the following limits:
+
+* Log stream names must be unique within the log group.
+* Log stream names can be between 1 and 512 characters long.
+* The ':' (colon) and '*' (asterisk) characters are not allowed.
+
+This package does not enforce or check log stream names with regard to these limits in case AWS decides to add or remove
+limitations. It is up to **you** to check the errors returned by the API to figure out if the problem is with the
+provided log stream name.

example/aws_cloudwatch.dart

@@ -0,0 +1,40 @@
+import 'package:aws_cloudwatch/aws_cloudwatch.dart';
+import 'package:intl/intl.dart';
+
+/// QUICK START LOGGING FILE
+///
+/// PLEASE FILL OUT THE FOLLOWING VARIABLES:
+
+const String _AWS_ACCESS_KEY_ID = 'YOUR_ACCESS_KEY';
+const String _AWS_SECRET_ACCESS_KEY = 'YOUR_SECRET_ACCESS_KEY';
+const String _Region = 'YOUR_REGION_CODE'; // (us-west-1, us-east-2, etc)
+const String _LogGroup = 'DESIRED_LOG_GROUP_NAME';
+const String _ErrorGroup = 'DESIRED_ERROR_LOG_GROUP_NAME';
+
+/// END OF VARIABLES
+
+CloudWatchHandler logging = CloudWatchHandler(
+  awsAccessKey: _AWS_ACCESS_KEY_ID,
+  awsSecretKey: _AWS_SECRET_ACCESS_KEY,
+  region: _Region,
+);
+
+String logStreamName = '';
+
+// You may want to edit this function to suit your needs
+String _getLogStreamName() {
+  if (logStreamName == "") {
+    logStreamName = DateFormat("yyyy-MM-dd HH-mm-ss").format(
+      DateTime.now().toUtc(),
+    );
+  }
+  return logStreamName;
+}
+
+void log(String logString, {isError = false}) {
+  logging.log(
+    msg: logString,
+    logGroupName: isError ? _LogGroup : _ErrorGroup,
+    logStreamName: _getLogStreamName(),
+  );
+}

example/pubspec.yaml

@@ -1,6 +1,6 @@
 name: example
 description: An AWS CloudWatch wrapper package for easy Flutter cloud logging. Currently only logging is supported.
-version: 0.1.10
+version: 0.2.0
 homepage: https://github.com/Zsmerritt/Flutter_AWS_CloudWatch
 
 environment: