Add version to nimble.

2025-07-07 21:49:35 -05:00
5 changed files with 438 additions and 890 deletions
--- a/.gitignore
+++ b/.gitignore
@ -3,4 +3,3 @@ nimcache/
 tests/tests
 src/namespaced_logging.out
 src/namespaced_logging/autoconfigured
 .worktrees
--- a/README.md
+++ b/README.md
@ -1,79 +1,36 @@
 # Namespaced Logging for Nim
-`namespaced_logging` is intended to be a high-performance, thread-safe logging
+`namespaced_logging` provides a logging framework similar to [log4j][] or
-framework similar to [std/logging][std-logging] with support for
+[logback][] for Nim. It has three main motivating features:
 namespace-scoped logging similar to [log4j][] or [logback][] for Nim. It has
 four main motivating features:
 - Hierarchical, namespaced logging
 - Safe and straightforward to use in multi-threaded applications.
- Native support for structured logging.
+- Native support for structured logging (old-style string logging is also
- Simple, autoconfigured usage pattern reminiscent of the
+  supported).
  [std/logging][std-logging] interface (*not yet implemented*)
 ## Getting Started
-Install the package via nimble:
+Install the package from nimble:
 ```bash
-# Not yet in official Nim packages. TODO once we've battle-tested it a little
+nimble install namespaced_logging
 nimble install https://github.com/jdbernard/nim-namespaced-logging
 ```
-## Usage Patterns
+Then, in your application, you can use the logging system like so:
 ### Manual Configuration
 ```nim
 import namespaced_logging
-# Manually creating a LogService. This is an independent logging root fully
+# On the main thread
-# isolated from subsequent LogServices initialized with initLogService
+let logService = initLogService()
-var ls = initLogService()
+logService.addAppender(initConsoleAppender(LogLevel.INFO))
-# Configure logging
+# On any thread, including the main thread
-ls.addAppender(initConsoleLogAppender())
+let logger = logService.getLogger("app/service/example")
-ls.addAppender(initFileLogAppender("app.log"))
+logger.info("Log from the example service")
 ls.setThreshold("api", lvlWarn)
-# Create loggers
+# Only get logs at the WARN or higher level from the database module
-let localLogSvc = threadLocalRef(ls)
+let logger = logService.getLogger("app/database", threshold = some(Level.lvlWarn))
-let apiLogger = localLogSvc.getLogger("api")
+logger.error("Database connection failed")
 let dbLogger = localLogSvc.getLogger("db")
 ```
 ### Manual Multithreaded Application
 ```nim
 import namespaced_logging
 # Main thread setup
 var logService = initLogService()
 logService.addAppender(initConsoleLogAppender())
 var localLogSvc = threadLocalRef(logService) # for use on main thread
 # Worker thread function
 proc worker(ls: LogService) {.thread.} =
  let localLogSvc = threadLocalRef(ls)
  let logger = localLogSvc.getLogger("worker")
  # Runtime configuration changes
  localLogSvc.setThreshold("worker", lvlDebug)
  logger.debug("Worker configured")
 # Safe thread creation
 createThread(workerThread, worker, logService)
 ```
 ### Dynamic Configuration
 ```nim
 # Configuration can change at runtime
 proc configureLogging(localLogSvc: ThreadLocalLogService, verbose: bool) =
  if verbose:
    localLogSvc.setRootThreshold(lvlDebug)
    localLogSvc.addAppender(initFileLogAppender("debug.log"))
  else:
    localLogSvc.setRootThreshold(lvlInfo)
 # Changes automatically propagate to all threads
 ```
 ## Loggers and Appenders
@ -86,383 +43,140 @@ threshold, which determines which log events are acted upon by the appender,
 and, optionally, a namespace filter, which determines from which loggers the
 appender accepts log events.
-### Heirarchical Logging Namespaces
+### Heirarchical Logging and Namespaces
 Loggers are organized hierarchically, with the hierarchy defined by the logger
-scope. A logger with the scope `app/service/example` is conceptually a child of
+name. A logger with the name `app/service/example` is a child of the logger
-the logger with the scope `app/service`. By default, appenders accept log
+with the name `app/service`. By default, appenders accept log events from all
-events from all loggers, but this can be restricted by setting a namespace
+loggers, but this can be restricted by setting a namespace filter on the
-filter on the appender. An appender with a namespace set will accept log events
+appender. An appender with a namespace set will accept log events from all
-from all loggers with scopes that start with the namespace. For example, an
+loggers with names that start with the namespace. For example, an appender with
-appender with the namespace `app` will accept log events from the loggers
+the namespace `app` will accept log events from the loggers `app`,
-`app`, `app/service`, and `app/service/example`, but not from `api/service`.
+`app/service`, and `app/service/example`, but not from `api/service`.
 The other impact of the logger heirarchy is in the effective logging level of
-the logger. An explicit logging level threshold can be set for any scope. Any
+the logger. Any logger can have an explicit logging level set, but if it does
-scope that does not have an explicit inherits its threshold from ancestor
+not, the effective logging level is inherited from ancestor loggers upwards in
-loggers upwards in the scope naming heirarchy. This pattern is explained in
+the logger heirarchy. This pattern is explained in detail in the [logback
-detail in the [logback documentation][effective logging level] and applies in
+documentation][effective logging level] and applies in the same manner to
-the same manner to loggers in this library.
+loggers in this library.
 ### LogMessageFormater
 Both the [ConsoleLogAppender](#ConsoleLogAppender) and
 [FileLogAppender](#FileLogAppender) can be given a *LogMessageFormatter* to
 determine how a log message is formatted before being written.
 ```nim
 type LogMessageFormatter* = proc (msg: LogMessage): string {.gcsafe.}
 ```
 ## Available Appenders
 ### ConsoleLogAppender
 Used for writing logs to stdout or stderr.
 ```nim
 proc initConsoleLogAppender*(
    formatter = formatSimpleTextLog,
      ## formatJsonStructuredLog is another useful formatter provided
      ## or you can write your own
    useStderr = false,  ## stdout is used by default
    namespace = "",     ## appender matches all scopes by default
    threshold = lvlAll  ## and accepts all message levels by default
  ): ConsoleLogAppender {.gcsafe.}
 ```
 The first time a message is sent to any *ConsoleLogAppender*, we create a
 writer thread which writes messages to the specified output in the order they
 are received, flushing the file handle after each write to enforce an ordering.
 The ConsoleLogAppender implementation uses a channel to send messages to the
 writer thread.
 ### FileLogAppender
 Used for writing logs to files.
 ```nim
 proc initFileLogAppender*(
    filePath: string,
    formatter = formatSimpleTextLog,
      ## formatJsonStructuredLog is another useful formatter provided
      ## or you can write your own
    namespace = "",
    threshold = lvlAll
  ): FileLogAppender {.gcsafe.}
 ```
 Similar to the *ConsoleLogAppender* implementation, the first time a message is
 sent to any *FileLogAppender* we create a writer thread which writes messages
 to files associated with the *FileLogAppender* configured for the current
 *LogService*.
 `namespaced_logging` does not currently have built-in logic for file
 rotation, but it does play nice with external file rotation strategies. We do
 not hold open file handles. The *FileLogAppender* attempts to batch messages
 by destination file, opens the file with mode `fmAppend`, writes the current
 batch of log messages, and then closes the file handle. Because of this, it has
 no problem if another process moves or truncates any of the target log files.
 ### StdLoggingAppender
 Provides a fallback to [std/logging][std-logging]-based logging. This is
 primarily intended for use in libraries or other contexts where you want to
 fall back to std/logging if the application is not using or hasn't configured
 namespaced\_logging.
 By default the *StdLoggingAppender* only logs when no namespaced\_logging
 appenders are configured but it can also be configured to always forward log
 messages regardless of whether namespaced\_logging has other appenders by
 setting `fallbackOnly = false`.
 ```nim
 func initStdLoggingAppender*(
    fallbackOnly = true,
    formatter = formatForwardedLog,
    namespace = "",
    threshold = lvlAll): StdLoggingAppender {.gcsafe.}
 ```
 ### CustomLogAppender
 Provides an extension point for custom logging implementations.
 ```nim
 func initCustomLogAppender*[T](
    state: T,   # arbitrary state needed for the appender
    doLogMessage: CustomLogAppenderFunc[T],
      # custom log appender implementation
    namespace = "",
    threshold = lvlAll): CustomLogAppender[T] {.gcsafe.} =
 ```
 The `state` field allows you to explicitly pass in any data that is required
 for the custom functionality.
 *TODO: rethink this. I chose this to avoid GC-safety issues copying closures
 across threads, but maybe I don't need this separate, explicit state field.*
 > [!CAUTION] The `state` data type must support copy semantics on assignment.
 > It is possible to pass a `ref` to `state` and/or data structures that include
 > `ref`s, but **you must guarantee they remain valid**, either by allocating
 > shared memeory, or (preferably) keeping alive a reference to them that the GC
 > is aware of, either on the thread where they were initialized or by
 > explicitly telling the GC about the cross-thread reference *(TODO: how?)*.
 See [testutil][] and the unit tests in [namespaced\_logging][nsl-unit-tests]
 for an example.
 ## Notes on Use in Multi-Threaded Applications
-The loggers and appenders in this library are thread-safe and are intended to
+The loggers and appenders in this library are thread-safe and behaves more
-behave more intuitively in a multi-threaded environment than
+intuitively in a multi-threaded environment than `std/logging`, particularly in
-[std/logging][std-logging] while presenting a similar API. This is particularly
+environments where the logging setup code may be separated from the
 true in environments where the logging setup code may be separated from the
 thread-management code (in an HTTP server, for example).
 The *LogService* object is the main entry point for the logging system and
-should be initialized on the main thread. The *LogService* contains a reference
+should be initialized on the main thread. The *LogService* contains the "source
-to the "source of truth" for logging configuration and is safe to be shared
+of truth" for logging configuration and is shared between all threads.
-between all threads.
+Internally all access to the *LogService* is protected by a mutex.
-The thread which initializes a *LogService* must also be the longest-living
+Logging can be very noisy and if the *LogService* needed to be consulted for
-thread that uses that *LogService* instance. If the initializing thread
+every log event, it could easily become a performance bottleneck. To avoid
-terminates or the *LogService* object in that thread goes out of scope while
+this, the *getLogger* procedure makes a thread-local copy of the logging system
-other threads are still running and using the *LogService*, the global state
+configuration (loggers defined and appenders attached).
 may be harvested by the garbage collector, leading to use-after-free errors
 when other threads attempt to log (likely causing segfaults).
-Individual threads should use the *threadLocalRef* proc to obtain a
+**Note** that this means that the thread-local cache of the logging system
-*ThreadLocalLogService* reference that can be used to create *Logger* objects.
+configuration can become stale if the logging system configuration is changed
-*ThreadLocalLogService* objects cache the global *LogService* state locally to
+after the thread-local copy is made (if another appender is added, for
-avoid expensive locks on the shared state. Instead an atomic configuration
+example). This is a trade-off to avoid the performance penalty of consulting
-version number is maintained to allow the thread-local state to detect global
+the *LogService* for every log event.
 configuration changes via an inexpensive [load][atomic-load] call and
 automatically synchronize only when necessary.
 This thread-local caching mechanism is the primary advantage of this logging
-system over std/logging in a multi-threaded environment as it means that
+system over `std/logging` in a multi-threaded environment as it means that
 the logging system itself is responsible for making sure appenders are
 configured for every thread where loggers are used, even if the thread
 initialization context is separated from the logging setup code.
 If you find yourself needing to change the logging configuration after the
 logging system has been initialized, the *reloadThreadState* procedure can be
 used to update the thread-local cache of the logging system configuration, but
 it must be called on the thread you wish to update.
-## Architectural Design
+As a final note, the advice to initialize the *LogService* on the main thread
 is primarily to simplify the configuration of the logging service and avoid the
 need to manually reload caches on individual threads. A *LogService* reference
 is required to call *getLogger*, but it can be created on any thread.
-### Overview
+## Custom Appender Implementations
-The namespaced logging library attempts to balance performance, safety, and
+Due to the thread-safety of the logging system, there are a few additional
-usability in multithreaded environments. The design centers on two key types:
+considerations when implementing custom appenders. The *LogAppender* abstract
-*LogService* and *ThreadLocalLogService*.
+class is the base class for all appenders. To implement a custom appender, two
 methods must be implemented:
-#### LogService (Value Type)
+### `appendLogMessage`
 ```nim
 type LogService* = object
  configVersion: int
  global: GlobalLogService
  appenders: seq[LogAppender]
  thresholds: TableRef[string, Level]
 ```
 The *LogService* object is intended to support uses cases such as:
 - **Main thread initialization**: a mutable *LogService* supports all of the
  configuration functions you would typically need when initializing logging
  for an application on the main thread.
 - **Cross-thread communication**: Being an `object` type, *LogService* follows
  value semantics and can be safely copied between threads.
 - **Service composition**: independently initialized *LogService* objects are
  truly independent and multiple can be created and embedded in larger
  application contexts.
 > [!TIP]
 > The *LogService* object is the object that is intended to be shared across
 > threads.
 #### ThreadLocalLogService (Reference Type)
 ```nim
 type ThreadLocalLogService* = ref LogService
 ```
 *ThreadLocalLogService* is a reference to a thread-local copy of a *LogService*
 and can be obtained via *threadLocalRef*. We purposefully use reference
 semantics within the context of a thread so that *Logger* objects created
 within the same thread context share the same *ThreadLocalLogService*
 reference, avoiding the need to synchronize every *Logger* individually.
 *ThreadLocalLogService* is the object that users are expected to interact with
 during regular operation and support both the configuration functions of
 *LogService* and the creation of *Logger* objects.
 > [!CAUTION]
 > *ThreadLocalLogService* objects should **never** be shared outside the
 > context of the thread in which they were initialized.
 #### GlobalLogService (Internal)
 Under the hood *LogService* holds a reference to a *GlobalLogService*, a
 heap-allocated object that serves as the single source of truth for logging
 configuration. This internal type is not exposed to library users but manages:
 - **Shared configuration state**: Appenders, thresholds, and root logging level
 - **Synchronization primitives**: Locks and atomic variables for thread
  coordination
 - **Background I/O threads**: Dedicated writer threads for console and file
  output
 - **Configuration versioning**: Atomic version numbers for efficient change
  detection
 The `GlobalLogService` ensures that configuration changes are safely propagated
 across all threads while maintaining high performance for logging operations.
 ### Thread Safety Model
 #### Safe Cross-Thread Pattern
 ```nim
 # Main thread setup
 let logService = initLogService()
 logService.addAppender(initConsoleLogAppender())
 # Safe: value semantics allow crossing thread boundaries
 proc workerThread(ls: LogService) {.thread.} =
  # Convert to thread-local reference for efficient operations
  let tlls = threadLocalRef(ls)
  let logger = tlls.getLogger("worker")
  logger.info("Worker thread started")
 createThread(worker, workerThread, logService)
 ```
 #### Unsafe Pattern (Avoided by Design)
 ```nim
 # DON'T DO THIS - unsafe reference sharing
 # ThreadLocalLogService should not be shared across threads
 let tlls = threadLocalRef(initLogService())
 createThread(worker, someProc, tlls)  # ❌ Potential GC issues
 ```
 ### Configuration Synchronization
 #### Atomic Version Checking
 The library uses atomic version numbers to efficiently detect configuration
 changes:
 ```nim
-proc ensureFreshness*(ls: var LogService) =
+method appendLogMessage*(appender: CustomLogAppender, msg: LogMessage): void {.base, gcsafe.}
  # Cheap atomic check first
  if ls.configVersion == ls.global.configVersion.load():
    return  # No changes, return immediately
  # Only acquire lock and copy if versions differ
  withLock ls.global.lock:
    ls.configVersion = ls.global.configVersion.load
    # Sync state...
 ```
-Goals/Motivation:
+This is the primary appender implementation that takes a LogMessage and
- Most logging operations skip expensive synchronization so the hot path is
+writes it to the appender's destination. As the signature suggests, the
-  fast.
+implementation must be GC-safe. As a multi-method, the *CustomLogAppender* type
- Propogate changes automatically so all threads see configuration updates.
+should be replaced by the actual name of your custom appender.
 - Minimize lock contention by only acquiring when configuration changes
-#### Thread-Local Caching
+Because the *LogAppender* uses multi-methods for dynamic dispatch, the
 custom appender class must also be a `ref` type.
-Each thread maintains its own copy of the logging configuration in
+### `initThreadCopy`
 *ThreadLocalLogService*:
 - **Appenders**: Thread-local copies created via `clone()` method
 - **Thresholds**: Complete copy of namespace-to-level mappings
 - **Version tracking**: Local version number for change detection
 This caching strategy provides:
 - **High performance**: No locks needed for normal logging operations
 - **Consistency**: All threads eventually see the same configuration
 - **Isolation**: Thread-local state prevents cross-thread interference
 ## Error Handling
 ### Overview
 For errors that occur during logging operations, there is a callback-based
 error handling system designed to attempt to gracefully handle such failures.
 Since logging is typically a non-critical operation we prioritize application
 stability over guaranteed log delivery.
 ### Error Handler
 The library uses a callback-based error handling pattern where applications can
 register custom error handlers to be notified when logging operations fail. The
 error handler receives:
 - `error`: The exception that caused the failure
 - `msg`: A descriptive message providing context about where the error occurred
 ```nim
-type ErrorHandlerFunc* = proc(error: ref Exception, msg: string) {.gcsafe, nimcall.}
+method initThreadCopy*(app: LogAppender): LogAppender {.base, gcsafe.}
 ```
-### Default Error Handler
+This method is used to create a thread-local copy of the appender. It is called
 by the *reloadThreadState* procedure to update the thread-local cache of the
 logging system configuration. The implementation will be passed the appender
 instance that was provided to the *addAppender* procedure and must return a
 thread-local copy of that appender.
-namespaced\_logging uses the `defaultErrorHandlerFunc` if a custom error
+The `initThreadCopy` implementations for the built-in *ConsoleLogAppender* and
-handler has not been configured. The default handler:
+*FileLogAppender* provide simple examples of how to implement this method by
 simply copying state into the local thread, but this method can also be used
 to perform any other thread-specific initialization that may be required for
 the appender implementation.
-1. Attempts to write to stderr, assuming it is likely to be available and monitored
+### Example Custom Appender
 2. Writes an error message and includes both the exception message and stack
   trace (not available in release mode).
 3. Fails silently if it is unable to write to to stderr.
-### Configuration
+The following defines a simple custom appender that writes log messages to a
-
+database table. It uses the [waterpark][] connection pooling library to manage
-#### Setting Custom Error Handlers
+database connections as waterpark is also thread-safe and makes implementation
-```nim
+straight-forward.
 # During initialization
 var logService = initLogService(errorHandler = myCustomErrorHandler)
 # Or at runtime on either the LogService...
 logService.setErrorHandler(myCustomErrorHandler)
 # ... or on a ThreadLocalLogService
 var localLogSvc = threadLocalRef(logService)
 localLogSvc.setErrorHandler(myCustomErrorHandler)
 ```
 #### Disabling Error Reporting
 ```nim
 proc silentErrorHandler(err: ref Exception, msg: string) {.gcsafe, nimcall.} =
  discard # Do nothing
 logService.setErrorHandler(silentErrorHandler)
 ```
 ### Best Practices
 #### Provide Fallbacks
 ```nim
-proc robustErrorHandler(err: ref Exception, msg: string) {.gcsafe, nimcall.} =
+import db_connectors/db_postgres
-  # Primary: Send to monitoring system
+import namespaced_logging, waterpark, waterpark/db_postgres
-  if not sendToMonitoring(err, msg):
+
-    # Secondary: Write to dedicated error log
+type DbLogAppender = ref object of LogAppender
-    if not writeToErrorLog(err, msg):
+  dbPool: PostgresPool
-      # Tertiary: Use stderr as last resort
+
-      try:
+let dbPool: PostgresPool = newPostgresPool(10, "", "", "", connectionString)
-        stderr.writeLine("LOGGING ERROR [" & msg & "]: " & err.msg)
+
-        stderr.flushFile()
+method initThreadCopy*(app: LogAppender): LogAppender =
-      except: discard
+  result = DbLogAppender(dbPool: dbPool) # copy semantics as PostgresPool is an object
 method appendLogMessage*(appender: DbLogAppender, msg: LogMessage): void {gcsafe.} =
  appender.withConnection conn:
    conn.insert(
      "INSERT INTO log_events " &
      "  (level, scope, message, error, timestamp, custom_fields) " &
      "VALUES " &
      "  (?, ?, ?, ?, ?, ?)",
      msg.level,
      msg.scope,
      msg.message,
      if msg.error.isSome: msg.error.msg
      else: "",
      msg.timestamp,
      msg.additionalData)
 ```
 #### Keep Error Handlers Simple
 As much as possible, avoid complex operations that might themselves fail.
 Don't do heavy operations like database writes, complex network operations, or
 file system operations that might fail and cause cascading errors.
 [log4j]: https://logging.apache.org/log4j/2.x/
 [logback]: https://logback.qos.ch/
 [effective logging level]: https://logback.qos.ch/manual/architecture.html#effectiveLevel
 [atomic-load]: https://nim-lang.org/docs/atomics.html#load%2CAtomic%5BT%5D%2CMemoryOrder
 [std-logging]: https://nim-lang.org/docs/logging.html
 [testutil]: /blob/main/src/namespaced_logging/testutil.nim
 [nsl-unit-tests]: https://github.com/jdbernard/nim-namespaced-logging/blob/main/src/namespaced_logging.nim#L904
--- a/namespaced_logging.nimble
+++ b/namespaced_logging.nimble
@ -1,6 +1,6 @@
 # Package
-version       = "2.0.2"
+version       = "2.0.0"
 author        = "Jonathan Bernard"
 description   = "Wrapper around std/logging to provide namespaced logging."
 license       = "MIT"
@ -13,7 +13,3 @@ requires @["nim >= 2.2.0", "zero_functional"]
 # from https://git.jdb-software.com/jdb/nim-packages
 requires "timeutils"
 task test, "Run unittests for the package.":
  exec "nimble c src/namespaced_logging.nim"
  exec "src/namespaced_logging.out"
--- a/src/namespaced_logging.nim
+++ b/src/namespaced_logging.nim
@ -1,10 +1,9 @@
-import std/[algorithm, atomics, exitprocs, json, locks, options, os, paths,
+import std/[algorithm, atomics, json, locks, options, os, paths, sequtils,
-            sequtils, strutils, tables, times]
+            strutils, tables, times]
 import timeutils
 import std/logging as stdlog
-from std/logging import Level
+from logging import Level
-export Level
+export logging.Level
 type
  GlobalLogServiceObj {.acyclic.} = object
@ -16,9 +15,13 @@ type
    thresholds: TableRef[string, Level]
    rootLevel: Atomic[Level]
    console: ThreadedConsoleLoggingState
    file: ThreadedFileLoggingState
    errorHandler: ErrorHandlerFunc
    errorHandlerLock: Lock
  GlobalLogService = ref GlobalLogServiceObj
@ -38,7 +41,7 @@ type
  ThreadLocalLogService* = ref LogService
-  Logger* = ref object
+  Logger* = object
    scope*: string
    threadSvc: ThreadLocalLogService
@ -84,11 +87,18 @@ type
    absPath: Path
-  LogWriterThreadState[M] = object
+  ThreadedConsoleLoggingState = object
    initialized: Atomic[bool]
    shutdown: Atomic[bool]
-    chan: Channel[M]
+    chan: Channel[ConsoleMessage]
-    writerThread: Thread[void]
+    writerThread: Thread[GlobalLogService]
  ThreadedFileLoggingState = object
    initialized: Atomic[bool]
    shutdown: Atomic[bool]
    chan: Channel[FileMessage]
    writerThread: Thread[GlobalLogService]
  ConsoleLogAppender* = ref object of LogAppender
@ -113,61 +123,6 @@ type
    formatter*: LogMessageFormatter
    absPath*: Path
  StdLoggingAppender* = ref object of LogAppender
    ## Log appender that forwards log messages to the std/logging
    ## implementation. This is primarily intended for libraries and other
    ## situations where you expect that your code will be third-party to others
    ## and want to respect applications which use std/logging for log handlers
    ## and configuration.
    fallbackOnly*: bool
      ## when true, only forward to std/logging where there are no appenders
      ## configured on the related LogService
    formatter*: LogMessageFormatter
 const UninitializedConfigVersion = low(int)
 let JNULL = newJNull()
 var consoleLogging {.global.}: LogWriterThreadState[ConsoleMessage]
 var fileLogging {.global.}: LogWriterThreadState[FileMessage]
 var loggingThreadInitLock {.global.}: Lock
 initLock(loggingThreadInitLock)
 proc initLogMessage*(
    scope: string,
    lvl: Level,
    message: string,
    error: Option[ref Exception] = none[ref Exception](),
    additionalData: JsonNode = JNULL): LogMessage =
  LogMessage(
    scope: scope,
    level: lvl,
    error: error,
    timestamp: now(),
    message: message,
    additionalData: additionalData)
 proc initLogMessage*(
    scope: string,
    lvl: Level,
    msg: JsonNode,
    error: Option[ref Exception] = none[ref Exception]()): LogMessage =
  LogMessage(
    scope: scope,
    level: lvl,
    error: error,
    timestamp: now(),
    message:
      if msg.hasKey("message"): msg["message"].getStr
      else: "",
    additionalData: msg)
 method clone*(app: LogAppender): LogAppender {.base, gcsafe.} =
  raise newException(CatchableError, "missing concrete implementation")
@ -189,39 +144,40 @@ proc defaultErrorHandlerFunc*(
    stderr.flushFile()
  except Exception: discard # we tried...
-proc shutdownThreadedConsoleLogging() =
+proc shutdownThreadedConsoleLogging(gls: var GlobalLogServiceObj) =
-  if not consoleLogging.initialized.load(): return
+  if not gls.console.initialized.load(): return
-  withLock loggingThreadInitLock:
+  gls.console.shutdown.store(true) # signal shutdown
    consoleLogging.shutdown.store(true) # signal shutdown
-    # Send sentinel values to wake up the writer thread
+  # Send sentinel values to wake up the writer thread
-    try: consoleLogging.chan.send(ConsoleMessage(message: "", useStderr: false))
+  try: gls.console.chan.send(ConsoleMessage(message: "", useStderr: false))
-    except Exception: discard
+  except Exception: discard
-    joinThread(consoleLogging.writerThread)
+  joinThread(gls.console.writerThread)
-    consoleLogging.chan.close()
+  gls.console.chan.close()
-    consoleLogging.initialized.store(false)
+  gls.console.initialized.store(false)
-proc shutdownThreadedFileLogging() =
+proc shutdownThreadedFileLogging(gls: var GlobalLogServiceObj) =
-  if not fileLogging.initialized.load(): return
+  if not gls.file.initialized.load(): return
-  fileLogging.shutdown.store(true) # signal shutdown
+  gls.file.shutdown.store(true) # signal shutdown
-  withLock loggingThreadInitLock:
+  try: gls.file.chan.send(FileMessage(message: "", absPath: Path("/")))
-    try: fileLogging.chan.send(FileMessage(message: "", absPath: Path("/")))
+  except Exception: discard
    except Exception: discard
-    joinThread(fileLogging.writerThread)
+  joinThread(gls.file.writerThread)
-    fileLogging.chan.close()
+  gls.file.chan.close()
-    fileLogging.initialized.store(false)
+  gls.file.initialized.store(false)
 proc `=destroy`*(gls: var GlobalLogServiceObj) =
  # only one thread should cleanup
  if not gls.initialized.exchange(false): return
  gls.shutdownThreadedConsoleLogging()
  gls.shutdownThreadedFileLogging()
  try: deinitLock(gls.lock)
  except Exception: discard
@ -254,28 +210,6 @@ proc ensureFreshness*(ls: var LogService) =
 proc ensureFreshness*(ls: ThreadLocalLogService) = ensureFreshness(ls[])
 proc initGlobalLogService(
    rootLevel = lvlAll,
    errorHandler = defaultErrorHandlerFunc): GlobalLogService =
  result = GlobalLogService()
  result.configVersion.store(0)
  initLock(result.lock)
  initLock(result.errorHandlerLock)
  result.appenders = @[]
  result.thresholds = newTable[string, Level]()
  result.rootLevel.store(rootLevel)
  result.errorHandler = errorHandler
  result.initialized.store(true)
 proc initLogService(gls: GlobalLogService): LogService =
  var lsRef: ThreadLocalLogService = ThreadLocalLogService(
    configVersion: UninitializedConfigVersion, global: gls)
  ensureFreshness(lsRef)
  result = lsRef[]
 proc initLogService*(
    rootLevel = lvlAll,
    errorHandler = defaultErrorHandlerFunc): LogService =
@ -293,12 +227,24 @@ proc initLogService*(
  ## configure thresholds, and create loggers. The ref returned by this
  ## procedure should also be retained by the main thread so that garbage
  ## collection does not harvest the global state while it is still in use.
-  let global = initGlobalLogService(rootLevel, errorHandler)
+  let global = GlobalLogService()
-  result = initLogService(global)
+  global.configVersion.store(0)
  global.initialized.store(true)
  initLock(global.lock)
  initLock(global.errorHandlerLock)
  global.appenders = @[]
  global.thresholds = newTable[string, Level]()
  global.rootLevel.store(rootLevel)
  global.errorHandler = errorHandler
  var lsRef: ThreadLocalLogService = ThreadLocalLogService(configVersion: -1, global: global)
  ensureFreshness(lsRef)
  result = lsRef[]
 proc threadLocalRef*(ls: LogService): ThreadLocalLogService =
-  new result
+  result = new(LogService)
  result[] = ls
@ -416,15 +362,6 @@ proc getLogger*(
  result = Logger(scope: scope, threadSvc: ls)
 proc getLogger*(
    ls: Option[ThreadLocalLogService],
    scope: string,
    lvl: Option[Level] = none[Level]()): Option[Logger] {.gcsafe.} =
  return
    if ls.isSome: some(getLogger(ls.get, scope, lvl))
    else: none[Logger]()
 proc addAppender*(ls: var LogService, appender: LogAppender) {.gcsafe.} =
  ## Add a log appender to the global log service and refresh the local thread
  ## state. The updated global state will trigger other threads to refresh
@ -441,19 +378,6 @@ proc addAppender*(ls: ThreadLocalLogService, appender: LogAppender) {.gcsafe.} =
  addAppender(ls[], appender)
 proc clearAppenders*(ls: var LogService) {.gcsafe.} =
  ## Remove all log appenders added to the global log service and refresh the
  ## local thread state. The updated global state will trigger other threads to
  ## refresh their state as well.
  withLock ls.global.lock:
    ls.global.appenders = @[]
    ls.global.configVersion.atomicInc
 proc clearAppenders*(ls: ThreadLocalLogService) {.gcsafe.} =
  clearAppenders(ls[])
 func getEffectiveThreshold(logger: Logger): Level {.gcsafe.} =
  ## Get the effective logging level threshold for a logger. This is the most
  ## specific level that is set for the logger or any of its parents. The root
@ -475,173 +399,89 @@ func getEffectiveThreshold(logger: Logger): Level {.gcsafe.} =
    result = logger.threadSvc.thresholds[namespaces[0]]
-proc isEnabled*(l: Logger, lvl: Level): bool {.inline,gcsafe.} =
+proc doLog(logger: Logger, msg: LogMessage) {.gcsafe.} =
-  lvl >= l.getEffectiveThreshold
+  ensureFreshness(logger.threadSvc)
  if msg.level < logger.getEffectiveThreshold: return
 proc sendToAppenders(logger: Logger, msg: LogMessage) {.gcsafe,inline.} =
  for app in logger.threadSvc.appenders:
    if logger.scope.startsWith(app.namespace) and msg.level >= app.threshold:
      app.appendLogMessage(logger.threadSvc, msg)
-template log*(l: Logger, lm: LogMessage) =
+proc log*(l: Logger, lvl: Level, msg: string) {.gcsafe.} =
-  ensureFreshness(l.threadSvc)
+  l.doLog(LogMessage(
-
+    scope: l.scope,
-  if lm.level >= l.getEffectiveThreshold:
+    level: lvl,
-    sendToAppenders(l, lm)
+    error: none[ref Exception](),
-
+    timestamp: now(),
-template log*(l: Logger, lvl: Level, msg: untyped) =
+    message: msg,
-  ensureFreshness(l.threadSvc)
+    additionalData: newJNull()))
  if lvl >= l.getEffectiveThreshold:
    sendToAppenders(l, initLogMessage(l.scope, lvl, msg))
-template log*[T: ref Exception](l: Logger, lvl: Level, err: T, msg: untyped) =
+proc log*(
-  ensureFreshness(l.threadSvc)
+    l: Logger,
  if lvl >= l.getEffectiveThreshold:
    sendToAppenders(
      l,
      initLogMessage(l.scope, lvl, msg, some(cast[ref Exception](err))))
 template log*(l: Option[Logger], lm: LogMessage) =
  if l.isSome: log(l.get, lm)
 template log*(l: Option[Logger], lvl: Level, msg: untyped) =
  if l.isSome: log(l.get, lvl, msg)
 template log*(
    l: Option[Logger],
    lvl: Level,
    error: ref Exception,
-    msg: untyped) =
+    msg: string ) {.gcsafe.} =
  l.doLog(LogMessage(
    scope: l.scope,
    level: lvl,
    error: some(error),
    timestamp: now(),
    message: msg,
    additionalData: newJNull()))
 proc log*(l: Logger, lvl: Level, msg: JsonNode) {.gcsafe.} =
  l.doLog(LogMessage(
    scope: l.scope,
    level: lvl,
    error: none[ref Exception](),
    timestamp: now(),
    message:
      if msg.hasKey("msg"): msg["msg"].getStr
      else: "",
    additionalData: msg))
 proc log*(l: Option[Logger], lvl: Level, msg: string) {.gcsafe.} =
  if l.isSome: log(l.get, lvl, msg)
 proc log*(l: Option[Logger], lvl: Level, msg: JsonNode) {.gcsafe.} =
  if l.isSome: log(l.get, lvl, msg)
 proc log*(l: Option[Logger], lvl: Level, error: ref Exception, msg: string) {.gcsafe.} =
  if l.isSome: log(l.get, lvl, error, msg)
-template debug*[L: Logger or Option[Logger], M](l: L, msg: M) =
+template debug*[T](l: Logger, msg: T) = log(l, lvlDebug, msg)
-  log(l, lvlDebug, msg)
+template info*[T](l: Logger, msg: T) = log(l, lvlInfo, msg)
 template notice*[T](l: Logger, msg: T) = log(l, lvlNotice, msg)
 template warn*[T](l: Logger, msg: T) = log(l, lvlWarn, msg)
-template info*[L: Logger or Option[Logger], M](l: L, msg: M) =
+template error*[T](l: Logger, msg: T) = log(l, lvlError, msg)
-  log(l, lvlInfo, msg)
+template error*(l: Logger, error: ref Exception, msg: string) =
 template notice*[L: Logger or Option[Logger], M](l: L, msg: M) =
  log(l, lvlNotice, msg)
 template warn*[L: Logger or Option[Logger], M](l: L, msg: M) =
  log(l, lvlWarn, msg)
 template error*[L: Logger or Option[Logger], M](l: L, msg: M) =
  log(l, lvlError, msg)
 template error*[L: Logger or Option[Logger], M](l: L, error: ref Exception, msg: M) =
  log(l, lvlError, error, msg)
-template fatal*[L: Logger or Option[Logger], M](l: L, msg: M) =
+template fatal*[T](l: Logger, msg: T) = log(l, lvlFatal, msg)
-  log(l, lvlFatal, msg)
+template fatal*(l: Logger, error: ref Exception, msg: string) =
 template fatal*[L: Logger or Option[Logger], M](l: L, error: ref Exception, msg: M) =
  log(l, lvlFatal, error, msg)
 template debug*[T](l: Option[Logger], msg: T) = log(l, lvlDebug, msg)
 template info*[T](l: Option[Logger], msg: T) = log(l, lvlInfo, msg)
 template notice*[T](l: Option[Logger], msg: T) = log(l, lvlNotice, msg)
 template warn*[T](l: Option[Logger], msg: T) = log(l, lvlWarn, msg)
 template error*[T](l: Option[Logger], msg: T) = log(l, lvlError, msg)
 template error*(l: Option[Logger], error: ref Exception, msg: string) =
  log(l, lvlError, error, msg)
 template fatal*[T](l: Option[Logger], msg: T) = log(l, lvlFatal, msg)
 template fatal*(l: Option[Logger], error: ref Exception, msg: string) =
  log(l, lvlFatal, error, msg)
 # -----------------------------------------------------------------------------
-# Writer Thread Implementations
+# CustomerLogAppender Implementation
 # -----------------------------------------------------------------------------
 proc consoleWriterLoop() {.thread.} =
  while not consoleLogging.shutdown.load():
    var didSomething = false
    let (hasData, msg) = consoleLogging.chan.tryRecv()
    if hasData and msg.message.len > 0:  # Skip empty sentinel messages
      try:
        let output =
          if msg.useStderr: stderr
          else: stdout
        output.write(msg.message)
        output.flushFile()
        didSomething = true
      except IOError:
        discard
    # Small delay if no work to prevent busy waiting
    if not didSomething: sleep(100)
 proc fileWriterLoop() {.thread.} =
  const bufLen = 128
  var msgsByPath = newTable[Path, seq[FileMessage]]()
  while not fileLogging.shutdown.load():
    var didSomething = false
    var msgBuf: array[bufLen, FileMessage]
    var recvIdx = 0
    var writeIdx = 0
    var dataAvailable = true
    while dataAvailable and recvIdx < bufLen:
      # Fill our message buffer if we can
      (dataAvailable, msgBuf[recvIdx]) = fileLogging.chan.tryRecv()
      if dataAvailable: inc recvIdx
    # Organize messages by destination file
    msgsByPath.clear()
    while writeIdx < recvIdx:
      let msg = msgBuf[writeIdx]
      inc writeIdx
      if msg.message.len > 0:  # skip empty sentinel messages
        if not msgsByPath.contains(msg.absPath): msgsByPath[msg.absPath] = @[]
        msgsByPath[msg.absPath].add(msg)
        didSomething = true
    # Write all messages in file order to optimize file open/flush/close
    for path, msgs in pairs(msgsByPath):
      var f: File
      if not open(f, $path, fmAppend):
        # TODO: can we do better than silently failing here?
        continue
      for m in msgs:
        try: writeLine(f, m.message)
        except Exception: discard
      flushFile(f)
      close(f)
    # Wait a bit if we had no work to prevent busy waiting
    if not didSomething: sleep(100)
 proc initThreadedConsoleLogging() =
  if consoleLogging.initialized.load: return
  withLock loggingThreadInitLock:
    if consoleLogging.initialized.load: return
    consoleLogging.chan.open()
    consoleLogging.shutdown.store(false)
    # Create writer thread with reference to the service
    createThread(consoleLogging.writerThread, consoleWriterLoop)
    consoleLogging.initialized.store(true)
 proc initThreadedFileLogging() =
  if fileLogging.initialized.load: return
  withLock loggingThreadInitLock:
    if fileLogging.initialized.load: return
    fileLogging.chan.open()
    fileLogging.shutdown.store(false)
    # Create writer thread with reference to the service
    createThread(fileLogging.writerThread, fileWriterLoop)
    fileLogging.initialized.store(true)
 # -----------------------------------------------------------------------------
 # CustomLogAppender Implementation
 # -----------------------------------------------------------------------------
 func initCustomLogAppender*[T](
@ -651,7 +491,7 @@ func initCustomLogAppender*[T](
    threshold = lvlAll): CustomLogAppender[T] {.gcsafe.} =
  if doLogMessage.isNil:
-    raise newException(ValueError, "initCustomLogAppender: doLogMessage is nil")
+    debugEcho "initCustomLogAppender: doLogMessage is nil"
  result = CustomLogAppender[T](
    namespace: namespace,
@ -660,8 +500,8 @@ func initCustomLogAppender*[T](
    state: state)
 method clone*[T](cla: CustomLogAppender[T]): LogAppender {.gcsafe.} =
-  assert not cla.doLogMessage.isNil,
+  if cla.doLogMessage.isNil:
-    "CustomLogAppender#clone: source doLogMessage is nil"
+    debugEcho "CustomLogAppender#clone: source doLogMessage is nil"
  result = CustomLogAppender[T](
    namespace: cla.namespace,
@ -676,7 +516,7 @@ method appendLogMessage[T](
    msg: LogMessage) {.gcsafe.} =
  try:
    if cla.doLogMessage.isNil:
-      raise newException(ValueError, "CustomLogAppender.appendLogMessage: doLogMessage is nil")
+      debugEcho "doLogMessage is nil"
    else: cla.doLogMessage(cla.state, msg)
  except Exception:
    ls.global.reportLoggingError(
@ -700,6 +540,41 @@ proc initConsoleLogAppender*(
    useStderr: useStderr)
 proc consoleWriterLoop(gls: GlobalLogService) {.thread.} =
  while not gls.console.shutdown.load():
    var didSomething = false
    let (hasData, msg) = gls.console.chan.tryRecv()
    if hasData and msg.message.len > 0:  # Skip empty sentinel messages
      try:
        let output =
          if msg.useStderr: stderr
          else: stdout
        output.write(msg.message)
        output.flushFile()
        didSomething = true
      except IOError:
        discard
    # Small delay if no work to prevent busy waiting
    if not didSomething: sleep(100)
 proc initThreadedConsoleLogging(gls: GlobalLogService) =
  if gls.console.initialized.load() or  # don't double-init
     not gls.initialized.load():        # don't init if the gls is shutting down
    return
  withLock gls.lock:
    if gls.console.initialized.load(): return
    gls.console.chan.open()
    gls.console.shutdown.store(false)
    # Create writer thread with reference to the service
    createThread(gls.console.writerThread, consoleWriterLoop, gls)
    gls.console.initialized.store(true)
 method clone*(cla: ConsoleLogAppender): LogAppender {.gcsafe.} =
  result = ConsoleLogAppender(
    namespace: cla.namespace,
@ -713,11 +588,11 @@ proc appendLogMessageMultiThreaded(
    ls: ref LogService,
    msg: LogMessage) {.gcsafe.} =
-  if not consoleLogging.initialized.load():
+  if not ls.global.console.initialized.load():
-    initThreadedConsoleLogging()
+    ls.global.initThreadedConsoleLogging()
  try:
-    consoleLogging.chan.send(ConsoleMessage(
+    ls.global.console.chan.send(ConsoleMessage(
      message: cla.formatter(msg),
      useStderr: cla.useStderr))
  except Exception:
@ -784,6 +659,67 @@ proc initFileLogAppender*(
    formatter: formatter,
    absPath: absolutePath(Path(filePath)))
  # TODO: initialize global state for the file log writer
 proc fileWriterLoop(gls: GlobalLogService) {.thread.} =
  const bufLen = 128
  var msgsByPath = newTable[Path, seq[FileMessage]]()
  while not gls.file.shutdown.load():
    var didSomething = false
    var msgBuf: array[bufLen, FileMessage]
    var recvIdx = 0
    var writeIdx = 0
    var dataAvailable = true
    while dataAvailable and recvIdx < bufLen:
      # Fill our message buffer if we can
      (dataAvailable, msgBuf[recvIdx]) = gls.file.chan.tryRecv()
      if dataAvailable: inc recvIdx
    # Organize messages by destination file
    msgsByPath.clear()
    while writeIdx < recvIdx:
      let msg = msgBuf[writeIdx]
      inc writeIdx
      if msg.message.len > 0:  # skip empty sentinel messages
        if not msgsByPath.contains(msg.absPath): msgsByPath[msg.absPath] = @[]
        msgsByPath[msg.absPath].add(msg)
        didSomething = true
    # Write all messages in file order to optimize file open/flush/close
    for path, msgs in pairs(msgsByPath):
      var f: File
      if not open(f, $path, fmAppend):
        # TODO: can we do better than silently failing here?
        continue
      for m in msgs:
        try: writeLine(f, m.message)
        except Exception: discard
      flushFile(f)
      close(f)
    # Wait a bit if we had no work to prevent busy waiting
    if not didSomething: sleep(100)
 proc initThreadedFileLogging(gls: GlobalLogService) =
  if gls.file.initialized.load(): return
  withLock gls.lock:
    if gls.file.initialized.load(): return
    gls.file.chan.open()
    gls.file.shutdown.store(false)
    # Create writer thread with reference to the service
    createThread(gls.file.writerThread, fileWriterLoop, gls)
    gls.file.initialized.store(true)
 method clone*(fla: FileLogAppender): LogAppender {.gcsafe.} =
  result = FileLogAppender(
@ -798,11 +734,11 @@ proc appendLogMessageMultiThreaded(
    ls: ref LogService,
    msg: LogMessage) {.gcsafe.} =
-  if not fileLogging.initialized.load():
+  if not ls.global.file.initialized.load():
-    initThreadedFileLogging()
+    ls.global.initThreadedFileLogging()
  try:
-    fileLogging.chan.send(FileMessage(
+    ls.global.file.chan.send(FileMessage(
      message: fla.formatter(msg),
      absPath: fla.absPath))
  except Exception: discard
@ -838,66 +774,14 @@ method appendLogMessage(
      "unable to append to FileLogAppender")
 # -----------------------------------------------------------------------------
 # StdLoggingAppender Implementation
 # -----------------------------------------------------------------------------
 func formatForwardedLog*(lm: LogMessage): string =
  ## Default formatter for the StdLoggingAppender that prepends the logger
  ## scope to the message before formatting the message via
  ## *formatSimpleTextLog*
  "[" & lm.scope & "] " & formatSimpleTextLog(lm)
 func initStdLoggingAppender*(
    fallbackOnly = true,
    formatter = formatForwardedLog,
    namespace = "",
    threshold = lvlAll): StdLoggingAppender {.gcsafe.} =
  result = StdLoggingAppender(
    namespace: namespace,
    threshold: threshold,
    fallbackOnly: fallbackOnly,
    formatter: formatter)
 method clone*(sla: StdLoggingAppender): LogAppender {.gcsafe.} =
  result = StdLoggingAppender(
    namespace: sla.namespace,
    threshold: sla.threshold,
    fallbackOnly: sla.fallbackOnly,
    formatter: sla.formatter)
 method appendLogMessage*(
    sla: StdLoggingAppender,
    ls: ThreadLocalLogService,
    msg: LogMessage) {.gcsafe.} =
  if sla.fallbackOnly and ls.appenders.len > 1: return
  stdlog.log(msg.level, sla.formatter(msg))
 # -----------------------------------------------------------------------------
 # Cleanup
 # -----------------------------------------------------------------------------
 addExitProc(proc() =
  shutdownThreadedConsoleLogging()
  shutdownThreadedFileLogging()
 )
 # -----------------------------------------------------------------------------
 # Tests
 # -----------------------------------------------------------------------------
 when isMainModule:
-  import std/[files, tempfiles, unittest]
+  import std/[tempfiles, unittest]
  import ./namespaced_logging/testutil
  # -----------------------------------------------------------------------------
  # Tests
  # -----------------------------------------------------------------------------
  suite "GlobalLogService Initialization":
@ -1021,7 +905,8 @@ when isMainModule:
    setup:
      let ls = threadLocalRef(initLogService())
      let loggedMsgs = initLoggedMessages()
-      ls.addAppender(initTestLogAppender(loggedMsgs))
+      let testAppender = initTestLogAppender(loggedMsgs)
      ls.addAppender(testAppender)
    test "getLogger creates logger with correct scope":
      let logger = ls.getLogger("api/users")
@ -1031,26 +916,6 @@ when isMainModule:
      let logger = ls.getLogger("api/users", some(lvlWarn))
      check ls.thresholds["api/users"] == lvlWarn
    test "log methods work":
      let logger = ls.getLogger("test")
      logger.log(lvlDebug, "debug string msg")
      logger.log(lvlInfo, %*{"message": "info json msg"})
      logger.log(lvlNotice, "notice string msg")
      logger.log(lvlError, newException(ValueError, "exception msg"), "error ex. msg")
      let lm = loggedMsgs.get()
      check:
        lm.len == 4
        lm[0].level == lvlDebug
        lm[0].message.contains("debug string msg")
        lm[1].level == lvlInfo
        lm[1].message.contains("info json msg")
        lm[2].level == lvlNotice
        lm[2].message.contains("notice string msg")
        lm[3].level == lvlError
        lm[3].message.contains("error ex. msg")
    test "logger convenience methods work":
      let logger = ls.getLogger("test")
@ -1099,7 +964,8 @@ when isMainModule:
    setup:
      let ls = threadLocalRef(initLogService())
      let loggedMsgs = initLoggedMessages()
-      ls.addAppender(initTestLogAppender(loggedMsgs))
+      let testAppender = initTestLogAppender(loggedMsgs)
      ls.addAppender(testAppender)
    test "root level filtering":
      ls.setRootThreshold(lvlInfo)
@ -1149,25 +1015,6 @@ when isMainModule:
        lm[0].scope == "api/users/detail"
        lm[0].level == lvlDebug
    test "message construction is avoided if the message is not logged":
      var expensiveCallCount = 0
      proc expensiveCall(): int =
        inc expensiveCallCount
        return expensiveCallCount
      ls.setThreshold("test", lvlInfo)
      let logger = ls.getLogger("test")
      logger.debug("Expensive call (" & $expensiveCall() & ")")
      logger.info("Expensive call (" & $expensiveCall() & ")")
      let lm = loggedMsgs.get()
      check:
        lm.len == 1
        lm[0].message.contains("Expensive call (1)")
        expensiveCallCount == 1
  suite "Appender Functionality":
    setup:
      let ls = threadLocalRef(initLogService())
@ -1266,8 +1113,6 @@ when isMainModule:
        lines.len == 1
        "test message" in lines[0]
      removeFile(pathStr)
    test "file appender clone":
      let original = initFileLogAppender("tempfile.log", namespace = "test")
      let cloned = clone(original)
@ -1276,107 +1121,3 @@ when isMainModule:
      let clonedFile = FileLogAppender(cloned)
      check clonedFile.absPath == original.absPath
      check clonedFile.namespace == "test"
  suite "StdLoggingAppender":
    var fileLogger: FileLogger
    var tempFile: File
    var tempFilename: string
    setup:
      let ls = threadLocalRef(initLogService())
      (tempFile, tempFilename) = createTempFile("stdlog_test", ".tmp.log")
      fileLogger = newFileLogger(tempFile, flushThreshold = lvlAll)
      addHandler(fileLogger)
    teardown:
      removeHandler(fileLogger)
      try: close(tempFile)
      except Exception: discard
      removeFile(tempFilename)
    test "forwards to std logging":
      ls.addAppender(initStdLoggingAppender())
      let logger = ls.getLogger("test")
      logger.debug("message at debug")
      logger.info("message at info")
      logger.error("message at error")
      tempFile.flushFile()
      close(tempFile)
      check open(tempFile, tempFilename, fmRead)
      let lines = toSeq(lines(tempFile))
      check:
        lines.len == 3
        lines[0] == "DEBUG [test] message at debug"
        lines[1] == "INFO [test] message at info"
        lines[2] == "ERROR [test] message at error"
    test "fallbackOnly works when on":
      ls.addAppender(initStdLoggingAppender())
      let logger = ls.getLogger("test")
      logger.debug("message at debug")
      logger.info("message at info")
      logger.error("message at error")
      let loggedMsgs = initLoggedMessages()
      ls.addAppender(initTestLogAppender(loggedMsgs))
      logger.notice("message at notice")
      logger.warn("message at warn")
      logger.fatal("message at fatal")
      tempFile.flushFile()
      close(tempFile)
      check open(tempFile, tempFilename, fmRead)
      let lines = toSeq(lines(tempFile))
      let lm = loggedMsgs.get()
      check:
        lines.len == 3
        lines[0] == "DEBUG [test] message at debug"
        lines[1] == "INFO [test] message at info"
        lines[2] == "ERROR [test] message at error"
        lm.len == 3
        lm[0].message.contains("message at notice")
        lm[1].message.contains("message at warn")
        lm[2].message.contains("message at fatal")
    test "fallbackOnly works when off":
      ls.addAppender(initStdLoggingAppender(fallbackOnly = false))
      let logger = ls.getLogger("test")
      logger.debug("message at debug")
      logger.info("message at info")
      logger.error("message at error")
      let loggedMsgs = initLoggedMessages()
      ls.addAppender(initTestLogAppender(loggedMsgs))
      logger.notice("message at notice")
      logger.warn("message at warn")
      logger.fatal("message at fatal")
      tempFile.flushFile()
      close(tempFile)
      check open(tempFile, tempFilename, fmRead)
      let lines = toSeq(lines(tempFile))
      let lm = loggedMsgs.get()
      check:
        lines.len == 6
        lines[0] == "DEBUG [test] message at debug"
        lines[1] == "INFO [test] message at info"
        lines[2] == "ERROR [test] message at error"
        lines[3] == "NOTICE [test] message at notice"
        lines[4] == "WARN [test] message at warn"
        lines[5] == "FATAL [test] message at fatal"
        lm.len == 3
        lm[0].message.contains("message at notice")
        lm[1].message.contains("message at warn")
        lm[2].message.contains("message at fatal")
--- a/src/namespaced_logging/autoconfigured.nim
+++ b/src/namespaced_logging/autoconfigured.nim
@ -0,0 +1,98 @@
 import std/[json, options]
 from logging import Level
 import ../namespaced_logging
 export
  # Types
  Level,
  Logger,
  LogAppender,
  LogMessage,
  ConsoleLogAppender,
  CustomLogAppender,
  CustomLogAppenderFunction,
  FileLogAppender,
  # Procs/Funcs
  `%`,
  initConsoleLogAppender,
  initCustomLogAppender,
  initFileLogAppender,
  formatJsonStructuredLog
 var globalLogServiceRef: ThreadLocalLogService = new(LogService)
 globalLogServiceRef[] = initLogService()
 var threadLocalLogServiceRef {.threadvar.}: ThreadLocalLogService
 var defaultLogger {.threadvar.}: Option[Logger]
 proc getThreadLocalLogServiceRef(): ThreadLocalLogService {.inline.} =
  if threadLocalLogServiceRef.isNil:
    threadLocalLogServiceRef = new(LogService)
    threadLocalLogServiceRef[] = globalLogServiceRef[]
  return threadLocalLogServiceRef
 proc getDefaultLogger(): Logger {.inline.} =
  if defaultLogger.isNone:
    defaultLogger = some(getThreadLocalLogServiceRef().getLogger(""))
  return defaultLogger.get
 proc useForAutoconfiguredLogging*(ls: LogService) =
  globalLogServiceRef[] = ls
 proc setRootLoggingThreshold*(lvl: Level) =
  setRootThreshold(getThreadLocalLogServiceRef(), lvl)
 proc setLoggingThreshold*(scope: string, lvl: Level) =
  setThreshold(getThreadLocalLogServiceRef(), scope, lvl)
 proc addLogAppender*(appender: LogAppender) =
  addAppender(getThreadLocalLogServiceRef(), appender)
 proc getLogger*(scope: string, lvl: Option[Level] = none[Level]()): Logger =
  getLogger(getThreadLocalLogServiceRef(), scope, lvl)
 proc log*(lvl: Level, msg: string) = getDefaultLogger().log(lvl, msg)
 proc log*(lvl: Level, msg: JsonNode) = getDefaultLogger().log(lvl, msg)
 proc log*(lvl: Level, error: ref Exception, msg: string) =
  getDefaultLogger().log(lvl, error, msg)
 template debug*[T](msg: T) = log(lvlDebug, msg)
 template info*[T](msg: T) = log(lvlInfo, msg)
 template notice*[T](msg: T) = log(lvlNotice, msg)
 template warn*[T](msg: T) = log(lvlWarn, msg)
 template error*[T](msg: T) = log(lvlError, msg)
 template error*(error: ref Exception, msg: string) = log(lvlError, error, msg)
 template fatal*[T](msg: T) = log(lvlFatal, msg)
 template fatal*(error: ref Exception, msg: string) = log(lvlFatal, error, msg)
 when isMainModule:
  import std/unittest
  import ./testutil
  suite "Autoconfigured Logging":
    setup:
      globalLogServiceRef[] = initLogService()
      let loggedMessages = initLoggedMessages()
      let testAppender = initTestLogAppender(loggedMessages)
    test "simple no-config logging":
      addLogAppender(testAppender)
      info("test message")
      let lm = loggedMessages.get()
      check:
        lm.len == 1
        lm[0].level == lvlInfo
        lm[0].message == "test message"