Logging

The Lightwheel SDK includes comprehensive logging capabilities to help you debug and monitor SDK operations.

Quick Setup

Basic Logging

from lightwheel_sdk.logger import setup_logger

# Setup logger with defaults
logger = setup_logger(name="my_app")

# Log messages
logger.info("Application started")
logger.debug("Debug information")
logger.warning("Warning message")
logger.error("Error occurred")
logger.critical("Critical error")

Custom Configuration

from lightwheel_sdk.logger import setup_logger

# Configure with custom settings
logger = setup_logger(
    name="my_app",
    level="DEBUG",
    log_file="/path/to/logfile.log"
)

Logging Levels

The SDK supports standard Python logging levels:

Level	Value	Description	Usage
DEBUG	10	Detailed diagnostic information	Development and troubleshooting
INFO	20	General informational messages	Normal operations
WARNING	30	Warning messages for potential issues	Non-critical issues
ERROR	40	Error messages for failures	Operation failures
CRITICAL	50	Critical errors that may stop the app	Severe errors

Environment Configuration

Set Log Level

export LW_SDK_LOG_LEVEL="DEBUG"

from lightwheel_sdk.loader import LightwheelClient

# Logger will use DEBUG level from environment
client = LightwheelClient(host="https://api.lightwheel.net")

Set Log File

export LW_SDK_LOG_FILE="/var/log/lightwheel/sdk.log"

The SDK will automatically create the log file and parent directories.

Logger Components

The SDK uses different logger names for different components:

Client Operations

# Logger: lightwheel_sdk.client
from lightwheel_sdk.loader import LightwheelClient

client = LightwheelClient(host="https://api.lightwheel.net")
# Logs: Initialization, API calls, authentication

Example logs:

2025-01-27 10:30:15,123 - lightwheel_sdk.client - INFO - Initializing LightwheelClient with host: https://api.lightwheel.net
2025-01-27 10:30:15,124 - lightwheel_sdk.client - INFO - Starting login process
2025-01-27 10:30:15,200 - lightwheel_sdk.client - INFO - Login successful for user: john_doe

Custom Logger

from lightwheel_sdk.logger import get_logger

# Get or create a logger
logger = get_logger("my_custom_logger")
logger.info("Custom log message")

Log Format

Default Format

%(asctime)s - %(name)s - %(levelname)s - %(message)s

Example output:

2025-01-27 10:30:15,123 - lightwheel_sdk.client - INFO - Initializing LightwheelClient

Custom Format

from lightwheel_sdk.logger import setup_logger

logger = setup_logger(
    name="my_app",
    format_string="[%(levelname)s] %(asctime)s | %(name)s | %(message)s"
)

Logging to File

Single File

from lightwheel_sdk.logger import setup_logger

logger = setup_logger(
    name="my_app",
    log_file="/var/log/my_app.log"
)

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

File Only (No Console)

import logging
from lightwheel_sdk.logger import setup_logger

logger = setup_logger(name="my_app", log_file="/var/log/my_app.log")

# Remove console handler
for handler in logger.handlers[:]:
    if isinstance(handler, logging.StreamHandler) and not isinstance(handler, logging.FileHandler):
        logger.removeHandler(handler)

Detailed Logging Examples

Debug HTTP Requests

import os
os.environ["LW_SDK_LOG_LEVEL"] = "DEBUG"

from lightwheel_sdk.loader import LightwheelClient

client = LightwheelClient(host="https://api.lightwheel.net")
client.login(username="user", password="pass")

# Logs every step:
# - HTTP POST request details
# - Request headers
# - Response status
# - Response body
response = client.post("/api/endpoint", data={"key": "value"})

Example debug output:

2025-01-27 10:30:15,123 - lightwheel_sdk.client - DEBUG - Making POST request to /api/endpoint
2025-01-27 10:30:15,124 - lightwheel_sdk.client - DEBUG - Making HTTP POST request to https://api.lightwheel.net/api/endpoint
2025-01-27 10:30:15,250 - lightwheel_sdk.client - DEBUG - HTTP POST request to https://api.lightwheel.net/api/endpoint completed with status 200
2025-01-27 10:30:15,251 - lightwheel_sdk.client - DEBUG - POST request to /api/endpoint completed successfully

Monitor Authentication

import os
os.environ["LW_SDK_LOG_LEVEL"] = "INFO"

from lightwheel_sdk.loader import LightwheelClient

client = LightwheelClient(host="https://api.lightwheel.net")
client.login(username="user", password="pass")

Output:

2025-01-27 10:30:15,123 - lightwheel_sdk.client - INFO - Initializing LightwheelClient with host: https://api.lightwheel.net
2025-01-27 10:30:15,124 - lightwheel_sdk.client - INFO - Starting login process
2025-01-27 10:30:15,125 - lightwheel_sdk.client - INFO - Performing fresh login
2025-01-27 10:30:15,126 - lightwheel_sdk.client - INFO - Performing authentication with API
2025-01-27 10:30:15,200 - lightwheel_sdk.client - INFO - Login credentials cached successfully
2025-01-27 10:30:15,201 - lightwheel_sdk.client - INFO - Login successful for user: user

Track Errors

import os
os.environ["LW_SDK_LOG_LEVEL"] = "ERROR"

from lightwheel_sdk.loader import LightwheelClient
from lightwheel_sdk.loader.exception import ApiException

client = LightwheelClient(host="https://api.lightwheel.net")

try:
    response = client.post("/api/invalid", data={})
except ApiException as e:
    # Error is automatically logged
    pass

Best Practices

Development

import os
os.environ["LW_SDK_LOG_LEVEL"] = "DEBUG"
os.environ["LW_SDK_LOG_FILE"] = "/tmp/lightwheel_debug.log"

Production

import os
os.environ["LW_SDK_LOG_LEVEL"] = "WARNING"
os.environ["LW_SDK_LOG_FILE"] = "/var/log/lightwheel/production.log"

Testing

import os
os.environ["LW_SDK_LOG_LEVEL"] = "ERROR"  # Reduce noise

Integration with Application Logging

import logging
from lightwheel_sdk.logger import setup_logger

# Configure root logger
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('/var/log/myapp.log'),
        logging.StreamHandler()
    ]
)

# Get SDK logger - it will inherit root config
sdk_logger = setup_logger("lightwheel_sdk")

# Your app logger
app_logger = logging.getLogger("myapp")

# Both loggers write to same destinations
app_logger.info("Application started")
sdk_logger.info("SDK initialized")

Disable Logging

import logging
from lightwheel_sdk.logger import get_logger

logger = get_logger("lightwheel_sdk.client")
logger.setLevel(logging.CRITICAL + 1)  # Disable all logging

Or via environment:

export LW_SDK_LOG_LEVEL="CRITICAL"