feat: Add supervisor:get_tree/1 for full supervision tree introspection by km-git007 · Pull Request #10972 · erlang/otp

km-git007 · 2026-04-04T11:19:03Z

Operators debugging distributed Erlang applications often need to understand the complete supervision structure at runtime. Previously, this required manually walking the supervision tree by repeatedly calling supervisor:which_children/1 on each supervisor found.

This commit introduces supervisor:get_tree/1, which returns a complete hierarchical representation of the supervision tree rooted at a given supervisor. The function recursively builds a nested structure containing:

Child ID, PID, type (worker/supervisor), and modules
Full subtrees for child supervisors
Empty subtrees for worker processes

The feature enables:

Better debugging of supervision hierarchies
Improved application visualization tools
Runtime introspection for operational monitoring
Automation of cluster topology discovery

The implementation:

Uses existing supervisor:which_children/1 as its foundation
Handles all supervisor reference types (pid, atom, global, via)
Gracefully handles errors and nonexistent supervisors
Returns structured data suitable for JSON serialization or display

Added comprehensive tests for:

Basic tree building with multiple children
Supervisor and worker process types
Terminated and undefined child processes
Error handling for invalid references

CLAassistant · 2026-04-04T11:19:10Z

All committers have signed the CLA.

github-actions · 2026-04-04T11:19:43Z

CT Test Results

2 files 100 suites 1h 8m 54s ⏱️
2 295 tests 2 241 ✅ 52 💤 2 ❌
2 714 runs 2 656 ✅ 56 💤 2 ❌

For more details on these failures, see this check.

Results for commit 3388e9a.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

// Erlang/OTP Github Action Bot

josevalim · 2026-04-09T06:37:58Z

+        SupPid = get_sup_pid(Supervisor),
+        {SupPid, [build_tree_node(Id, Child, Type, Modules) ||
+                  {Id, Child, Type, Modules} <- Children]}


It seems get_sup_pid is a bit unrelated to this function. If you need the supervisor pid, then perhaps you could call a separate function and expand it yourself, and keep it outside of this new functionality?

Furthermore, there is a subtle race condition in this code. The Supervisor can actually change between which_children and get_sup_pid, so you would return the children of one supervisor and the Pid of another.

Thanks for catching both issues. I've fixed the race condition by resolving the supervisor reference first via resolve_supervisor_reference/1 and then passing the stable PID to which_children/1. I've also extracted the helper into a standalone resolve_supervisor_reference/1 function with a spec and a comment explaining the race-avoidance rationale, keeping it separate from the tree-building logic.

josevalim · 2026-04-09T06:40:12Z

+    %% Add a worker child
+    {ok, Child1} = supervisor:start_child(SupPid, #{id => child1,
+						    start => {supervisor_1, start_child, []}}),
+    {SupPid, [{child1, Child1, worker, [supervisor_1], []}]} = supervisor:get_tree(SupPid),


This is not testing many of the scenarios in the code above, such as different names, undefined children, etc.

Good catch. I've added 5 new tests covering: local atom name reference, global name reference, undefined (terminated) children, nested supervisor hierarchies, and mixed running/undefined child states. These are now grouped under a get_tree test group in the suite.

josevalim · 2026-04-09T06:40:43Z

+%% Helper function to build a tree node for a single child
+build_tree_node(Id, Child, Type, Modules) ->
+    Subtree = case Type of
+        supervisor when is_pid(Child), Child =/= undefined ->


If Child is a pid, then it is certainly =/= from undefined:

Suggested change

supervisor when is_pid(Child), Child =/= undefined ->

supervisor when is_pid(Child) ->

Correct, is_pid/1 already excludes undefined. Applied the suggestion.

Operators debugging distributed Erlang applications often need to understand the complete supervision structure at runtime. Previously, this required manually walking the supervision tree by repeatedly calling supervisor:which_children/1 on each supervisor found. This commit introduces supervisor:get_tree/1, which returns a complete hierarchical representation of the supervision tree rooted at a given supervisor. The function recursively builds a nested structure containing: - Child ID, PID, type (worker/supervisor), and modules - Full subtrees for child supervisors - Empty subtrees for worker processes The feature enables: - Better debugging of supervision hierarchies - Improved application visualization tools - Runtime introspection for operational monitoring - Automation of cluster topology discovery The implementation: - Uses existing supervisor:which_children/1 as its foundation - Handles all supervisor reference types (pid, atom, global, via) - Gracefully handles errors and nonexistent supervisors - Returns structured data suitable for JSON serialization or display Added comprehensive tests for: - Basic tree building with multiple children - Supervisor and worker process types - Terminated and undefined child processes - Error handling for invalid references

- Fix race condition in get_tree/1: resolve supervisor reference once via resolve_supervisor_reference/1 and reuse the stable PID for which_children/1, preventing children of one supervisor being paired with the PID of another when a registered name rebinds between calls - Rename get_sup_pid/1 to resolve_supervisor_reference/1 with -spec and comment explaining the race-avoidance intent; separates reference resolution from tree-building logic - Simplify build_tree_node/4 guard: is_pid(Child) already excludes undefined, so the redundant Child =/= undefined clause is removed - Add 5 tests covering previously untested scenarios: local atom name reference, global name reference, undefined children, nested supervisor hierarchies, and mixed running/undefined child states

juhlig · 2026-04-14T10:44:47Z

+-type supervision_tree() :: {Pid :: pid(),
+                             [supervision_tree_node()]} |
+                            {error, no_supervision_info}.


The error response does not belong in this type...

Suggested change

-type supervision_tree() :: {Pid :: pid(),

[supervision_tree_node()]} |

{error, no_supervision_info}.

-type supervision_tree() :: {Pid :: pid(),

[supervision_tree_node()]}.

Instead it should be...

juhlig · 2026-04-14T10:45:50Z

+```
+""".
+-doc(#{since => <<"OTP 28.0">>}).
+-spec get_tree(SupRef) -> supervision_tree() when


... here.

Suggested change

-spec get_tree(SupRef) -> supervision_tree() when

-spec get_tree(SupRef) -> supervision_tree() | {error, no_supervision_info} when

Yes, agree.

But {error, no_supervision_info} is in itself not all that great. It glosses over, like, everything. SupRef could not be a process identifier (of sorts). Even if, the process could not be alive (any more). Even if, it could be that the process is not a supervisor. Or something else could have gone wrong when building the tree. All that is conflated into this one error tuple, and even that I would object to: it should rather be a badarg exception, depending on what went wrong.

@Maria-12648430 you're not putting too fine a point on it, but I agree.

Yeah, sorry... 🙍‍♀️ Just when the jetlag from going to Singapore started wearing off, I had to return to Germany, and there it is back again... 😩 So, sorry @km-git007 for being blunt. Nevertheless, my point stands.

IngelaAndin · 2026-04-14T12:48:30Z

@km-git007 We think the idea is interesting. It will take some polishing, and it is not in time for OTP-29.0 so we will come back to you with OTP-team feedback after the the release, as we need to prioritize the release right now. @josevalim , @Maria-12648430 and@juhlig usually have good feedback, so that you can consider in the mean time. It could end up in later version of 29 or in 30 depending on a lot of things that we can not address right now, just saying hang in there.

juhlig · 2026-04-14T15:43:35Z

@@ -2537,3 +2596,43 @@ dyn_init(Child,State) when ?is_temporary(Child) ->
    State#state{dynamics={mapsets,maps:new()}};
 dyn_init(_Child,State) ->
    State#state{dynamics={maps,maps:new()}}.
+
+%% Resolve a supervisor reference (pid | atom | {global,Name} | {via,Mod,Name})


A sup_ref can also be {Name, Node}, which your implementation does not consider.

Aside from that, I think a function like this would be better placed in the gen module (with another name, of course), since it equally applies to all other gen_* behaviors.

Yeah. The other thing is that this function makes many assumptions (for example, it will catch child failures, it will return the PID, etc), which I am not sure are general enough for inclusion either here or in gen. It feels this is app specific code or, if the goal is debugging, add a version the prints the tree to the c module, without exposing the implementation details seen here.

@josevalim are you referring to the build_tree_node function below? As far as that goes, I agree 👍

But in this comment, I was referring to only resolve_supervisor_reference, which determines the pid for a given sup_ref.

since it equally applies to all other gen_* behaviors.

Oh, that would indeed be handy, I'd love that 🥰

rickard-green added the team:PS Assigned to OTP team PS label Apr 7, 2026

IngelaAndin assigned dgud and IngelaAndin Apr 7, 2026

josevalim reviewed Apr 9, 2026

View reviewed changes

km-git007 added 2 commits April 9, 2026 23:03

km-git007 force-pushed the feature/supervisor-tree-introspection branch from feff915 to 3388e9a Compare April 9, 2026 17:34

juhlig suggested changes Apr 14, 2026

View reviewed changes

IngelaAndin added the stalled waiting for input by the Erlang/OTP team label Apr 14, 2026

juhlig reviewed Apr 14, 2026

View reviewed changes

	supervisor when is_pid(Child), Child =/= undefined ->
	supervisor when is_pid(Child) ->

	-spec get_tree(SupRef) -> supervision_tree() when
	-spec get_tree(SupRef) -> supervision_tree() \| {error, no_supervision_info} when

Conversation

km-git007 commented Apr 4, 2026

Uh oh!

CLAassistant commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CT Test Results

Artifacts

Uh oh!

josevalim Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

juhlig Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Maria-12648430 Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

IngelaAndin commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

CLAassistant commented Apr 4, 2026 •

edited

Loading

github-actions Bot commented Apr 4, 2026 •

edited

Loading

josevalim Apr 9, 2026 •

edited

Loading

juhlig Apr 14, 2026 •

edited

Loading

Maria-12648430 Apr 14, 2026 •

edited

Loading

IngelaAndin commented Apr 14, 2026 •

edited

Loading