Quick Start¶

# Just import and log - it works automatically!
from logly import logger

logger.info("Hello, Logly!")         # ✅ Logs appear immediately (white)
logger.success("Task completed!")     # ✅ Green color
logger.warning("This works right away!")  # ✅ Yellow color  
logger.error("Connection failed!")    # ✅ Red color
logger.fail("Login failed!")          # ✅ NEW: Magenta color

# Logs appear automatically because:
# - Auto-configure runs on import
# - auto_sink=True creates console sink automatically
# - console=True enables logging globally

from logly import logger

# Configure logging level and output format (optional)
logger.configure(
    level="INFO",      # Minimum log level (default: "INFO")
    color=True,        # Colored output for console (default: True)
    console=True,      # Global enable/disable ALL logging (default: True)
    auto_sink=True     # Auto-create console sink (default: True)
)

# Start logging with your custom config
logger.info("Logging with custom configuration")

# Add a file sink (logs go to both console and file)
file_id = logger.add("app.log")

# Or disable auto console sink and use only files
logger.configure(auto_sink=False)  # No automatic console sink
logger.add("app.log")  # Manual file sink only

from logly import logger

# All levels with their default colors (when color=True)
logger.trace("Entering function")       # Cyan - most verbose
logger.debug("Variable x = 42")         # Blue  
logger.info("Server started")           # White
logger.success("Payment processed")     # Green
logger.warning("Disk space low")        # Yellow
logger.error("Database timeout")        # Red
logger.critical("System crash!")        # Bright Red
logger.fail("Authentication failed")    # Magenta - NEW in v0.1.5

# Log messages at different levels with context
logger.info("Application started", version="1.0.0", port=8000)
logger.debug("Debug information", step=1, data={"key": "value"})
logger.success("User created", user_id=123, email="user@example.com")

# Log warnings and errors
logger.warning("Low disk space", available_gb=2.5)
logger.error("Failed to connect", retry_count=3, reason="timeout")
logger.fail("Payment failed", card_last4="1234", reason="insufficient_funds")
logger.critical("System out of memory")

# Always call complete() before exit
logger.complete()

from logly import logger

# Method 1: Using the callable logger (recommended)
custom_logger = logger(auto_update_check=False)
custom_logger.configure(level="INFO", color=True)

# Method 2: Using PyLogger directly
from logly import PyLogger
direct_logger = PyLogger(auto_update_check=False)
direct_logger.configure(level="INFO", color=True)

from logly import logger

# Method 1: Enable during initialization (recommended for new loggers)
debug_logger = logger(
    internal_debug=True,
    debug_log_path="logly_debug.log"  # Optional, defaults to "logly_debug.log"
)

# Now all internal operations are logged
debug_logger.info("This is logged normally")
# Internal debug log captures: sink operations, config changes, etc.

from logly import logger

def main():
    # Configure
    logger.configure(level="INFO", color=True)

    # Add sinks
    logger.add("console")
    logger.add("logs/app.log", rotation="daily", retention=7)

    # Log messages
    logger.info("Application starting", version="1.0.0")

    try:
        # Your application logic
        process_data()
        logger.success("Processing complete")

    except Exception as e:
        logger.exception("Application error")
        raise

    finally:
        # Cleanup
        logger.complete()

def process_data():
    logger.debug("Processing data", records=1000)
    # ... processing logic ...
    logger.info("Data processed successfully")

if __name__ == "__main__":
    main()

from logly import logger
from fastapi import FastAPI, Request

app = FastAPI()

# Configure once at startup
@app.on_event("startup")
async def setup_logging():
    logger.configure(level="INFO", json=True)
    logger.add("console")
    logger.add("logs/api.log", rotation="hourly", retention=24)

# Log requests
@app.middleware("http")
async def log_requests(request: Request, call_next):
    request_logger = logger.bind(
        request_id=request.headers.get("X-Request-ID", "unknown"),
        method=request.method,
        path=request.url.path
    )

    request_logger.info("Request received")
    response = await call_next(request)
    request_logger.info("Response sent", status=response.status_code)

    return response

@app.get("/api/users/{user_id}")
async def get_user(user_id: int):
    logger.info("Fetching user", user_id=user_id)
    # ... fetch user logic ...
    return {"user_id": user_id, "name": "Alice"}

from logly import logger
import time

def process_batch(batch_id, items):
    batch_logger = logger.bind(batch_id=batch_id)
    batch_logger.info("Batch started", items=len(items))

    for idx, item in enumerate(items):
        with batch_logger.contextualize(item_id=item.id):
            try:
                # Process item
                process_item(item)
                batch_logger.debug("Item processed", progress=f"{idx+1}/{len(items)}")
            except Exception:
                batch_logger.exception("Item failed")

    batch_logger.success("Batch complete", duration=time.time())

def main():
    logger.configure(level="INFO")
    logger.add("console")
    logger.add("logs/batch.log", rotation="daily")

    batches = get_batches()
    for batch_id, items in enumerate(batches):
        process_batch(batch_id, items)

    logger.complete()

if __name__ == "__main__":
    main()

from logly import logger

def alert_on_errors(record):
    """Send alerts for critical errors"""
    if record.get("level") == "CRITICAL":
        send_slack_alert(f"🚨 Critical: {record['message']}")

def collect_metrics(record):
    """Collect metrics from logs"""
    if record.get("level") == "ERROR":
        increment_error_counter()

def main():
    logger.configure(level="INFO")
    logger.add("console")

    # Register callbacks
    logger.add_callback(alert_on_errors)
    logger.add_callback(collect_metrics)

    # Application logic
    logger.info("Application started")

    try:
        risky_operation()
    except Exception:
        logger.exception("Operation failed")  # Triggers callbacks

    logger.complete()

if __name__ == "__main__":
    main()

# Examples
logger.trace("Function called", args={"x": 1, "y": 2})
logger.debug("Variable value", x=42)
logger.info("User logged in", user="alice")
logger.success("Payment processed", amount=99.99)
logger.warning("API rate limit approaching", remaining=10)
logger.error("Database connection failed", retry_count=3)
logger.critical("System out of memory", available_mb=10)

logger.configure(json=False, color=True)
logger.info("User logged in", user="alice", ip="192.168.1.1")

logger.configure(json=True, pretty_json=False)
logger.info("User logged in", user="alice", ip="192.168.1.1")

logger.configure(json=True, pretty_json=True)
logger.info("User logged in", user="alice", ip="192.168.1.1")

from logly import logger

# Add file sink with custom time format
logger.add(
    "logs/app.log",
    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}"
)

logger.info("Server started")

# Date-only format
logger.add("console", format="{time:YYYY-MM-DD} [{level}] {message}")
# Output: 2025-10-11 [INFO] User logged in

# Date and time with milliseconds
logger.add("console", format="{time:YYYY-MM-DD HH:mm:ss.SSS} {message}")
# Output: 2025-10-11 13:46:27.324 Database query completed

# ISO 8601 format
logger.add("console", format="{time:YYYY-MM-DDTHH:mm:ss} {level} {message}")
# Output: 2025-10-11T13:46:27 INFO Request processed

# Month names
logger.add("console", format="{time:MMMM DD, YYYY} - {message}")
# Output: October 11, 2025 - System initialized

# 12-hour format with AM/PM
logger.add("console", format="{time:hh:mm:ss A} {message}")
# Output: 01:46:27 PM Application ready

# Daily rotation (new file every day at midnight)
logger.add("logs/app.log", rotation="daily", retention=7)

# Hourly rotation
logger.add("logs/app.log", rotation="hourly", retention=24)

# Minutely rotation (for testing)
logger.add("logs/app.log", rotation="minutely", retention=60)

# Rotate when file reaches 10MB
logger.add("logs/app.log", size_limit="10MB", retention=5)

# Combine time and size rotation
logger.add("logs/app.log", rotation="daily", size_limit="500MB", retention=7)

# Various size formats (case-insensitive):
logger.add("logs/tiny.log", size_limit="100")       # 100 bytes
logger.add("logs/small.log", size_limit="500b")     # 500 bytes (lowercase)
logger.add("logs/medium.log", size_limit="5kb")     # 5 kilobytes (lowercase)
logger.add("logs/large.log", size_limit="10M")      # 10 megabytes (short form)
logger.add("logs/huge.log", size_limit="1gb")       # 1 gigabyte (lowercase)

# Keep last 7 rotated files (older files auto-deleted)
logger.add("logs/app.log", rotation="daily", retention=7)

# Unlimited retention (set to None)
logger.add("logs/app.log", rotation="daily", retention=None)

# Create logger with persistent context
request_logger = logger.bind(request_id="r-123", user="alice")

# All logs include context
request_logger.info("Request started")
# Output: ... request_id=r-123 user=alice

request_logger.error("Request failed")
# Output: ... request_id=r-123 user=alice

request_logger = logger.bind(request_id="r-123")

with request_logger.contextualize(step="validation"):
    request_logger.debug("Validating input")
    # Output: ... request_id=r-123 step=validation

request_logger.info("Validation complete")
# Output: ... request_id=r-123 (no step field)

# As decorator (swallow exception)
@logger.catch(reraise=False)
def may_fail():
    return 1 / 0  # Exception logged, not raised

# As decorator (re-raise)
@logger.catch(reraise=True)
def critical_operation():
    risky_code()  # Exception logged and re-raised

# As context manager
with logger.catch(reraise=True):
    dangerous_operation()

# Manual exception logging
try:
    risky_operation()
except Exception:
    logger.exception("Operation failed", operation="data_sync")

from logly import logger

# Add sinks and store their IDs
console_id = logger.add("console")
app_log_id = logger.add("logs/app.log")
debug_log_id = logger.add("logs/debug.log")

# Disable debug file in production
import os
if os.getenv("ENV") == "production":
    logger.disable_sink(debug_log_id)

logger.info("Application started")  # → console + app.log only

# Enable debug file for troubleshooting
logger.enable_sink(debug_log_id)
logger.debug("Detailed diagnostics")  # → all three sinks

# Check sink status
if logger.is_sink_enabled(debug_log_id):
    logger.info("Debug logging is active")

# 1. Always call complete() before exit
logger.complete()

# 2. Use appropriate log levels
logger.error("Connection failed", retry=3)  # Error condition
logger.info("User logged in", user="alice")  # Normal info

# 3. Include context
request_logger = logger.bind(request_id=req_id)
request_logger.info("Processing")

# 4. Configure once at startup
logger.configure(level="INFO", json=True)
logger.add("console")
logger.add("logs/app.log", rotation="daily")

# 1. Don't log sensitive data
logger.info("Login attempt", password=password)  # ❌ Security risk

# 2. Don't log in tight loops without filtering
for i in range(1000000):
    logger.debug(f"Iteration {i}")  # ❌ Performance hit

# 3. Don't forget cleanup
# ... logging ...
# (missing logger.complete())  # ❌ Buffered logs may be lost

# 4. Don't use string concatenation
logger.info("User " + user + " logged in")  # ❌ Use structured logging instead

# 5. Don't configure multiple times
logger.configure(level="INFO")
logger.configure(level="DEBUG")  # ❌ Configure once