json_tagged_logger 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d9b6a0f1e36ce3cc9e4bc89ea942c6ecea3868d240f58230604c30c954232a2
-  data.tar.gz: 10acc0b50c43dd4d938920a315e11aad21b860022397f4e36273e98f3f4d9192
+  metadata.gz: 5d6a91dae71312da17de8ad46580f46a3a5d7c6c20d8e1444107734cb7775c49
+  data.tar.gz: 159b9a61bf557b8324c2d1c1f3dd03e4fc2f37625996046e7de29fd2b2f05a0f
 SHA512:
-  metadata.gz: 19ee0ae1fa6341aafb6443c21d805e6e787e7bcd5f8e7447a42a38b428925f47a88b101025e3beef34e2db1b74c968ce2ff819374897c8d2d848253cbb9c27c3
-  data.tar.gz: c5697f900381e3d33862b1ff750385ea4feb7a8e05723f719c1b3853a09f7d1336ae7a332caf3fa8b9684c3482019b2bfb319a4cd7ef9b35a5b9a1737addc9f9
+  metadata.gz: 43d1c8b1d1905f04271bdb538618e4b24d6b1eefc1d2864d01c38949ae5b1f6dcfccc0af60254136667cef7dd345becf52cf65169030818f911d4d56c7abdf4f
+  data.tar.gz: 06fd82f28251e33f49a31273d415f76d4d9a5b1fc085b05a707722b3be9046f96148731f64324c9a44f6cbc86c2a3769d44652c893713f7fd4553173e35df1d9

data/README.md

@@ -1,89 +1,139 @@
 # JsonTaggedLogger
 
-JsonTaggedLogger provides a log formatter that works in conjunction with ActiveSupport::TaggedLogging to product JSON-formatted log output.
+`JsonTaggedLogger` works in conjunction with [`ActiveSupport::TaggedLogging`](https://api.rubyonrails.org/classes/ActiveSupport/TaggedLogging.html) and (optionally) [Lograge](https://github.com/roidrage/lograge) to produce JSON-formatted log output. By itself, `ActiveSupport::TaggedLogging` supports simple tagging. With `JsonTaggedLogger`, you can compose key/value pairs, simple tags, and the log message itself into a single JSON document for easy consumption and parsing in log aggregators.
 
+## Usage
+
+Given the following configuration,
 
 ```ruby
 # Gemfile
 gem 'json_tagged_logger'
+gem 'lograge' # since you probably want all your request logs in JSON
 
 # config/environments/production.rb
 Rails.application.configure do
-	# …
-	config.log_tags = JsonTaggedLogger::LogTagsConfig.generate(:request_id, :host, ->(request) { { example: "proc" }.to_json })
-	logger = ActiveSupport::Logger.new(STDOUT)
-	config.logger = JsonTaggedLogger::Logger.new(logger)
-	# …
+  # …
+  config.log_tags = JsonTaggedLogger::LogTagsConfig.generate(
+    :request_id,
+    :host,
+    ->(request) { { my_param: request.query_parameters["my_param"] }.to_json },
+    JsonTaggedLogger::TagFromSession.get(:user_id),
+    JsonTaggedLogger::TagFromHeaders.get(:my_custom_header, "X-Custom-Header"),
+  )
+
+  logger = ActiveSupport::Logger.new(STDOUT)
+  config.logger = JsonTaggedLogger::Logger.new(logger)
+
+  config.lograge.enabled = true
+  config.lograge.formatter = Lograge::Formatters::Json.new
+  # …
 end
-
 ```
 
-
-## Why?
-
-On its own, ActiveSupport::TaggedLogging adds individual tags wrapped in squre brackets at the start of each line of log output, like so
+A request like
 
 ```
-[tag1] [tag2] : Foo bar
+curl -H "X-Custom-Header: some header value" 'http://127.0.0.1:3000/?my_param=param%20value'
 ```
 
-This is fine as far as it goes, but if you wish to use tagged logging with something like [Lograge](https://github.com/roidrage/lograge) to format your logs as JSON, there's no good way to get the tags into that json output, specially if any of your tags are generated by procs.
-
-## How does it work?
+will get you something like
 
-First, JsonTaggedLogger::LogTags helps you generate an array lof log tags suitable for passing to Rails.application.config.log_tags to produce JSON logs. For example, given
-
-```
-Rails.application.config.log_tags = JsonTaggedLogger::LogTags.generate_config(:request_id, :host)
+```json
+{
+  "level": "INFO",
+  "request_id": "914f6104-538d-4ddc-beef-37bfe06ca1c7",
+  "host": "127.0.0.1",
+  "my_param": "param value",
+  "user_id": "99",
+  "my_custom_header": "some header value",
+  "method": "GET",
+  "path": "/",
+  "format": "*/*",
+  "controller": "SessionsController",
+  "action": "new",
+  "status": 302,
+  "duration": 0.51,
+  "view": 0,
+  "db": 0,
+  "location": "http://127.0.0.1:3000/profile"
+}
 ```
 
-ActiveSupport::TaggedLogging will see the following log tags
+[Note: I've pretty-printed the output in these examples for easier reading. The actual log output will be on a single line without extra whitespace.]
 
-```
-[
-  -> (request) { { request_id: request.send(:request_id) }.to_json },
-  -> (request) { { host: request.send(:host) }.to_json }
-]
+Importantly, if the controller action (or any code it calls along the way) has an explicit call to `Rails.logger.tagged("TAG").info("tagged log message")`, you'll get the same key/value tags (`request_id`, `host`, `my_param`, &c.) in the JSON document along with a `tags` key:
+
+```json
+{
+  "level": "INFO",
+  "request_id": "914f6104-538d-4ddc-beef-37bfe06ca1c7",
+  "host": "127.0.0.1",
+  "my_param": "param value",
+  "user_id": "99",
+  "my_custom_header": "some header value",
+  "tags": [
+    "TAG"
+  ],
+  "msg": "tagged log message"
+}
 ```
 
-Why is this an improvement over `Rails.application.config.log_tags = [:request_id, :host]`? Well, with the JsonTaggedLogger version, your logs will now contain
+If you have nested calls to the tagged logger, like
+
+```ruby
+Rails.logger.tagged("TAG") do
+  Rails.logger.tagged("NESTED").info("nested tagged log message")
+end
 
-```
-[{"request_id":"c31c3658-5b76-40cd-b583-d0fcbdee0710"}] [{"host":"127.0.0.1"}] log message
 ```
 
-which `JsonTaggedLogger::Formatter` will turn into
+those will be added to the `tags` key in the JSON document
 
 ```json
-{"request_id":"c31c3658-5b76-40cd-b583-d0fcbdee0710","host":"127.0.0.1","msg":"log message"}
+{
+  "level": "INFO",
+  "request_id": "914f6104-538d-4ddc-beef-37bfe06ca1c7",
+  "host": "127.0.0.1",
+  "my_param": "param value",
+  "user_id": "99",
+  "my_custom_header": "some header value",
+  "tags": [
+    "TAG",
+    "NESTED"
+  ],
+  "msg": "nested tagged log message"
+}
 ```
 
-Lovely, eh?
+## Why?
 
-The real advantage comes when you have more complicated procs that generage your log tags. So long as your proc produces a JSON string, `JsonTaggedLogger::Formatter` will be able to extract it from the tag and add it to the log hash.
+On its own, `ActiveSupport::TaggedLogging` adds individual tags wrapped in squre brackets at the start of each line of log output. A configuration like
 
 ```ruby
-class UserInfoLogTag
-  def self.user_info
-		lambda do |request|
-		  user_info = build_user_info_from_session(request) # build user info from request by inspecting session, etc
-			{ user_info: user_info }.to_json
-		end
-  end
-
-	private
-
-	def self.build_user_info_from_session(request)
-	  # left as an exercise for the reader
-	end
+Rails.application.configure do
+  # …
+  config.log_tags = [ :request_id, :host, ->(request) { request.query_parameters["my_param"] } ]
+  logger = ActiveSupport::Logger.new(STDOUT)
+  config.logger = ActiveSupport::TaggedLogging.new(logger)
+  # …
 end
-
-Rails.application.config.log_tags = [ :request_id, :host, UserInfoLogTag.user_info ]
 ```
 
-That will get you
+will get you logs like
 
 ```
-{"request_id":"c31c3658-5b76-40cd-b583-d0fcbdee0710","host":"127.0.0.1","user_info":{"user_id":"1234","user_email":"user@example.com"},"msg":"log message"}
+[22a03298-5fd9-4b28-bbe2-1d4c0d7f74f0] [127.0.0.1] [param value] Started GET "/?my_param=param%20value" for 127.0.0.1 at 2023-01-15 00:13:21 -0500
+[22a03298-5fd9-4b28-bbe2-1d4c0d7f74f0] [127.0.0.1] [param value] Processing by SessionsController#new as */*
+[22a03298-5fd9-4b28-bbe2-1d4c0d7f74f0] [127.0.0.1] [param value]   Parameters: {"my_param"=>"param value"}
+[22a03298-5fd9-4b28-bbe2-1d4c0d7f74f0] [127.0.0.1] [param value] [TAG] [NESTED] nested tagged log message
+[22a03298-5fd9-4b28-bbe2-1d4c0d7f74f0] [127.0.0.1] [param value] Redirected to http://127.0.0.1:3000/sign_in
+[22a03298-5fd9-4b28-bbe2-1d4c0d7f74f0] [127.0.0.1] [param value] Completed 302 Found in 1ms (ActiveRecord: 0.0ms | Allocations: 1070)
 ```
 
+This is fine as far as it goes, but if you use tagged logging with something like [Lograge](https://github.com/roidrage/lograge) to format your request logs as JSON, the list of square-bracketed tags will still just be prepended to the log line, followed by the JSON. Also, any calls to `Rails.logger.tagged` will be logged as plain text:
+
+```
+[d4fac896-f916-48d7-9d32-d35a39cfb7d8] [127.0.0.1] [param value] [TAG] [NESTED] nested tagged log message
+[d4fac896-f916-48d7-9d32-d35a39cfb7d8] [127.0.0.1] [param value] {"method":"GET","path":"/","format":"*/*","controller":"SessionsController","action":"new","status":302,"duration":1.2,"view":0.0,"db":0.0,"location":"http://127.0.0.1:3000/sign_in"}
+```

data/lib/json_tagged_logger/tag_from_headers.rb

@@ -0,0 +1,9 @@
+module JsonTaggedLogger
+  module TagFromHeaders
+    def self.get(log_label, header_key)
+      lambda do |request|
+        { log_label => request.headers[header_key] }.to_json
+      end
+    end
+  end
+end

data/lib/json_tagged_logger/tag_from_session.rb

@@ -1,8 +1,8 @@
 module JsonTaggedLogger
   module TagFromSession
-    def self.get(key)
+    def self.get(log_label, session_key = log_label)
       lambda do |request|
-        { key => get_value_from_session(request, key) }.to_json
+        { log_label => get_value_from_session(request, session_key) }.to_json
       end
     end
 

data/lib/json_tagged_logger/version.rb

@@ -1,3 +1,3 @@
 module JsonTaggedLogger
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/json_tagged_logger.rb

@@ -1,4 +1,5 @@
 require 'json_tagged_logger/formatter'
 require 'json_tagged_logger/log_tags_config'
 require 'json_tagged_logger/logger'
+require 'json_tagged_logger/tag_from_headers'
 require 'json_tagged_logger/tag_from_session'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_tagged_logger
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Sean Santry
@@ -23,6 +23,7 @@ files:
 - lib/json_tagged_logger/formatter.rb
 - lib/json_tagged_logger/log_tags_config.rb
 - lib/json_tagged_logger/logger.rb
+- lib/json_tagged_logger/tag_from_headers.rb
 - lib/json_tagged_logger/tag_from_session.rb
 - lib/json_tagged_logger/version.rb
 homepage: https://github.com/santry/json_tagged_logger