ons-json-logger 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 759ed29d813c6ac95eb31020797758b86b81eb1ac22e5139cda8f3fa3b107794
+  data.tar.gz: 03c07936733e47cb2863d880a27855a0ede25adcf9a09a6895429590302544f1
+SHA512:
+  metadata.gz: 7043230cc29dab6ecab1915536eb8874527196d8cddba9d93ad177f07814bcf3dc9b1502f1c01e17e58ea09d92520d214718df2c96d9f4657cb35926da591e61
+  data.tar.gz: 7099ba5e33de14fba486d998e387575c4de4848eb0da3229d71ef2a0bab9c0c036b58833510dc653778b5e8d6097fb522901055b91d20dc7876c66c8cfd56fdf

data/README.md

@@ -0,0 +1,37 @@
+# ONS JSON Logger RubyGem
+A utility class for generating structured JSON log entries with optional additional fields suitable for web applications. Note that this gem targets Ruby 3.1 and above.
+
+## Installation
+```
+gem install ons-json-logger
+```
+
+## Examples
+
+```ruby
+require 'logger'
+require 'ons-json-logger'
+require 'sinatra'
+
+LOGGER      = Logger.new($stdout)
+JSON_LOGGER = JSONLogger.new(application: 'amazing-webapp', environment: 'production')
+
+get '/signout' do
+  LOGGER.info(JSON_LOGGER.log(level: 'INFO',
+                              message: 'User signed out',
+                              module_name: 'app',
+                              user: { id: @user_login_id, ip_address: @client_ip },
+                              http: { method: 'GET', path: '/signout', status: 200, user_agent: request.user_agent }))
+end
+```
+
+## Testing
+```
+rake test
+```
+
+## Licence
+This library is licensed under the MIT licence. Full licence text is available in [LICENCE](LICENCE).
+
+## Copyright
+Copyright (C) 2024 Crown Copyright (Office for National Statistics)

data/lib/ons-json-logger/json_logger.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+# Class that generates structured JSON log entries.
+class JSONLogger
+  # Constructor that initialises the JSON logger.
+  #
+  # @param application [String] the name of the application
+  # @param environment [String] the name of the environment the application is deployed to. Defaults to +development+
+  # @raise [ArgumentError] if application is nil
+  def initialize(application:, environment: 'development')
+    raise ArgumentError, 'application cannot be nil' if application.nil?
+
+    @application = application
+    @environment = environment
+  end
+
+  # Returns a structured JSON log entry from the passed arguments.
+  #
+  # @param level the log level e.g. +DEBUG+, +ERROR+, +INFO+
+  # @param message the log message
+  # @param module_name the name of the application module/component generating the log message
+  # user optional Hash containing details of the user making the request such as username and IP address
+  # http optional Hash containing details of the HTTP request such as the method, path, status code and user agent
+  # error optional Hash containing details of an error that occurred such as the error code and message
+  # @raise [ArgumentError] if level is nil
+  # @raise [ArgumentError] id message is nil
+  # @raise [ArgumentError] if module_name is nil
+  def log(level:, message:, module_name:, user: {}, http: {}, error: {})
+    raise ArgumentError, 'level cannot be nil' if level.nil?
+    raise ArgumentError, 'message' if level.nil?
+    raise ArgumentError, 'module_name cannot be nil' if level.nil?
+
+    log_entry = {
+      timestamp: Time.now.utc.iso8601,
+      level:,
+      message:,
+      application: @application,
+      environment: @environment,
+      module: module_name
+    }
+
+    # Add optional fields if they are provided.
+    log_entry[:user]  = user unless user.empty?
+    log_entry[:http]  = http unless http.empty?
+    log_entry[:error] = error unless error.empty?
+
+    JSON.generate(log_entry)
+  end
+end

data/lib/ons-json-logger/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ONSJSONLogger
+  module Version
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 0
+  end
+  VERSION = [Version::MAJOR, Version::MINOR, Version::TINY].compact * '.'
+end

data/lib/ons-json-logger.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ons-json-logger/json_logger'

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: ons-json-logger
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- John Topley
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-01-04 00:00:00.000000000 Z
+dependencies: []
+description: 'A utility class for generating structured JSON log entries with optional
+  additional fields suitable for web applications.
+
+  '
+email:
+- john.topley@ons.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ons-json-logger.rb
+- lib/ons-json-logger/json_logger.rb
+- lib/ons-json-logger/version.rb
+homepage: https://github.com/ONSdigital/ons-json-logger
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.15
+signing_key:
+specification_version: 4
+summary: A class for generating structured JSON log entries.
+test_files: []