convlogpy 0.1.2

A python logger build on top of logging base in conventionallogs

ConvLogPy

ConvLogPy is a lightweight JSON logger built on top of Python's standard logging module. It outputs structured logs to stdout and/or files, making them easy to parse, search, and aggregate in modern log management systems.

Features

• Singleton logger instance per process to ensure consistent configuration
• JSON-formatted logs with:
  • severity
  • scope
  • message
  • timestamp (ISO 8601, UTC with Z suffix)
• Optional custom fields under fields (e.g. user_id, ip)
• Automatic enrichment of error logs with:
  • module
  • function
  • line
• Flexible file logging with multiple handler types:
  • Standard file handler
  • Size-based rotating file handler
  • Time-based rotating file handler
• Log rotation with configurable limits
• Directory auto-creation for log files
• Variable debugging decorator for function-level inspection

Installation

pip install convlogpy

Quick Start

Basic Example

from convlogpy import ConvLogPy

logger = ConvLogPy(scope="web-app")

logger.info("User login successful", user_id=123, ip="192.168.1.1")
logger.error("User login failed", username="Bob")

Example output:

{
  "severity": "INFO",
  "scope": "web-app",
  "message": "User login successful",
  "timestamp": "2026-01-21T19:55:00.000000Z",
  "fields": {
    "user_id": 123,
    "ip": "192.168.1.1"
  }
}

{
  "severity": "ERROR",
  "scope": "web-app",
  "message": "User login failed",
  "timestamp": "2026-01-21T19:55:01.000000Z",
  "fields": {
    "username": "Bob"
  },
  "module": "views",
  "function": "login",
  "line": 42
}

Core Features

Logging Methods

ConvLogPy exposes the standard logging methods:

logger.debug("Debug message", foo="bar")
logger.info("Info message")
logger.warning("Warning message", context="auth")
logger.error("Error message", error_code=500)
logger.critical("Critical issue", system="payments")
logger.exception("Exception occurred", traceback=exc_info)

All keyword arguments passed to these methods are added under the fields key.

Scope

You can set a default scope at initialization:

logger = ConvLogPy(scope="billing-service")

You can also override it per log call:

logger.info("Processing payment", scope="payment-worker", order_id=42)

Console vs File Logging

By default, logs go to stdout. You can disable console output:

# Disable console logging
logger = ConvLogPy(scope="service", console=False)

# Add file handlers only
logger.add_file_handler("app.log")

File Logging

Basic File Handler

logger = ConvLogPy(scope="my-app", console=False)

# Add a simple file handler
logger.add_file_handler("logs/app.log")

# Add error-only logs to separate file
logger.add_file_handler("logs/error.log", level=40)  # 40 = logging.ERROR

# Log messages
logger.info("Application started")
logger.error("Something went wrong", error_code=500)

Debug

Debug function local variables and arguments

log = convlogpy.ConvLogPy(scope="function.admin")
@log.debug_vars(['t', 'x', 's']) # Enter only variable you want to retrieve value after function execution, usefull to debugging without modify your function
def my_function(age=10):
    x = None
    t = 1
    age += 10
    s = "je suis deja la"