GitHub

The official Treblle SDK for JavaScript frameworks including Django. Seamlessly integrate Treblle to manage communication with your dashboard, send errors, and secure sensitive data.

Treblle with Django

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 = {
    'sdk_token': 'your_sdk_token',
    'api_key': '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'
    ],
}

Tip

Treblle automatically masks common sensitive fields, but you can extend this list to include any custom fields specific to your application.

Treblle Docs