Metadata-Version: 2.4
Name: error-explorer-django
Version: 1.2.0
Summary: Error Explorer SDK for Django - Automatic error tracking and monitoring
Author-email: Error Explorer <support@error-explorer.com>
License: MIT
Project-URL: Homepage, https://github.com/error-explorer/error-explorer-sdks
Project-URL: Documentation, https://docs.error-explorer.com/sdks/django
Project-URL: Repository, https://github.com/error-explorer/error-explorer-sdks
Project-URL: Issues, https://github.com/error-explorer/error-explorer-sdks/issues
Keywords: error,tracking,monitoring,django,exception,logging
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Bug Tracking
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: error-explorer>=1.0.0
Requires-Dist: django>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-django>=4.5; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# Error Explorer Django SDK

Automatic error tracking and monitoring for Django applications.

## Installation

```bash
pip install error-explorer-django
```

## Quick Start

### 1. Add to INSTALLED_APPS

```python
# settings.py
INSTALLED_APPS = [
    ...
    'error_explorer_django',
]
```

### 2. Add Middleware

```python
# settings.py
MIDDLEWARE = [
    'error_explorer_django.middleware.ErrorExplorerMiddleware',
    ...  # Should be early in the list to catch all errors
]
```

### 3. Configure

```python
# settings.py
ERROR_EXPLORER = {
    'token': 'your_project_token',
    'environment': 'production',  # or 'staging', 'development'
    'release': '1.0.0',
}
```

That's it! Errors will be automatically captured and sent to Error Explorer.

## Configuration Options

```python
ERROR_EXPLORER = {
    # Required
    'token': 'your_project_token',

    # Optional - Environment & Release
    'environment': 'production',
    'release': '1.0.0',
    'project': 'my-django-app',

    # Optional - HMAC Authentication
    'endpoint': 'https://your-server.com/api/v1/webhook',
    'hmac_secret': 'your_hmac_secret',

    # Optional - Behavior
    'debug': False,                  # Enable debug mode
    'sample_rate': 1.0,             # 0.0 to 1.0 (100%)
    'max_breadcrumbs': 50,          # Max breadcrumbs to keep
    'attach_stacktrace': True,      # Include stack traces
    'send_default_pii': False,      # Include PII (email, etc.)

    # Optional - Capture Settings
    'capture_user': True,           # Capture authenticated user
    'capture_signals': True,        # Capture Django signals
    'capture_logging': True,        # Capture log messages
    'capture_404': False,           # Capture 404 errors
    'capture_403': False,           # Capture 403 errors
    'capture_cli': False,           # Capture in management commands

    # Optional - Data Scrubbing
    'scrub_fields': [
        'password',
        'secret',
        'token',
        'api_key',
        'credit_card',
    ],
}
```

## Logging Integration

Capture log messages as breadcrumbs and errors:

```python
# settings.py
LOGGING = {
    'version': 1,
    'handlers': {
        'error_explorer': {
            'class': 'error_explorer_django.logging.ErrorExplorerHandler',
            'level': 'WARNING',
        },
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'django': {
            'handlers': ['console', 'error_explorer'],
            'level': 'INFO',
        },
        'myapp': {
            'handlers': ['console', 'error_explorer'],
            'level': 'DEBUG',
        },
    },
}
```

## Event Filtering with before_send

Use the `before_send` callback to filter or modify events before they're sent:

```python
# settings.py
def before_send(event):
    # Drop events from specific paths
    if event.get("request", {}).get("url", "").startswith("/health"):
        return None  # Drop the event

    # Remove sensitive data
    if "extra" in event and "api_response" in event["extra"]:
        event["extra"]["api_response"] = "[REDACTED]"

    # Add custom data
    event["tags"] = event.get("tags", {})
    event["tags"]["deployment_id"] = os.environ.get("DEPLOYMENT_ID", "unknown")

    return event

ERROR_EXPLORER = {
    'token': 'your_project_token',
    'before_send': before_send,
}
```

## Manual Usage

You can also use Error Explorer manually:

```python
from error_explorer import ErrorExplorer, Breadcrumb, User

# Add custom breadcrumb
ErrorExplorer.add_breadcrumb(Breadcrumb(
    message="User clicked checkout",
    category="user.action",
    data={"cart_total": 99.99},
))

# Set user context (overrides auto-detected user)
ErrorExplorer.set_user(User(
    id="user_123",
    email="user@example.com",
    plan="pro",
))

# Set tags for filtering
ErrorExplorer.set_tags({
    "feature": "checkout",
    "ab_test": "new_flow",
})

# Capture exception manually
try:
    process_payment()
except PaymentError as e:
    ErrorExplorer.capture_exception(e)

# Capture message
ErrorExplorer.capture_message("Payment processed", level="info")
```

## What's Captured Automatically

### Request/Response
- HTTP method, path, query string
- Response status code
- Safe headers (User-Agent, Referer, etc.)
- Client IP address

### User Context
- User ID
- Username
- Full name
- Email (if `send_default_pii=True`)

### Django Signals
- User login/logout
- Failed login attempts
- Database connections

### Breadcrumbs
- All incoming requests
- All responses
- Log messages (if logging handler is configured)
- Auth events

## Testing

Disable Error Explorer in tests:

```python
# settings.py or conftest.py
ERROR_EXPLORER = {
    'token': 'test_token',
    'capture_signals': False,
    'capture_logging': False,
}
```

Or in pytest:

```python
# conftest.py
@pytest.fixture(autouse=True)
def reset_error_explorer():
    from error_explorer import ErrorExplorer
    ErrorExplorer.reset()
    yield
    ErrorExplorer.reset()
```

## License

MIT
