Treblle with Django

treblle-python

The official Treblle SDK for Python, tailored for the Django framework. Seamlessly integrate Treblle into your Django applications to effortlessly manage communication with your dashboard, transmit errors, and safeguard sensitive data.

Requirements

Python: 3.7 or higher
Django: 2.2 or higher
Requests: 2.25.0 or higher

Note: Django 5.0+ requires Python 3.10 or higher. If you’re using Django 5.x, ensure you have Python 3.10+.

Installation

You can install Treblle for Django via PyPI.

For the latest stable version:

$ pip install treblle==2.0.3

Don’t forget to load the required python modules in your settings.py like so:

INSTALLED_APPS = [
    ...
    'treblle',
]

MIDDLEWARE = [
    ...
    'treblle.middleware.TreblleMiddleware',
]

Getting Started

Create a FREE account on treblle.com, copy your SDK Token and API Key from the Treblle Dashboard to settings.py like so:

TREBLLE = {
    'SDK_TOKEN': os.environ.get('TREBLLE_SDK_TOKEN'),
    'API_KEY': os.environ.get('TREBLLE_API_KEY'),
    'MASKED_FIELDS': ['custom_field', 'internal_id'],  # Optional - additional fields to mask
    'DEBUG': True,  # Optional - enables debug logging (default: False)
    'EXCLUDED_ROUTES': ['/health/', '/ping', '/admin/*'],  # Optional - routes to exclude from tracking
}

Visit the Treblle Dashboard and see requests appear in real-time.

🔄 Migrating from v1 to v2

If you’re upgrading from v1, you’ll need to make these changes:

1. Configuration Format (REQUIRED)

Old v1 Format:

TREBLLE_INFO = {
    'api_key': 'your_sdk_token',
    'project_id': 'your_api_key',
    'hidden_keys': ['password']
}

New v2 Format:

TREBLLE = {
    'SDK_TOKEN': 'your_sdk_token',
    'API_KEY': 'your_api_key',
    'MASKED_FIELDS': ['password'], # Optional
    'DEBUG': False, # Optional
    'EXCLUDED_ROUTES': ['/health/', '/ping'], # Optional
}

2. Django Settings Update (REQUIRED)

Old v1 Middleware:

MIDDLEWARE_CLASSES = [  # Deprecated Django setting
    'treblle.middleware.TreblleMiddleware',
]

New v2 Middleware:

MIDDLEWARE = [  # Modern Django setting
    'treblle.middleware.TreblleMiddleware',
]

Debug Mode

Enable debug mode to get detailed logging about the SDK’s operation:

Configuration errors: Missing or invalid SDK_TOKEN/API_KEY
Middleware loading: Confirmation that Treblle is active
API responses: HTTP status codes from Treblle endpoints
Error handling: 4xx/5xx errors with helpful troubleshooting tips
Data processing: JSON validation and masking information

TREBLLE = {
    'SDK_TOKEN': 'your_sdk_token',
    'API_KEY': 'your_api_key',
    'DEBUG': True  # Enable debug mode
}

Route Exclusion

You can exclude specific routes from being tracked by Treblle. This is useful for health checks, monitoring endpoints, or other routes that generate high-frequency, low-value traffic:

TREBLLE = {
    'SDK_TOKEN': 'your_token',
    'API_KEY': 'your_key',
    'EXCLUDED_ROUTES': [
        '/health/',           # Exact path match
        '/api/health',        # Exact path match
        '/ping',              # Exact path match
        '/admin/*',           # Wildcard: excludes /admin/login, /admin/users, etc.
        '*/metrics',          # Wildcard: excludes /api/metrics, /internal/metrics, etc.
        '/status/*',          # Wildcard: excludes anything under /status/
    ],
}

Pattern matching:

Exact matches: /health/ only matches exactly /health/
Wildcards: Use * for flexible matching (e.g., /admin/* matches /admin/login, /admin/users/1)
Debug logging: Enable DEBUG: True to see which routes are being excluded

Field Masking

You can mask sensitive fields in your API requests and responses by specifying them in the MASKED_FIELDS configuration:

TREBLLE = {
    'SDK_TOKEN': 'your_token',
    'API_KEY': 'your_key',
    'MASKED_FIELDS': [
        'password',
        'api_key',
        'token',
        'credit_card',
        'ssn',
        'custom_sensitive_field'
    ],
}