From 633c18b7dbe9562b42d1abb9699e6f7dc307c829 Mon Sep 17 00:00:00 2001
From: Lukas Franz <lksfrnz@amazon.com>
Date: Wed, 31 Jul 2024 00:25:23 +0000
Subject: [PATCH] Added a readme to annotations

---
 README.md             |  6 ++++
 annotations/README.md | 75 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 annotations/README.md

diff --git a/README.md b/README.md
index 8342e39c..fe68e005 100644
--- a/README.md
+++ b/README.md
@@ -391,6 +391,12 @@ config.setShouldWriteToStdout(true);
 AWS_EMF_WRITE_TO_STDOUT="true"
 ```
 
+## Annotations
+
+This library includes a package implmenting annotations that log metrics about method behaviour. This package was seperated so that it can be optionally imported because it adds a large dependency.
+
+Please see the [README](annotations/README.md) in the annotations project folder to learn more.
+
 ## Thread-safety
 
 ### Internal Synchronization
diff --git a/annotations/README.md b/annotations/README.md
new file mode 100644
index 00000000..de887972
--- /dev/null
+++ b/annotations/README.md
@@ -0,0 +1,75 @@
+# Annotations
+
+## Setup
+
+Getting this package to work requires the following additions to a gradle build file:
+```gradle
+plugins {
+	...
+	id "io.freefair.aspectj.post-compile-weaving" version "6.4.3"
+}
+
+dependencies {
+	...
+	implementation project(':annotations')
+	implementation "org.aspectj:aspectjweaver:1.9.8.RC3"
+}
+
+```
+
+## Usage
+
+This pacakge adds `@CountMetric` and `@ExecutionTimeMetric` method annotations.
+
+### @CountMetric
+@CountMetric will log a value of 1 whenever it is triggered.
+
+### @ExecutionTimeMetric
+@ExecutionTimeMetric will log the execution time of a method whenever it is triggered.
+
+### Annotation Parameters
+
+- `String Name` (Default: `""`)
+	- The name the metric is published under
+	- If the name is left as `""` it will be replaced with `"<ClassName>.<MethodName>.<AnnotationType>"` when being sent to CWL
+- `Boolean logSuccess` (Default `True` )
+	- Determines if this annotation will log a metric when the method exits successfully
+- `Class<? extends Throwable>[] LogErrors`  (Default: `[Throwable.class]` )
+	- Determines if this annotation will log a metric when the method exits with an error (will log if the method exits by a throwing an in the given list)
+- `String Logger` (Default: `""`)
+	- Determines which logger this annotation’s metric will be put into.
+	- If `null` or there is no logger associated with that key then the default logger will be used
+- `bool flush` (Default: `false` )
+	- Determines whether the metric logger attached to this annotation should flush after this function
+
+
+### Loggers
+This package also implements a singleton `MetricAnnotationMediator` which handles the logging of all metrics created by annotations. This singleton contains a default `MetricsLogger` instance that all annotations will default to; however, other loggers can be added to it using its `addLogger(name, logger)` method. Annotations can then be sent to the added logger by specifying the name of the logger as an annotation parameter.
+
+There are two ways to flush these metrics to CloudWatch:
+1. Call `MetricAnnotationMediator.flushAll()` which flushes all the loggers that the singleton has a reference to
+2. Flush the logger that the metrics have been added to. Loggers can be retrieved from the `MetricAnnotationMediator` using the methods `MetricAnnotationMediator.getDefaultLogger()` and `MetricAnnotationMediator.getLogger(name)`
+
+```java
+import software.amazon.cloudwatchlogs.emf.annotations.CountMetric;
+import software.amazon.cloudwatchlogs.emf.annotations.ExecutionTimeMetric;
+import software.amazon.cloudwatchlogs.emf.annotations.MetricAnnotationMediator;
+
+class Example {
+
+	@CountMetric
+	@ExecutionTimeMetric
+	public static void doSomething() {
+		// Do something
+		...
+	}
+
+	public static void main(String[] args) {
+		MetricsLogger metrics = new MetricsLogger();
+
+		doSomething();
+
+		MetricAnnotationMediator.flushAll();
+	}
+}
+```