simple_structured_logger 0.1.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd3c01ed526e586a28acf3c9dcc9c3d8220bea4547c264568cf32c4293c9a77c
-  data.tar.gz: dc3beaa6509ca46fb2be4405e6211b75b373f87221dca5f7ba66e25ed723c4a2
+  metadata.gz: 824ec497606b6c639fdc7209c9854243512457bb7b97bc3ae3b6300354f85916
+  data.tar.gz: 56bdbf5858c33164a08ec88ee96cb0842c8f11a2caeef1123af14f3a2b0a73f7
 SHA512:
-  metadata.gz: 9a1a5ba635be779a15ea83a4d17d8e71af96f0dc5cc0324bc2ac83af8e76fb959047d236b9e1191990481dfeaaf390469c0b737bfbc532f3bc24fe4979cdf636
-  data.tar.gz: 94830ac9e6452c82183564f9a67e58560d9eacd617a7aea1d69c1d291ffc4187da7726c386895361f78da3e1faa4f020c12c452ac4b01e639c1cbf06bf13a1c2
+  metadata.gz: 8296498d2355f715ccc7a8b089f3129ed39688ebb8503e940f1b729d18d754142878524c48f3ab9cc8221910be0ea6200259ad9c1b1d4fa994f8e2dcab363ad2
+  data.tar.gz: 384a55748e300dcc7903be2609094af12fd88a4e2d3c58abf5646fb819314e9cb68b034c25890c2562355fe26babcd89fc422d617fd3373dff255ff0dc6b9ab9

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,59 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master ]
+  schedule:
+    - cron: '24 16 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

data/.github/workflows/ruby.yml

@@ -19,15 +19,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0']
+        ruby-version: ['2.6', '2.7', '3.0', '3.1']
 
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby
-      uses: ruby/setup-ruby@v1      
+      uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true
     - name: Run tests
       run: bundle exec rake
- 
+

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 /vendor/bundle
+/*.gem

data/.tool-versions

@@ -1 +1 @@
-ruby 2.7.3
+ruby 3.1.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Michael Bianco
+
+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

@@ -3,23 +3,107 @@
 
 # SimpleStructuredLogger
 
-Dead-simple structured logging in ruby with a dead-simple codebase. That's it.
+Dead-simple structured logging in ruby with a dead-simple codebase. No dependencies, everything logs to stdout, and simple hooks to customize. That's it.
 
 ```ruby
 gem 'simple_structured_logger'
 ```
 
+## Usage
+
+You can use this logger anywhere. Class methods, instance methods, use it as a logger for libraries, etc.
+
+Some examples:
+
+```ruby
+# in a console or simple script
+include SimpleStructuredLogger
+log.info 'core message', key: Time.now.to_i
+
+# in class & instance methods
+class LoggingInModule
+  include SimpleStructuredLogger
+
+  def self.log_something
+    log.info 'including the module enables a class and instance method', key: Time.now.to_i
+  end
+
+  def log_something_else
+    log.info 'the class and instance method share the same logging context', key: Time.now.to_i
+  end
+end
+
+# So, how do I set the context? How can I customize how it's set?
+SimpleStructuredLogger.configure do
+  expand_context do |context|
+    # you can pass in a object and use `expand_context` to extract the relevant keys
+    if context[:user]
+      context[:user_id] = context[:user].id
+      context[:user_name] = context[:user].name
+    end
+
+    context
+  end
+end
+
+class ExampleJob
+  def perform(user_id)
+    user = get_user(user_id, job_argument)
+    log.set_context(user: user, job: self.class, job_argument: job_argument)
+    log.info 'the log will contain the user_id, job_argument, and job class'
+
+    # you can also add additional default pairs without resetting context
+    log.default_tags[:something] = 'else'
+  end
+end
+
+# Can you pass object arguments as values and automatically expand them? Well, yes, you can!
+SimpleStructuredLogger.configure do
+  expand_log do |tags, default_tags|
+    if tags[:stripe_resource] && tags[:stripe_resource].respond_to?(:id)
+      stripe_resource = tags.delete(:stripe_resource)
+      tags[:stripe_resource_id] = stripe_resource.id
+      tags[:stripe_resource_type] = stripe_resource.class.to_s
+    end
+
+    # this is a really nice pattern I like to use. The `metric` key can trigger a call out to your observability tooling
+    if tags[:metric]
+      dimensions = default_tags.slice(:stripe_user_id, :other_default_tag)
+      metrics.track_counter(tags[:metric], dimensions: dimensions)
+    end
+
+    tags
+  end
+end
+
+# want simple formatting? You got it!
+SimpleStructuredLogger.logger.formatter = proc do |severity, _datetime, _progname, msg|
+  "#{severity}: #{msg}\n"
+end
+
+# Configure the logger directly if you need to
+SimpleStructuredLogger.logger.level(Logger::INFO)
+```
+
+Want to change the log level quickly? Without modifying source?
+
+```shell
+LOG_LEVEL=DEBUG ruby your_script.rb
+
+# case does not matter
+LOG_LEVEL=info ruby your_script.rb
+```
+
 ## Design Goals
 
 * Extremely simple codebase that's easy to read and override
-* Structured logging that reads nicely
+* Structured logging that reads nicely and is easy to filter using grep or something like Papertrail
 * Ability to easily set context, and expand context with user-configurable hook
 * Ability to easily add structured log pre-processing. I want to be able to pass
-  in an object specific to my application and for the relavent important keys to
+  in an object specific to my application and for the relevant important keys to
   be expanded automatically.
 * `Rails.logger = SimpleStructuredLogger.new(STDOUT)`
-* Not designed around massive systems or scale
-* Don't support multiple log destinations
+* Not designed around massive systems or scale: no JSON logging, multiple log destinations, and other fanciness.
 * Don't build in fancy pre-processing for errors or other common ruby objects
 
 ### Opinionated Devops Setup
@@ -37,6 +121,10 @@ gem 'simple_structured_logger'
 * https://github.com/nishidayuya/structured_logger
 * https://github.com/rocketjob/semantic_logger
 
+## Related
+
+* https://github.com/roidrage/lograge
+
 ## Why is structured logging important?
 
 * https://engineering.linkedin.com/distributed-systems/log-what-every-software-engineer-should-know-about-real-time-datas-unifying
@@ -45,33 +133,14 @@ gem 'simple_structured_logger'
 ## What about Rail's tagged logging?
 
 Tagged logging is not structured logging. I want to be able to search through
-PaperTrail and easily grab an audit trail for a specific context, i.e. `the_job=FailingJob the_user=1`.
-
-## Usage
-
-```ruby
-# config/initializers/logger.rb
-if Rails.env.development? || Rails.env.test?
-  SimpleStructuredLogger::Writer.instance.logger = Rails.logger
-end
-
-# models/order.rb
-class Order
-  include SimpleStructuredLogger
-
-  def initialize
-    log.reset_context!
-    log.default_tags[:global] = 'key'
-  end
-
-  def do_something
-    log.info 'simple structured logging', key: value, shopify_id: 123
-  end
-end
-```
+PaperTrail/Splunk/etc and easily grab an audit trail for a specific context, i.e. `the_job=FailingJob the_user=1`.
 
 ## Testing
 
 ```
 bundle exec rake
 ```
+
+## TODO
+
+- [ ] Support logs as blocks?

data/lib/simple_structured_logger.rb

@@ -2,6 +2,14 @@ require 'logger'
 require 'singleton'
 
 module SimpleStructuredLogger
+  def self.configure(&block)
+    SimpleStructuredLogger::Configuration.instance_eval(&block)
+  end
+
+  def self.logger
+    SimpleStructuredLogger::Writer.instance.logger
+  end
+
   def log
     SimpleStructuredLogger::Writer.instance
   end
@@ -13,25 +21,27 @@ module SimpleStructuredLogger
         SimpleStructuredLogger::Writer.instance
       end
     end
-
   end
 
   module Configuration
     extend self
 
+    @expand_context = nil
+    @expand_log = nil
+
     def expand_context(&block)
       if block.nil?
-        @expand_context = block
-      else
         @expand_context
+      else
+        @expand_context = block
       end
     end
 
     def expand_log(&block)
       if block.nil?
-        @expand_log = block
-      else
         @expand_log
+      else
+        @expand_log = block
       end
     end
   end
@@ -44,6 +54,16 @@ module SimpleStructuredLogger
     def initialize
       @logger = ::Logger.new(STDOUT)
       @default_tags = {}
+
+      set_log_level_from_environment
+    end
+
+    def set_log_level_from_environment
+      env_log_level = ENV['LOG_LEVEL']
+
+      if !env_log_level.nil? && Logger::Severity.const_defined?(env_log_level.upcase)
+        @logger.level = Logger::Severity.const_get(env_log_level.upcase)
+      end
     end
 
     def reset_context!
@@ -53,8 +73,8 @@ module SimpleStructuredLogger
     def set_context(context)
       reset_context!
 
-      if self.respond_to?(:expand_context)
-        context = self.expand_context(context)
+      if SimpleStructuredLogger::Configuration.expand_context
+        context = SimpleStructuredLogger::Configuration.expand_context.call(context)
       end
 
       @default_tags.merge!(context)
@@ -73,26 +93,18 @@ module SimpleStructuredLogger
     end
 
     def warn(msg, opts={})
-      # TODO consider returning the generated log string with structured keys
-
       @logger.warn("#{msg}: #{stringify_tags(opts)}")
     end
 
-    private
+    private def stringify_tags(additional_tags)
+      additional_tags = additional_tags.dup
 
-      def generate_log(msg, opts)
-        #code
+      if SimpleStructuredLogger::Configuration.expand_log
+        additional_tags = SimpleStructuredLogger::Configuration.expand_log.call(additional_tags, self.default_tags)
       end
 
-      def stringify_tags(additional_tags)
-        additional_tags = additional_tags.dup
-
-        if self.respond_to?(:expand_log)
-          additional_tags = self.expand_log(additional_tags)
-        end
-
-        @default_tags.merge(additional_tags).map { |k,v| "#{k}=#{v}" }.join(' ')
-      end
+      @default_tags.merge(additional_tags).map {|k, v| "#{k}=#{v}" }.join(' ')
+    end
 
   end
 end

data/simple_structured_logger.gemspec

@@ -4,20 +4,19 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "simple_structured_logger"
-  spec.version       = '0.1.5'
+  spec.version       = '1.0.0'
   spec.authors       = ["Michael Bianco"]
   spec.email         = ["mike@mikebian.co"]
+  spec.licenses      = ['MIT']
 
-  spec.summary       = "Dead-simple structured logging in ruby with a simple codebase."
-  # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.summary       = "Dead-simple structured logging in ruby with a simple codebase"
   spec.homepage      = "https://github.com/iloveitaly/simple_structured_logger"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.2.15"
-  spec.add_development_dependency "rake", "~> 12.3.3"
-  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "bundler", "~> 2.3.10"
+  spec.add_development_dependency "rake", "~> 13.0.6"
+  spec.add_development_dependency "minitest", "~> 5.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_structured_logger
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 1.0.0
 platform: ruby
 authors:
 - Michael Bianco
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2021-05-05 00:00:00.000000000 Z
+date: 2022-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,54 +16,58 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.15
+        version: 2.3.10
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.2.15
+        version: 2.3.10
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: 13.0.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: 13.0.6
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.15'
 description:
 email:
 - mike@mikebian.co
-executables: []
+executables:
+- console
+- setup
 extensions: []
 extra_rdoc_files: []
 files:
 - ".github/dependabot.yml"
+- ".github/workflows/codeql-analysis.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".tool-versions"
 - Gemfile
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
@@ -71,7 +75,8 @@ files:
 - lib/simple_structured_logger.rb
 - simple_structured_logger.gemspec
 homepage: https://github.com/iloveitaly/simple_structured_logger
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -88,8 +93,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Dead-simple structured logging in ruby with a simple codebase.
+summary: Dead-simple structured logging in ruby with a simple codebase
 test_files: []