Jogging 项目技术文档

1. 安装指南

1.1 下载

你可以通过以下两种方式获取最新版本的 Jogging：

• 从 GitHub 的 Downloads 部分下载最新版本。
• 使用 pip 命令安装：

  pip install jogging
  

1.2 安装

1. 将 'jogging' 添加到 Django 项目的 INSTALLED_APPS 中。
2. 将 'jogging.middleware.LoggingMiddleware' 添加到 MIDDLEWARE_CLASSES 中。

2. 项目的使用说明

2.1 配置

Jogging 允许你通过 settings.py 文件进行详细的日志配置。以下是一些配置示例：

基本配置

from jogging.handlers import DatabaseHandler
import logging

GLOBAL_LOG_LEVEL = logging.INFO
GLOBAL_LOG_HANDLERS = [DatabaseHandler()]  # 使用 Python 的 Handler 对象

此配置将所有 INFO 级别及以上的日志记录到数据库中。

中级配置

from jogging.handlers import DatabaseHandler
from logging import StreamHandler
import logging

LOGGING = {
    # 所有来自 myapp1 的日志都记录到数据库
    'myapp1': {
        'handler': DatabaseHandler(),
        'level': logging.DEBUG,
    },
    
    # 除了这个视图，它将 CRITICAL 级别的日志记录到 stderr
    'myapp1.views.super_important_view': {
        'handler': StreamHandler(),
        'level': logging.CRITICAL,
    },
}

只有最具体的日志记录器会被匹配。

高级配置

from jogging.handlers import DatabaseHandler
from logging import StreamHandler, FileHandler
import logging

LOGGING = {
    # 所有来自 myapp1 的日志都记录到数据库
    'myapp1': {
        'handler': DatabaseHandler(),
        'level': logging.DEBUG,
    },
    
    # 这次，super_important_view 将 CRITICAL 级别的日志记录到 stderr，同时也将所有日志记录到数据库
    'myapp1.views.super_important_view': {
        'handlers': [
            { 'handler': StreamHandler(), 'level': logging.CRITICAL, 
                'format': "%(asctime)-15s %(source): %(message)s %(foo)s" },
            { 'handler': DatabaseHandler(), 'level': logging.DEBUG },
        ]
    },
    
    # 这是一个第三方应用已经使用的日志记录器名称，你可以像其他日志记录器一样配置它，而不会破坏任何东西
    'simple_example': {
        'handler': StreamHandler(),
        'level': logging.CRITICAL,
    }
}

format 属性支持 Python 日志格式的所有指定符，并添加了一些额外内容：

• %(source)s 是调用日志记录的方法。
• %(foo)s 是传递给日志记录调用的参数。

2.2 使用

from jogging import logging
logging.info("I'm an info message")
logging.debug(msg="I'm a debug message", foo="bar")

记住高级配置中的 %(foo)s，在 debug 调用中它将被填充为 "bar"。

3. 项目API使用文档

3.1 自定义 Handler

• jogging.handlers.DatabaseHandler：将日志记录到数据库，以便在管理界面中浏览、搜索和过滤日志。
• jogging.handlers.EmailHandler：将日志记录到电子邮件。
• jogging.handlers.InlineOnPageHandler：即将推出。将日志附加到渲染页面的底部。

4. 项目安装方式

4.1 安装步骤

1. 将 'jogging' 添加到 INSTALLED_APPS。
2. 将 'jogging.middleware.LoggingMiddleware' 添加到 MIDDLEWARE_CLASSES。

4.2 配置

在 settings.py 中配置日志记录器，如上文所述。

通过以上步骤，你可以轻松地在 Django 项目中使用 Jogging 进行日志记录。