feat: Expose logger API (#526)

Author: elementbound

addons/netfox.extras/netfox-extras.gd

@@ -4,7 +4,7 @@ extends EditorPlugin
 const ROOT = "res://addons/netfox.extras"
 
 var SETTINGS = [
-	_NetfoxLogger.make_setting("netfox/logging/netfox_extras_log_level"),
+	NetfoxLogger._make_setting("netfox/logging/netfox_extras_log_level"),
 
 	# Window Tiler Settings
 	{

addons/netfox.extras/network-simulator.gd

@@ -35,7 +35,7 @@ var latency_ms: int = 0
 ## Simulated packet loss percentage
 var packet_loss_percent: float = 0.0
 
-static var _logger: _NetfoxLogger = _NetfoxLogger.for_extras("NetworkSimulator")
+static var _logger: NetfoxLogger = NetfoxLogger._for_extras("NetworkSimulator")
 
 var _enet_peer: ENetMultiplayerPeer = ENetMultiplayerPeer.new()
 

addons/netfox.extras/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.extras"
 description="Game-specific utilities for Netfox"
 author="Tamas Galffy and contributors"
-version="1.33.4"
+version="1.34.0"
 script="netfox-extras.gd"

addons/netfox.extras/rewindable-random-number-generator.gd

@@ -20,7 +20,7 @@ var _rng: RandomNumberGenerator
 var _last_reset_tick := -1
 var _last_reset_rollback_tick := -1
 
-static var _logger := _NetfoxLogger.for_extras("RewindableRandomNumberGenerator")
+static var _logger := NetfoxLogger._for_extras("RewindableRandomNumberGenerator")
 
 func _init(p_seed: int):
 	_rng = RandomNumberGenerator.new()

addons/netfox.extras/state-machine/rewindable-state-machine.gd

@@ -45,7 +45,7 @@ signal on_state_changed(old_state: RewindableState, new_state: RewindableState)
 ## This signal is emitted whenever the state after a tick loop has changed.
 signal on_display_state_changed(old_state: RewindableState, new_state: RewindableState)
 
-static var _logger: _NetfoxLogger = _NetfoxLogger.for_extras("RewindableStateMachine")
+static var _logger: NetfoxLogger = NetfoxLogger._for_extras("RewindableStateMachine")
 
 var _state_object: RewindableState = null
 var _previous_state_object: RewindableState = null

addons/netfox.extras/weapon/network-weapon.gd

@@ -10,7 +10,7 @@ var _reconcile_buffer: Array = []
 var _rng: RandomNumberGenerator = RandomNumberGenerator.new()
 var _fired_tick: int = -1
 
-static var _logger: _NetfoxLogger = _NetfoxLogger.for_extras("NetworkWeapon")
+static var _logger: NetfoxLogger = NetfoxLogger._for_extras("NetworkWeapon")
 
 func _ready():
 	_rng.randomize()

addons/netfox.extras/window-tiler.gd

@@ -11,7 +11,7 @@ var _prefix: String = "netfox-window-tiler-%x" % [ProjectSettings.get_setting(&"
 var _sid: String = "%x" % [hash(int(Time.get_unix_time_from_system() / 2.))]
 var _uid: String = "%d" % [Time.get_unix_time_from_system() * 1000_0000.]
 
-static var _logger: _NetfoxLogger = _NetfoxLogger.for_extras("WindowTiler")
+static var _logger: NetfoxLogger = NetfoxLogger._for_extras("WindowTiler")
 
 func _ready() -> void:
 	# Running on a non-editor (export template) build

addons/netfox.internals/logger.gd

@@ -1,28 +1,38 @@
 extends RefCounted
-class_name _NetfoxLogger
+class_name NetfoxLogger
+
+## Logger implementation for use with netfox
+##
+## NetfoxLoggers implement distinct log levels. These can be used to filter
+## which messages are actually emitted. All messages are output using [method 
+## @GlobalScope.print]. Warnings and errors are also pushed to the debug panel,
+## using [method @GlobalScope.push_warning] and [method @GlobalScope.push_error]
+## respectively, if [member push_to_debugger] is enabled.
+## [br][br]
+## Every logger has a name, and belongs to a module. Logging level can be
+## overridden per module, using [member module_log_level].
+## [br][br]
+## Loggers also support tags. Tags can be used to provide extra pieces of 
+## information that are logged with each message. Some tags are provided by
+## netfox. Additional tags can be added using [method register_tag].
+##
+## @tutorial(Logging Guide): https://foxssake.github.io/netfox/latest/netfox/guides/logging/
+
 
 enum {
-	LOG_MIN,
-	LOG_TRACE,
-	LOG_DEBUG,
-	LOG_INFO,
-	LOG_WARN,
-	LOG_ERROR,
-	LOG_MAX
+	LOG_ALL,	## Filter level to log every message
+	LOG_TRACE,	## Trace logs, the most verbose level
+	LOG_DEBUG,	## Debug logs
+	LOG_INFO,	## Info logs
+	LOG_WARN,	## Warnings
+	LOG_ERROR,	## Errors
+	LOG_NONE	## Filter level to log no messages
 }
 
+## Default log level to fall back on, if not configured
 const DEFAULT_LOG_LEVEL := LOG_DEBUG
 
-static var log_level: int
-static var module_log_level: Dictionary
-
-static var _tags: Dictionary = {}
-static var _ordered_tags: Array[Callable] = []
-
-var module: String
-var name: String
-
-const level_prefixes: Array[String] = [
+const _LEVEL_PREFIXES: Array[String] = [
 	"",
 	"TRC",
 	"DBG",
@@ -32,24 +42,32 @@ const level_prefixes: Array[String] = [
 	""
 ]
 
-static func for_netfox(p_name: String) -> _NetfoxLogger:
-	return _NetfoxLogger.new("netfox", p_name)
+## Global logging level, used by all loggers
+static var log_level: int
 
-static func for_noray(p_name: String) -> _NetfoxLogger:
-	return _NetfoxLogger.new("netfox.noray", p_name)
+## Per-module logging level, used only by loggers belonging to the given module
+## [br][br]
+## This is a dictionary that associates module names ( strings ) to log levels
+## ( int, e.g. [constant LOG_DEBUG] ).
+static var module_log_level: Dictionary
 
-static func for_extras(p_name: String) -> _NetfoxLogger:
-	return _NetfoxLogger.new("netfox.extras", p_name)
+## Set to true to enable calling [@GlobalScope.push_warning] and
+## [@GlobalScope.push_error]
+static var push_to_debugger := true
 
-static func make_setting(name: String) -> Dictionary:
-	return {
-		"name": name,
-		"value": DEFAULT_LOG_LEVEL,
-		"type": TYPE_INT,
-		"hint": PROPERTY_HINT_ENUM,
-		"hint_string": "All,Trace,Debug,Info,Warning,Error,None"
-	}
+static var _tags: Dictionary = {}
+static var _ordered_tags: Array[Callable] = []
 
+## Logger module
+var module: String
+## Logger name
+var name: String
+
+
+## Register a tag
+## [br][br]
+## Tags are callables that provide pieces of context, included in all log
+## messges. The [param tag] callable must return a string.
 static func register_tag(tag: Callable, priority: int = 0) -> void:
 	# Save tag
 	if not _tags.has(priority):
@@ -67,6 +85,7 @@ static func register_tag(tag: Callable, priority: int = 0) -> void:
 		var tag_group = _tags[prio_group]
 		_ordered_tags.append_array(tag_group)
 
+## Free an already registered tag
 static func free_tag(tag: Callable) -> void:
 	for priority in _tags.keys():
 		var priority_group := _tags[priority] as Array
@@ -86,10 +105,76 @@ static func _static_init():
 		"netfox.extras": ProjectSettings.get_setting(&"netfox/logging/netfox_extras_log_level", DEFAULT_LOG_LEVEL)
 	}
 
+static func _for_netfox(p_name: String) -> NetfoxLogger:
+	return NetfoxLogger.new("netfox", p_name)
+
+static func _for_noray(p_name: String) -> NetfoxLogger:
+	return NetfoxLogger.new("netfox.noray", p_name)
+
+static func _for_extras(p_name: String) -> NetfoxLogger:
+	return NetfoxLogger.new("netfox.extras", p_name)
+
+static func _make_setting(name: String) -> Dictionary:
+	return {
+		"name": name,
+		"value": DEFAULT_LOG_LEVEL,
+		"type": TYPE_INT,
+		"hint": PROPERTY_HINT_ENUM,
+		"hint_string": "All,Trace,Debug,Info,Warning,Error,None"
+	}
+
+
 func _init(p_module: String, p_name: String):
 	module = p_module
 	name = p_name
 
+## Log a trace message
+## [br][br]
+## Traces are the most verbose, usually used for drilling down into very niche
+## bugs.
+func trace(text: String, values: Array = []):
+	_log_text(text, values, LOG_TRACE)
+
+## Log a debug message
+## [br][br]
+## Debug messages are verbose, usually used to reconstruct and investigate bugs.
+func debug(text: String, values: Array = []):
+	_log_text(text, values, LOG_DEBUG)
+
+## Log an info message
+## [br][br]
+## Info messages provide general notifications about application events.
+func info(text: String, values: Array = []):
+	_log_text(text, values, LOG_INFO)
+
+## Log a warning message
+## [br][br]
+## This is also forwarded to [method @GlobalScope.push_warning], if enabled with
+## [member push_to_debugger]. Warning messages usually indicate that something
+## has gone wrong, but is recoverable.
+func warning(text: String, values: Array = []):
+	if _check_log_level(LOG_WARN):
+		var formatted_text = _format_text(text, values, LOG_WARN)
+		if push_to_debugger:
+			push_warning(formatted_text)
+
+		# Print so it shows up in the Output panel too
+		print(formatted_text)
+
+## Log an error message
+## [br][br]
+## This is also forwarded to [method @GlobalScope.push_error], if enabled with
+## [member push_to_debugger]. Error messages usually indicate an issue that
+## can't be recovered from.
+func error(text: String, values: Array = []):
+	if _check_log_level(LOG_ERROR):
+		var formatted_text = _format_text(text, values, LOG_ERROR)
+		if push_to_debugger:
+			push_error(formatted_text)
+
+		# Print so it shows up in the Output panel too
+		print(formatted_text)
+
 func _check_log_level(level: int) -> bool:
 	var cmp_level = log_level
 	if level < cmp_level:
@@ -102,11 +187,11 @@ func _check_log_level(level: int) -> bool:
 	return true
 
 func _format_text(text: String, values: Array, level: int) -> String:
-	level = clampi(level, LOG_MIN, LOG_MAX)
+	level = clampi(level, LOG_TRACE, LOG_ERROR)
 
 	var result := PackedStringArray()
 
-	result.append("[%s]" % [level_prefixes[level]])
+	result.append("[%s]" % [_LEVEL_PREFIXES[level]])
 	for tag in _ordered_tags:
 		result.append("[%s]" % [tag.call()])
 	result.append("[%s::%s] " % [module, name])
@@ -121,26 +206,3 @@ func _format_text(text: String, values: Array, level: int) -> String:
 func _log_text(text: String, values: Array, level: int):
 	if _check_log_level(level):
 		print(_format_text(text, values, level))
-
-func trace(text: String, values: Array = []):
-	_log_text(text, values, LOG_TRACE)
-
-func debug(text: String, values: Array = []):
-	_log_text(text, values, LOG_DEBUG)
-
-func info(text: String, values: Array = []):
-	_log_text(text, values, LOG_INFO)
-
-func warning(text: String, values: Array = []):
-	if _check_log_level(LOG_WARN):
-		var formatted_text = _format_text(text, values, LOG_WARN)
-		push_warning(formatted_text)
-		# Print so it shows up in the Output panel too
-		print(formatted_text)
-
-func error(text: String, values: Array = []):
-	if _check_log_level(LOG_ERROR):
-		var formatted_text = _format_text(text, values, LOG_ERROR)
-		push_error(formatted_text)
-		# Print so it shows up in the Output panel too
-		print(formatted_text)

addons/netfox.internals/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.internals"
 description="Shared internals for netfox addons"
 author="Tamas Galffy and contributors"
-version="1.33.4"
+version="1.34.0"
 script="plugin.gd"

addons/netfox.internals/plugin.gd

@@ -2,7 +2,7 @@
 extends EditorPlugin
 
 var SETTINGS = [
-	_NetfoxLogger.make_setting("netfox/logging/log_level")
+	NetfoxLogger._make_setting("netfox/logging/log_level")
 ]
 
 func _enter_tree():