WIP: Logging configuration

Pipfile

@@ -15,7 +15,7 @@ django-filter = "*"
 djangorestframework = "*"
 factory-boy = "*"
 filemagic = "*"
-fuzzywuzzy = {extras = ["speedup"], version = "==0.15.0"}
+fuzzywuzzy = {extras = ["speedup"],version = "==0.15.0"}
 gunicorn = "*"
 inotify-simple = "*"
 langdetect = "*"
@@ -36,6 +36,7 @@ pytest-env = "*"
 pytest-xdist = "*"
 psycopg2 = "*"
 djangoql = "*"
+pyyaml = "*"
 
 [dev-packages]
 ipython = "*"

docs/index.rst

@@ -37,6 +37,7 @@ Contents
    setup
    consumption
    api
+   logging
    utilities
    guesswork
    migrating

docs/logging.rst

@@ -0,0 +1,100 @@
+.. _logging:
+
+Logging
+=======
+
+By default paperless logs to standard output and to the database. Logs can be browsed from the paperless web interface in the ``Log`` section.
+
+Sentry
+------
+
+Paperless can be configured to send errors to the  `sentry.io`_ error tracking software by setting the ``PAPERLESS_SENTRY_DSN`` value in ``paperless.conf``.
+
+.. _sentry.io: https://sentry.io/welcome/
+
+Custom logger
+-------------
+
+Paperless support customizing the logging configuration by using a ``/etc/paperless/logging.yml`` file. This file should be in the yaml format and is passed without modification to the python logging ``dictConfig``. For more information
+about the format see:
+
+    - `Django logging documentation`_
+    - `Python logging dictConfig documentation`_
+
+.. _Django logging documentation: https://docs.djangoproject.com/en/2.1/topics/logging/
+.. _Python logging dictConfig documentation: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+
+Examples
+--------
+
+Default
++++++++
+
+.. code-block:: yaml
+
+    version: 1
+    disable_existing_loggers: False
+    handlers:
+        consumer:
+            class: documents.loggers.PaperlessLogger
+    loggers:
+        documents:
+            handlers:
+                - consumer
+            level: INFO
+
+Send errors by email
+++++++++++++++++++++
+
+.. code-block:: yaml
+
+    version: 1
+    disable_existing_loggers: False
+    handlers:
+        consumer:
+            class: documents.loggers.PaperlessLogger
+        email:
+            class: logging.handlers.SMTPHandler
+            mailhost: localhost
+            fromaddr: [email protected]
+            toaddrs: 
+                - [email protected]
+            subject: oops!
+            credentials:
+                - root
+                - hunter2
+    loggers:
+        documents:
+            propagate: true
+            handlers:
+                - consumer
+            level: INFO
+    root:
+        handlers:
+            - email
+        level: ERROR
+
+Log debug to a file
++++++++++++++++++++
+
+.. code-block:: yaml
+
+    version: 1
+    disable_existing_loggers: False
+    handlers:
+        consumer:
+            class: documents.loggers.PaperlessLogger
+        file:
+            class: logging.handlers.RotatingFileHandler
+            filename: paperless.log
+            maxBytes: 100000000
+    loggers:
+        documents:
+            propagate: true
+            handlers:
+                - consumer
+            level: INFO
+    root:
+        handlers:
+            - file
+        level: DEBUG

docs/migrating.rst

@@ -92,7 +92,7 @@ files, the ``migrate`` step may not update anything.  This is totally normal.
 Additionally, as new features are added, the ability to control those features
 is typically added by way of an environment variable set in ``paperless.conf``.
 You may want to take a look at the ``paperless.conf.example`` file to see if
-there's anything new in there compared to what you've got int ``/etc``.
+there's anything new in there compared to what you've got in ``/etc``.
 
 If you are :ref:`using Docker <setup-installation-docker>` the update process
 is similar:

src/paperless/settings.py

@@ -11,15 +11,20 @@
 """
 
 import os
+import yaml
 
 from dotenv import load_dotenv
 
 
 # Tap paperless.conf if it's available
 if os.path.exists("/etc/paperless.conf"):
     load_dotenv("/etc/paperless.conf")
+elif os.path.exists("/etc/paperless/paperless.conf"):
+    load_dotenv("/etc/paperless/paperless.conf")
 elif os.path.exists("/usr/local/etc/paperless.conf"):
     load_dotenv("/usr/local/etc/paperless.conf")
+elif os.path.exists("/usr/local/etc/paperless/paperless.conf"):
+    load_dotenv("/usr/local/etc/paperless/paperless.conf")
 
 
 def __get_boolean(key, default="NO"):
@@ -222,22 +227,48 @@ def __get_boolean(key, default="NO"):
 
 # Logging
 
-LOGGING = {
-    "version": 1,
-    "disable_existing_loggers": False,
-    "handlers": {
-        "consumer": {
-            "class": "documents.loggers.PaperlessLogger",
-        }
-    },
-    "loggers": {
-        "documents": {
-            "handlers": ["consumer"],
-            "level": os.getenv("PAPERLESS_CONSUMER_LOG_LEVEL", "INFO"),
+# Django use the python dictConfig format for logging. For more info See:
+#  * https://docs.djangoproject.com/en/2.1/topics/logging/
+#  * https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+#
+# Removing the default logging configuration will disable logging into the database
+# and the log view from the interface
+
+if os.path.exists("/etc/paperless/logging.yml"):
+    with open("/etc/paperless/logging.yml", 'r') as config:
+        LOGGING = yaml.load(config)
+elif os.path.exists("/usr/local/etc/paperless/logging.yml"):
+    with open("/usr/local/etc/paperless/logging.yml", 'r') as config:
+        LOGGING = yaml.load(config)
+else:
+    LOGGING = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "consumer": {
+                "class": "documents.loggers.PaperlessLogger",
+            }
+        },
+        "loggers": {
+            "documents": {
+                "handlers": ["consumer"],
+                "level": os.getenv("PAPERLESS_CONSUMER_LOG_LEVEL", "INFO"),
         },
     },
 }
 
+if os.getenv("PAPERLESS_SENTRY_DSN"):
+    import sentry_sdk
+    from sentry_sdk.integrations.django import DjangoIntegration
+
+    sentry_logging = LoggingIntegration(
+        level=logging.INFO,        # Capture info and above as breadcrumbs
+        event_level=logging.ERROR  # Send errors as events
+    )
+    sentry_sdk.init(
+        dsn=os.getenv("PAPERLESS_SENTRY_DSN"),
+        integrations=[sentry_logging, DjangoIntegration()]
+    )
 
 # The default language that tesseract will attempt to use when parsing
 # documents.  It should be a 3-letter language code consistent with ISO 639.