docs

docs/guide/src/docs/asciidoc/index.adoc

@@ -8,10 +8,11 @@ include::{includedir}/_links.adoc[]
 
 :leveloffset: 1
 include::{includedir}/introduction.adoc[]
+include::{includedir}/installation.adoc[]
 include::{includedir}/usage.adoc[]
 
 = Links
 
 link:api/index.html[Javadoc, window="_blank"]
 
-link:api-html/index.html[Source, window="_blank"]
+link:api-html/index.html[Source, window="_blank"]

docs/guide/src/docs/asciidoc/installation.adoc

@@ -0,0 +1,52 @@
+
+[[_installation]]
+= Installation
+
+First of all you need to add the dependency to your build file.
+
+.Gradle Installation
+[source,subs='verbatim,attributes']
+----
+repositories {
+    jcenter()
+}
+
+dependencies {
+    // load just simple implementation with POJO client and reflection based parser
+    testCompile "com.agorapulse:micronaut-log4aws:{version}"
+}
+----
+
+Also be sure that your build file **does not contain any referrence to Logback**:
+
+.Build File Cleanup
+[source,subs='verbatim,attributes']
+```
+dependencies {
+    // remove following line from your build file if present
+    runtime "ch.qos.logback:logback-classic:1.2.3"
+}
+```
+
+Then remove Logback configuration file from `src/main/resources/logback.groovy`
+and replace it with a new file `log4j2.xml` with following content. Feel free to update the file to fit your needs.
+
+
+.Log4J2 Configuration
+[source,xml,subs='verbatim,attributes']
+```
+include::../../../../../subprojects/micronaut-log4aws/src/test/resources/log4j2.xml[lines=1;21..51]
+```
+
+As a last step you need to create a file `sentry.properties` for sentry configuration - also in `src/main/resources`:
+
+.sentry.properties
+[source,properties,subs='verbatim,attributes']
+```
+# guarantees all events are logged before the function execution is finished
+async=false
+
+# you should consider adding your packages here to enable filtering of stack traces in Sentry
+
+# stacktrace.app.packages=agorapulse,com.agorapulse
+```

docs/guide/src/docs/asciidoc/introduction.adoc

@@ -2,4 +2,5 @@
 [[_introduction]]
 = Introduction
 
-Lorem ipsum dolor sit amet
+Micronaut Log4AWS simplifies integration of https://aws.amazon.com/lambda/[AWS Lambda] functions written with https://micronaut-projects.github.io/micronaut-aws/latest/guide/[Micronaut]
+into https://sentry.io/[Sentry] service.

docs/guide/src/docs/asciidoc/usage.adoc

@@ -2,4 +2,38 @@
 [[_usage]]
 = Usage
 
-Lorem ipsum dolor sit amet
+Sentry logger is initialised automatically during the application startup. There is also `SentryClient` instance available for injection if you need to access lower level API.
+
+All the errors have to be logged to be propagated to Sentry. You can use `LogErrors` around advice
+around your method to simplify the logging boilerplate:
+
+.Using LogError Annotation
+[source,java]
+----
+/**
+* This class is an entrypoint called by AWS Lambda. Keep the code to minimum.
+* Method handleRequest is called directly by the AWS Lambda container.
+*/
+class ReportsExporter extends FunctionInitializer implements RequestHandler<SQSEvent, Void> {
+
+    @Inject private ReportsService reportsService;
+
+    Void handleRequest(SQSEvent event, Context context) {
+        return reportsService.handlerRequest(event);
+    }
+
+}
+
+/**
+* This class is handled by Micronaut and can use the advice.
+*/
+class ReportsService implements RequestHandler<SQSEvent, Void> {
+
+    @LogError
+    Void handleRequest(SQSEvent event, Context context) {
+        return reportsService.handlerRequest(event);
+    }
+
+}
+----
+

subprojects/micronaut-log4aws/src/test/resources/log4j2.xml

@@ -34,18 +34,11 @@
             <!-- Note that the Sentry logging threshold is overridden to the WARN level -->
             <AppenderRef ref="Sentry" level="warn"/>
         </Root>
-        <Logger name="com.mysql" level="error" additivity="false">
-            <AppenderRef ref="Console" />
-        </Logger>
         <Logger name="io.sentry" level="warn" additivity="false">
             <AppenderRef ref="Console" />
         </Logger>
         <Logger name="software.amazon" level="warn" additivity="false">
             <AppenderRef ref="Console" />
         </Logger>
-        <Logger name="agorapulse" level="debug" additivity="false">
-            <AppenderRef ref="Console" />
-            <AppenderRef ref="Sentry" level="warn"/>
-        </Logger>
     </Loggers>
 </Configuration>