{"id":8102,"library":"django-guid","title":"Django GUID","description":"django-guid is a Python middleware library for Django applications, enabling single request-response cycle tracing by injecting a unique ID (GUID) into project logs. It supports both ASGI and WSGI applications and includes integrations for tools like Sentry and Celery. The library is currently at version 3.5.2 and maintains an active release cadence, frequently updating to support new Django and Python versions.","status":"active","version":"3.5.2","language":"en","source_language":"en","source_url":"https://github.com/snok/django-guid","tags":["django","middleware","logging","guid","tracing","correlation-id","celery","sentry","asgi"],"install":[{"cmd":"pip install django-guid","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core functionality is a Django middleware. Requires Django >= 3.2 for django-guid v3.4.0+.","package":"Django","optional":false},{"reason":"Required for Sentry integration features (optional).","package":"sentry-sdk","optional":true},{"reason":"Required for Celery integration features (optional).","package":"celery","optional":true}],"imports":[{"note":"The primary middleware for request GUID injection.","symbol":"GuidMiddleware","correct":"from django_guid.middleware import GuidMiddleware"},{"note":"Used in Django's LOGGING configuration to inject the GUID into log records.","symbol":"CorrelationId","correct":"from django_guid.log_filters import CorrelationId"},{"note":"Direct access to the GUID context variable was moved from `utils` to `context` in versions 3.5.1+.","wrong":"from django_guid.utils import guid_context","symbol":"guid_context","correct":"from django_guid.context import guid_context"},{"note":"Required to enable Sentry integration.","symbol":"SentryIntegration","correct":"from django_guid.integrations import SentryIntegration"},{"note":"Required to enable Celery integration.","symbol":"CeleryIntegration","correct":"from django_guid.integrations import CeleryIntegration"},{"note":"API function to retrieve the current request's GUID.","symbol":"get_guid","correct":"from django_guid.api import get_guid"}],"quickstart":{"code":"import logging\nfrom django.http import HttpResponse\nfrom django.conf import settings\n\n# Minimal settings.py content for quickstart\nsettings.configure(\n    INSTALLED_APPS=['django_guid'],\n    MIDDLEWARE=['django_guid.middleware.GuidMiddleware'],\n    LOGGING={\n        'version': 1,\n        'disable_existing_loggers': False,\n        'filters': {\n            'correlation_id': {\n                '()': 'django_guid.log_filters.CorrelationId'\n            }\n        },\n        'formatters': {\n            'verbose': {\n                'format': '{levelname} {asctime} {module} {process:d} {thread:d} {correlation_id} {message}',\n                'style': '{',\n            },\n        },\n        'handlers': {\n            'console': {\n                'class': 'logging.StreamHandler',\n                'formatter': 'verbose',\n                'filters': ['correlation_id']\n            },\n        },\n        'loggers': {\n            'django': {\n                'handlers': ['console'],\n                'level': 'INFO',\n                'propagate': True,\n            },\n            '': { # root logger\n                'handlers': ['console'],\n                'level': 'INFO',\n            }\n        }\n    }\n)\n\nlogger = logging.getLogger(__name__)\n\ndef my_view(request):\n    logger.info(\"This log message will include the GUID.\")\n    return HttpResponse(\"Hello, world!\")\n\n# To demonstrate outside a full Django runserver context (for testing):\n# from django.test import RequestFactory\n# from django_guid.middleware import GuidMiddleware\n# from django.urls import path\n# from django.core.handlers.wsgi import WSGIRequest\n\n# try:\n#     from django.test.utils import setup_test_environment, teardown_test_environment\n# except ImportError:\n#     # For Django < 1.10\n#     pass\n\n# if hasattr(settings, 'configure') and settings.configured is False:\n#     settings.configure(DEBUG=True)\n\n# # Basic URLConf for demonstration\n# urlpatterns = [\n#     path('test-guid/', my_view),\n# ]\n\n# # Simulate a request (requires more setup for full Django context)\n# # This part is illustrative; a real test suite or `python manage.py runserver` is needed.\n# if __name__ == '__main__':\n#     print(\"To run, integrate into a Django project with 'python manage.py runserver'.\")\n#     print(\"Ensure settings.py includes 'django_guid' in INSTALLED_APPS and GuidMiddleware.\")\n#     print(\"Logging configuration should apply 'correlation_id' filter as shown above.\")\n\n","lang":"python","description":"To quickly integrate `django-guid`, add `'django_guid'` to `INSTALLED_APPS` and `GuidMiddleware` to your `MIDDLEWARE` in `settings.py`. It's recommended to place the middleware at the top of the list. Crucially, configure your `LOGGING` dictionary to use the `django_guid.log_filters.CorrelationId` filter and include `{correlation_id}` in your formatter strings."},"warnings":[{"fix":"Ensure your project is running on Python 3.8 or newer and Django 3.2 or newer before upgrading to `django-guid` v3.4.0 or later.","message":"`django-guid` v3.4.0 introduced breaking changes by dropping support for Python 3.7 and Django versions lower than 3.2.","severity":"breaking","affected_versions":">=3.4.0"},{"fix":"Verify that your `LOGGING` configuration includes `django_guid.log_filters.CorrelationId` as a filter, that your handlers reference this filter, and that your formatters include the `{correlation_id}` placeholder.","message":"The GUID will not appear in your application logs if the `CorrelationId` filter is not correctly applied to your logging handlers and formatters in `settings.py`.","severity":"gotcha","affected_versions":"All"},{"fix":"Update imports from `from django_guid.utils import guid_context` to `from django_guid.context import guid_context`.","message":"Direct access to the GUID context variable moved from `django_guid.utils.guid_context` to `django_guid.context.guid_context` in `django-guid` v3.5.1.","severity":"deprecated","affected_versions":">=3.5.1"},{"fix":"If integrating with Sentry for Celery, consult the `django-guid` documentation for Sentry integration settings and ensure your Sentry SDK version is compatible or upgrade to Sentry SDK v2+.","message":"When using `django-guid` with Sentry, support for Sentry SDK v2 (`sentry>2`) was added in v3.5.2 for Celery integration. Ensure compatibility if you are using older Sentry SDK versions.","severity":"gotcha","affected_versions":">=3.5.2"},{"fix":"Add `DJANGO_GUID = {'UUID_FORMAT': 'string'}` to your `settings.py` to enable the string format for generated UUIDs.","message":"The `UUID_FORMAT` setting (introduced in v3.3.0) defaults to `hex`. If you need the standard UUID string format with hyphens (e.g., `776336d4-545e-...`), you must explicitly configure it.","severity":"gotcha","affected_versions":">=3.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change `from django_guid.utils import guid_context` (or similar) to `from django_guid.context import guid_context`.","cause":"Attempting to import `guid_context` or other utilities from the deprecated `django_guid.utils` module after upgrading to `django-guid` v3.5.1 or newer.","error":"ModuleNotFoundError: No module named 'django_guid.utils'"},{"fix":"Add `'django_guid'` to your `INSTALLED_APPS` list in `settings.py`.","cause":"The `django_guid` app has not been added to your `INSTALLED_APPS` list in your Django project's `settings.py` file.","error":"ImproperlyConfigured: 'django_guid' must be in your INSTALLED_APPS"},{"fix":"Review your `LOGGING` configuration in `settings.py`. Ensure that `CorrelationId` is defined as a filter, included in your desired handler(s), and that the formatter used by those handlers has `{correlation_id}` in its format string.","cause":"The `django_guid.log_filters.CorrelationId` filter is not correctly applied to your logging handlers or the formatter string does not include `{correlation_id}`.","error":"Log messages appear without the correlation_id field."},{"fix":"Refer to the `django-guid` documentation's compatibility matrix. For Django versions 3.1.1 or above, use `django-guid` v3.x.x for both ASGI and WSGI. Older Django versions (3.0.0-3.1.0 or 2.2.x) should use v2.x.x (WSGI only).","cause":"Using an incorrect `django-guid` version for your Django setup (e.g., v2.x.x for Django 3.1+ with ASGI/async, which requires v3.x.x).","error":"Multiple versions of Django-GUID for different Django versions (e.g., 2.x.x vs 3.x.x for ASGI/WSGI)"}]}