L-147 Add documentation and example project (#14)

.gitignore

@@ -10,6 +10,7 @@
 .ruby-version
 coverage
 Gemfile.lock
+!/example-project/Gemfile.lock
 *.swp
 *.gem
 

README.md

@@ -1,10 +1,111 @@
 # 🪵 Logtail Integration For Rack
 
+  [![Logtail ruby dashboard](https://user-images.githubusercontent.com/19272921/154085622-59997d5a-3f91-4bc9-a815-3b8ead16d28d.jpeg)](https://betterstack.com/logtail)
+
 [![ISC License](https://img.shields.io/badge/license-ISC-ff69b4.svg)](LICENSE.md)
 [![Gem Version](https://badge.fury.io/rb/logtail-rack.svg)](https://badge.fury.io/rb/logtail-rack)
-[![Build Status](https://github.com/logtail/logtail-ruby-rack/workflows/build/badge.svg)](https://github.com/logtail/logtail-ruby-rack/actions?query=workflow%3Abuild)
+[![Build Status](https://github.com/logtail/logtail-ruby-rack/actions/workflows/main.yml/badge.svg)](https://github.com/logtail/logtail-ruby-rack/actions/workflows/main.yml)
 
 This library integrates the [`logtail` Ruby library](https://github.com/logtail/logtail-ruby) with the [rack](https://github.com/rack/rack) framework,
 turning your Rack logs into rich structured events.
 
-* **Sign-up: [https://logtail.com](https://logtail.com)**
+* **Sign-up: [https://logs.betterstack.com](https://logs.betterstack.com)**
+
+Collect logs directly from your Ruby Rack projects. To start logging Ruby projects explore the [Logtail Ruby library](https://github.com/logtail/logtail-ruby).
+
+[Better Stack](https://logs.betterstack.com) is a hosted service that centralizes all of your logs into one place.
+Allowing for analysis, correlation and filtering with SQL.
+Actionable Grafana dashboards and collaboration come built-in.
+Logtail works with [any language or platform and any data source](https://betterstack.com/docs/logs/).
+
+### Features
+- Simple integration.
+- Support for structured logging and events.
+- Automatically captures useful context.
+- Performant, light weight, with a thoughtful design.
+
+### Supported language versions
+- Ruby 2.3 or newer
+- Rack 1.2 or newer
+
+# Installation
+Install the Logtail Rack client library, run the following command:
+
+```bash
+bundle add logtail-rack
+```
+
+Alternatively, add `gem "logtail-rack"` to your `Gemfile` manually and then run `bundle install`.
+
+Then add following configuration into your `config.ru`:
+
+```ruby
+# Initialization of logging middlewares (you don't have to use all)
+use Logtail::Integrations::Rack::HTTPContext
+use Logtail::Integrations::Rack::HTTPEvents
+use Logtail::Integrations::Rack::ErrorEvent
+use Logtail::Integrations::Rack::UserContext
+use Logtail::Integrations::Rack::SessionContext
+
+http_io_device = Logtail::LogDevices::HTTP.new("<SOURCE_TOKEN>")
+logger = Logtail::Logger.new(http_io_device)
+Logtail::Config.instance.logger = logger
+
+# Here is your application initialization
+run ...
+```
+
+*Don't forget to replace `<SOURCE_TOKEN>` with your actual source token which you can find by going to [Better Stack Logs](https://logs.betterstack.com/dashboard) -> Source -> Edit.*
+
+---
+
+# Example project
+
+To help you get started with using Better Stack in your Rails projects, we have prepared a simple program that showcases the usage of Logtail logger.
+
+## Download and install the example project
+
+You can download the [example project](https://github.com/logtail/logtail-ruby-rack/tree/main/example-project) from GitHub directly or you can clone it to a select directory. Make sure you are in the projects directory and run the following command:
+
+```bash
+bundle install
+```
+
+This will install all dependencies listed in the `Gemfile.lock` file.
+
+Then replace `<SOURCE_TOKEN>` in `config.ru` with your actual source token which you can find by going to [Better Stack Logs](https://logs.betterstack.com/dashboard) -> Source -> Edit.
+
+```ruby
+http_io_device = Logtail::LogDevices::HTTP.new("<YOUR_ACTUAL_SOURCE_TOKEN>")
+```
+
+## Run the example project
+
+To run the example application, run the following command:
+
+```bash
+rackup
+```
+
+This will start a local server and you visit [http://127.0.0.1:9292](http://127.0.0.1:9292) in your browser.
+
+You should see the following output:
+
+```bash
+All done!
+Log into your Logtail account to check your logs.
+```
+
+This will create a total of 4 different logs. You can review these logs in Better Stack.
+
+You can visit any path on the server to see the request path being logged in context. Visit [/error](http://127.0.0.1:9292) to see an example exception being logged.
+
+## Explore how example project works
+
+Learn how to setup Ruby logging by exploring the workings of the [example project](https://github.com/logtail/logtail-ruby-rack/tree/main/example-project) in detail.
+
+---
+
+## Get in touch
+
+Have any questions? Please explore the Better Stack [documentation](https://betterstack.com/docs/logs/) or contact our [support](https://betterstack.com/help).

example-project/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gem "rack", "~> 3.0"
+
+gem "rackup", "~> 2.1"
+
+gem "logtail-rack", "~> 0.2.4"

example-project/Gemfile.lock

@@ -0,0 +1,25 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    logtail (0.1.12)
+      msgpack (~> 1.0)
+    logtail-rack (0.2.4)
+      logtail (~> 0.1)
+      rack (>= 1.2, < 4.0)
+    msgpack (1.7.2)
+    rack (3.0.0)
+    rackup (2.1.0)
+      rack (>= 3)
+      webrick (~> 1.8)
+    webrick (1.8.1)
+
+PLATFORMS
+  arm64-darwin-22
+
+DEPENDENCIES
+  logtail-rack (~> 0.2.4)
+  rack (~> 3.0)
+  rackup (~> 2.1)
+
+BUNDLED WITH
+   2.3.14

example-project/config.ru

@@ -0,0 +1,23 @@
+require 'logtail-rack'
+require './logging_app'
+
+# Initialization of logging middlewares
+use Logtail::Integrations::Rack::HTTPContext
+use Logtail::Integrations::Rack::HTTPEvents
+use Logtail::Integrations::Rack::ErrorEvent
+
+# HTTP IO device sends logs to Better Stack, replace <SOURCE_TOKEN> with your real source token
+http_io_device = Logtail::LogDevices::HTTP.new("<SOURCE_TOKEN>")
+
+# STDOUT IO device sends logs to console output
+stdout_io_device = STDOUT
+
+# Logger initialization, you can use any number of IO devices
+logger = Logtail::Logger.new(http_io_device, stdout_io_device)
+Logtail::Config.instance.logger = logger
+
+# App initialization
+logging_app = LoggingApp.new(logger)
+run do |env|
+  logging_app.run(env)
+end

example-project/logging_app.rb

@@ -0,0 +1,24 @@
+require 'logtail-rack'
+
+class LoggingApp
+  def initialize(logger)
+    @logger = logger
+  end
+
+  def run(env)
+    @logger.info("I am using Better Stack! 🚀")
+
+    # You can also provide additional information when logging
+    @logger.debug("Logging structured data...",
+      name: {
+        first: "John",
+        last: "Smith"
+      },
+      id: 123456
+    )
+
+    raise RuntimeError.new("Visiting /error raises an error. You should see it in Better Stack.") if env["REQUEST_PATH"].start_with?("/error")
+
+    [200, {}, ["All done!\nLog into your Logtail account to check your logs."]]
+  end
+end