Getting Started Guide¶

Welcome to Logly! This guide will walk you through installing Logly and setting up your first logging configuration. By the end, you'll have a working logging setup that you can customize for your needs.

Prerequisites¶

Before you begin, ensure you have:

Python 3.10+ installed
pip package manager
Basic familiarity with Python

Step 1: Installation¶

pip (Recommended)uvpoetryFrom Source

pip install logly

uv add logly

poetry add logly

git clone https://github.com/muhammad-fiaz/logly.git
cd logly
pip install -e .

Step 2: Basic Setup¶

NEW in v0.1.5: Just import and log - no configuration needed!

# app.py
from logly import logger

# That's it! Start logging immediately
logger.info("Application started")      # ✅ Works right away
logger.warning("This is a warning")     # ⚠️ No configure() needed  
logger.error("This is an error")        # ❌ Auto-configured on import

print("Check your console output above!")

Why it works: - Logger is auto-configured on import (since v0.1.5) - Default settings: console=True, auto_sink=True - Console sink created automatically - File sinks are NEVER automatic - add them explicitly with logger.add("file.log")

Optional: Customize Configuration¶

If you need custom settings, call configure():

from logly import logger

# Customize logging (optional)
logger.configure(
    level="DEBUG",     # Change minimum log level
    color=True,        # Enable colors
    show_time=True     # Show timestamps
)

logger.debug("Debug messages now visible")

Run it:

python app.py

You should see colored output like:

2025-01-15 10:30:45 | INFO  | Application started
2025-01-15 10:30:45 | WARN  | This is a warning
2025-01-15 10:30:45 | ERROR | This is an error

Step 3: Understanding the Basics¶

Log Levels¶

Logly supports standard logging levels:

logger.debug("Detailed debug information")
logger.info("General information")
logger.warning("Warning messages")
logger.error("Error messages")
logger.critical("Critical errors")

Extra Data¶

Add extra fields to your logs:

logger.info("Request processed",
           method="POST",
           url="/api/users",
           status_code=200,
           response_time=0.145)

Step 4: File Logging¶

Let's add file logging to persist your logs:

from logly import logger

logger.configure(
    level="INFO",
    format="{time} | {level} | {message}",
    sinks=[
        {
            "type": "console"  # Keep console logging
        },
        {
            "type": "file",
            "path": "app.log"  # Log to file
        }
    ]
)

logger.info("This goes to both console and file")

Now check app.log - it should contain your log messages.

Step 5: Adding Context¶

Context helps track related operations:

from logly import logger

# Set up logging
logger.configure(
    level="INFO",
    format="{time} | {level} | {context} | {message}"
)

# Add persistent context
logger.bind(user_id=12345, session_id="abc-123")

logger.info("User authentication started")
logger.info("Credentials validated")

# Temporary context for specific operations
with logger.contextualize(request_id="req-456"):
    logger.info("Processing request")
    logger.info("Request completed")

logger.info("Session ended")

Step 6: Exception Handling¶

Logly makes exception handling easy:

from logly import logger, catch

logger.configure(level="INFO")

@catch(level="ERROR", message="Function failed")
def risky_operation():
    raise ValueError("Something went wrong!")

# This will log the error automatically
result = risky_operation()

Step 7: Production Configuration¶

For production, consider this setup:

import os
from logly import logger

# Production configuration
logger.configure(
    level=os.getenv("LOG_LEVEL", "INFO"),
    format="{time} | {level} | {file}:{line} | {message}",
    sinks=[
        {
            "type": "console",
            "level": "INFO"
        },
        {
            "type": "file",
            "path": "/var/log/app.log",
            "level": "DEBUG",
            "rotation": "100 MB",
            "retention": "30 days"
        }
    ]
)

Step 8: Next Steps¶

Now that you have the basics, explore:

Configuration Guide: Advanced configuration options
Examples: Real-world usage examples
API Reference: Complete API documentation

Troubleshooting¶

Common Issues¶

No output? - Check your log level - messages below the configured level are filtered out - Ensure you're calling logger.configure() before logging

Import error? - Verify Logly is installed: pip list | grep logly - Check Python version: python --version (needs 3.10+)

Colors not showing? - Some terminals don't support colors - try setting colorize: false in console sink

Getting Help¶

Check the API Reference for detailed documentation
Look at Examples for common patterns
File an issue on GitHub

Summary¶

You've now learned: - ✅ How to install Logly - ✅ Basic console and file logging - ✅ Log levels and formatting - ✅ Context binding - ✅ Exception handling - ✅ Production configuration

Your logging setup is ready! Customize it further based on your application's needs.