3.1 KiB

Raw Blame History

Error Handling Strategy

This section defines a unified strategy for error handling and logging across the application. The primary goals are to ensure that errors are handled gracefully, and that logs are structured, informative, and actionable.

General Approach

The application will use a centralized logging configuration initialized at startup. All logging will be structured (JSON format) to facilitate machine parsing and analysis, especially in preparation for future integration with log aggregation services (e.g., AWS CloudWatch, Datadog).

Logging Standards

Library: Python's built-in logging module will be used. It is powerful, flexible, and requires no external dependencies.
Format: All logs will be output as a single-line JSON object. This ensures consistency and makes them easy to parse and query.

Example Log Format

{
  "timestamp": "2025-10-18T03:07:43Z",
  "level": "INFO",
  "message": "Content generation for project 123 complete.",
  "module": "src.generation.service",
  "context": {
    "correlation_id": "job-run-xyz-789",
    "project_id": 123,
    "user_id": 1
  }
}

Log Levels

DEBUG: Detailed information, typically of interest only when diagnosing problems. (e.g., API request bodies, specific function inputs).
INFO: Confirmation that things are working as expected. (e.g., "Job run started", "File deployed successfully").
WARNING: An indication that something unexpected happened, or indicative of some problem in the near future (e.g., 'disk space low'). The software is still working as expected. (e.g., "Retrying API call, 2 of 3").
ERROR: Due to a more serious problem, the software has not been able to perform some function. This is for handled exceptions. The error should be logged with a full stack trace.
CRITICAL: A serious error, indicating that the program itself may be unable to continue running.

Required Context

To make logs useful, the following context must be included wherever possible:

Correlation ID:
- For CLI jobs, a unique ID will be generated at the start of each job run and passed through all subsequent function calls.
- For the Internal API, a FastAPI middleware will generate a unique request ID and attach it to every log message within that request's lifecycle.
Service Context: The logger configuration will automatically include the module and function name (%(name)s, %(funcName)s) where the log was emitted.
User Context: For any authenticated action (CLI or API), the user_id must be included in the log's context.

Error Handling Patterns

Exception Handling: All expected errors (e.g., file not found, API connection error) will be caught in try...except blocks. When an exception is caught and handled, it will be logged at the ERROR level, including the full stack trace.
API Errors: The FastAPI application will use a global exception handler to catch any unhandled errors, log them with a CRITICAL level, and return a standardized 500 Internal Server Error response to the client, ensuring no internal details or stack traces are leaked.

3.1 KiB Raw Blame History