django-observatory 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. django_observatory-0.1.0/CHANGELOG.md +36 -0
  2. django_observatory-0.1.0/CONTRIBUTING.md +69 -0
  3. django_observatory-0.1.0/LICENSE +21 -0
  4. django_observatory-0.1.0/MANIFEST.in +5 -0
  5. django_observatory-0.1.0/PKG-INFO +237 -0
  6. django_observatory-0.1.0/README.md +194 -0
  7. django_observatory-0.1.0/SECURITY.md +26 -0
  8. django_observatory-0.1.0/benchmarks/overhead.py +79 -0
  9. django_observatory-0.1.0/django_observatory/__init__.py +35 -0
  10. django_observatory-0.1.0/django_observatory/admin.py +69 -0
  11. django_observatory-0.1.0/django_observatory/alerts.py +212 -0
  12. django_observatory-0.1.0/django_observatory/apps.py +32 -0
  13. django_observatory-0.1.0/django_observatory/audit.py +47 -0
  14. django_observatory-0.1.0/django_observatory/checks.py +82 -0
  15. django_observatory-0.1.0/django_observatory/conf.py +197 -0
  16. django_observatory-0.1.0/django_observatory/context.py +156 -0
  17. django_observatory-0.1.0/django_observatory/correlation/__init__.py +0 -0
  18. django_observatory-0.1.0/django_observatory/correlation/causal.py +117 -0
  19. django_observatory-0.1.0/django_observatory/correlation/engine.py +345 -0
  20. django_observatory-0.1.0/django_observatory/correlation/graph.py +97 -0
  21. django_observatory-0.1.0/django_observatory/correlation/rules.py +220 -0
  22. django_observatory-0.1.0/django_observatory/exporters.py +73 -0
  23. django_observatory-0.1.0/django_observatory/fingerprints.py +74 -0
  24. django_observatory-0.1.0/django_observatory/health.py +165 -0
  25. django_observatory-0.1.0/django_observatory/instrumentation/__init__.py +32 -0
  26. django_observatory-0.1.0/django_observatory/instrumentation/database.py +71 -0
  27. django_observatory-0.1.0/django_observatory/instrumentation/exceptions.py +75 -0
  28. django_observatory-0.1.0/django_observatory/instrumentation/http.py +173 -0
  29. django_observatory-0.1.0/django_observatory/instrumentation/otel.py +115 -0
  30. django_observatory-0.1.0/django_observatory/internal.py +50 -0
  31. django_observatory-0.1.0/django_observatory/logging.py +127 -0
  32. django_observatory-0.1.0/django_observatory/maintenance.py +77 -0
  33. django_observatory-0.1.0/django_observatory/management/__init__.py +0 -0
  34. django_observatory-0.1.0/django_observatory/management/commands/__init__.py +0 -0
  35. django_observatory-0.1.0/django_observatory/management/commands/observability_cleanup.py +21 -0
  36. django_observatory-0.1.0/django_observatory/management/commands/observability_export.py +33 -0
  37. django_observatory-0.1.0/django_observatory/management/commands/observability_health.py +19 -0
  38. django_observatory-0.1.0/django_observatory/management/commands/observability_rebuild_fingerprints.py +37 -0
  39. django_observatory-0.1.0/django_observatory/management/commands/observability_stats.py +15 -0
  40. django_observatory-0.1.0/django_observatory/management/commands/observability_test.py +145 -0
  41. django_observatory-0.1.0/django_observatory/metrics.py +257 -0
  42. django_observatory-0.1.0/django_observatory/middleware.py +262 -0
  43. django_observatory-0.1.0/django_observatory/migrations/0001_initial.py +509 -0
  44. django_observatory-0.1.0/django_observatory/migrations/__init__.py +0 -0
  45. django_observatory-0.1.0/django_observatory/models.py +562 -0
  46. django_observatory-0.1.0/django_observatory/observe.py +42 -0
  47. django_observatory-0.1.0/django_observatory/permissions.py +55 -0
  48. django_observatory-0.1.0/django_observatory/pipeline.py +176 -0
  49. django_observatory-0.1.0/django_observatory/redaction.py +119 -0
  50. django_observatory-0.1.0/django_observatory/routers.py +35 -0
  51. django_observatory-0.1.0/django_observatory/scheduler.py +77 -0
  52. django_observatory-0.1.0/django_observatory/search.py +200 -0
  53. django_observatory-0.1.0/django_observatory/security.py +47 -0
  54. django_observatory-0.1.0/django_observatory/signals.py +53 -0
  55. django_observatory-0.1.0/django_observatory/static/django_observatory/app.css +195 -0
  56. django_observatory-0.1.0/django_observatory/static/django_observatory/app.js +372 -0
  57. django_observatory-0.1.0/django_observatory/storage/__init__.py +24 -0
  58. django_observatory-0.1.0/django_observatory/storage/base.py +30 -0
  59. django_observatory-0.1.0/django_observatory/storage/django.py +175 -0
  60. django_observatory-0.1.0/django_observatory/system.py +207 -0
  61. django_observatory-0.1.0/django_observatory/tables.py +182 -0
  62. django_observatory-0.1.0/django_observatory/templates/django_observatory/_cells.html +1 -0
  63. django_observatory-0.1.0/django_observatory/templates/django_observatory/_chart.html +1 -0
  64. django_observatory-0.1.0/django_observatory/templates/django_observatory/_hbars.html +3 -0
  65. django_observatory-0.1.0/django_observatory/templates/django_observatory/_range.html +4 -0
  66. django_observatory-0.1.0/django_observatory/templates/django_observatory/_waterfall.html +12 -0
  67. django_observatory-0.1.0/django_observatory/templates/django_observatory/alerts.html +29 -0
  68. django_observatory-0.1.0/django_observatory/templates/django_observatory/base.html +55 -0
  69. django_observatory-0.1.0/django_observatory/templates/django_observatory/dashboard.html +26 -0
  70. django_observatory-0.1.0/django_observatory/templates/django_observatory/database.html +18 -0
  71. django_observatory-0.1.0/django_observatory/templates/django_observatory/exception_detail.html +21 -0
  72. django_observatory-0.1.0/django_observatory/templates/django_observatory/external.html +19 -0
  73. django_observatory-0.1.0/django_observatory/templates/django_observatory/health.html +12 -0
  74. django_observatory-0.1.0/django_observatory/templates/django_observatory/incident_detail.html +36 -0
  75. django_observatory-0.1.0/django_observatory/templates/django_observatory/issue_detail.html +32 -0
  76. django_observatory-0.1.0/django_observatory/templates/django_observatory/list.html +27 -0
  77. django_observatory-0.1.0/django_observatory/templates/django_observatory/log_detail.html +26 -0
  78. django_observatory-0.1.0/django_observatory/templates/django_observatory/metrics.html +15 -0
  79. django_observatory-0.1.0/django_observatory/templates/django_observatory/performance.html +29 -0
  80. django_observatory-0.1.0/django_observatory/templates/django_observatory/request_detail.html +46 -0
  81. django_observatory-0.1.0/django_observatory/templates/django_observatory/search.html +13 -0
  82. django_observatory-0.1.0/django_observatory/templates/django_observatory/settings.html +17 -0
  83. django_observatory-0.1.0/django_observatory/templates/django_observatory/system.html +11 -0
  84. django_observatory-0.1.0/django_observatory/templates/django_observatory/trace_detail.html +17 -0
  85. django_observatory-0.1.0/django_observatory/templatetags/__init__.py +0 -0
  86. django_observatory-0.1.0/django_observatory/templatetags/observatory.py +41 -0
  87. django_observatory-0.1.0/django_observatory/tracing.py +214 -0
  88. django_observatory-0.1.0/django_observatory/urls.py +33 -0
  89. django_observatory-0.1.0/django_observatory/views.py +898 -0
  90. django_observatory-0.1.0/django_observatory.egg-info/PKG-INFO +237 -0
  91. django_observatory-0.1.0/django_observatory.egg-info/SOURCES.txt +121 -0
  92. django_observatory-0.1.0/django_observatory.egg-info/dependency_links.txt +1 -0
  93. django_observatory-0.1.0/django_observatory.egg-info/requires.txt +11 -0
  94. django_observatory-0.1.0/django_observatory.egg-info/top_level.txt +1 -0
  95. django_observatory-0.1.0/docs/alerts.md +138 -0
  96. django_observatory-0.1.0/docs/api.md +146 -0
  97. django_observatory-0.1.0/docs/architecture.md +74 -0
  98. django_observatory-0.1.0/docs/commands.md +99 -0
  99. django_observatory-0.1.0/docs/configuration.md +289 -0
  100. django_observatory-0.1.0/docs/data-model.md +145 -0
  101. django_observatory-0.1.0/docs/deployment.md +67 -0
  102. django_observatory-0.1.0/docs/development.md +154 -0
  103. django_observatory-0.1.0/docs/faq.md +128 -0
  104. django_observatory-0.1.0/docs/getting-started.md +167 -0
  105. django_observatory-0.1.0/docs/incident-correlation.md +89 -0
  106. django_observatory-0.1.0/docs/index.md +36 -0
  107. django_observatory-0.1.0/docs/instrumentation.md +284 -0
  108. django_observatory-0.1.0/docs/opentelemetry.md +34 -0
  109. django_observatory-0.1.0/docs/privacy.md +47 -0
  110. django_observatory-0.1.0/docs/query-language.md +290 -0
  111. django_observatory-0.1.0/docs/security.md +46 -0
  112. django_observatory-0.1.0/docs/server-monitoring.md +93 -0
  113. django_observatory-0.1.0/docs/troubleshooting.md +29 -0
  114. django_observatory-0.1.0/docs/user-guide.md +222 -0
  115. django_observatory-0.1.0/pyproject.toml +61 -0
  116. django_observatory-0.1.0/setup.cfg +4 -0
  117. django_observatory-0.1.0/tests/__init__.py +0 -0
  118. django_observatory-0.1.0/tests/settings.py +29 -0
  119. django_observatory-0.1.0/tests/test_capture.py +573 -0
  120. django_observatory-0.1.0/tests/test_core.py +167 -0
  121. django_observatory-0.1.0/tests/test_intelligence.py +488 -0
  122. django_observatory-0.1.0/tests/test_ui.py +245 -0
  123. django_observatory-0.1.0/tests/urls.py +49 -0
@@ -0,0 +1,36 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/),
4
+ and the project uses [Semantic Versioning](https://semver.org/).
5
+
6
+ ## Unreleased
7
+
8
+ ## 0.1.0 - 2026-10-05
9
+
10
+ First public release.
11
+
12
+ ### Capture
13
+ - Logging handler with automatic attachment; structured `observe` API
14
+ - Request middleware for WSGI and ASGI; request and trace ids; W3C Trace Context in and out
15
+ - Traces and spans (`span`, `task`); SQL monitoring with normalisation, fingerprints and slow-query detection
16
+ - Outbound HTTP monitoring for `urllib`, `requests` and `httpx`
17
+ - Exception capture, issue grouping and lifecycle (open, acknowledged, resolved, ignored, regressed), breadcrumbs
18
+ - Metrics: counters, gauges, histograms, timers; one-minute buckets rolled up to hourly and daily
19
+ - Server resources: CPU, memory and disk per host (psutil optional)
20
+ - Security events (logins, failures, permission denied, CSRF, password changes)
21
+ - Append-only, hash-chained audit trail; Django admin changes audited automatically
22
+
23
+ ### Intelligence
24
+ - Alert rules with deduplication, cooldown, email and webhook channels; eight default rules
25
+ - Incident detection with rule-based correlation: external service, database, server resources, deployment,
26
+ exception spike, security spike; facts and inference kept separate
27
+ - Per-request causal analysis ("Why is this slow?" / "Why did this fail?")
28
+ - Application Observability Graph
29
+
30
+ ### Interface and operations
31
+ - Built-in UI (Django templates and vanilla JavaScript, light and dark, no external assets) and JSON API
32
+ - Query language, global search, CSV / JSON / NDJSON export
33
+ - Central redaction engine, sampling, per-kind retention, health page, system checks
34
+ - OTLP/HTTP trace export without the OpenTelemetry SDK
35
+ - Management commands: `observability_test`, `_health`, `_stats`, `_cleanup`, `_export`, `_rebuild_fingerprints`
36
+ - Optional separate telemetry database through `ObservabilityRouter`
@@ -0,0 +1,69 @@
1
+ # Contributing
2
+
3
+ Thank you for helping. Bug reports, documentation fixes and code are all welcome.
4
+
5
+ ## Ground rules
6
+
7
+ These are what make the project what it is. Changes that break them are not merged.
8
+
9
+ 1. **Zero infrastructure.** Nothing may require Redis, Celery, Docker, a message broker, a search engine,
10
+ a SaaS or a CDN. Django is the only mandatory dependency; prefer the standard library.
11
+ 2. **Offline.** No runtime network access except what the operator configures (webhook, OTLP endpoint).
12
+ The UI ships all of its assets.
13
+ 3. **Failure isolation.** A bug or outage in observability must never fail, block or slow the host
14
+ application's request. New capture code is wrapped and gets a test that breaks it on purpose.
15
+ 4. **Privacy by default.** Everything stored, exported or displayed goes through `redaction`. New capture of
16
+ potentially sensitive data is opt-in.
17
+ 5. **Portable.** Windows Server and Linux; SQLite, PostgreSQL and SQL Server. No database-specific SQL, no
18
+ Unix-only APIs without a fallback.
19
+ 6. **Explainable.** Incident rules state the evidence behind every inference. No opaque scoring, no LLM in
20
+ the core.
21
+
22
+ ## Development setup
23
+
24
+ ```bash
25
+ git clone https://github.com/AzeemQidwai/django-observatory.git
26
+ cd django-observatory
27
+ python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
28
+ pip install -e ".[all]"
29
+ python -m django test tests --settings=tests.settings
30
+ ```
31
+
32
+ Run the demo project to see your change in the UI:
33
+
34
+ ```bash
35
+ cd example
36
+ python manage.py migrate && python manage.py createsuperuser
37
+ python manage.py runserver
38
+ ```
39
+
40
+ Open `/observability/`. `/sap/degrade/?on=1` makes the simulated dependency slow so that an incident is
41
+ detected.
42
+
43
+ ## Making a change
44
+
45
+ - Open an issue first for anything larger than a small fix, so the approach can be agreed.
46
+ - Keep pull requests focused: one change, with its tests and documentation.
47
+ - Tests live in `tests/` and use Django's test runner. They run with the synchronous pipeline
48
+ (`PIPELINE.SYNC`), so assertions are deterministic; `tests/test_capture.py::PipelineTests` covers the real
49
+ worker thread.
50
+ - Model changes need a migration (`python -m django makemigrations django_observatory --settings=tests.settings`).
51
+ - UI changes: no build step, no framework, no external assets. Check light and dark mode and a phone-width
52
+ viewport. Charts follow the conventions already in `static/django_observatory/app.js`.
53
+ - Add a line to the *Unreleased* section of `CHANGELOG.md`.
54
+
55
+ See [docs/development.md](docs/development.md) for the code layout, how to add an incident rule, a storage
56
+ backend or a notification channel, and the release process.
57
+
58
+ ## Reporting bugs
59
+
60
+ Use the bug report template. Include the output of `python manage.py observability_test` and
61
+ `observability_health`, and remove secrets and production data from anything you paste.
62
+
63
+ ## Security issues
64
+
65
+ Do not open a public issue. See [SECURITY.md](SECURITY.md).
66
+
67
+ ## Licence
68
+
69
+ By contributing you agree that your contributions are licensed under the MIT licence of this project.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 django-observability contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,5 @@
1
+ include LICENSE README.md CHANGELOG.md SECURITY.md CONTRIBUTING.md
2
+ recursive-include docs *.md
3
+ recursive-include tests *.py
4
+ recursive-include benchmarks *.py
5
+ global-exclude __pycache__ *.py[cod] *.sqlite3 *.sqlite3-*
@@ -0,0 +1,237 @@
1
+ Metadata-Version: 2.4
2
+ Name: django-observatory
3
+ Version: 0.1.0
4
+ Summary: Django-native, offline-first observability: logs, requests, traces, SQL, exceptions, metrics, server resources, security/audit events, alerts and incident correlation in a built-in UI, with no separate infrastructure.
5
+ Author: Azeem Qidwai
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/AzeemQidwai/django-observatory
8
+ Project-URL: Documentation, https://github.com/AzeemQidwai/django-observatory/blob/main/docs/index.md
9
+ Project-URL: Repository, https://github.com/AzeemQidwai/django-observatory
10
+ Project-URL: Issues, https://github.com/AzeemQidwai/django-observatory/issues
11
+ Project-URL: Changelog, https://github.com/AzeemQidwai/django-observatory/blob/main/CHANGELOG.md
12
+ Keywords: django,observability,monitoring,logging,tracing,apm,metrics,error-tracking,audit-log,incident,opentelemetry,offline,air-gapped
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Web Environment
15
+ Classifier: Framework :: Django
16
+ Classifier: Framework :: Django :: 4.2
17
+ Classifier: Framework :: Django :: 5.2
18
+ Classifier: Framework :: Django :: 6.0
19
+ Classifier: Intended Audience :: Developers
20
+ Classifier: Intended Audience :: System Administrators
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Programming Language :: Python :: 3
23
+ Classifier: Programming Language :: Python :: 3 :: Only
24
+ Classifier: Programming Language :: Python :: 3.10
25
+ Classifier: Programming Language :: Python :: 3.11
26
+ Classifier: Programming Language :: Python :: 3.12
27
+ Classifier: Programming Language :: Python :: 3.13
28
+ Classifier: Topic :: Internet :: WWW/HTTP
29
+ Classifier: Topic :: System :: Logging
30
+ Classifier: Topic :: System :: Monitoring
31
+ Requires-Python: >=3.10
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ Requires-Dist: Django>=4.2
35
+ Provides-Extra: process
36
+ Requires-Dist: psutil>=5.9; extra == "process"
37
+ Provides-Extra: otel
38
+ Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
39
+ Provides-Extra: all
40
+ Requires-Dist: psutil>=5.9; extra == "all"
41
+ Requires-Dist: opentelemetry-api>=1.20; extra == "all"
42
+ Dynamic: license-file
43
+
44
+ # django-observatory
45
+
46
+ [![PyPI](https://img.shields.io/pypi/v/django-observatory.svg)](https://pypi.org/project/django-observatory/)
47
+ [![Python](https://img.shields.io/pypi/pyversions/django-observatory.svg)](https://pypi.org/project/django-observatory/)
48
+ [![Django](https://img.shields.io/badge/django-4.2%20%7C%205.2%20%7C%206.x-0C4B33.svg)](https://www.djangoproject.com/)
49
+ [![CI](https://github.com/AzeemQidwai/django-observatory/actions/workflows/ci.yml/badge.svg)](https://github.com/AzeemQidwai/django-observatory/actions/workflows/ci.yml)
50
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
51
+
52
+ **Production observability for Django without a separate observability infrastructure.**
53
+
54
+ `pip install`, three settings, `migrate` — and `/observability/` is a complete operations console for your
55
+ application: logs, requests, traces, SQL, exceptions, metrics, server resources, security and audit events,
56
+ alerts, and incidents with a probable cause. Everything is stored in your own database and rendered by
57
+ Django. No Docker, Redis, Elasticsearch, Prometheus, Grafana, Sentry, agent, collector or cloud service.
58
+
59
+ It was built for places where the usual stack is not an option: Windows servers, air-gapped networks,
60
+ regulated environments where telemetry must not leave the organisation, and teams that are only allowed to
61
+ install Python packages. It stays compatible with the wider ecosystem through W3C Trace Context and OTLP
62
+ export.
63
+
64
+ ![Dashboard](https://raw.githubusercontent.com/AzeemQidwai/django-observatory/main/docs/images/dashboard.png)
65
+
66
+ ## Why
67
+
68
+ Most observability tools answer *what happened*. This one is designed to walk an operator from there to
69
+ *where*, *what caused it*, *who was affected* and *what to look at next* — inside the application it is
70
+ monitoring.
71
+
72
+ | | |
73
+ |---|---|
74
+ | **Zero infrastructure** | Python + Django + your existing database. One background thread per process. |
75
+ | **Offline first** | No outbound network calls, no CDN, no external assets. Works air-gapped. |
76
+ | **Django aware** | Request → view → template → ORM → SQL → external API, correlated automatically. |
77
+ | **Explains incidents** | Deterministic rules turn correlated signals into one incident with evidence. No AI. |
78
+ | **Private by default** | Bodies, cookies, auth headers and SQL parameters are never stored; secrets are redacted. |
79
+ | **Cannot take you down** | If observability fails, your application keeps serving. This is tested explicitly. |
80
+
81
+ ## Features
82
+
83
+ - **Logs** – your existing `logging` calls are captured with no configuration; structured `observe.info(...)` API
84
+ - **Requests** – every request gets a request id and trace id (`X-Request-ID`, `X-Trace-ID` response headers)
85
+ - **Traces** – waterfall of view, templates, SQL and outbound HTTP; manual `span()` and `@task`
86
+ - **SQL** – normalised statements, fingerprints, slow-query detection, N+1 hints, drill-down to the request
87
+ - **External APIs** – `urllib`, `requests`, `httpx`: latency and failure rate per service
88
+ - **Exceptions and issues** – grouping by stable fingerprint, lifecycle with regression detection, breadcrumbs
89
+ - **Metrics** – counters, gauges, histograms, timers, percentiles; automatic rollups
90
+ - **Server resources** – CPU, memory and disk per host
91
+ - **Security events** – logins, failed logins, permission denied, CSRF failures, password changes
92
+ - **Audit trail** – append-only, hash-chained, tamper-evident, separately permissioned
93
+ - **Alerts** – rules with deduplication and cooldown; in-app, email, webhook
94
+ - **Incidents** – correlated detection with probable cause, confidence, impact and evidence
95
+ - **Causal analysis** – "Why is this slow?" / "Why did this fail?" on every request
96
+ - **Query language** – `status:>=500 AND duration:>1000 NOT path:/health*`
97
+ - **Exports and API** – CSV, JSON, NDJSON; read-only JSON API
98
+ - **OpenTelemetry** – W3C Trace Context in and out; OTLP/HTTP export without the SDK
99
+
100
+ ## Quick start
101
+
102
+ ```bash
103
+ pip install django-observatory
104
+ ```
105
+
106
+ ```python
107
+ # settings.py
108
+ INSTALLED_APPS = [
109
+ # ...
110
+ "django_observatory",
111
+ ]
112
+
113
+ MIDDLEWARE = [
114
+ "django_observatory.middleware.ObservabilityMiddleware", # first, so it times the whole stack
115
+ # ...
116
+ ]
117
+ ```
118
+
119
+ ```python
120
+ # urls.py
121
+ from django.urls import include, path
122
+
123
+ urlpatterns = [
124
+ # ...
125
+ path("observability/", include("django_observatory.urls")),
126
+ ]
127
+ ```
128
+
129
+ ```bash
130
+ python manage.py migrate
131
+ python manage.py observability_test # verifies every component in your environment
132
+ python manage.py runserver
133
+ ```
134
+
135
+ Open <http://localhost:8000/observability/> as a staff user. That is the whole setup.
136
+
137
+ Optional extras: `pip install "django-observatory[process]"` adds `psutil` (CPU and memory readings on every
138
+ platform, per-process memory).
139
+
140
+ ## Use it from your code
141
+
142
+ Nothing is required: requests, SQL, outbound HTTP, exceptions and `logging` are captured automatically.
143
+ The API is for what only you know.
144
+
145
+ ```python
146
+ import logging
147
+ from django_observatory import observe, span, task, metrics, audit, security
148
+
149
+ logging.getLogger(__name__).info("material created", extra={"material_code": "A1023"}) # just works
150
+ observe.warning("stock_low", material_code="A1023", quantity=4)
151
+
152
+ with span("generate_monthly_report", report_type="monthly"):
153
+ generate_report()
154
+
155
+ @task
156
+ def nightly_sync(): ...
157
+
158
+ metrics.increment("invoice.processed")
159
+ metrics.gauge("queue.depth", 42)
160
+ with metrics.timer("invoice.processing"):
161
+ process_invoice()
162
+
163
+ audit.record(action="UPDATE", object_type="Material", object_id="A1023",
164
+ changes={"quantity": {"before": 120, "after": 80}})
165
+ security.record(event="PERMISSION_DENIED", resource="/api/materials/", reason="Missing permission")
166
+ ```
167
+
168
+ ## From a symptom to a cause
169
+
170
+ A dependency slows down. Within a minute the dashboard shows one incident instead of a wall of alerts:
171
+
172
+ ![Incident](https://raw.githubusercontent.com/AzeemQidwai/django-observatory/main/docs/images/incident.png)
173
+
174
+ The probable cause is an inference and is labelled as one, with its confidence. The evidence beneath it is
175
+ observed fact: the numbers before and after, the share of failing requests that call the service, the
176
+ exceptions raised. Opening any affected request shows where its time went:
177
+
178
+ ![Request](https://raw.githubusercontent.com/AzeemQidwai/django-observatory/main/docs/images/request.png)
179
+
180
+ More screenshots: [endpoints](docs/images/performance.png) · [server](docs/images/server.png) ·
181
+ [logs](docs/images/logs.png) · [database, dark mode](docs/images/database-dark.png)
182
+
183
+ ## Documentation
184
+
185
+ | Start here | Reference | Operate |
186
+ |---|---|---|
187
+ | [Getting started](docs/getting-started.md) | [Configuration](docs/configuration.md) | [Deployment](docs/deployment.md) |
188
+ | [User guide to the UI](docs/user-guide.md) | [Python API](docs/instrumentation.md) | [Alerts](docs/alerts.md) |
189
+ | [FAQ](docs/faq.md) | [Query language](docs/query-language.md) | [Incident correlation](docs/incident-correlation.md) |
190
+ | | [JSON API and exports](docs/api.md) | [Server monitoring](docs/server-monitoring.md) |
191
+ | | [Management commands](docs/commands.md) | [Security](docs/security.md) · [Privacy](docs/privacy.md) |
192
+ | | [Data model](docs/data-model.md) | [OpenTelemetry](docs/opentelemetry.md) |
193
+ | | [Architecture](docs/architecture.md) | [Troubleshooting](docs/troubleshooting.md) |
194
+
195
+ Full index: [docs/index.md](docs/index.md)
196
+
197
+ ## Requirements
198
+
199
+ - Python 3.10 – 3.13
200
+ - Django 4.2, 5.2 or 6.x
201
+ - Any database Django supports. Tested on SQLite; designed for PostgreSQL and SQL Server (portable column
202
+ types, no database-specific SQL)
203
+ - Windows, Linux or macOS; WSGI or ASGI
204
+
205
+ ## Try the demo
206
+
207
+ ```bash
208
+ git clone https://github.com/AzeemQidwai/django-observatory.git
209
+ cd django-observatory/example
210
+ pip install -e ..
211
+ python manage.py migrate
212
+ python manage.py createsuperuser
213
+ python manage.py runserver
214
+ ```
215
+
216
+ Browse `/api/materials/` a few times, open `/sap/degrade/?on=1` to make the simulated SAP dependency slow,
217
+ call `/api/materials/` again, and watch `/observability/` open an incident named after the cause.
218
+
219
+ ## What this is not
220
+
221
+ It is not the first observability tool for Django, and it does not replace OpenTelemetry, or Sentry in
222
+ every scenario. Django Silk, Django Debug Toolbar, Sentry and the OpenTelemetry integrations are excellent
223
+ at what they do. This package combines Django-native instrumentation, local storage, security and audit
224
+ monitoring, and incident correlation into something you can deploy anywhere Django runs — and it exports
225
+ to those ecosystems when you outgrow it.
226
+
227
+ Scaling limits are documented honestly in [Architecture](docs/architecture.md#deliberate-limits) and
228
+ [Deployment](docs/deployment.md#sizing-and-retention).
229
+
230
+ ## Contributing
231
+
232
+ Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the
233
+ [Code of Conduct](CODE_OF_CONDUCT.md). Security reports go through [SECURITY.md](SECURITY.md).
234
+
235
+ ## License
236
+
237
+ [MIT](LICENSE)
@@ -0,0 +1,194 @@
1
+ # django-observatory
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/django-observatory.svg)](https://pypi.org/project/django-observatory/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/django-observatory.svg)](https://pypi.org/project/django-observatory/)
5
+ [![Django](https://img.shields.io/badge/django-4.2%20%7C%205.2%20%7C%206.x-0C4B33.svg)](https://www.djangoproject.com/)
6
+ [![CI](https://github.com/AzeemQidwai/django-observatory/actions/workflows/ci.yml/badge.svg)](https://github.com/AzeemQidwai/django-observatory/actions/workflows/ci.yml)
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
+
9
+ **Production observability for Django without a separate observability infrastructure.**
10
+
11
+ `pip install`, three settings, `migrate` — and `/observability/` is a complete operations console for your
12
+ application: logs, requests, traces, SQL, exceptions, metrics, server resources, security and audit events,
13
+ alerts, and incidents with a probable cause. Everything is stored in your own database and rendered by
14
+ Django. No Docker, Redis, Elasticsearch, Prometheus, Grafana, Sentry, agent, collector or cloud service.
15
+
16
+ It was built for places where the usual stack is not an option: Windows servers, air-gapped networks,
17
+ regulated environments where telemetry must not leave the organisation, and teams that are only allowed to
18
+ install Python packages. It stays compatible with the wider ecosystem through W3C Trace Context and OTLP
19
+ export.
20
+
21
+ ![Dashboard](https://raw.githubusercontent.com/AzeemQidwai/django-observatory/main/docs/images/dashboard.png)
22
+
23
+ ## Why
24
+
25
+ Most observability tools answer *what happened*. This one is designed to walk an operator from there to
26
+ *where*, *what caused it*, *who was affected* and *what to look at next* — inside the application it is
27
+ monitoring.
28
+
29
+ | | |
30
+ |---|---|
31
+ | **Zero infrastructure** | Python + Django + your existing database. One background thread per process. |
32
+ | **Offline first** | No outbound network calls, no CDN, no external assets. Works air-gapped. |
33
+ | **Django aware** | Request → view → template → ORM → SQL → external API, correlated automatically. |
34
+ | **Explains incidents** | Deterministic rules turn correlated signals into one incident with evidence. No AI. |
35
+ | **Private by default** | Bodies, cookies, auth headers and SQL parameters are never stored; secrets are redacted. |
36
+ | **Cannot take you down** | If observability fails, your application keeps serving. This is tested explicitly. |
37
+
38
+ ## Features
39
+
40
+ - **Logs** – your existing `logging` calls are captured with no configuration; structured `observe.info(...)` API
41
+ - **Requests** – every request gets a request id and trace id (`X-Request-ID`, `X-Trace-ID` response headers)
42
+ - **Traces** – waterfall of view, templates, SQL and outbound HTTP; manual `span()` and `@task`
43
+ - **SQL** – normalised statements, fingerprints, slow-query detection, N+1 hints, drill-down to the request
44
+ - **External APIs** – `urllib`, `requests`, `httpx`: latency and failure rate per service
45
+ - **Exceptions and issues** – grouping by stable fingerprint, lifecycle with regression detection, breadcrumbs
46
+ - **Metrics** – counters, gauges, histograms, timers, percentiles; automatic rollups
47
+ - **Server resources** – CPU, memory and disk per host
48
+ - **Security events** – logins, failed logins, permission denied, CSRF failures, password changes
49
+ - **Audit trail** – append-only, hash-chained, tamper-evident, separately permissioned
50
+ - **Alerts** – rules with deduplication and cooldown; in-app, email, webhook
51
+ - **Incidents** – correlated detection with probable cause, confidence, impact and evidence
52
+ - **Causal analysis** – "Why is this slow?" / "Why did this fail?" on every request
53
+ - **Query language** – `status:>=500 AND duration:>1000 NOT path:/health*`
54
+ - **Exports and API** – CSV, JSON, NDJSON; read-only JSON API
55
+ - **OpenTelemetry** – W3C Trace Context in and out; OTLP/HTTP export without the SDK
56
+
57
+ ## Quick start
58
+
59
+ ```bash
60
+ pip install django-observatory
61
+ ```
62
+
63
+ ```python
64
+ # settings.py
65
+ INSTALLED_APPS = [
66
+ # ...
67
+ "django_observatory",
68
+ ]
69
+
70
+ MIDDLEWARE = [
71
+ "django_observatory.middleware.ObservabilityMiddleware", # first, so it times the whole stack
72
+ # ...
73
+ ]
74
+ ```
75
+
76
+ ```python
77
+ # urls.py
78
+ from django.urls import include, path
79
+
80
+ urlpatterns = [
81
+ # ...
82
+ path("observability/", include("django_observatory.urls")),
83
+ ]
84
+ ```
85
+
86
+ ```bash
87
+ python manage.py migrate
88
+ python manage.py observability_test # verifies every component in your environment
89
+ python manage.py runserver
90
+ ```
91
+
92
+ Open <http://localhost:8000/observability/> as a staff user. That is the whole setup.
93
+
94
+ Optional extras: `pip install "django-observatory[process]"` adds `psutil` (CPU and memory readings on every
95
+ platform, per-process memory).
96
+
97
+ ## Use it from your code
98
+
99
+ Nothing is required: requests, SQL, outbound HTTP, exceptions and `logging` are captured automatically.
100
+ The API is for what only you know.
101
+
102
+ ```python
103
+ import logging
104
+ from django_observatory import observe, span, task, metrics, audit, security
105
+
106
+ logging.getLogger(__name__).info("material created", extra={"material_code": "A1023"}) # just works
107
+ observe.warning("stock_low", material_code="A1023", quantity=4)
108
+
109
+ with span("generate_monthly_report", report_type="monthly"):
110
+ generate_report()
111
+
112
+ @task
113
+ def nightly_sync(): ...
114
+
115
+ metrics.increment("invoice.processed")
116
+ metrics.gauge("queue.depth", 42)
117
+ with metrics.timer("invoice.processing"):
118
+ process_invoice()
119
+
120
+ audit.record(action="UPDATE", object_type="Material", object_id="A1023",
121
+ changes={"quantity": {"before": 120, "after": 80}})
122
+ security.record(event="PERMISSION_DENIED", resource="/api/materials/", reason="Missing permission")
123
+ ```
124
+
125
+ ## From a symptom to a cause
126
+
127
+ A dependency slows down. Within a minute the dashboard shows one incident instead of a wall of alerts:
128
+
129
+ ![Incident](https://raw.githubusercontent.com/AzeemQidwai/django-observatory/main/docs/images/incident.png)
130
+
131
+ The probable cause is an inference and is labelled as one, with its confidence. The evidence beneath it is
132
+ observed fact: the numbers before and after, the share of failing requests that call the service, the
133
+ exceptions raised. Opening any affected request shows where its time went:
134
+
135
+ ![Request](https://raw.githubusercontent.com/AzeemQidwai/django-observatory/main/docs/images/request.png)
136
+
137
+ More screenshots: [endpoints](docs/images/performance.png) · [server](docs/images/server.png) ·
138
+ [logs](docs/images/logs.png) · [database, dark mode](docs/images/database-dark.png)
139
+
140
+ ## Documentation
141
+
142
+ | Start here | Reference | Operate |
143
+ |---|---|---|
144
+ | [Getting started](docs/getting-started.md) | [Configuration](docs/configuration.md) | [Deployment](docs/deployment.md) |
145
+ | [User guide to the UI](docs/user-guide.md) | [Python API](docs/instrumentation.md) | [Alerts](docs/alerts.md) |
146
+ | [FAQ](docs/faq.md) | [Query language](docs/query-language.md) | [Incident correlation](docs/incident-correlation.md) |
147
+ | | [JSON API and exports](docs/api.md) | [Server monitoring](docs/server-monitoring.md) |
148
+ | | [Management commands](docs/commands.md) | [Security](docs/security.md) · [Privacy](docs/privacy.md) |
149
+ | | [Data model](docs/data-model.md) | [OpenTelemetry](docs/opentelemetry.md) |
150
+ | | [Architecture](docs/architecture.md) | [Troubleshooting](docs/troubleshooting.md) |
151
+
152
+ Full index: [docs/index.md](docs/index.md)
153
+
154
+ ## Requirements
155
+
156
+ - Python 3.10 – 3.13
157
+ - Django 4.2, 5.2 or 6.x
158
+ - Any database Django supports. Tested on SQLite; designed for PostgreSQL and SQL Server (portable column
159
+ types, no database-specific SQL)
160
+ - Windows, Linux or macOS; WSGI or ASGI
161
+
162
+ ## Try the demo
163
+
164
+ ```bash
165
+ git clone https://github.com/AzeemQidwai/django-observatory.git
166
+ cd django-observatory/example
167
+ pip install -e ..
168
+ python manage.py migrate
169
+ python manage.py createsuperuser
170
+ python manage.py runserver
171
+ ```
172
+
173
+ Browse `/api/materials/` a few times, open `/sap/degrade/?on=1` to make the simulated SAP dependency slow,
174
+ call `/api/materials/` again, and watch `/observability/` open an incident named after the cause.
175
+
176
+ ## What this is not
177
+
178
+ It is not the first observability tool for Django, and it does not replace OpenTelemetry, or Sentry in
179
+ every scenario. Django Silk, Django Debug Toolbar, Sentry and the OpenTelemetry integrations are excellent
180
+ at what they do. This package combines Django-native instrumentation, local storage, security and audit
181
+ monitoring, and incident correlation into something you can deploy anywhere Django runs — and it exports
182
+ to those ecosystems when you outgrow it.
183
+
184
+ Scaling limits are documented honestly in [Architecture](docs/architecture.md#deliberate-limits) and
185
+ [Deployment](docs/deployment.md#sizing-and-retention).
186
+
187
+ ## Contributing
188
+
189
+ Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the
190
+ [Code of Conduct](CODE_OF_CONDUCT.md). Security reports go through [SECURITY.md](SECURITY.md).
191
+
192
+ ## License
193
+
194
+ [MIT](LICENSE)
@@ -0,0 +1,26 @@
1
+ # Security policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Please report suspected vulnerabilities **privately**:
6
+ <https://github.com/AzeemQidwai/django-observatory/security/advisories/new>
7
+
8
+ Do not open a public issue. Include the affected version, a description and steps to reproduce. You will
9
+ receive an acknowledgement within five working days, and a fix or mitigation plan as soon as the report is
10
+ confirmed. You will be credited in the release notes unless you prefer otherwise.
11
+
12
+ Of particular interest:
13
+
14
+ - telemetry storing an unredacted secret under the default configuration
15
+ - access to observability data without the required permission
16
+ - modification of audit records that `AuditEvent.verify_chain()` does not detect
17
+ - any input that makes observability fail, block or noticeably slow the host application
18
+ - cross-site scripting through stored telemetry, or injection through the query language
19
+
20
+ ## Supported versions
21
+
22
+ Security fixes are released for the latest minor version.
23
+
24
+ ## Security model
25
+
26
+ See [docs/security.md](docs/security.md) and [docs/privacy.md](docs/privacy.md).
@@ -0,0 +1,79 @@
1
+ """Measure the synchronous overhead observability adds to a request.
2
+
3
+ python benchmarks/overhead.py (from the repository root)
4
+
5
+ Compares the same views with observability disabled and enabled (asynchronous pipeline,
6
+ the production configuration), plus logging and SQL-monitoring cost in isolation.
7
+ """
8
+ import logging
9
+ import os
10
+ import statistics
11
+ import sys
12
+ import tempfile
13
+ import time
14
+ from pathlib import Path
15
+
16
+ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
17
+ os.environ["DJANGO_SETTINGS_MODULE"] = "tests.settings"
18
+
19
+ import django # noqa: E402
20
+ from django.conf import settings # noqa: E402
21
+
22
+ django.setup()
23
+ settings.DATABASES["default"]["NAME"] = os.path.join(tempfile.mkdtemp(), "bench.sqlite3")
24
+
25
+ from django.core.management import call_command # noqa: E402
26
+ from django.db import connection # noqa: E402
27
+ from django.test import Client, override_settings # noqa: E402
28
+
29
+ from django_observatory import pipeline # noqa: E402
30
+
31
+ N = 400
32
+ ASYNC = {"SCHEDULER": {"ENABLED": False}, "LOGGING": {"AUTO_ATTACH": False}}
33
+
34
+
35
+ def timed(fn, n=N):
36
+ for _ in range(20):
37
+ fn()
38
+ samples = []
39
+ for _ in range(n):
40
+ t0 = time.perf_counter()
41
+ fn()
42
+ samples.append((time.perf_counter() - t0) * 1000)
43
+ samples.sort()
44
+ return statistics.mean(samples), samples[int(n * 0.95)]
45
+
46
+
47
+ def run(label, fn, variants):
48
+ results = {}
49
+ for name, obs in variants.items():
50
+ with override_settings(OBSERVABILITY=obs):
51
+ results[name] = timed(fn)
52
+ pipeline.flush(30)
53
+ base = results["off"][0]
54
+ print(f"\n{label}")
55
+ for name, (mean, p95) in results.items():
56
+ delta = f" (+{mean - base:.3f} ms)" if name != "off" else ""
57
+ print(f" {name:<28} mean {mean:7.3f} ms p95 {p95:7.3f} ms{delta}")
58
+
59
+
60
+ def main():
61
+ connection.close()
62
+ call_command("migrate", verbosity=0)
63
+ client = Client()
64
+ log = logging.getLogger("bench")
65
+ log.setLevel(logging.INFO)
66
+ log.propagate = False
67
+ from django_observatory.logging import ObservabilityHandler
68
+
69
+ log.addHandler(ObservabilityHandler())
70
+ off = {**ASYNC, "ENABLED": False}
71
+ print(f"{N} iterations each, asynchronous pipeline, SQLite file database")
72
+ run("Request with 2 SQL queries (/sql/)", lambda: client.get("/sql/"), {
73
+ "off": off, "on": ASYNC, "on, SQL monitoring disabled": {**ASYNC, "DATABASE": {"ENABLED": False}},
74
+ "on, 10% request sampling": {**ASYNC, "SAMPLING": {"requests": 0.1}}})
75
+ run("Logging: logger.info() with extra", lambda: log.info("bench %s", 1, extra={"k": "v"}), {"off": off, "on": ASYNC})
76
+
77
+
78
+ if __name__ == "__main__":
79
+ main()