Usage¤

A quick note about environment variables¤

The exemples showcase various environment variable settings with the with_env("LOGGIA_ENV_VARIABLE", "value"). You are of course not encouraged to modify the environment at runtime, and instead to use the usual mechanisms, like .env files, CI variables, shell initialization files, Kubernetes settings or what have you.

Simplest usage¤

# Setup
from loggia.logger import initialize

# One-line setup -- get the default config from environment variables
initialize()

# Using the standard logger will now benefit from Loggia configuration
import logging

logger = logging.getLogger(__name__)
logger.info("Hello world!")

With this setup, you get a default logger, with a default configuration. It supports JSON structured logging, and it is configured to work with DataDog. You can configure it using environment variables.

Use with Loguru¤

Note

You do not have to use Loguru --- but if you already adopted it, Loggia will configure it to interop with Python's standard logging library.

This library will automatically add to new log levels to match Loguru configuration:

TRACE (level 5)
SUCCESS (level 25)

...

# Setup
from loggia.logger import initialize

initialize()

# Use loguru
import loguru

loguru.logger.info("Hello world loguru!")

# Using standard logger should still work uniformly
import logging

logger = logging.getLogger()
logger.info("Hello world std_lib!")

You can opt out of this interop through the capture_loguru setting.

Warning

While we try to have the same log management for loguru and standard logging, there are some differences. Even in this example, you can notice the name of the loggers is different.

Make the output pretty using the `dev` preset¤

# We're forcing the `dev` preset to fill the `main` slot
with_env("LOGGIA_PRESETS", "dev")

from loggia.logger import initialize

initialize()

import logging

logging.getLogger("test").warning("hello from logging", extra={"with_extra": "100% yes!"})  # Will show up colored

See the Presets documentation for more information.

Set level to TRACE using the API¤

# Setup

from loggia.conf import LoggerConfiguration
from loggia.logger import initialize

# Prepare a configuration
# Here, debug_show_config will be ignored because it's not a boolean!
log_config = LoggerConfiguration()
log_config.set_general_level(5)  # This is the numerical level for 'TRACE'

initialize(log_config)

# Use just like the standard logger
import logging

logger = logging.getLogger(__name__)
logger.info("Hello world!")
logger.log(5, "Hello trace")  # Sending a trace with typings OK
logger.log(4, "Hello? Hello?")  # This will not show up

You probably want to configure the standard Python logger as well, e.g., to change the log level for some libraries.

This is done using environment variables LOGGIA_SUB_LEVEL, or by using calling set_logger_level.

# Setup
from loggia.conf import LoggerConfiguration
from loggia.logger import initialize

# Force colored logging, even if environment variables is set
log_config = LoggerConfiguration(
    settings={
        "LOGGIA_SUB_LEVEL": "test.warn_only:WARNING",
    },
    presets=["dev"],
)
initialize(log_config)

# Use just like the standard logger
import logging

logger = logging.getLogger("test")
logger.info("Hello world first!")
logger = logging.getLogger("test.warn_only")
logger.info("Hello world bis is not shown")
logger.warning("Warning are shown")

Configure the standard logger¤

Be careful, the handler is called default

Using the TRACE level from the standard logger¤

To be compatible with loguru, and have similar levels to other loggers, we extended the standard logger to expose a trace level at priority 5.