production trust and operations diagnostics

README.md

@@ -625,6 +625,21 @@ For detailed testing instructions, see [TESTING.md](TESTING.md).
 
 ## 🚀 Performance & Production
 
+### Production Diagnostics
+
+Run production diagnostics before deploying database logging:
+
+```bash
+python manage.py drf_api_logger_doctor
+python manage.py drf_api_logger_doctor --format json
+python manage.py drf_api_logger_doctor --fail-level warning
+```
+
+The doctor command is read-only. It checks logging mode, database readiness,
+migrations, table availability, queue settings, worker status, payload limits,
+masking configuration, and profiling risk. Use `--fail-level error` when a
+deployment should fail only for blocking misconfiguration.
+
 ### Database Optimization
 
 For high-traffic applications:

TESTING.md

@@ -63,6 +63,7 @@ make check-package
 - `tests/test_middleware.py`: request/response logging, filtering, tracing, body limits, and content types.
 - `tests/test_models.py`: model fields, admin display, filters, and CSV export.
 - `tests/test_signals.py`: event listeners, background queue behavior, app startup, and worker stats.
+- `tests/test_diagnostics.py`: production doctor checks for logging mode, database readiness, queue status, payload limits, masking, and profiling risk.
 - `tests/test_observability.py`: dependency-free Prometheus, OpenTelemetry, and Sentry helper behavior.
 - `tests/test_policy.py`: logging policy decisions, endpoint rules, callable overrides, extra mask keys, and safe failure behavior.
 - `tests/test_profiling.py`: profiling settings, SQL tracking, admin diagnosis, and nullable profiling fields.
@@ -116,6 +117,14 @@ python manage.py prune_api_logs --days 30 --dry-run
 python manage.py prune_api_logs --days 30 --batch-size 1000
 ```
 
+Production diagnostics:
+
+```bash
+python manage.py drf_api_logger_doctor
+python manage.py drf_api_logger_doctor --format json
+python manage.py drf_api_logger_doctor --fail-level warning
+```
+
 Queue health check:
 
 ```python

docs/developer_testing.rst

@@ -88,6 +88,9 @@ Add or update tests for every behavior change. Cover the touched surface:
   label prevention.
 - Policy gate behavior for full log drops, metadata-only logging, extra mask
   keys, signal/export gating, safe failures, and default backward compatibility.
+- Production diagnostics and doctor command behavior, including JSON output,
+  fail-level behavior, database readiness, queue health, payload limits,
+  masking, and profiling risk.
 - Background queue flushing, stats, shutdown, and database alias handling.
 - Admin display, filters, CSV export, and profiling diagnosis.
 - Management commands such as ``prune_api_logs``.
@@ -103,6 +106,14 @@ Retention command:
    python manage.py prune_api_logs --days 30 --dry-run
    python manage.py prune_api_logs --days 30 --batch-size 1000
 
+Production diagnostics:
+
+.. code-block:: bash
+
+   python manage.py drf_api_logger_doctor
+   python manage.py drf_api_logger_doctor --format json
+   python manage.py drf_api_logger_doctor --fail-level warning
+
 Queue health:
 
 .. code-block:: python

docs/index.rst

@@ -612,6 +612,18 @@ Model Schema
 Performance & Production
 =========================
 
+Run production diagnostics during deployment:
+
+.. code-block:: bash
+
+   python manage.py drf_api_logger_doctor
+   python manage.py drf_api_logger_doctor --format json
+   python manage.py drf_api_logger_doctor --fail-level warning
+
+The command is read-only and reports database readiness, queue health, payload
+limits, masking configuration, and profiling risk. Use ``--fail-level error``
+when deployment checks should fail only on blocking misconfiguration.
+
 .. code-block:: python
 
    # Use a dedicated database for logs

docs/operations.rst

@@ -16,6 +16,73 @@ DRF API Logger 1.2.3 supports:
 The GitHub Actions workflow tests representative Django versions from this
 support range before publishing package artifacts.
 
+Production Doctor Command
+-------------------------
+
+Run ``drf_api_logger_doctor`` before enabling database logging in production
+and after deployment changes that affect logging, storage, retention, masking,
+payload limits, or profiling.
+
+.. code-block:: bash
+
+   python manage.py drf_api_logger_doctor
+
+The command is read-only. It validates logging mode, database alias readiness,
+DRF API Logger migrations, the log table, queue settings, background worker
+status, payload limits, masking configuration, and profiling settings. It does
+not create tables, run migrations, prune rows, or inspect stored request or
+response payloads.
+
+Use JSON output in CI or deployment checks:
+
+.. code-block:: bash
+
+   python manage.py drf_api_logger_doctor --format json
+
+Fail a deployment on warnings or errors:
+
+.. code-block:: bash
+
+   python manage.py drf_api_logger_doctor --fail-level warning
+   python manage.py drf_api_logger_doctor --fail-level error
+
+Use ``--database`` when ``DRF_API_LOGGER_DEFAULT_DATABASE`` points to a
+dedicated log database and the deployment check must inspect that alias
+explicitly:
+
+.. code-block:: bash
+
+   python manage.py drf_api_logger_doctor --database logs_db --format json
+
+Result levels:
+
+``OK``
+   The checked condition is valid for the current configuration.
+
+``WARNING``
+   The package can run, but the setting or runtime state deserves operator
+   attention before production use.
+
+``ERROR``
+   The package is likely misconfigured for the selected logging mode. Fix the
+   issue before relying on production database logging.
+
+Deployment Checklist
+--------------------
+
+Before enabling database logging in production:
+
+- Run ``python manage.py migrate drf_api_logger`` on the configured log
+  database.
+- Run ``python manage.py drf_api_logger_doctor --fail-level warning``.
+- Keep finite body limits with ``DRF_API_LOGGER_MAX_REQUEST_BODY_SIZE`` and
+  ``DRF_API_LOGGER_MAX_RESPONSE_BODY_SIZE``.
+- Add application-specific secrets to ``DRF_API_LOGGER_EXCLUDE_KEYS``.
+- Skip health and metrics endpoints with ``DRF_API_LOGGER_SKIP_URL_NAME`` or
+  ``DRF_API_LOGGER_SKIP_NAMESPACE``.
+- Schedule ``prune_api_logs`` with a dry run first.
+- Monitor ``queue_backlog``, ``dropped_count``, and ``failed_insert_count``.
+
 Database Growth
 ---------------