aiologger

Because actual stream initialization only occurs upon the first log call (lazy initialization), you can safely instantiate aiologger.Logger objects outside of a running asyncio event loop.

from aiologger import Logger

# This is safe to do before the loop starts
logger = Logger.with_default_handlers(name='my-logger')

By default, all data passed to log methods is nested under the msg key. You can use the flatten parameter to move dictionary keys to the root of the JSON object.

• As an instance attribute: Set flatten=True when initializing the logger to make all subsequent calls flattened.
• As a method parameter: Pass flatten=True to a specific log call to flatten only that entry.

Warning: Flattening can overwrite existing root-level keys (like logged_at).

# As an instance attribute
logger = JsonLogger.with_default_handlers(flatten=True)
await logger.info({"status_code": 200})
# Result: {"status_code": 200, "logged_at": "...", ...}

# As a method parameter
logger = JsonLogger.with_default_handlers()
await logger.info({"status_code": 200}, flatten=True)

Because actual stream initialization only occurs upon the first log call (lazy initialization), you can safely initialize aiologger.Logger instances outside of a running event loop.

import asyncio
from aiologger import Logger

# This is safe to do before the loop starts
logger = Logger.with_default_handlers(name='my-logger')

async def main():
    await logger.debug("debug")
    await logger.shutdown()

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

While aiologger is designed for asynchronous applications, its non-blocking behavior depends on the destination of the logs:

• stdout/stderr: Logging to standard output or standard error is fully async.
• Files on disk: Logging to files is NOT truly async. Because there is no stable async I/O interface for disk files in the OS, aiologger uses aiofiles, which utilizes a Thread Pool to perform writes.

If you require file logging, ensure you have aiofiles installed as an optional dependency.

The AsyncFileHandler requires an optional dependency to function. To ensure file operations are handled asynchronously, install aiologger with the [aiofiles] extra using pip.

pip install aiologger[aiofiles]

The JsonLogger is a drop-in replacement for the default aiologger.Logger. It ensures that all log output is valid, single-line JSON. It can handle strings, dictionaries, and complex objects (like datetime or exceptions) by serializing them into the msg field of the JSON log entry.

import asyncio
from aiologger.loggers.json import JsonLogger

async def main():
    logger = JsonLogger.with_default_handlers()
    await logger.info("Im a string")
    await logger.info({
        'key': 'value'
    })
    await logger.shutdown()

loop = asyncio.get_event_loop()
loop.run_until_complete(main())
loop.close()

To migrate from the standard Python logging module to aiologger:

1. Change Imports: Replace from logging import getLogger with from aiologger import Logger.
2. Change Instantiation: Replace logger = getLogger(__name__) with logger = Logger.with_default_handlers(name='your-name').
3. Handle Lifecycle: Ensure you call await logger.shutdown() to properly close handlers when your application exits.
4. Update Calls (Optional but Recommended): If log order is important, add await to your logging calls (e.g., await logger.info(...)).

You can use aiologger as a drop-in replacement for the standard logging library if you want to keep your existing synchronous syntax. Behind the scenes, logs will still be generated asynchronously.

To migrate, replace your standard logger initialization with aiologger.Logger.

Standard Library approach:

from logging import getLogger
logger = getLogger(__name__)
logger.info("message")

aiologger (Synchronous-style) approach:

from aiologger import Logger
logger = Logger.with_default_handlers()
logger.info("message")

Note: When using the synchronous-style calls without await, the output order is not guaranteed.

from aiologger import Logger

logger = Logger.with_default_handlers()
logger.info("info")

Install the aiologger package using pip to enable asynchronous, non-blocking logging for your Python asyncio applications.

pip install aiologger