NexusLog

High-performance async logging library, compatible with Python standard logging API.

中文文档

Benchmark

Benchmarking with 1,000,000 log messages

------------------------------------------------------------
Logger               Time (s)     Msgs/sec        Log size    
------------------------------------------------------------
loguru               7.675        130,297         89,888,890 bytes
Python logging       5.313        188,206         82,888,890 bytes
picologging          2.038        490,626         79,888,888 bytes
spdlog               0.199        5,034,527       79,888,890 bytes
NexusLogger          0.049        20,304,036      97,888,890 bytes
NexusLogger unix_ts  0.049        20,451,884      83,868,922 bytes
------------------------------------------------------------

NexusLogger is 4.03x faster than spdlog
NexusLogger is 41.38x faster than picologging
NexusLogger is 107.88x faster than Python logging
NexusLogger is 155.83x faster than loguru
NexusLogger unix_ts is 4.06x faster than spdlog
NexusLogger unix_ts is 41.69x faster than picologging
NexusLogger unix_ts is 108.67x faster than Python logging
NexusLogger unix_ts is 156.96x faster than loguru

Installation

pip install nexuslog

Quick Start

import nexuslog as logging

logging.basicConfig(level=logging.INFO)

logging.info("Hello, world!")
logging.warning("This is a warning")
logging.error("This is an error")

API

Log Levels

logging.TRACE
logging.DEBUG
logging.INFO
logging.WARNING
logging.ERROR

Module-level Functions

logging.basicConfig(filename=None, level=logging.INFO, unix_ts=False, color="auto", format="logfmt")
logging.basicConfig(
    level=logging.INFO,
    name_levels={"db": logging.DEBUG, "http.client": logging.WARNING},
)
logging.trace(message, *args)
logging.debug(message, *args)
logging.info(message, *args)
logging.warning(message, *args)
logging.error(message, *args)

Lazy %-style Formatting

Like the standard logging module, extra arguments are merged into the message with %-style formatting — but only if the log level is enabled. When the level is disabled, the arguments are never formatted (no str()/repr() calls), making disabled log calls nearly free:

logger.info("price=%s qty=%s side=%s", price, qty, side)
logger.debug("state=%r retries=%d", state, retries)  # zero cost at INFO level

Supported conversions: %s %r %d %i %f %e %g %x %o %%, plus the full % operator spec (width, precision, flags, %(name)s with a dict argument) with semantics identical to Python's message % args. Simple placeholders are rendered natively in Rust — formatting with args is faster than building the message with an f-string at the call site. A message logged without args is emitted verbatim, so literal % needs no escaping.

Colored Output

logging.basicConfig(color="auto")  # default

The color option controls ANSI colorization of the level value (by severity) and the logfmt keys (dimmed):

• "auto" (default) — color only when writing to a color-capable terminal. File and piped output stay plain. Honors the NO_COLOR (force off) and FORCE_COLOR (force on) environment variables; NO_COLOR wins.
• "off" — never emit ANSI color.
• "always" — always emit ANSI color, even to files and pipes.

Colors: error red, warn yellow, info green, debug cyan, trace dim. The message body is never colored. There is no cost on the hot path when color is inactive.

JSON Output

logging.basicConfig(filename="app.log", format="json")

format selects the line layout:

• "logfmt" (default) — time=... level=... [name=...] msg="...".

• "json" — one JSON object per line (NDJSON):

  {"time":"2026-07-09T09:45:59.914644+08:00","level":"warn","name":"svc","msg":"disk 90% full"}
  

  Fields are {time, level, name, msg}, with proper JSON escaping of the message. time is an ISO-8601 string, or a number when unix_ts=True. name is omitted when unset. JSON output ignores color (it is never colorized).

NDJSON is the recommended format for shipping logs to a database: write to a file, then let a forwarder (Vector, Fluent Bit, Fluentd, Logstash) tail it and insert into ClickHouse / PostgreSQL / etc. — the JSON parses with near-zero configuration.

Logger Class

from nexuslog import Logger, Level

logger = Logger("myapp", path="/var/log/app", level=Level.Info)
logger.info("message")
logger.shutdown()

getLogger

import nexuslog as logging

logging.basicConfig(filename="/var/log/app.log", level=logging.DEBUG)
logger = logging.getLogger("myapp")
logger.info("message")

License

MIT