Django 教學 - 設定 Logging

Apr 29, 2017 Djnago English

Django 在 Python 開發社群中是相當有名的 Web 框架，它其中一個重要功能就是提供了靈活的 Logging 設定。但是，若你才剛開始接觸 Django 那可能會有點不知道如何下手，因此本篇文章將讓你初步了解 Logging 與如何設定。

前置準備

若你還未將環境設定好，你可以使用以下指令快速建立：

# 安裝 Django
python -m pip install Django

# 檢查 Django 版本
python -m django --version

# 建立 Django 專案
django-admin startproject <project-name>

專案的預設結構如下：

project-name/
├── project-name
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── wsgi.py

了解 Logging 設定

在我們繼續接下來的步驟之前，先來了解一些基本的概念，然後再接著深入了解各細部設定。首先，當你使用指令 django-admin startproject 來建立專案，預設的設定檔並不會有 Logging 的設定。所以我們需要將相關設定加入至 settings.py。以下是一個簡單的範例：

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        # TODO
    },
    'handlers': {
        # TODO
    },
    'loggers': {
        # TODO
    },
    'filters': {
        # TODO
    },
}

作為一個 Django 初學者，讓我們先專注在 formatters、handlers 與 loggers 即可：

formatters：描述你想要怎麼顯示你的 Log，類似建立模板的概念。
handlers：定義你想要怎麼處理你 Log 的方式，試想如果我有非例行的任務，我可能只需要它顯示於 Console 或者存放在不同的地方，這時候我們就可以使用不同的 Handler 來處理。
loggers：這部分代表我們將前兩項組合起來形成一個"模組"，這樣方便我們在程式中使用。

以下以一個簡單的圖來描述它們彼此的關係：

設定 Formatters

了解大致上的內容後，讓我們來了解細部設定，首先針對 formatters，範例如下：

    'formatters': {
        'your-formatter': {
            '()': 'django.utils.log.ServerFormatter',
            'format': '[%(asctime)s] %(message)s',
        }
    },

如你所見，我定義了一個字串格式 ( [%(asctime)s] %(message)s )：

%(asctime)s：使用人類比較習慣的時間格式，如：2003-07-08 16:49:45,896。
%(message)s：你要輸出的訊息。

所以實際上 Log 產生的結果會如同下面格式：

[2017-04-26 11:07:33,380] Your message is here

當然我們有更多的選項（如不同的時間格式、其他資訊）可以使用，請參考這裡.

設定 Handlers

以下為設定 Handlers 的範例：

    'handlers': {
        'web': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': '/path/to/your-web.log',
            'formatter': 'your-formatter'
        },
        'other_service': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': '/path/to/your-other-service.log',
            'formatter': 'your-formatter'
        },
    },

上面的範例中，你可以看到我定義了兩個 Handler 針對不同的任務，它們將會各自在不同的資料夾中建立 Log 檔案。

level：指定 Log 層級。
class：定義處理 Log 訊息的程式名稱。此範例中，我們設定兩個 Handler 都要寫入文字檔，所以使用 logging.FileHandler。
filename：若你要寫入文字檔，你需要指定檔案名稱以及存放位置。
formatter：描述我們要使用哪個模板。

若要取得更多設定的細節，請參考這裡。

設定 Loggers

以下為設定 Loggers 範例：

    'loggers': {
        'your-logger': {
            'handlers': ['web'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },

handlers：指定哪些 Handler 來處理，注意這邊可以指定多個。
level：定義 Log 層級。

至於 propagate 參數則需要另一個篇幅來解釋比較恰當，所以就不在這邊討論。但是你可以參考文件。

使用 Logging

設定好一切參數後，在程式中使用你剛剛已經定義好的 Logger 即可：

# Use logging library
import logging

# Get an instance of a logger
logger = logging.getLogger('your-logger')

# Log a message
logger.info('Your message is here.')