From 9ab8cbb383c9b6b4d4a2372ad4ad678fec51d179 Mon Sep 17 00:00:00 2001
From: Gonzalo <456459+grzuy@users.noreply.github.com>
Date: Tue, 20 Aug 2024 11:34:05 -0300
Subject: [PATCH] docs: usage

---
 README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 71 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 249d438..0934eac 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,28 @@
 [![Hex.pm](https://img.shields.io/hexpm/v/tower.svg)](https://hex.pm/packages/tower)
 [![Docs](https://img.shields.io/badge/docs-gray.svg)](https://hexdocs.pm/tower)
 
-Solid error handling and reporting
+Solid and simple **error handling** and **reporting** in Elixir
 
-## Installation
+## Usage
 
-The package can be installed by adding `tower` to your list of dependencies in `mix.exs`:
+Tower is an Elixir package that tries to do one job well, **handle** error **events** in an Elixir application
+**and inform** about them to configured **reporters** (one or many).
+
+You can either write your own reporter or use any amount of the following reporters:
+
+- [tower_rollbar](http://github.com/mimiquate/tower_rollbar)
+- [tower_slack](http://github.com/mimiquate/tower_slack)
+
+In case you use any of the above reporters, you don't need to include `tower` as a dependency. It will be a transitive dependency
+of any of the above reporters.
+
+### Writing a custom reporter
+
+In case you don't want to use pre-built reporters and you want to write your own, first include
+the core `tower` package:
 
 ```elixir
+# mix.exs
 def deps do
   [
     {:tower, "~> 0.4.0"}
@@ -18,6 +33,59 @@ def deps do
 end
 ```
 
+Implement you custom reporting by implementing `Tower.Reporter` behaviour:
+
+```elixir
+# lib/my_app/error_reporter.ex
+defmodule MyApp.ErrorReporter do
+  use Tower.Reporter
+
+  @impl true
+  def report_event(%Tower.Event{} = event) do
+    # Do whatever you want with event...
+
+    # A `Tower.Event` is a struct with the following typespec:
+    #
+    # %Tower.Event{
+    #   id: Uniq.UUID.t(),
+    #   datetime: DateTime.t(),
+    #   level: :logger.level(),
+    #   kind: :error | :exit | :throw | :message,
+    #   reason: Exception.t() | term(),
+    #   stacktrace: Exception.stacktrace() | nil,
+    #   log_event: :logger.log_event() | nil,
+    #   plug_conn: struct() | nil,
+    #   metadata: map()
+    # }
+  end
+end
+```
+
+Tell `tower` you want your reporter to be informed about events.
+
+```elixir
+# config/runtime.exs
+
+config :tower, reporters: [MyApp.ErrorReporter]
+```
+
+Finally attach Tower to your application.
+
+```elixir
+# lib/my_app/application.ex
+defmodule MyApp.Application do
+  ...
+
+  def start(_type, _args) do
+    Tower.attach()
+
+    ...
+  end
+
+  ...
+end
+```
+
 ## License
 
 Copyright 2024 Mimiquate