klogger-logger 1.3.1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05fcc83ebb5b6dcc9d947576d52b6d14ddd47c89de9ccfbe361df9dc1f9f33ed
-  data.tar.gz: f3f0d69f3427200dc9bbc74dee90f7dc8ad63aeb1364d8a47ec4c81e463189fb
+  metadata.gz: ec65c2728e6aee2870704aeb67e2224f3ffe8b94173f0dafa5e54354f9ec4737
+  data.tar.gz: 51244c5f4ab5fc54d5a9dda4aa14a1051fed37fd718b205c3bd14cf62b7d52ee
 SHA512:
-  metadata.gz: c7e688edcf1a9454b422b9aefa6e687298b133a7f847b5c2f6dd0717a1afae395dd83ff68b639a238256e7f1a70f130ae5de18c779cbe6ac3f7c53f824631558
-  data.tar.gz: 77a325bb4eada003e7bfd46a47ec662db1436a4d85c9e12ce2da6bd7a1d5a8ba6d7bbe8ea5f79d73dbadff1baa6adebc1e968bbdc06da2f11e47bcd0b74e235b
+  metadata.gz: dab76a4af78b3684b078caf4348712637b952bd4abdc61cf73ba5bc1722feb6754b3dee5eaa4d1a49f5bf22cb86c5a30a5570861822735a64c4c379c56bfe27b
+  data.tar.gz: 0b4fe70463502a574a6e461aec57559bf26e1141ae24d1b129fb2320058fb1acba31c42979564db4e1058c42f4785034fdb586ea05a5e8b5c944c53a4c48ca20

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Krystal Hosting Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,190 @@
+![Screenshot](https://share.adam.ac/23/Screen-Shot-2023-03-09-16-00-57.65-DWjwl4M5Gu.png)
+
+<p align="center">
+  <a href="https://rubygems.org/gems/klogger-logger">
+    <img src="https://img.shields.io/gem/v/klogger-logger?label=RubyGems&logo=rubygems" alt="RubyGems">
+  </a>
+  <a href="https://github.com/krystal/klogger/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/krystal/klogger/commit.yaml?branch=main&logo=github" alt="Actions Status">
+  </a>
+  <a href="https://github.com/krystal/klogger/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/krystal/klogger.svg?style=flat" alt="License Status">
+  </a>
+</p>
+
+Klogger is an opinionated logger for Ruby applications to allow consistent and structured logging.
+
+- Output can be sent to STDOUT or a file. The logger is backed by the standard Ruby `Logger` class.
+- Ouput can be presented in various formats.
+- Output can be highlighted with appropriate colours based on severity (optional).
+- Additional destinations can easily be added for shipping log data to other services.
+
+## Installation
+
+Add the gem to your Gemfile.
+
+```ruby
+gem "klogger-logger", '~> 1.1'
+```
+
+## Usage
+
+This shows some typical usage of the logger along with example output. The `Klogger::Logger` instance will output to STDOUT by default but can be redirectly.
+
+### Setting up a logger
+
+To begin, you need an instance of your logger. Loggers are thread-safe so you can use a single instance across multiple classes and requests. There are a few options that you can control about a logger. These are documented below.
+
+```ruby
+# The most basic logger includes a name and nothing else. This will log to STDOUT and use
+# the default formatter without colouring.
+Klogger.new(name)
+
+# You can customise where log output goes using the destination argument. You can provide a device
+# that response to write & close or a path to a file. The same as Ruby's logger class.
+Klogger.new(name, destination: $stderr)
+Klogger.new(name, destination: 'log/events.log')
+Klogger.new(name, destination: StringIO.new)
+
+# To customise the formatting of the log output, you can provide a formatter.
+Klogger.new(name, formatter: :json)
+Klogger.new(name, formatter: :simple)
+Klogger.new(name, formatter: :go)
+
+# You can also enable colouring/highlighting.
+Klogger.new(name, highlight: true)
+Klogger.new(name, highlight: Rails.env.development?)
+
+# You can add tags to be included in all log lines for this logger.
+Klogger.new(name, tags: { app: 'example-app' })
+```
+
+### Logging
+
+When you want to log something, you have the option of 5 severities (`debug`, `info`, `warn`, `error` and `fatal`). For this example, we'll use `info` but it is interchangable with any of the other severities.
+
+```ruby
+# The most basic way to log is to provide a message.
+logger.info("Hello world!")
+
+# To add additional tags to the line, you can do so by passing a hash.
+logger.info("Sending e-mail", recipient: "adam@example.com", subject: "Hello world!")
+
+# The message is optional and you can just pass a hash too
+logger.info(ip_address: "1.2.3.4", method: "POST", path: "/login")
+
+# Blocks can also be passed to the logger to log the result of that block
+logger.info { "Hello world!" }
+logger.info('Result of 1 + 1') { 1 + 1 } # Logs with a message of "Result: 2"
+```
+
+### Loggging exceptions
+
+Exceptions happen and when they do, you want to know about them. Klogger provides a helper method to log exceptions. These will automatically be logged with the `error` severity.
+
+```ruby
+begin
+  # Do somethign bad
+rescue => e
+  # Just log the exception
+  logger.exception(e)
+
+  # You can also provide a message
+  logger.exception(e, "Something went wrong")
+
+  # You can also provide a hash of additional tags
+  logger.exception(e, "Something went wrong", tags: { user_id: 123 })
+end
+```
+
+### Groups
+
+Groups allow you to group related log entries together. They do two things:
+
+1. They allow you to add tags to all logs which are within the group
+2. They assign a random ID to the group which is included with all logs within the group
+
+Here's an example of how they work.
+
+```ruby
+# In this example, both log entries within the block will be tagged with the `url` tag from the group.
+logger.group(url: "https://example.com/my-files.zip") do # 92b1b62c
+  logger.info("Download starting")
+  file = download_file('...')
+  logger.info("Download complete", size: file.size)
+end
+```
+
+You'll notice in that example the comment `92b1b62c`. This is the group ID for this block. This is a random ID which is generated when the group is created. It is included with all logs within the group thus allowing you to search for that reference to find all logs related to that group. If groups are nested, you'll have multiple IDs. By default, these group IDs are not shown in your output.
+
+```ruby
+# If you wish for group IDs to be included in your output, you can enable that in the logger
+Klogger.new(name, include_group_ids: true)
+```
+
+When executed like this groups will only apply to the logger in question. If you want to group messages from different loggers, you can use the `Klogger.group` method where groups and their data will apply to all Klogger loggers.
+
+```ruby
+logger1 = Klogger.new(:logger1)
+logger2 = Klogger.new(:logger2)
+Klogger.group(ip: '1.2.3.4') do
+  logger1.info('Hello world!') # will be tagged with ip=1.2.3.4
+  Klogger.group(user: 'user_abcdef')
+    logger2.info('Example') # will be tagged with ip=1.2.3.4 and user=user_abcdef
+  end
+end
+
+# If you can't use a block you can manually open and close a group but you'll need to be sure to close it
+# when you're finished.
+group_id = Klogger.global_groups.add(ip: '1.2.3.4')
+# ... do anything that you want - everything will be tagged as appropriate
+Klogger.global_groups.pop
+```
+
+Finally, you can use groups without IDs to simply add tags to all logs within the group using the `tagged` method.
+
+```ruby
+logger.tagged(name: 'steve') do
+  logger.info("Download starting")
+end
+```
+
+### Silencing
+
+Sometimes you don't want to log for a little while. You can use the `silence` method to temporarily disable logging.
+
+```ruby
+# Calling this will silence the logs until you unsilence again
+logger.silence!
+logger.unsilence!
+
+# Alternative, you can use the block option which will unsilence when complete.
+logger.silence! do
+  # Logs will be silenced here
+end
+```
+
+### Sending log data elsewhere
+
+In many cases you won't want to keep your log data on a local disk or within STDOUT. You can use this additional option to have data dispatched automatically to other services which you decide upon.
+
+```ruby
+# This is just an example class. You can create whatever class you want here and it'll be called
+# with the call method.
+class GraylogDestination
+
+  def initialize(host, port)
+    @notifier = GELF::Notifier.new(host, port)
+  end
+
+  def call(logger, payload, group_ids)
+    message = payload.delete(:message)
+    @notifer.notify!(facility: "my-app", short_message: message, group_ids: group_ids, **payload)
+  end
+
+end
+
+# Create a logger and add the destination
+logger = Klogger.new(name)
+logger.add_destination(GraylogDestination.new('graylog.example.com', 12201))
+```

data/VERSION

@@ -0,0 +1 @@
+1.3.2

data/lib/klogger/logger.rb

@@ -2,11 +2,14 @@
 
 require 'logger'
 require 'securerandom'
+
+require 'concurrent/atomic/thread_local_var'
+
 require 'klogger/formatters/json'
 require 'klogger/formatters/simple'
 require 'klogger/formatters/go'
-require 'concurrent/atomic/thread_local_var'
 require 'klogger/group_set'
+require 'klogger/version'
 
 module Klogger
   class Logger < ::Logger
@@ -35,10 +38,14 @@ module Klogger
     end
 
     def exception(exception, message = nil, **tags)
-      error({ message: message,
-              exception: exception.class.name,
-              exception_message: exception.message,
-              backtrace: exception.backtrace[0, 4].join("\n") }.merge(tags))
+      error(
+        **{
+          message: message,
+          exception: exception.class.name,
+          exception_message: exception.message,
+          backtrace: exception.backtrace[0, 4].join("\n")
+        }.merge(tags)
+      )
     end
 
     LEVELS.each do |level|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: klogger-logger
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.2
 platform: ruby
 authors:
 - Adam Cooke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-03-10 00:00:00.000000000 Z
+date: 2023-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -71,6 +71,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
+- README.md
+- VERSION
 - lib/klogger-logger.rb
 - lib/klogger.rb
 - lib/klogger/colors.rb