Metadata-Version: 2.4
Name: django-ops-logger
Version: 0.1.0
Summary: A comprehensive operation logging app for Django.
Home-page: 
Author: 0716gzs
Author-email: 
License: MIT License
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Django Operation Logger (django_ops_logger)

一款功能强大、即插即用的 Django 全方位操作日志记录应用。它能够在不侵入业务逻辑的情况下，记录请求、数据库查询、缓存操作、信号等的全生命周期日志。

## 功能特性

- **零侵入**：只需在 `INSTALLED_APPS` 和 `MIDDLEWARE` 中注册即可使用。
- **全链路追踪**：通过唯一的 `Trace ID` 将 HTTP 请求、数据库查询、缓存操作和信号串联起来。
- **高性能**：使用异步队列和后台 Worker 进行批量数据库写入，确保不影响主业务性能。
- **数据脱敏**：自动对敏感数据（如密码、Token）进行脱敏处理。
- **全面覆盖**：
    - HTTP 请求（方法、路径、用户、IP、耗时）
    - 数据库查询（SQL 语句、参数、耗时）
    - 缓存操作（Get/Set/Delete、命中/未命中）
    - 用户认证（登录成功/失败）
    - 系统启动事件

## 安装步骤

1. 将 `django_ops_logger` 包复制到您的 Django 项目根目录。

2. 添加到 `INSTALLED_APPS`：

```python
INSTALLED_APPS = [
    # ...
    'django_ops_logger',
]
```

3. 添加到 `MIDDLEWARE`：

> **注意**：建议将其放置在 `AuthenticationMiddleware` 之后，以便能够捕获用户信息。

```python
MIDDLEWARE = [
    # ...
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django_ops_logger.middleware.RequestLogMiddleware', 
    # ...
]
```

4. 运行数据库迁移：

```bash
python manage.py makemigrations django_ops_logger
python manage.py migrate
```

## 配置说明

在 `settings.py` 中添加 `DJANGO_OPS_LOGGER` 配置项以自定义行为：

```python
DJANGO_OPS_LOGGER = {
    'ENABLED': True,             # 总开关
    'SQL_LOG_ENABLE': True,      # 记录数据库查询
    'JWT_SECRET_KEY': 'jwt key', # 必须和setting一致
    'CACHE_LOG_ENABLE': False,   # 记录缓存操作（默认关闭，因为日志量可能很大）
}
```

## 使用方法

安装完成后，日志记录器会自动工作。您可以通过 Django Admin（如果已注册）或直接通过 `OperationLog` 模型查询日志。

### 查询日志

```python
from django_ops_logger.models import OperationLog

# 获取特定 Trace ID 的所有日志
logs = OperationLog.objects.filter(trace_id='your-trace-id')

# 获取慢查询（耗时超过 500ms）
slow_queries = OperationLog.objects.filter(
    operation_type='db', 
    duration__gt=500
)
```

### 手动记录日志

您也可以在视图或业务逻辑中手动记录自定义事件：

```python
from django_ops_logger.queue import enqueue_log
from django_ops_logger.models import OperationLog
from django_ops_logger.context import TrackerContext
from django.utils import timezone

def my_custom_logic():
    # ... 业务逻辑 ...
    
    enqueue_log(
        trace_id=TrackerContext.get_trace_id(),
        operation_type=OperationLog.OpType.CUSTOM,
        level='INFO',
        start_time=timezone.now(),
        details={'action': 'payment_processed', 'amount': 100}
    )
```

## 架构设计

- **上下文追踪**：使用 `contextvars` 在请求生命周期内维护 `trace_id`。
- **中间件**：捕获请求/响应周期，并处理异常日志。
- **包装器 (Wrappers)**：Monkey-patch 数据库和缓存后端以拦截底层操作。
- **异步队列**：所有日志被推送到内存队列中，并由后台线程批量刷新到数据库，以确保对响应时间的影响降至最低。
