feat: Add colorization based on health level for panels and toolbar by hunzlahmalik · Pull Request #2178 · django-commons/django-debug-toolbar

hunzlahmalik · 2025-08-10T20:44:45Z

Colorize the minimized DDT icon #1395

Description

This PR introduces a unified health/alert state for Django Debug Toolbar panels and updates the UI to reflect panel.
The name health is debatable, but the alert was already taken by the panel.

Key Changes

Adds a ToolbarHealthLevel enum (NONE, WARNING, CRITICAL) for numeric health states.
Adds a health_level property to the base Panel class, allowing panels to report their health status.
Implements health_level in AlertsPanel and SQLPanel for alert and slow query detection.
The toolbar now computes the maximum health level across all panels and uses it to color the hidden toolbar handle.
UI Updates:
- Panel buttons and the hidden toolbar handle use new CSS classes and colors based on health level.
- Adds CSS variables and styles for warning and critical states.

Warning	Warning on Hover	Critical	Critical on Hover

Critical on Panel	Warning on Panel

Motivation

Improves user experience by visually highlighting issues in the toolbar.

Checklist:

I have added the relevant tests for this change.
I have added an item to the Pending section of docs/changes.rst.
Add to Documentation

hunzlahmalik · 2025-08-10T20:48:45Z

@matthiask @tim-schilling

I'll be writing the testcases for this. It would be great if you could take a look at it before testcases.

Thanks!

Edit: You can also suggest how to compute health(debatable name) across other panel profiling, time etc...

matthiask

I like the idea! I added some nitpicks and comments/general questions.

matthiask · 2025-08-14T17:07:31Z

+
+    --djdt-health-bg-1: #4b3f1b;
+    --djdt-health-color-1: #ffe761;
+    --djdt-health-bc-1: #ffcc00;


What is bc? Background color? I think we prefer using variable names without abbreviations.

matthiask · 2025-08-14T17:08:04Z

+
+#djDebug .djdt-toolbarhandle-health-2 {
+    border-color: var(--djdt-health-bc-2) !important;
+}


Can you add a comment why all these !important are necessary? And/or remove them when they are not?

Overwriting CSS statements is also slow. Ideally, you set the correct value in one shot. You could even calculate it with a 120deg hue range between green and red.

matthiask · 2025-08-14T17:08:59Z

  </div>
  <div class="djdt-hidden" id="djDebugToolbarHandle">
-    <div title="{% translate 'Show toolbar' %}" id="djShowToolBarButton">
+    <div title="{% translate 'Show toolbar' %}" id="djShowToolBarButton" class="{% if toolbar.health_level %} djdt-toolbarhandle-health-{{ toolbar.health_level }}{% endif %}">


I generally do not like uppercase letters much in ID and class attributes, but I wonder if we should keep capitalization for internal consistency here? Any thoughts?

They are inconsistent right now. Some places use camelCase when starting class names with dj, while others use lowercase with dashes (mostly when starting with djdt).

Rightnow, I can change them to camelcase if you want, but for consistency the changes in whole project will be required in future.

Ah, don't worry about it then. Being as consistent as possible is good enough.

matthiask · 2025-08-14T17:09:55Z

+        Return the maximum health level across all panels.
+        This is used to color the toolbar hidden button.
+        """
+        return max(panel.health_level for panel in self.panels)


What happens when self.panels is empty? Is it possible? I think you might want to provide a default value as a fallback (max((...), NONE))

matthiask · 2025-08-14T17:10:41Z

    )
+
+
+class ToolbarHealthLevel(IntEnum):


I think this could be called HealthLevel only since it actually doesn't only apply to the toolbar itself but also to individual panels.

for more information, see https://pre-commit.ci

tim-schilling · 2025-09-20T13:11:11Z

+    --djdt-health-background-color-1: #4b3f1b;
+    --djdt-health-color-1: #ffe761;
+    --djdt-health-border-color-1: #ffcc00;
+    --djdt-health-background-color-2: #5a2327;
+    --djdt-health-color-2: #ffb3b3;
+    --djdt-health-border-color-2: #ff0000;


Could we use a descriptive word rather than 1 and 2 here please?

This might also be a good application for the HSL color space. It also makes it much easier to review than RGB hex code.

This will also add a dark mode, much easier in the future.

tim-schilling · 2025-09-20T13:14:37Z

    )
+
+
+class HealthLevel(IntEnum):


@matthiask @hunzlahmalik do we want to bikeshed a bit on the name here? If we build out an API, this will likely be included in that and no longer be a private-ish thing. In my mind, "severity" may be more appropriate, but then it may lack the context of what is the severity in relation to.

Not sure, but want to bring it up since it's likely to become a public interface in the near future (< 1 years).

Yes we can change the name. I thought about it and was inclined to using the alert, but it was already taking in the app for the panel. We can use severity, we can see this as independent from the colorization. Later this can be use to get the panel severitylevel to do something else.

tim-schilling · 2025-09-20T13:17:17Z

@hunzlahmalik this is really neat! How does it work with the history panel? Does the color only show for the request that renders the button? If you switch to a request that has problems, does the color update? Last question, I promise, did you consider adding the health level to the history panel so a person can view the high level issues of all the requests in a summary-esque view? I personally think that would be a fantastic way to leverage this feature.

Co-authored-by: Tim Schilling <schilling711@gmail.com>

hunzlahmalik · 2025-09-23T07:37:03Z

For the panels that do define the health_level logic, after switching the request they should update the color too. Right now there are only two panels with health_level login, sqlpanel and alerts.

See this:

Regarding summary-esque view, what do you have in mind. We can colorize the rows in the history panel based on health, or do you want a separate some kind of filter/tab for it. I think coloring the rows looks good to me. Like if there is a request with health_level CRITICAL, then that row will be red, with warning, that row will be yellowish.

codingjoe

Hi @hunzlahmalik,

Thanks for the contribution! Since I am somewhat of a frontend nerd, I invested some time to leave you a thorough review. I hope it's helpful. Don't hesitate to ask questions should my comments have been too vague.

Cheers!
Joe

codingjoe · 2026-04-17T22:01:58Z

+        stats = self.get_stats()
+        slow_queries = len([1 for q in stats.get("queries", []) if q.get("is_slow")])
+        if slow_queries > 10:
+            return HealthLevel.CRITICAL
+        elif slow_queries > 0:
+            return HealthLevel.WARNING


The current implementation is susceptible to the number of queries executed on a page. A mean or median threshold might be more reliable.

Also, this is a great usecase for matcht..case.

codingjoe · 2026-04-17T22:04:13Z

+        """
+        Return the health level of the SQL panel.
+        This is determined by the number of slow queries recorded.
+        """


I don't love overwriting docstrings. PEP257 would have you document the behavior of a function, not its implementation. And the behavior usually doesn't change in subclasses, but only its implementation does.

codingjoe · 2026-04-17T22:08:04Z

+    @property
+    def health_level(self):
+        """
+        Returns the health level of the panel as a `ToolbarHealthLevel` enum value.


I know we currently have a wild mix, but it's never too late to write docstrings in the present tense imperative mood.

Suggested change

Returns the health level of the panel as a `ToolbarHealthLevel` enum value.

Return a calculated health level of the page as a `ToolbarHealthLevel` enum value.

codingjoe · 2026-04-17T22:08:41Z

+        This property is used by the toolbar to determine the overall health status of each panel.
+        The default implementation returns `ToolbarHealthLevel.NONE`, indicating no issues.


Suggested change

This property is used by the toolbar to determine the overall health status of each panel.

The default implementation returns `ToolbarHealthLevel.NONE`, indicating no issues.

Used by the toolbar to determine the overall health status of each panel.

The default implementation returns `ToolbarHealthLevel.NONE`, indicating no issues.

codingjoe · 2026-04-17T22:10:18Z

+        Subclasses should override this property to provide custom health logic, returning
+        `ToolbarHealthLevel.WARNING` or `ToolbarHealthLevel.ERROR` as appropriate based on panel-specific conditions.


The enum might get more entries later, you might not want to list them.

codingjoe · 2026-04-17T22:13:49Z

+    --djdt-health-background-color-1: #4b3f1b;
+    --djdt-health-color-1: #ffe761;
+    --djdt-health-border-color-1: #ffcc00;
+    --djdt-health-background-color-2: #5a2327;
+    --djdt-health-color-2: #ffb3b3;
+    --djdt-health-border-color-2: #ff0000;


This might also be a good application for the HSL color space. It also makes it much easier to review than RGB hex code.

codingjoe · 2026-04-17T22:15:02Z

 }

+/* Panel and Toolbar hidden button health states */
+#djDebug .djdt-health-1 {


All browsers support nesting these days. So one #djDebug will do just fine.

codingjoe · 2026-04-17T22:15:32Z

+    --djdt-health-background-color-1: #4b3f1b;
+    --djdt-health-color-1: #ffe761;
+    --djdt-health-border-color-1: #ffcc00;
+    --djdt-health-background-color-2: #5a2327;
+    --djdt-health-color-2: #ffb3b3;
+    --djdt-health-border-color-2: #ff0000;


This will also add a dark mode, much easier in the future.

codingjoe · 2026-04-17T22:18:28Z

+
+#djDebug .djdt-toolbarhandle-health-2 {
+    border-color: var(--djdt-health-bc-2) !important;
+}


Overwriting CSS statements is also slow. Ideally, you set the correct value in one shot. You could even calculate it with a 120deg hue range between green and red.

codingjoe · 2026-04-17T22:21:31Z

+        if not self.panels:
+            return HealthLevel.NONE
+
+        return max(panel.health_level for panel in self.enabled_panels)


EAFP: Just try to return the max and catch the ValueError and return .NONE. Branching is expensive.

hunzlahmalik · 2026-04-20T10:29:30Z

Thanks for the review @codingjoe. Will definitely go through these carefully in free time.

matthiask reviewed Aug 14, 2025

View reviewed changes

hunzlahmalik force-pushed the main branch 2 times, most recently from 2c46d26 to b38335d Compare August 17, 2025 11:28

feat: Add colorization based on health level for panels and toolbar

85b08f0

hunzlahmalik force-pushed the main branch from ed0661b to 85b08f0 Compare August 17, 2025 11:32

pre-commit-ci Bot and others added 2 commits August 17, 2025 11:32

[pre-commit.ci] auto fixes from pre-commit.com hooks

427ec23

for more information, see https://pre-commit.ci

Merge branch 'django-commons:main' into main

0c15dde

hunzlahmalik requested a review from matthiask August 17, 2025 11:34

tim-schilling reviewed Sep 20, 2025

View reviewed changes

Comment thread debug_toolbar/toolbar.py Outdated

Update debug_toolbar/toolbar.py

2f8c3d4

Co-authored-by: Tim Schilling <schilling711@gmail.com>

fix: get alerts from stats instead of local var

aa96318

codingjoe reviewed Apr 17, 2026

View reviewed changes

	Returns the health level of the panel as a `ToolbarHealthLevel` enum value.
	Return a calculated health level of the page as a `ToolbarHealthLevel` enum value.

		This property is used by the toolbar to determine the overall health status of each panel.
		The default implementation returns `ToolbarHealthLevel.NONE`, indicating no issues.

		Subclasses should override this property to provide custom health logic, returning
		`ToolbarHealthLevel.WARNING` or `ToolbarHealthLevel.ERROR` as appropriate based on panel-specific conditions.

Conversation

hunzlahmalik commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key Changes

Motivation

Checklist:

Uh oh!

hunzlahmalik commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthiask left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tim-schilling commented Sep 20, 2025

Uh oh!

hunzlahmalik commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codingjoe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hunzlahmalik commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hunzlahmalik commented Aug 10, 2025 •

edited

Loading

hunzlahmalik commented Aug 10, 2025 •

edited

Loading

hunzlahmalik commented Sep 23, 2025 •

edited

Loading