console 1.29.2 → 1.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60457e10e6e444b206349262e1a13a45d2da0fa1aad7ecfa48f22e4b48e44eb8
-  data.tar.gz: 2b9bc10d6e5981286f93fd573e4ca7afad7aa1da9399ec4e8f4f643e38afcc0c
+  metadata.gz: 749f01df7fec2a4868a2b4958b23ee328ddb2911b0fc2a635bdf298d901cae60
+  data.tar.gz: 32daa46920a77f0fa713685d0176dc24ed034fe39fe99cde3d1d789ecfb1c48b
 SHA512:
-  metadata.gz: 0a2554093f2fd42567a2cfa5924518a9e689e19394630a88af25d3e89f20a29250d12dc0a63216aa719b49c6dd957f28e79a8fead0a35103a2c5930794791273
-  data.tar.gz: 003a9d78b6d2835b63f202dcbf3d95618339b04a1f363e07b40a6502008be14b0a85a09b114a85d9b136083e8ce9fa4334371c1ba0fe53161d299e2f7cee4da6
+  metadata.gz: 51796e3366c0778f6e811428ff9e8aeffb0a34fe99ce0528488fd9931c392596c1a654f34e49781f68afd1377898ef16ce6aeaaa3a35c82c201bf4579f423073
+  data.tar.gz: 82af50570a7e55a26562cda15f7ccf5622bcc956ef6b6a065f4a1e38ecf663911f84ccf6a47de1443bc85f1b1e79effeec1fcbdccc21480c0b18b53872efdc13

data/context/command-line.md

@@ -0,0 +1,47 @@
+# Command Line
+
+This guide explains how the `console` gem can be controlled using environment variables.
+
+## Environment Variables
+
+The following program, `app.rb` will be used to explain the different environmet variables:
+
+~~~ ruby
+#!/usr/bin/env ruby
+
+require 'console'
+
+class MyApplication
+	def do_work
+		Console.logger.debug(self, "Doing some work.")
+	end
+end
+
+Console.logger.debug(self, "Creating the application.")
+application = MyApplication.new
+application.do_work
+~~~
+
+### `CONSOLE_LEVEL=debug`
+
+Control the default logger level. You can set it to any of the supported log levels: `debug`, `info`, `warn`, `error`, `fatal`.
+
+By default, the debug level is not enabled, but you can enable it using `CONSOLE_LEVEL=debug`:
+
+<pre>&gt; <font color="#00AFFF">CONSOLE_LEVEL</font><font color="#00A6B2">=</font><font color="#00AFFF">debug</font> <font color="#005FD7">./app.rb</font>
+<font color="#00AAAA">  0.0s    debug:</font> <b>Object</b> <font color="#717171">[oid=0x3c] [ec=0x50] [pid=990900] [2022-10-12 17:28:15 +1300]</font>
+               | Creating the application.
+<font color="#00AAAA">  0.0s    debug:</font> <b>MyApplication</b> <font color="#717171">[oid=0x64] [ec=0x50] [pid=990900] [2022-10-12 17:28:15 +1300]</font>
+               | Doing some work.
+</pre>
+
+### `CONSOLE_DEBUG=MyClass,MyModule::MyClass`
+
+Enable debug logging for the specified class names. You can specify one or more class names which will be resolved at runtime. This is specifically related to subject logging.
+
+By default, the debug level is not enabled, but you can enable it for the specific `MyApplication` class using `CONSOLE_DEBUG=MyApplication`:
+
+<pre>&gt; <font color="#00AFFF">CONSOLE_DEBUG</font><font color="#00A6B2">=</font><font color="#00AFFF">MyApplication</font> <font color="#005FD7">./app.rb</font>
+<font color="#00AAAA">  0.0s    debug:</font> <b>MyApplication</b> <font color="#717171">[oid=0x64] [ec=0x78] [pid=991855] [2022-10-12 17:30:56 +1300]</font>
+               | Doing some work.
+</pre>

data/context/configuration.md

@@ -0,0 +1,23 @@
+# Configuration
+
+This guide explains how to implement per-project configuration for the `console` gem.
+
+## Configuration File
+
+The `console` gem can load a configuration file, by default `config/console.rb`. This file is evaluated in an instance of {ruby Console::Config} which allows you to override methods that implement the default behaviour for a given project.
+
+Here is an example configuration file:
+
+```ruby
+# config/console.rb
+
+# Override the default log level
+def log_level
+	:debug
+end
+
+# Override the default output
+def make_output
+	Console::Output::Datadog.new(Console::Output::Default.new)
+end
+```

data/context/events.md

@@ -0,0 +1,71 @@
+# Events
+
+This guide explains how to log structured events with a well-defined schema.
+
+## Overview
+
+Logs often fall into two categories:
+
+- Free-form logs which include some structured data, but are primarily text-based and used for debugging or troubleshooting.
+- Structured logs which are designed to be machine-readable and can be used for monitoring, alerting, auditing and analytics.
+
+Events are a type of structured log which are designed to be machine-readable and have a well-defined schema. They are used to represent a specific occurrence within a system, such as a request, a response, an error, or a warning. You can create custom events to represent any structured data you like.
+
+## Core Concepts
+
+- {ruby Console::Event::Generic} is the base class for all events.
+- {ruby Console::Terminal::Formatter} includes a collection of formatters for rendering specific events in a human-readable format.
+
+## Emitting Events
+
+To emit an event, you can create an instance of a specific event class and call the `#emit` method. For example, to emit a failure event:
+
+```ruby
+def handle_request
+	begin
+		# ... user code ...
+	rescue => error
+		Console::Event::Failure.for(error).emit(self, "Failed to handle request!")
+	end
+end
+```
+
+This will emit a failure event with the error message and backtrace.
+
+### Emitting Events with Different Severity Levels
+
+Events can have different severity levels, such as `:info`, `:warn`, `:error`, and `:fatal`. You can specify the severity level when emitting an event:
+
+```ruby
+Console::Event::Failure.for(error).emit(self, "Failed to handle request!", severity: :debug)
+```
+
+## Custom Events
+
+You can create custom events by subclassing {ruby Console::Event::Generic} and defining the schema for the event. For example, to create a custom event for tracking user logins:
+
+```ruby
+class UserLoginEvent < Console::Event::Generic
+	def self.for(request, user)
+		self.new(user.id, request.ip)
+	end
+	
+	def new(id, ip)
+		@id = id
+		@ip = ip
+	end
+	
+	def to_hash
+		{
+			# Specifying a type field is recommended:
+			type: :login,
+			
+			# Custom fields:
+			id: @id,
+			ip: @ip
+		}
+	end
+end
+
+UserLoginEvent.for(request, user).emit(self, "User logged in.")
+```

data/context/getting-started.md

@@ -0,0 +1,170 @@
+# Getting Started
+
+This guide explains how to use `console` for logging.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add console
+~~~
+
+## Core Concepts
+
+`console` has several core concepts:
+
+- A log message which consists of a set of arguments and options, which includes a timestamp, severity, and other structured data.
+- The {ruby Console} module which provides an abstract interface for logging.
+- A {ruby Console::Logger} instance which is the main entry point for logging for a specific system and writes data to a given output formatter.
+- An output instance such as {ruby Console::XTerm}, {ruby Console::Serialized::Logger} which formats these log messages and writes them to a specific output device.
+- An event instance, such as {ruby Console::Event::Progress} or {ruby Console::Event::Spawn} which represents a structured event within a system, which can be formatted in a specific way.
+
+## Basic Logging
+
+Out of the box, {ruby Console}  provides a logger interface that outputs to the current terminal via `stderr`.
+
+~~~ ruby
+require 'console'
+
+Console.info("Hello World")
+~~~
+
+<pre>
+<font color="#00AA00">  0.0s     info:</font> <b>Hello World</b> <font color="#717171">[pid=219113] [2020-08-08 12:21:26 +1200]</font>
+</pre>
+
+The method name `info` indicates the severity level of the log message. You can filter out severity levels, and by default, `debug` messages are filtered out. Here are some examples of the different log levels:
+
+~~~ ruby
+require 'console'
+
+Console.debug("The input voltage has stabilized.")
+Console.info("Making a request to the machine.")
+Console.warn("The machine has detected a temperature anomaly.")
+Console.error("The machine was unable to complete the request!")
+Console.fatal("Depressurisation detected, evacuate the area!")
+~~~
+
+From the terminal, you can control the log level using the `CONSOLE_LEVEL` environment variable. To log all messages including `debug`:
+
+~~~ bash
+$ CONSOLE_LEVEL=debug ./machine
+~~~
+
+Alternatively to restrict log messages to warnings and above:
+
+~~~ bash
+$ CONSOLE_LEVEL=warn ./machine
+~~~
+
+If otherwise unspecified, Ruby's standard `$DEBUG` and `$VERBOSE` global variables will be checked and adjust the log level appropriately.
+
+## Metadata
+
+You can add any options you like to a log message and they will be included as part of the log output:
+
+~~~ ruby
+duration = measure{...}
+Console.info("Execution completed!", duration: duration)
+~~~
+
+## Subject Logging
+
+The first argument to the log statement becomes the implicit subject of the log message.
+
+~~~ ruby
+require 'console'
+
+class Machine
+	def initialize(voltage)
+		@voltage = voltage.floor
+		Console.info(self, "The input voltage has stabilized.")
+	end
+end
+
+Machine.new(5.5)
+~~~
+
+The given subject, in this case `self`, is used on the first line, along with associated metadata, while the message itself appears on subsequent lines:
+
+<pre>
+<font color="#00AA00">  0.0s     info:</font> <b>Machine</b> <font color="#717171">[oid=0x3c] [pid=219041] [2020-08-08 12:17:33 +1200]</font>
+               | The input voltage has stabilized.
+</pre>
+
+If you want to disable log messages which come from this particular class, you can execute your command:
+
+~~~ bash
+$ CONSOLE_FATAL=Machine ./machine
+~~~
+
+This will prevent any log message which has a subject of class `Machine` from logging messages of a severity less than `fatal`.
+
+## Exception Logging
+
+If your code has an unhandled exception, you may wish to log it. In order to log a full backtrace, you must log the subject followed by the exception.
+
+~~~ ruby
+require 'console'
+
+class Cache
+	def initialize
+		@entries = {}
+	end
+	
+	def fetch(key)
+		@entries.fetch(key)
+	rescue => error
+		Console.warn(self, "Cache fetch failure!", error)
+	end
+end
+
+Cache.new.fetch(:foo)
+~~~
+
+This will produce the following output:
+
+<pre><font color="#C01C28">  0.0s    error:</font> <b>Cache</b> <font color="#8B8A88">[oid=0x848] [ec=0x85c] [pid=571936] [2024-05-03 10:55:11 +1200]</font>
+               | Cache fetch failure!
+               |   <font color="#C01C28"><b>KeyError</b></font>: <b>key not found: :foo (</b><u style="text-decoration-style:solid"><b>KeyError</b></u><b>)</b>
+               |   → <font color="#C01C28">test.rb:15</font> in `fetch&apos;
+               |     <font color="#C01C28">test.rb:15</font> in `fetch&apos;
+               |     <font color="#C01C28">test.rb:21</font> in `&lt;top (required)&gt;&apos;
+</pre>
+
+## Program Structure
+
+Generally, programs should use the global `Console` interface to log messages.
+
+Individual classes should not be catching and logging exceptions. It makes for simpler code if this is handled in a few places near the top of your program. Exceptions should collect enough information such that logging them produces a detailed backtrace leading to the failure.
+
+### Multiple Outputs
+
+Use `Console::Split` to log to multiple destinations.
+
+``` ruby
+require "console"
+require "console/output/split"
+
+terminal = Console::Output::Terminal.new($stderr)
+serialized = Console::Output::Serialized.new(File.open("log.json", "a"))
+Console.logger = Console::Logger.new(Console::Output::Split[terminal, serialized])
+
+Console.info "I can go everywhere!"
+```
+
+### Custom Log Levels
+
+`Console::Filter` implements support for multiple log levels.
+
+``` ruby
+require "console"
+
+MyLogger = Console::Filter[noise: 0, stuff: 1, broken: 2]
+
+# verbose: true - log severity/name/pid etc.
+logger = MyLogger.new(Console.logger, name: "Java", verbose: true)
+
+logger.broken("It's so janky.")
+```

data/context/index.yaml

@@ -0,0 +1,28 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Beautiful logging for Ruby.
+metadata:
+  documentation_uri: https://socketry.github.io/console/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/console.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `console` for logging.
+- path: command-line.md
+  title: Command Line
+  description: This guide explains how the `console` gem can be controlled using environment
+    variables.
+- path: configuration.md
+  title: Configuration
+  description: This guide explains how to implement per-project configuration for
+    the `console` gem.
+- path: integration.md
+  title: Integration
+  description: This guide explains how to integrate the `console` output into different
+    systems.
+- path: events.md
+  title: Events
+  description: This guide explains how to log structured events with a well-defined
+    schema.

data/context/integration.md

@@ -0,0 +1,37 @@
+# Integration
+
+This guide explains how to integrate the `console` output into different systems.
+
+## Output Redirection
+
+The `console` is primarily an interface for logging, with a general purpose implementation which can log to a terminal (human readable) or a file (JSON by default). Output can also be augmented, redirected or manipulated by adding output wrappers. The output wrappers are generally configured using environment variables.
+
+### `Console::Output::Datadog`
+
+This output wrapper augments log messages with trace metadata so that the log messages can be correlated with spans. Note that the default output is still used `Console::Output::Default`.
+
+~~~ bash
+$ CONSOLE_OUTPUT='Console::Output::Datadog,Console::Output::Default' ./app.rb
+~~~
+
+The `Console::Output::Datadog` is a wrapper that augments the metadata of the log message with the `trace_id` and `span_id`.
+
+### Custom Output Wrapper
+
+It's straight forward to define your own output wrapper:
+
+~~~ ruby
+# Add a happy face to all log messages.
+class HappyLogger
+	def call(subject = nil, *arguments, **options, &block)
+		arguments << "😊"
+		
+		@output.call(subject, *arguments, **options, &block)
+	end
+end
+~~~
+
+## Adapters
+
+- [Console::Adapter::Rails](https://github.com/socketry/console-adapter-rails)
+- [Console::Adapter::Sidekiq](https://github.com/socketry/console-adapter-sidekiq)

data/lib/console/capture.rb

@@ -1,64 +1,90 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require_relative "filter"
 require_relative "output/failure"
 
 module Console
-	# A general sink which captures all events into a buffer.
+	# A buffer which captures all logged messages into a buffer.
 	class Capture
+		# Create a new log capture buffer.
 		def initialize
 			@records = []
 			@verbose = false
 		end
 		
+		# @attribute [Array(Hash)] All records captured by this buffer.
 		attr :records
 		
-		# @deprecated Use {#records} instead of {#buffer}.
+		# @deprecated Use {records} instead of {buffer}.
 		alias buffer records
 		
+		# @deprecated Use {records} instead of {to_a}.
 		alias to_a records
 		
+		# @attribute [Boolean] If true, the buffer will capture verbose messages.
 		attr :verbose
 		
+		# Whether the buffer includes any records with the given subject or message pattern.
+		#
+		# @returns [Boolean] True if the buffer includes any records with the given pattern.
 		def include?(pattern)
 			@records.any? do |record|
 				record[:subject].to_s&.match?(pattern) or record[:message].to_s&.match?(pattern)
 			end
 		end
 		
+		# Iterate over all records in the buffer.
+		#
+		# @yields {|record| ...} each record in the buffer.
+		# 	@parameter record [Hash] The record itself.
 		def each(&block)
 			@records.each(&block)
 		end
 		
 		include Enumerable
 		
+		# @returns [Hash] The first record in the buffer.
 		def first
 			@records.first
 		end
 		
+		# @returns [Hash] The last record in the buffer.
 		def last
 			@records.last
 		end
 		
+		# Clear all records from the buffer.
 		def clear
 			@records.clear
 		end
 		
+		# @returns [Boolean] True if the buffer is empty.
 		def empty?
 			@records.empty?
 		end
 		
+		# Sets the verbose flag which controls whether verbose messages are captured.
 		def verbose!(value = true)
 			@verbose = value
 		end
 		
+		# @returns [Boolean] True if the buffer is capturing verbose messages.
 		def verbose?
 			@verbose
 		end
 		
+		# Record a log message in the buffer.
+		#
+		# @parameter subject [Object] The subject of the log message.
+		# @parameter arguments [Array] The arguments to the log message.
+		# @parameter severity [Symbol] The severity of the log message.
+		# @parameter event [Event] The event associated with the log message.
+		# @parameter options [Hash] Additional options to pass to the log message.
+		# @yields {|buffer| ...} A block which can be used to write additional information to the log message.
+		# 	@parameter buffer [IO] The (optional) buffer to write to.
 		def call(subject = nil, *arguments, severity: UNKNOWN, event: nil, **options, &block)
 			record = {
 				time: ::Time.now.iso8601,

data/lib/console/clock.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
+# Copyright, 2026, by William T. Nelson.
 
 module Console
+	# A simple clock utility for tracking and formatting time.
 	module Clock
+		# Format a duration in seconds as a human readable string.
+		#
+		# @parameter duration [Numeric] The duration in seconds.
+		# @returns [String] The formatted duration.
 		def self.formatted_duration(duration)
 			if duration < 60.0
-				return "#{duration.round(2)}s"
+				return format("%.2fs", duration)
 			end
 			
 			duration /= 60.0
@@ -27,7 +33,7 @@ module Console
 			return "#{duration.floor}d"
 		end
 		
-		# Get the current elapsed monotonic time.
+		# @returns [Time] The current monotonic time.
 		def self.now
 			::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
 		end

data/lib/console/compatible/logger.rb

@@ -1,35 +1,55 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
+# Copyright, 2025, by Yasha Krasnou.
 
 require "logger"
 
 module Console
+	# @namespace
 	module Compatible
 		# A compatible interface for {::Logger} which can be used with {Console}.
 		class Logger < ::Logger
+			# A compatible log device which can be used with {Console}. Suitable for use with code which (incorrectly) assumes that the log device a public interface and has certain methods/behaviours.
 			class LogDevice
+				# Create a new log device.
+				#
+				# @parameter subject [String] The subject of the log messages.
+				# @parameter output [Console::Interface] The output interface.
 				def initialize(subject, output)
 					@subject = subject
 					@output = output
 				end
 				
+				# Write a message to the log device.
+				#
+				# @parameter message [String] The message to write.
 				def write(message)
 					@output.call(@subject, message)
 				end
 				
+				# Log a message with the given severity.
+				#
+				# @paraemter arguments [Array] The arguments to log.
+				# @parameter options [Hash] Additional options.
 				def call(*arguments, **options)
 					@output.call(*arguments, **options)
 				end
 				
+				# Reopen the log device. This is a no-op.
 				def reopen
 				end
 				
+				# Close the log device. This is a no-op.
 				def close
 				end
 			end
-
+			
+			# Create a new (compatible) logger.
+			#
+			# @parameter subject [String] The subject of the log messages.
+			# @parameter output [Console::Interface] The output interface.
 			def initialize(subject, output = Console)
 				super(nil)
 				
@@ -37,7 +57,13 @@ module Console
 				@logdev = LogDevice.new(subject, output)
 			end
 			
-			def add(severity, message = nil, progname = nil)
+			# Log a message with the given severity.
+			#
+			# @parameter severity [Integer] The severity of the message.
+			# @parameter message [String] The message to log.
+			# @parameter progname [String] The program name.
+			# @returns [Boolean] True if the message was logged.
+			def add(severity, message = nil, progname = nil, **options)
 				severity ||= UNKNOWN
 				
 				if @logdev.nil? or severity < level
@@ -59,12 +85,17 @@ module Console
 				
 				@logdev.call(
 					progname, message,
+					**options,
 					severity: format_severity(severity)
 				)
 				
 				return true
 			end
 			
+			# Format the severity.
+			#
+			# @parameter value [Integer] The severity value.
+			# @returns [Symbol] The formatted severity.
 			def format_severity(value)
 				super.downcase.to_sym
 			end