feat(logging): Improve logging and log config #292 (#298)

Added Rotating Log files.
Added logging configuration to ENV files.
Extended logging options for running project in Docker.
	This is primarily for log capture with Loki and Promtail.
Added logging How-To.
Update quickstart with logging.
Update README.

closes #292

README.rst

@@ -58,6 +58,7 @@ Django Project Features
    The Admin panel now has the protections provided by django-allauth.
 #. `htmx`_ built in by default using `django-htmx`_.
 #. `django-tailwind`_ and `django-browser-reload`_ built in by default.
+#. Customisable logging with rotating log files, see `how-to-logging`_.
 
 If you are new to Django and Cookiecutters and would like to take it for a spin,
 see our tutorial, `Create a Django-Cookiecutter Project`_.
@@ -72,6 +73,7 @@ see our tutorial, `Create a Django-Cookiecutter Project`_.
 .. _django-htmx: https://github.com/adamchainz/django-htmx
 .. _django-tailwind: https://github.com/timonweb/django-tailwind
 .. _django-browser-reload: https://github.com/adamchainz/django-browser-reload
+.. _how-to-logging: https://django-cookiecutter.readthedocs.io/en/latest/how-tos/how-to-logging.html
 
 Django Project Creation Options
 -------------------------------

docs/source/how-tos/how-to-htmx.rst

@@ -3,6 +3,7 @@
 .. index:: how-to-htmx ; Index
 
 .. _how-to-htmx:
+
 ====
 HTMX
 ====

docs/source/how-tos/how-to-logging.rst

@@ -0,0 +1,154 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: how-to-logging ; Index
+
+.. _how-to-logging:
+
+==============
+Logging Config
+==============
+
+You can modify the logging configuration through `.env`` settings files.
+
+All environments share the same logging file ENV Variable Name.
+
+Sharing a common ENV Variable Name keeps configuration simplifies changing the
+logging file name for each environment.
+
+
+Rotating Log Files
+------------------
+
+django-cookiecutter uses Rotating Logs to prevent log file size from growing
+too large.  The default settings, see below, are located in
+`config/settings/base.py`.
+
+The `backupCount` setting allows up to five log files before it starts removing them.
+
+The `maxBytes` setting is the maximum size a file can be before it is closed and rotated to a new file.
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 8,9
+
+    "rotated_logs": {
+        "class": "logging.handlers.RotatingFileHandler",
+        "filename": DJANGO_LOG_FILE,
+        "level": DJANGO_LOGGING_LEVEL,
+        "mode": "a",
+        "encoding": "utf-8",
+        "formatter": "verbose",
+        "backupCount": 5,
+        "maxBytes": 10485760,
+    },
+
+
+Local and Test
+--------------
+
+`Local` and `Test` environments also share the same logging level ENV Variable name.
+
+See the local environment configuration file below.
+
+.. code-block:: bash
+    :linenos:
+    :emphasize-lines: 3,6
+
+     my-django-project
+         └── .env
+             ├── .local
+             ├── .production
+             ├── .staging
+             └── .testing
+
+.. code-block:: bash
+    :linenos:
+    :emphasize-lines: 3, 4
+
+    ALLOWED_HOSTS=localhost,0.0.0.0,127.0.0.1
+    DJANGO_DEBUG=True
+    DJANGO_LOG_FILE="logging/rotating_local.log"
+    DJANGO_LOGGING_LEVEL="DEBUG"
+    DJANGO_LOGGING_MAIL_ADMINS="ERROR"
+    DJANGO_MANAGEPY_MIGRATE=on
+    DJANGO_SECRET_KEY="!!!INSECURE_PRODUCTION_SECRET!!!"
+    DJANGO_SETTINGS_MODULE=config.settings.local
+    EMAIL_BACKEND="django.core.mail.backends.console.EmailBackend"
+    INTERNAL_IPS=127.0.0.1,10.0.2.2
+    DB_ENGINE=""
+    DB_NAME=""
+    DB_USER=""
+    DB_PASSWORD=""
+    DB_HOST=""
+    DB_PORT=""
+
+
+
+Staging and Production
+----------------------
+
+`Staging` and `Production` environments add the environment suffix to the
+ENV Variable to differentiate between the two environments.
+
+See the production file below, showing the addition of the `_PRODUCTION`
+suffix, and specifying the production logging file location.
+
+
+.. code-block:: bash
+    :linenos:
+    :emphasize-lines: 4, 5
+
+     my-django-project
+         └── .env
+             ├── .local
+             ├── .production
+             ├── .staging
+             └── .testing
+
+
+.. code-block:: bash
+    :linenos:
+    :emphasize-lines: 2,3
+
+    DJANGO_DEBUG=FALSE
+    DJANGO_LOG_FILE="logging/rotating_production.log"
+    DJANGO_LOGGING_LEVEL_PRODUCTION="INFO"
+    DJANGO_LOGGING_MAIL_ADMINS="ERROR"
+    DJANGO_MANAGEPY_MIGRATE=on
+    DJANGO_SECRET_KEY=""
+    DJANGO_SETTINGS_MODULE=config.settings.production
+    DB_ENGINE=""
+    DB_NAME=""
+    DB_USER=""
+    DB_PASSWORD=""
+    DB_HOST=""
+    DB_PORT=""
+    INTERNAL_IPS=""
+
+
+Email Admins
+------------
+
+By default, Sending emails to admins is set to `ERROR` for all environments.
+
+You can change what logging level the Admins will receive an email with the
+email admins variable; see below.
+
+.. code-block:: bash
+    :linenos:
+    :emphasize-lines: 4
+
+    DJANGO_DEBUG=FALSE
+    DJANGO_LOG_FILE="logging/rotating_production.log"
+    DJANGO_LOGGING_LEVEL_PRODUCTION="INFO"
+    DJANGO_LOGGING_MAIL_ADMINS="ERROR"
+    DJANGO_MANAGEPY_MIGRATE=on
+    DJANGO_SECRET_KEY=""
+    DJANGO_SETTINGS_MODULE=config.settings.production
+    DB_ENGINE=""
+    DB_NAME=""
+    DB_USER=""
+    DB_PASSWORD=""
+    DB_HOST=""
+    DB_PORT=""
+    INTERNAL_IPS=""

docs/source/how-tos/how-to-quickstart.rst

@@ -270,3 +270,12 @@ To select another testing database, you can:
 
 
 .. _cookiecutter: https://cookiecutter.readthedocs.io/en/1.7.2/README.html
+
+
+Configure Logging
+-----------------
+
+You can customise the logging configuration for each environment in the
+respective  `.env` file.
+
+For more information see :ref:`How-to logging<how-to-logging>`.

docs/source/how-tos/how-to-tailwind.rst

@@ -3,6 +3,7 @@
 .. index:: how-to-tail ; Index
 
 .. _how-to-tail:
+
 =========================
 Tailwind & Browser Reload
 =========================

docs/source/how-tos/index-how-to.rst

@@ -17,6 +17,7 @@ See below for a list of How-To for Django Cookiecutter.
    how-to-quickstart
    how-to-custom-user
    how-to-htmx
+   how-to-logging
    how-to-tailwind
    how-to-test-env-settings
    how-to-docker-linux-cheatsheet

docs/source/reference/reference-project-inputs.rst

@@ -2,6 +2,7 @@
 .. index:: django-proj-inputs ; Index
 
 .. _project-inputs:
+
 ==================
 New Project Inputs
 ==================