bruce-django-requests-logger 0.1.1
A Django middleware for comprehensive HTTP request logging
Requires Python: >=3.8
Keywords: django, logging, middleware, request, monitoring, bruce

# Bruce Django Requests Logger

一个功能完整的 Django 中间件，用于详细记录 HTTP 请求信息。

## 功能特性

- 📝 记录完整的请求信息（方法、路径、状态码、持续时间等）
- 🕒 高精度时间测量和格式化显示
- 🌐 客户端 IP 地址检测（支持代理）
- 🔍 可配置的请求过滤（排除静态文件等）
- 🛠 管理命令查看日志统计
- 📊 JSON 格式的结构化日志输出
- ⚡ 轻量级，对性能影响极小

## 安装

### 使用 pip 安装

```bash
pip install bruce-django-requests-logger
```

### 使用方法
1. 添加到 INSTALLED_APPS
```aiignore
# settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    
    # 其他应用...
    
    # 添加 Bruce Django Requests Logger
    'bruce_django_requests_logger',
]
```
2.添加中间件
```aiignore
# settings.py

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    
    # 其他中间件...
    
    # 添加 Bruce Requests Logger 中间件
    # 建议放在其他中间件之前，以便准确测量整个请求处理时间
    'bruce_django_requests_logger.middleware.BruceRequestsLoggerMiddleware',
]
```
3. 基本使用
配置完成后，中间件会自动记录所有请求。启动 Django 开发服务器：
```aiignore
python manage.py runserver
```
访问您的 Django 应用任意页面，查看控制台输出，您将看到格式化的请求信息：
```aiignore
[BRUCE_REQUESTS_LOGGER] {
  "timestamp": "2024-01-01T10:00:00+08:00",
  "method": "GET",
  "path": "/admin/",
  "query_string": "",
  "status_code": 200,
  "duration": 0.145,
  "duration_formatted": "145ms",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "ip_address": "172.18.0.1",
  "content_type": "text/html; charset=utf-8",
  "content_length": "12345"
}
```
4. 使用管理命令
```aiignore
# 查看最近的10条请求日志（默认）
python manage.py view_logs

# 查看最近5条GET请求
python manage.py view_logs --limit 5 --method GET

# 查看状态码为404的请求
python manage.py view_logs --status 404

# 查看最近20条日志
python manage.py view_logs --limit 20
```
### 日志字段说明
字段名	|说明	|示例
---|----|---
timestamp	|请求时间戳（ISO 8601 格式）	|"2024-01-01T10:00:00+08:00"
method	|HTTP 方法	|"GET", "POST", "PUT", "DELETE"
path|	请求路径	|"/admin/", "/api/users/"
query_string|	URL 查询参数|	"page=1&size=20"
status_code|	HTTP 状态码	|200, 404, 500
duration|	请求处理时间（秒）|	0.145
duration_formatted|	格式化后的处理时间	|"145ms"
user_agent	|客户端用户代理	|"Mozilla/5.0..."
ip_address	|客户端 IP 地址	|"172.18.0.1"
content_type|	响应内容类型|	"text/html; charset=utf-8"
content_length	|响应内容长度	|"12345"

### 高级配置
#### 自定义日志输出
您可以创建自定义中间件类来扩展或修改日志行为：
```aiignore
# your_app/middleware.py

from bruce_django_requests_logger.middleware import BruceRequestsLoggerMiddleware

class CustomRequestsLogger(BruceRequestsLoggerMiddleware):
    def _log_request(self, log_entry):
        # 自定义日志输出，例如写入文件或发送到日志服务
        custom_log = f"CUSTOM: {log_entry['method']} {log_entry['path']} - {log_entry['duration_formatted']}"
        print(custom_log)
        
        # 同时保留原始日志输出
        super()._log_request(log_entry)
```
然后在 settings.py 中使用您的自定义类：
```
MIDDLEWARE = [
    # ...
    'your_app.middleware.CustomRequestsLogger',  # 使用自定义中间件
]
```
### 排除特定路径
如果您希望排除某些路径的日志记录，可以创建自定义的请求检查函数：
```aiignore
# your_app/utils.py

from bruce_django_requests_logger.utils import should_log_request

def custom_should_log_request(request):
    # 排除健康检查路径和管理后台静态文件
    excluded_paths = ['/health/', '/admin/static/']
    
    for path in excluded_paths:
        if request.path.startswith(path):
            return False
    
    return should_log_request(request)
```
### 生产环境配置
在生产环境中，建议将日志输出重定向到文件：
```aiignore
# settings.py

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/var/log/django/requests.log',
            'formatter': 'verbose',
        },
    },
    'formatters': {
        'verbose': {
            'format': '{name} {levelname} {asctime} {message}',
            'style': '{',
        },
    },
    'loggers': {
        'bruce_django_requests_logger': {
            'handlers': ['file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}
```