logtail-rails 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36cc8a6525761e524273966307ac9a3ec250e797030ba959016f6a633b404076
-  data.tar.gz: c9a0c0999fcef3fcb8277a618ba5efe23c74cd257805205c3736a2ea9398174b
+  metadata.gz: 7eb050c970571683d40dcd025672d9fb0eebcc72261627e7716115b7e16bd3a4
+  data.tar.gz: abc54338cfdb59ddc885fc5c3589119b21e9ce6a7bb6d7f8b73301f6f94f2233
 SHA512:
-  metadata.gz: 7a739ca51649acfba9dc3c49c1ff7105728fe43738d7c60fd566644eb9c73428bfeabb96a5fed3da44fba80ce98b3fc2a5dc8825028d7b5362e433a1d3022c77
-  data.tar.gz: 460aa9fe05000534e693b4dabefb4f19fcf8d967aa895ba7e475f94309b4291d20fd72c376ae2d190b9fcccc747c57ef318b0bf7c1d07a5ea06dfe9303827c5f
+  metadata.gz: 493ff5967c0a198b4667bd693074267f4ebe6e543363496a93825e41dd03736ced0e85357c207e1c3ce225375527c9feef424e51f0bd040b977403326e410c6a
+  data.tar.gz: d5886072cbfbd130164e68bc7d23c3aaf1e335ee2b8dbb5e115c380c57ae437e6d45ba8797c824847014e3372b4c01600692ede1701c0c283721022c01e18640

data/README.md

@@ -1,10 +1,97 @@
-# 🪵 Logtail Integration For Rails
+# Logtail - Ruby on Rails Logging Made Easy
+  
+  [![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-ruby.svg)](https://badge.fury.io/rb/logtail-ruby)
 [![Build Status](https://github.com/logtail/logtail-ruby-rails/workflows/build/badge.svg)](https://github.com/logtail/logtail-ruby-rails/actions?query=workflow%3Abuild)
 
-This library integrates the [`logtail` Ruby library](https://github.com/logtail/logtail-ruby) with
-the [rails](https://github.com/rails/rails) framework, turning your rails logs into rich structured events.
+Collect logs directly from your Ruby on Rails projects. To start logging Ruby projects explore the [Logtail Ruby library](https://github.com/logtail/logtail-ruby).
 
-* **Sign-up: [https://logtail.com](https://logtail.com)**
+[Logtail](https://betterstack.com/logtail) 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.7.0 or newer
+- Rails 6.1.4.2 or newer
+
+# Installation
+Install the Logtail Ruby on Rails client library, run the following command:
+
+```bash
+bundle add logtail-rails
+```
+
+Alternatively, add `gem "logtail-rails"` to your `Gemfile` manually and then run `bundle install`.
+
+Then add following configuration line into your `config/application.rb`:
+
+```ruby
+module YourProject
+  class Application < Rails::Application
+    # ...
+    # configuration of your project
+    # ...
+
+    config.logger = Logtail::Logger.create_default_logger("<SOURCE_TOKEN>")
+  end
+end
+```
+
+*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 Logtail in your Ruby on 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-rails/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/application.rb` with your actual source token which you can find by going to [Better Stack Logs](https://logs.betterstack.com/dashboard) -> Source -> Edit.
+
+```ruby
+config.logger = Logtail::Logger.create_default_logger("<YOUR_ACTUAL_SOURCE_TOKEN>")
+```
+
+ ## Run the example project
+ 
+ To run the example application, run the following command:
+
+```bash
+rails server
+```
+
+This will open a local server [127.0.0.1:3000.](http://127.0.0.1:3000/) On the main page, click the "Let's go!" button to generate test logs.
+
+You should see the following output:
+
+```bash
+All done!
+Log into your Logtail account to check your logs.
+```
+
+This will create a total of 6 different logs, each corresponding to a different log level and one with additional structured data. You can review these logs in Logtail.
+
+## 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-rails/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).

data/example-project/.gitattributes

@@ -0,0 +1,7 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored

data/example-project/.gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-*
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore uploaded files in development.
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+
+/public/assets
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key

data/example-project/Gemfile

@@ -0,0 +1,74 @@
+source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+ruby "3.1.2"
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 7.0.6"
+
+# The original asset pipeline for Rails [https://github.com/rails/sprockets-rails]
+gem "sprockets-rails"
+
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", "~> 1.4"
+
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", "~> 5.0"
+
+# Use JavaScript with ESM import maps [https://github.com/rails/importmap-rails]
+gem "importmap-rails"
+
+# Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]
+gem "turbo-rails"
+
+# Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]
+gem "stimulus-rails"
+
+# Build JSON APIs with ease [https://github.com/rails/jbuilder]
+gem "jbuilder"
+
+# Use Redis adapter to run Action Cable in production
+gem "redis", "~> 4.0"
+
+# Use Kredis to get higher-level data types in Redis [https://github.com/rails/kredis]
+# gem "kredis"
+
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ mingw mswin x64_mingw jruby ]
+
+# Reduces boot times through caching; required in config/boot.rb
+gem "bootsnap", require: false
+
+# Use Sass to process CSS
+# gem "sassc-rails"
+
+# Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
+# gem "image_processing", "~> 1.2"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[ mri mingw x64_mingw ]
+end
+
+group :development do
+  # Use console on exceptions pages [https://github.com/rails/web-console]
+  gem "web-console"
+
+  # Add speed badges [https://github.com/MiniProfiler/rack-mini-profiler]
+  # gem "rack-mini-profiler"
+
+  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
+  # gem "spring"
+end
+
+group :test do
+  # Use system testing [https://guides.rubyonrails.org/testing.html#system-testing]
+  gem "capybara"
+  gem "selenium-webdriver"
+  gem "webdrivers"
+end
+
+gem "logtail-rails", "~> 0.1.7"

data/example-project/README.md

@@ -0,0 +1,211 @@
+# Logtail Ruby on Rails example project
+
+To help you get started with using Logtail in your Ruby on 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 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/application.rb` with your actual source token which you can find by going to [Better Stack](https://logs.betterstack.com/) -> Sources -> Edit.
+
+```ruby
+config.logger = Logtail::Logger.create_default_logger("<YOUR_ACTUAL_SOURCE_TOKEN>")
+```
+
+## Run the example project
+ 
+To run the example application, run the following command:
+
+```bash
+rails server
+```
+
+This will open a local server [127.0.0.1:3000.](http://127.0.0.1:3000/) On the main page, click the "Let's go!" button to generate test logs.
+
+You should see the following output:
+
+```bash
+All done!
+Log into your Logtail account to check your logs.
+```
+
+This will create a total of 6 different logs, each corresponding to a different log level and one with additional structured data. You can review these logs in Logtail.
+
+# Logging
+
+To send logs to Logtail use the `Rails.logger` logger. It provides 5 logging methods for the 5 default log levels. The log levels and their method are:
+
+- **DEBUG** - Send debug messages using the `debug()` method
+- **INFO** - Send informative messages about the application progress using the `info()` method
+- **WARN** - Report non-critical issues using the `warn()` method
+- **ERROR** - Send messages about serious problems using the `error()` method
+- **FATAL** - Send messages about fatal events that caused the app to crash using the `fatal()` method
+
+## Logging example
+
+In this example, we will send two logs - **DEBUG** and **INFO**
+
+```ruby
+# Send debug logs messages using the debug() method
+Rails.logger.debug("Logtail is ready!")
+
+# Send informative messages about interesting events using the info() method
+Rails.logger.info("I am using Logtail!")
+```
+
+This will create the following output:
+
+```json
+{
+    "dt": "2021-03-29T11:24:54.788Z",
+    "level": "debug",
+    "message": "Logtail is ready!",
+    "context": {
+        "runtime": {
+            "thread_id": 123,
+            "file": "main.rb",
+            "line": 6,
+            "frame": null,
+            "frame_label": "<main>"
+        },
+        "system": {
+            "hostname": "hostname",
+            "pid": 1234
+        }
+    }
+}
+
+{
+    "dt": "2021-03-29T11:24:54.788Z",
+    "level": "info",
+    "message": "I am using Logtail!",
+    "context": {
+        "runtime": {
+            "thread_id": 123,
+            "file": "main.rb",
+            "line": 6,
+            "frame": null,
+            "frame_label": "<main>"
+        },
+        "system": {
+            "hostname": "hostname",
+            "pid": 1234
+        }
+    }
+}
+```
+
+## Log structured data
+
+You can also log additional structured data. This can help you provide additional information when debugging and troubleshooting your application. You can provide this data as the second argument to any logging method.
+
+```ruby
+# Send messages about worrying events using the warn() method
+# You can also log additional structured data
+Rails.logger.warn(
+    "log structured data",
+    item: {
+        url: "https://fictional-store.com/item-123",
+        price: 100.00
+    }
+)
+```
+
+This will create the following output:
+
+```json
+{
+    "dt": "2021-03-29T11:24:54.788Z",
+    "level": "warn",
+    "message": "log structured data",
+    "item": {
+        "url": "https://fictional-store.com/item-123",
+        "price": 100.00
+    },
+    "context": {
+        "runtime": {
+            "thread_id": 123,
+            "file": "main.rb",
+            "line": 7,            
+            "frame": null,
+            "frame_label": "<main>"
+        },
+        "system": {
+            "hostname": "hostname",
+            "pid": 1234
+        }
+    }
+}
+```
+
+## Context
+
+We add information about the current runtime environment and the current process into a `context` field of the logged item by default.
+
+If you want to add custom information to all logged items (e.g., the ID of the current user), you can do so by adding a custom context:
+
+```ruby
+# Provide context to the logs
+Logtail.with_context(user: { id: 123 }) do
+    Rails.logger.info('new subscription')
+end
+```
+
+This will generate the following JSON output:
+
+```json
+{
+    "dt": "2021-03-29T11:24:54.788Z",
+    "level": "warn",
+    "message": "new subscription",
+    "context": {
+        "runtime": {
+            "thread_id": 123456,
+            "file": "main.rb",
+            "line": 2,            
+            "frame": null,
+            "frame_label": "<main>"
+        },
+        "system": {
+            "hostname": "hostname",
+            "pid": 1234
+        },
+        "user": {
+            "id": 123
+        }
+    }
+}
+```
+
+We will automatically add the information about the current user to each log if you're using Ruby on Rails and the Devise gem.
+
+If you're not using Devise or you want to log some additional information for every request your Rails app handles, you can easily implement this using Rails' `around_action` in your application controller. A simple implementation could look like this:
+
+```ruby
+class ApplicationController < ActionController::Base
+  around_action :with_logtail_context
+
+  private
+
+    def with_logtail_context
+      if user_signed_in?
+        Logtail.with_context(user_context) { yield }
+      else
+        yield
+      end
+    end
+    
+    def user_context
+      Logtail::Contexts::User.new(
+        id: current_user.id,
+        name: current_user.name,
+        email: current_user.email
+      )
+    end
+end
+```

data/example-project/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/example-project/app/assets/config/manifest.js

@@ -0,0 +1,4 @@
+//= link_tree ../images
+//= link_directory ../stylesheets .css
+//= link_tree ../../javascript .js
+//= link_tree ../../../vendor/javascript .js

data/example-project/app/assets/stylesheets/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS (and SCSS, if configured) file within this directory, lib/assets/stylesheets, or any plugin's
+ * vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/example-project/app/channels/application_cable/channel.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/example-project/app/channels/application_cable/connection.rb

@@ -0,0 +1,4 @@
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+  end
+end

data/example-project/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base
+end

data/example-project/app/controllers/example_controller.rb

@@ -0,0 +1,40 @@
+class ExampleController < ApplicationController
+    # Index action
+    def index
+        send_logs_path = '/send_logs'
+    end
+
+    # The following action send example logs
+    def send_logs
+        # Sending logs using the Rails.logger
+
+        # Send debug logs messages using the debug() method
+        Rails.logger.debug("Hey! I am debuging!")
+
+        # Send informative messages about interesting events using the info() method
+        Rails.logger.info("You know what's interesting? Logtail !")
+
+        # Send messages about worrying events using the warn() method
+        Rails.logger.warn("Something might not be quite right...")
+
+        # Send error messages using the error() method
+        Rails.logger.error("Oops! Something went wrong.")
+
+        # Send messages about fatal events thet caused the app to crash using the fatal() method
+        Rails.logger.fatal("Application crashed! Needs to be fixed ASAP!")
+
+
+        # You can optionally add tags when logging
+        Rails.logger.tagged("tag1", "tag2").info("log message with tags")
+
+
+        # You can also provide additional information when logging
+        Rails.logger.warn("log structured data",
+            name: {
+                first: "John",
+                last: "Smith"
+            },
+            id: 123456
+        )
+    end
+end

data/example-project/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/example-project/app/helpers/example_helper.rb

@@ -0,0 +1,2 @@
+module ExampleHelper
+end

data/example-project/app/javascript/application.js

@@ -0,0 +1,3 @@
+// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
+import "@hotwired/turbo-rails"
+import "controllers"

data/example-project/app/javascript/controllers/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+
+const application = Application.start()
+
+// Configure Stimulus development experience
+application.debug = false
+window.Stimulus   = application
+
+export { application }

data/example-project/app/javascript/controllers/hello_controller.js

@@ -0,0 +1,7 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    this.element.textContent = "Hello World!"
+  }
+}

data/example-project/app/javascript/controllers/index.js

@@ -0,0 +1,11 @@
+// Import and register all your controllers from the importmap under controllers/*
+
+import { application } from "controllers/application"
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)
+
+// Lazy load controllers as they appear in the DOM (remember not to preload controllers in import map!)
+// import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+// lazyLoadControllersFrom("controllers", application)

data/example-project/app/jobs/application_job.rb

@@ -0,0 +1,7 @@
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+
+  # Most jobs are safe to ignore if the underlying records are no longer available
+  # discard_on ActiveJob::DeserializationError
+end

data/example-project/app/mailers/application_mailer.rb

@@ -0,0 +1,4 @@
+class ApplicationMailer < ActionMailer::Base
+  default from: "from@example.com"
+  layout "mailer"
+end

data/example-project/app/models/application_record.rb

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end

data/example-project/app/views/example/index.html.erb

@@ -0,0 +1,3 @@
+<h1>Hello from Logtail</h1>
+<p>Click the button below to send some example logs</p>
+<%= button_to "Let's go!", send_logs_path, method: :get %>

data/example-project/app/views/example/send_logs.html.erb

@@ -0,0 +1,4 @@
+<b>All done!</b>
+<p>
+ Log into your Logtail account to check your logs.
+</p>

data/example-project/app/views/layouts/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>LogtailExampleProject</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/example-project/app/views/layouts/mailer.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <style>
+      /* Email styles need to be inline */
+    </style>
+  </head>
+
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/example-project/app/views/layouts/mailer.text.erb

@@ -0,0 +1 @@
+<%= yield %>