labFusion/services/service-adapters/LOGGING.md

Unified Logging Configuration

This document describes the unified logging setup and usage in the LabFusion Service Adapters.

Overview

The service adapters use Python's built-in logging module with a centralized configuration system that provides unified logging for both application logs and incoming request logs. All logs use the same format, handler, and configuration for consistency and easier monitoring.

Logging Levels

• DEBUG: Detailed information for debugging (status checker operations)
• INFO: General information about application flow
• WARNING: Warning messages for non-critical issues
• ERROR: Error messages for failed operations
• CRITICAL: Critical errors that may cause application failure

Configuration

Logging is configured in services/logging_config.py with unified settings:

• Root Level: INFO
• Status Checker: DEBUG (detailed health check logging)
• Routes: INFO (API endpoint logging)
• Request Logging: INFO (unified with application logs)
• HTTP Client: WARNING (reduced verbosity)
• Unified Handler: Single handler for all log types

Log Format

Unified Format (same for application and request logs):

2024-01-15 10:30:45,123 - services.status_checker - INFO - status_checker.py:140 - Starting health check for 4 services
2024-01-15 10:30:45,124 - uvicorn.access - INFO - logging_middleware.py:45 - Request started: GET /services from 192.168.1.100
2024-01-15 10:30:45,125 - routes.general - INFO - general.py:78 - Service status endpoint called - checking all services
2024-01-15 10:30:45,126 - uvicorn.access - INFO - logging_middleware.py:55 - Request completed: GET /services -> 200 in 0.123s

Format includes:

• Timestamp
• Logger name (unified across all log types)
• Log level
• Filename and line number
• Message

Usage Examples

Basic Logging

import logging
from services.logging_config import get_logger

logger = get_logger(__name__)

logger.debug("Debug information")
logger.info("General information")
logger.warning("Warning message")
logger.error("Error occurred")

Request Logging

from services.logging_config import get_request_logger

request_logger = get_request_logger()
request_logger.info("Custom request log message")

Application Logging

from services.logging_config import get_application_logger

app_logger = get_application_logger()
app_logger.info("Application-level log message")

Service Status Logging

The status checker automatically logs:

• Health check start/completion
• Individual service responses
• Response times
• Error conditions
• Authentication status

API Endpoint Logging

Routes log:

• Endpoint calls
• Request processing
• Response generation

Request Middleware Logging

The logging middleware automatically logs:

• Request start (method, path, client IP, user agent)
• Request completion (status code, processing time)
• Request errors (exceptions, processing time)

Debug Endpoint

A debug endpoint is available at /debug/logging to:

• Test unified log levels across all logger types
• View current configuration
• Verify unified logging setup
• Test request, application, and route loggers

Environment Variables

You can control logging behavior with environment variables:

# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
export LOG_LEVEL=DEBUG

# Disable timestamps
export LOG_NO_TIMESTAMP=true

Log Files

Currently, logs are output to stdout. For production, consider:

• File logging with rotation
• Structured logging (JSON)
• Log aggregation (ELK stack, Fluentd)
• Log levels per environment

Troubleshooting

No Logs Appearing

1. Check log level configuration
2. Verify logger names match module names
3. Ensure logging is initialized before use

Too Many Logs

1. Increase log level to WARNING or ERROR
2. Disable DEBUG logging for specific modules
3. Use log filtering

Performance Impact

1. Use appropriate log levels
2. Avoid logging in tight loops
3. Consider async logging for high-volume applications

Best Practices

1. Use appropriate levels: DEBUG for development, INFO for production
2. Include context: Service names, request IDs, user information
3. Structured messages: Consistent format for parsing
4. Avoid sensitive data: No passwords, tokens, or personal information
5. Performance: Log asynchronously when possible
6. Monitoring: Set up alerts for ERROR and CRITICAL levels