Django 實作教學 - 設定 Logging ( Django - Configure logging settings for your application )

我最常使用的 Python Web 框架為 Tornado，但因其他專案需要而重回 Django 的懷抱。因此接下來將會慢慢地將遇到的問題與心得做個紀錄。本篇將介紹如何設定 Django 的 Logging。( 其他 Django 相關教學可以參考本篇整理。If you want to read this article in English, you can visit here )



前置作業
在開始設定之前，若你還沒將環境建立起來的話，先安裝 Django 並建立專案：

# 安裝 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 所提供的 Logging 設定很靈活，但也因為這樣反而一開始會有點不知所措。所以，先來了解大項目然後接著深入了解細部設定。Logging 設定基本上是存放於 settings.py 檔案中，預設的設定檔不會有 Logging 相關參數，所以你需要自行加入，內容如下：

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

目前你主要需要了解的部分為 formatters、handlers、loggers：

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

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

---

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

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

你需要注意的部分是 format 參數：

• %(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'
        },
    },

這個部分你需要注意的設定如下：

• level：Log 層級
• class：代表我們要怎麼處理 Log 訊息，例如寫入文字檔，或者輸出至 Console。此範例中，我們設定兩個 Handler 都要寫入文字檔，所以使用 logging.FileHandler。
• filename：若你要寫入文字檔，你需要指定檔案要存放在哪裡。
• formatter：代表我們要使用哪個模板（也就是我們剛剛前面設定的）。

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

---

Loggers 設定

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

這部分需要注意的設定：

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

至於 propagate 則需要另一個篇幅來解釋比較恰當，或者你可以參考文件。

---

使用 Logging
在你的程式中加入：

# 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.')

---

Environment :
  ・ Debian
Reference :
  ・ Django - Logging