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
```python
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
```python
from services.logging_config import get_request_logger

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

### Application Logging
```python
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:

```bash
# 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