Introduce README.md with a project introduction

Allow people to discover the Audit trail plugin and have more
insights of what it is and what are the benefits provided.

Change-Id: Iee2493392c4a41bb09c20767384c5f735c2ba269

README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d4c4c19
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# Audit plugin for Gerrit
+
+Plug into the Gerrit Code Review audit extension and format and forward all
+the events to an [SLF4J appender](https://www.slf4j.org), the same logging
+system used internally for the generation of all logs..
+
+## How to configure logging?
+
+Audit events are by default stored into the Gerrit error_log under the appender
+`com.googlesource.gerrit.plugins.auditsl4j.LoggerAudit`. However, it is possible
+to generate a separate audit file and having the audit records formatted into
+CSV or JSON.
+
+For more details, see the [configuration guide](src/main/resources/Documentation/config.md)
+in the plugin.
+
+## Why auditing events on Gerrit?
+
+Audits leave an immutable trace of what happened on Gerrit and allows to answer
+the question "who did what and when?".
+
+When aggregated by time, project or user, can give an overall figure on how much
+the system is utilized and allow to make a better planning of the hardware resources allocation
+and planning the downtimes to reduce the impact on the people and projects.
+
+## Is this a duplicate of Gerrit stream events?
+
+Gerrit stream events are triggered on Git-related operations and reviews, but do
+not cover most of the actions that happen on Gerrit and do not include all the system
+information that is typically needed for audit-trail purposes.
+
+Furthermore, stream events are designed to be consumed in near-real-time while audits,
+are typically archived and consumed off-line.
+
+## What the audit events look like?
+
+The format of Gerrit audits changes across the different releases because they reflect
+the internal representation of the Java objects in memory.
+
+They share an overall basic structure:
+
+- type: Audit java class
+- event: Audit event
+  - session_id: unique identifier of the user's session
+  - who: user that generated the event
+    - account_id: user unique id
+    - access_path: how the user accessed the system
+  - when: epoch time-stamp of the event
+  - what: action performed
+  - result: result of the action
+  - time_at_start: epoch time-stamp of when the action started
+  - elapsed: how long the action lasted (msec)
+  - uuid: audit event UUID
+
+Example audit of a login from a Git client over SSH:
+```json
+{
+  "type": "SshAuditEvent",
+  "event": {
+    "session_id": "0261c43e",
+    "who": {
+      "account_id": {
+        "id": 1011575
+      },
+      "access_path": "GIT",
+      "last_login_external_id_property_key": {}
+    },
+    "when": 1539561891898,
+    "what": "LOGOUT",
+    "params": {},
+    "result": "0",
+    "time_at_start": 1539561891898,
+    "elapsed": 0,
+    "uuid": {
+      "uuid": "audit:f135cb10-59be-4087-a9e0-571680b93a59"
+    }
+  }
+}
+```
+
+Example audit of a Gerrit changes query over SSH:
+```json
+{
+  "type": "SshAuditEvent",
+  "event": {
+    "session_id": "22688824",
+    "who": {
+      "account_id": {
+        "id": 1011203
+      },
+      "access_path": "SSH_COMMAND",
+      "last_login_external_id_property_key": {}
+    },
+    "when": 1539561891503,
+    "what": "gerrit.query.--format.json.--current-patch-set.project:mycompany/myproject commit:798b22fcf3614e8575e0ef23019a9706b8acebcc NOT is:draft",
+    "params": {},
+    "result": "0",
+    "time_at_start": 1539561891503,
+    "elapsed": 3,
+    "uuid": {
+      "uuid": "audit:171a9b6f-327a-40a2-9b66-c47a39eba68c"
+    }
+  }
+}
+```